From 0275e513e92d4d46a336af54d15b230130c3aea8 Mon Sep 17 00:00:00 2001 From: glimmer07 Date: Mon, 13 Jul 2009 17:33:36 +0000 Subject: [PATCH] Documentation helper files. Building documentation is currently done by shell script, but will be integrated into the build system eventually. --- src/extension/dbus/doc/config.xsl | 7 + .../dbus/doc/dbus-introspect-docs.dtd | 33 ++ src/extension/dbus/doc/docbook.css | 79 +++ src/extension/dbus/doc/inkscapeDbusRef.xml | 81 +++ src/extension/dbus/doc/inkscapeDbusTerms.xml | 131 +++++ src/extension/dbus/doc/spec-to-docbook.xsl | 544 ++++++++++++++++++ 6 files changed, 875 insertions(+) create mode 100644 src/extension/dbus/doc/config.xsl create mode 100644 src/extension/dbus/doc/dbus-introspect-docs.dtd create mode 100644 src/extension/dbus/doc/docbook.css create mode 100644 src/extension/dbus/doc/inkscapeDbusRef.xml create mode 100644 src/extension/dbus/doc/inkscapeDbusTerms.xml create mode 100644 src/extension/dbus/doc/spec-to-docbook.xsl diff --git a/src/extension/dbus/doc/config.xsl b/src/extension/dbus/doc/config.xsl new file mode 100644 index 000000000..26949c4ef --- /dev/null +++ b/src/extension/dbus/doc/config.xsl @@ -0,0 +1,7 @@ + + + + + diff --git a/src/extension/dbus/doc/dbus-introspect-docs.dtd b/src/extension/dbus/doc/dbus-introspect-docs.dtd new file mode 100644 index 000000000..47816713e --- /dev/null +++ b/src/extension/dbus/doc/dbus-introspect-docs.dtd @@ -0,0 +1,33 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/extension/dbus/doc/docbook.css b/src/extension/dbus/doc/docbook.css new file mode 100644 index 000000000..aed08dce1 --- /dev/null +++ b/src/extension/dbus/doc/docbook.css @@ -0,0 +1,79 @@ +body +{ + font-family: sans-serif; +} +h1.title +{ +} +.permission +{ + color: #ee0000; + text-decoration: underline; +} +.synopsis, .classsynopsis +{ + background: #eeeeee; + border: solid 1px #aaaaaa; + padding: 0.5em; +} +.programlisting +{ + background: #eeeeff; + border: solid 1px #aaaaff; + padding: 0.5em; +} +.variablelist +{ + padding: 4px; + margin-left: 3em; +} +.variablelist td:first-child +{ + vertical-align: top; +} +td.shortcuts +{ + color: #770000; + font-size: 80%; +} +div.refnamediv +{ + margin-top: 2em; +} +div.toc +{ + border: 2em; +} +a +{ + text-decoration: none; +} +a:hover +{ + text-decoration: underline; + color: #FF0000; +} + +div.table table +{ + border-collapse: collapse; + border-spacing: 0px; + border-style: solid; + border-color: #777777; + border-width: 1px; +} + +div.table table td, div.table table th +{ + border-style: solid; + border-color: #777777; + border-width: 1px; + padding: 3px; + vertical-align: top; +} + +div.table table th +{ + background-color: #eeeeee; +} + diff --git a/src/extension/dbus/doc/inkscapeDbusRef.xml b/src/extension/dbus/doc/inkscapeDbusRef.xml new file mode 100644 index 000000000..6bf134a60 --- /dev/null +++ b/src/extension/dbus/doc/inkscapeDbusRef.xml @@ -0,0 +1,81 @@ + + + + + + +]> + + + + Inkscape Dbus Documentation + Version 0.0 + 7 July, 2009 + + + Soren + Berg + +
+ glimmer07@gmail.com +
+ + + + + + + Introduction + +This is the documentation for scripting Inkscape using Dbus. This framework was developed to let users quickly and easily write scripts to create or manipulate images in a variety of languages. Once the API has stabilized there will also be a C library that encapsulates the Dbus functionality. + + +The guiding principles behind the design of this API were: + + +Easy to use: Use of insider terms was limited where possible, and many functions have been simplified to provide a easy entry point for beginning users. Ideally one should not need any experience with Inkscape or even vector graphics to begin using the interface. At the same time, functions that can call arbitrary verbs or manipulate nodes and their attributes directly give knowledgeable users some flexibility. + + +Interactive: Since Dbus ties in with the main loop, users can mix scripting and mouse driven actions seamlessly. This allows for some unique uses but more importantly makes it easier for people to learn the API since they can play around with it in a scripting console, or even a simple python shell. + + +Responsive: Since one of the advantages of scripting is the ability to repeat actions many times with great precision it is obvious that the system would have to be fairly fast. The amount of overhead has been limited where possible and functions have been tested for speed. A system to pause updates and only refresh the display after a large number of operations have been completed, ensures that even very complicated renders will not take too long. + + + + + Concepts + + &Terms; + + + + + Reference + + + D-Bus API Reference + + + + Inkscape provides a D-Bus API for programs to interactivly script vector graphics. + + + This API is not yet stable and is likely to change in the future. + + + + &dbus-Application; + &dbus-Document; + &dbus-Proposed; + + + + + + Index + + + + diff --git a/src/extension/dbus/doc/inkscapeDbusTerms.xml b/src/extension/dbus/doc/inkscapeDbusTerms.xml new file mode 100644 index 000000000..cd41195a9 --- /dev/null +++ b/src/extension/dbus/doc/inkscapeDbusTerms.xml @@ -0,0 +1,131 @@ + + Connecting to the API + + + Overview + +There are really two Dbus interfaces provided by Inkscape. One is the application interface, which is constant, and allows one to control the Inkscape application as a whole and create new documents or windows. The second is the document interface. A document interface is automatically generated for every open window, and the commands sent to that interface will affect that particular window. + + +So the basic way of connecting goes like this: Connect to the session bus. Connect to the application interface. Request a new document. Connect to the newly created document interface using the name returned in the last step. Manipulate the document however you want (load files, create shapes, save, etc.) After the connection example there is a shortcut that will shorten this process somewhat in certain circumstances. + + + + Connection example + +Here is a basic example of connecting to the Bus and getting a new document. (In python for now because it's easy to read.) + + + +import dbus + +#get the session bus. +bus = dbus.SessionBus() + +#get the object for the application. +inkapp = bus.get_object('org.inkscape', + '/org/inkscape/application') + +#request a new desktop. +desk2 = inkapp.desktop_new(dbus_interface='org.inkscape.application') + +#get the object for that desktop. +inkdoc1 = bus.get_object('org.inkscape', desk2) + +#tell it what interface it is using so we don't have to type it for every method. +doc1 = dbus.Interface(inkdoc1, dbus_interface="org.inkscape.document") + +#use! +doc1.rectangle (0,0,100,100) + + + + + + Shortcut + +Here is a quicker way if you don't need multiple documents open at once. Since Inkscape starts automatically, and it always creates a blank document we can just connect to that. + + +WARNING: This may not always work, it also might connect you to a document that is in use if Inkscape was already running. Only recommended for testing/experimenting. + + + +import dbus + +#get the session bus. +bus = dbus.SessionBus() + +#get object +inkdoc1 = bus.get_object('org.inkscape', '/org/inkscape/desktop_0') + +#get interface +doc1 = dbus.Interface(inkdoc1, dbus_interface="org.inkscape.document") + +#ta-da +doc1.rectangle (0,0,100,100) + + + + + + + + Terminology + + + + Coordinate System + +The coordinate system used by this API may be different than what you are used to (although it is standard in the computer graphics industry.) Simply put the origin (0,0) is in the upper left hand corner of the document. X increases to the right and Y increases downwards. Therefore everything with positive coordinates is in the document. + + +For example: (100,100) would be just below and to the right of the top left corner of the document. + + + + + + Selections + +Selections are extremely useful ways of managing groups of objects and applying effects to all of them at once. Since much of Inkscapes core functionality is built around manipulating selections they are the key to much of this APIs utility. Manipulate the list of selected objects with selection_set(), selection_add(), and selection_box() and then call whatever selection function you need. + + + + + + Groups + +Groups are collections of objects that are treated as a single object. Groups have their own id and can be passed to any function that accepts an object, though some will not have any effect (groups ignore style for instance.) Groups can be transformed and occupy a single level in their layer. Objects within a group can still be modified using their ids, but this will not have any affect on the other group members. Functions like move_to may not work as expected if used on an object that is part of a group that has a transformation applied. + + + + + + Layers and Levels + +The basic idea is that things on top cover up things beneath them. The potentially confusing part is that Inkscape implements this in two ways: layers and levels. Levels are what order objects are in within a single layer. So the highest level object is still below all of the objects in the layer above it. layer_change_level() changes the order of layers and selection_change_level() changes the order of objects within a layer. + + +Changing the level of a selection also deserves some explanation. The selection_change_level() function can work in two ways. It can be absolute, "to_top" and "to_bottom" work like you'd expect, sending the entire selection to the top or bottom of that layer. But it can also be relative. "raise" and "lower" only work if there is another shape overlaping above or beneath the selection at the moment. Also if you have two objects selected and they are both occluded by a third, raising the selection once will only raise the first object in the selection above the third object. In other words selections don't move as a group. + + + + + + Style Strings + +Style strings look something like this: "fill:#ff0000;fill-opacity:1;stroke:#0000ff;stroke-width:5;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none". It is a string of key value pairs that determines the style of a particular object. Style strings affect most objects. They can be set all at once or specific key value pairs can be added one by one. Style strings can also be merged, with the new string replacing key/value pairs that it contains and leaving the rest as they were. One could also think of it as the new string taking any attributes it does not have and adopting them from the old string. + + + + + + Nodes and Paths + +To be written. + + + + + diff --git a/src/extension/dbus/doc/spec-to-docbook.xsl b/src/extension/dbus/doc/spec-to-docbook.xsl new file mode 100644 index 000000000..e200a05e0 --- /dev/null +++ b/src/extension/dbus/doc/spec-to-docbook.xsl @@ -0,0 +1,544 @@ + + + + + + + + + + + + + + + + + + + + + + interface + + + + Methods + + + + + + + + + + + Signals + + + + + + + + + + + Implemented Interfaces + + Objects implementing also implements + org.freedesktop.DBus.Introspectable, + org.freedesktop.DBus.Properties + + + + + + + Properties + + + + + + + + + + + Description + + + + + + + Details + + + + + + + + + Signal Details + + + + + + + + + + + Property Details + + + + + + + + + + + + + + + + +: + + + + + + + + + + + + + + + + + + + + + + <anchor role="function"><xsl:attribute name="id"><xsl:value-of select="$basename"/>:<xsl:value-of select="@name"/></xsl:attribute></anchor>The "<xsl:value-of select="@name"/>" property + +'' + + + + + + + + + + + + + +: + + + + + + + + + + + + + + + + + + + + + <anchor role="function"><xsl:attribute name="id"><xsl:value-of select="$basename"/>::<xsl:value-of select="@name"/></xsl:attribute></anchor>The <xsl:value-of select="@name"/> signal + + () + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + : + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Since + + + + + + + + /> + + + + + + + is deprecated since version and should not be used in newly-written code. Use + + + + + : + + + :: + + + . + + + + + + + + + + + + + + + +instead. + + + + + + + + + + + + + + + + + +See also: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +: + + + + + + + + + + + + Errors + + + + : + + + + + + + + + + + + Permissions + + + + + + + + + + + + + + + + + + <anchor role="function"><xsl:attribute name="id"><xsl:value-of select="$basename"/>.<xsl:value-of select="@name"/></xsl:attribute></anchor><xsl:value-of select="@name"/> () + + () + + + + + + + + + + + + + + + + +:'' + + + + + + + + + + + + +::() + + + + + + + + + + + + +.() + + + + + +'' +, + + + + + +'' +, + + + + + + +'' + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -- 2.30.2