Documentation helper files. Building documentation is currently done by shell script...

diff --git a/src/extension/dbus/doc/config.xsl b/src/extension/dbus/doc/config.xsl
new file mode 100644 (file)
index 0000000..26949c4
--- /dev/null
+++ b/src/extension/dbus/doc/config.xsl
@@ -0,0 +1,7 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:fo="http://www.w3.org/1999/XSL/Format"
+                version="1.0">
+  <xsl:param name="html.stylesheet" select="'docbook.css'"/>
+</xsl:stylesheet>
+

diff --git a/src/extension/dbus/doc/dbus-introspect-docs.dtd b/src/extension/dbus/doc/dbus-introspect-docs.dtd
new file mode 100644 (file)
index 0000000..4781671
--- /dev/null
+++ b/src/extension/dbus/doc/dbus-introspect-docs.dtd
@@ -0,0 +1,33 @@
+<!-- DTD for D-Bus Introspection Documentation -->
+
+<!ELEMENT doc (summary?,description?,errors?,permission?,since?,deprecated,seealso?)>
+
+<!ELEMENT summary (#PCDATA|ref)*>
+<!ELEMENT description (#PCDATA|para|example)*>
+<!ELEMENT errors (error)*>
+<!ELEMENT permission (#PCDATA|ref|para)*>
+<!ELEMENT since EMPTY>
+<!ATTLIST since version CDATA #REQUIRED>
+<!ELEMENT deprecated (#PCDATA|ref)>
+<!ATTLIST deprecated version CDATA #REQUIRED>
+<!ATTLIST deprecated instead CDATA #REQUIRED>
+<!ELEMENT seealso (ref+)>
+
+<!ELEMENT error (#PCDATA|para)*>
+<!ATTLIST error name CDATA #REQUIRED>
+<!ELEMENT para (#PCDATA|example|code|list|ref)*>
+<!ELEMENT example (#PCDATA|para|code|ref)*>
+<!ATTLIST language (c|glib|python|shell) #REQUIRED>
+<!ATTLIST title CDATA #IMPLIED>
+<!ELEMENT list (item*)>
+<!ATTLIST list type (bullet|number) #REQUIRED>
+<!ELEMENT item (term|definition)*>
+<!ELEMENT term (#PCDATA|ref)*>
+<!ELEMENT definition (#PCDATA|para)*>
+
+<!ELEMENT code (#PCDATA)>
+<!ATTLIST code lang CDATA #IMPLIED>
+<!ELEMENT ref CDATA>
+<!ATTLIST ref type (parameter|arg|signal|method|interface) #REQUIRED>
+<!ATTLIST ref to CDATA #REQUIRED>
+

diff --git a/src/extension/dbus/doc/docbook.css b/src/extension/dbus/doc/docbook.css
new file mode 100644 (file)
index 0000000..aed08dc
--- /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 (file)
index 0000000..6bf134a
--- /dev/null
+++ b/src/extension/dbus/doc/inkscapeDbusRef.xml
@@ -0,0 +1,81 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY dbus-Application SYSTEM "org.inkscape.application.ref.xml">
+<!ENTITY dbus-Document SYSTEM "org.inkscape.document.ref.xml">
+<!ENTITY dbus-Proposed SYSTEM "org.inkscape.proposed.ref.xml">
+<!ENTITY Terms SYSTEM "inkscapeDbusTerms.xml">
+
+]>
+
+<book id="index">
+  <bookinfo>
+    <title>Inkscape Dbus Documentation</title>
+    <releaseinfo>Version 0.0</releaseinfo>
+    <date>7 July, 2009</date>
+    <authorgroup>
+      <author>
+        <firstname>Soren</firstname>
+        <surname>Berg</surname>
+        <affiliation>
+          <address>
+            <email>glimmer07@gmail.com</email>
+          </address>
+        </affiliation>
+      </author>
+    </authorgroup>
+  </bookinfo>
+
+  <preface>
+    <title>Introduction</title>
+    <para>
+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.
+    </para>
+    <para>
+The guiding principles behind the design of this API were:
+    </para>
+    <para>
+<emphasis>Easy to use:</emphasis>  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.
+    </para>
+    <para>
+<emphasis>Interactive:</emphasis>  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.  
+    </para>
+    <para>
+<emphasis>Responsive:</emphasis>  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.
+    </para>
+  </preface>
+
+  <part>
+    <title>Concepts</title>
+
+    &Terms;
+
+  </part>
+
+  <part>
+    <title>Reference</title>
+
+    <reference id="dbus-reference">
+      <title>D-Bus API Reference</title>
+
+      <partintro>
+        <para>
+        Inkscape provides a D-Bus API for programs to interactivly script vector graphics.
+        </para>
+        <para>
+        This API is not yet stable and is likely to change in the future.
+        </para>
+      </partintro>
+
+      &dbus-Application;
+      &dbus-Document;
+      &dbus-Proposed;
+
+    </reference>
+  </part>
+
+  <index>
+    <title>Index</title>
+  </index>
+
+</book>
+

diff --git a/src/extension/dbus/doc/inkscapeDbusTerms.xml b/src/extension/dbus/doc/inkscapeDbusTerms.xml
new file mode 100644 (file)
index 0000000..cd41195
--- /dev/null
+++ b/src/extension/dbus/doc/inkscapeDbusTerms.xml
@@ -0,0 +1,131 @@
+<chapter id="connecting">
+  <title>Connecting to the API</title>
+
+  <sect1>
+    <title>Overview</title>
+    <para>
+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.
+    </para>
+    <para>
+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.
+    </para>
+  </sect1>
+  <sect1>
+    <title>Connection example</title>
+    <para>
+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.)
+    </para>
+    <informalexample language="python" title="simple example">
+    <programlisting>
+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)
+    </programlisting>
+    </informalexample>
+  </sect1>
+
+  <sect1>
+    <title>Shortcut</title>
+    <para>
+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.  
+    </para>
+    <warning><para>
+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.
+    </para></warning>
+    <informalexample language="python" title="simple example">
+    <programlisting>
+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)
+    </programlisting>
+    </informalexample>
+  </sect1>
+
+</chapter>
+
+<chapter id="terms">
+  <title>Terminology</title>
+
+  <anchor id="Coordinate System"/>
+  <sect1>
+    <title>Coordinate System</title>
+    <para>
+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.
+    </para>
+    <para>
+For example: (100,100) would be just below and to the right of the top left corner of the document.
+    </para>
+  </sect1>
+
+  <anchor id="Selections"/>
+  <sect1>
+    <title>Selections</title>
+    <para>
+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 <link linkend="document.selection_set">selection_set()</link>, <link linkend="document.selection_add">selection_add()</link>, and <link linkend="document.selection_box">selection_box()</link> and then call whatever selection function you need.
+    </para>
+  </sect1>
+
+  <anchor id="Groups"/>
+  <sect1>
+    <title>Groups</title>
+    <para>
+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.
+    </para>
+  </sect1>
+
+  <anchor id="Layers and Levels"/>
+  <sect1>
+    <title>Layers and Levels</title>
+    <para>
+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. <link linkend="document.layer_change_level">layer_change_level()</link> changes the order of layers and <link linkend="document.selection_change_level">selection_change_level()</link> changes the order of objects within a layer.
+    </para>
+    <para>
+Changing the level of a selection also deserves some explanation.  The <link linkend="document.selection_change_level">selection_change_level()</link> 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.  
+    </para>
+  </sect1>
+
+  <anchor id="Style Strings"/>
+  <sect1>
+    <title>Style Strings</title>
+    <para>
+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. 
+    </para>
+  </sect1>
+
+  <anchor id="Nodes and Paths"/>
+  <sect1>
+    <title>Nodes and Paths</title>
+    <para>
+To be written.
+    </para>
+  </sect1>
+
+</chapter>
+

diff --git a/src/extension/dbus/doc/spec-to-docbook.xsl b/src/extension/dbus/doc/spec-to-docbook.xsl
new file mode 100644 (file)
index 0000000..e200a05
--- /dev/null
+++ b/src/extension/dbus/doc/spec-to-docbook.xsl
@@ -0,0 +1,544 @@
+<?xml version='1.0'?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+  xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd"
+  exclude-result-prefixes="doc">
+<!--
+     Convert D-Bus Glib xml into DocBook refentries
+     Copyright (C) 2007 William Jon McCann
+     License: GPL
+-->
+<xsl:output method="xml" indent="yes" encoding="UTF-8"/>
+
+<xsl:template match="/">
+
+<xsl:variable name="interface" select="//interface/@name"/>
+<xsl:variable name="basename">
+  <xsl:call-template name="interface-basename">
+    <xsl:with-param name="str" select="$interface"/>
+  </xsl:call-template>
+</xsl:variable>
+
+<refentry><xsl:attribute name="id"><xsl:value-of select="$basename"/></xsl:attribute>
+  <refmeta>
+    <refentrytitle role="top_of_page"><xsl:value-of select="//interface/@name"/></refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname><xsl:value-of select="//interface/@name"/></refname>
+    <refpurpose><xsl:value-of select="$basename"/> interface</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv role="synopsis">
+    <title role="synopsis.title">Methods</title>
+    <synopsis>
+  <xsl:call-template name="methods-synopsis">
+    <xsl:with-param name="basename" select="$basename"/>
+  </xsl:call-template>
+    </synopsis>
+  </refsynopsisdiv>
+
+  <xsl:choose>
+    <xsl:when test="count(///signal) > 0">
+      <refsect1 role="signal_proto">
+        <title role="signal_proto.title">Signals</title>
+        <synopsis>
+          <xsl:call-template name="signals-synopsis">
+            <xsl:with-param name="basename" select="$basename"/>
+          </xsl:call-template>
+        </synopsis>
+      </refsect1>
+    </xsl:when>
+  </xsl:choose>
+
+  <refsect1 role="impl_interfaces">
+    <title role="impl_interfaces.title">Implemented Interfaces</title>
+    <para>
+    Objects implementing <xsl:value-of select="$interface"/> also implements
+    org.freedesktop.DBus.Introspectable,
+    org.freedesktop.DBus.Properties
+    </para>
+  </refsect1>
+
+  <xsl:choose>
+    <xsl:when test="count(///property) > 0">
+      <refsect1 role="properties">
+        <title role="properties.title">Properties</title>
+        <synopsis>
+          <xsl:call-template name="properties-synopsis">
+            <xsl:with-param name="basename" select="$basename"/>
+          </xsl:call-template>
+        </synopsis>
+      </refsect1>
+    </xsl:when>
+  </xsl:choose>
+
+  <refsect1 role="desc">
+    <title role="desc.title">Description</title>
+    <para>
+      <xsl:apply-templates select="//interface/doc:doc"/>
+    </para>
+  </refsect1>
+
+  <refsect1 role="details">
+    <title role="details.title">Details</title>
+    <xsl:call-template name="method-details">
+      <xsl:with-param name="basename" select="$basename"/>
+    </xsl:call-template>
+  </refsect1>
+
+  <xsl:choose>
+    <xsl:when test="count(///signal) > 0">
+      <refsect1 role="signals">
+        <title role="signals.title">Signal Details</title>
+        <xsl:call-template name="signal-details">
+          <xsl:with-param name="basename" select="$basename"/>
+        </xsl:call-template>
+      </refsect1>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:choose>
+    <xsl:when test="count(///property) > 0">
+      <refsect1 role="property_details">
+        <title role="property_details.title">Property Details</title>
+        <xsl:call-template name="property-details">
+          <xsl:with-param name="basename" select="$basename"/>
+        </xsl:call-template>
+      </refsect1>
+    </xsl:when>
+  </xsl:choose>
+
+</refentry>
+</xsl:template>
+
+
+<xsl:template name="property-doc">
+  <xsl:apply-templates select="doc:doc/doc:description"/>
+
+  <variablelist role="params">
+    <xsl:for-each select="arg">
+<varlistentry><term><parameter><xsl:value-of select="@name"/></parameter>:</term>
+<listitem><simpara><xsl:value-of select="doc:doc/doc:summary"/></simpara></listitem>
+</varlistentry>
+    </xsl:for-each>
+  </variablelist>
+
+  <xsl:apply-templates select="doc:doc/doc:since"/>
+  <xsl:apply-templates select="doc:doc/doc:deprecated"/>
+  <xsl:apply-templates select="doc:doc/doc:permission"/>
+  <xsl:apply-templates select="doc:doc/doc:seealso"/>
+</xsl:template>
+
+
+<xsl:template name="property-details">
+  <xsl:param name="basename"/>
+  <xsl:variable name="longest">
+    <xsl:call-template name="find-longest">
+      <xsl:with-param name="set" select="@name"/>
+    </xsl:call-template>
+  </xsl:variable>
+  <xsl:for-each select="///property">
+  <refsect2>
+    <title><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</title>
+<indexterm><primary><xsl:value-of select="@name"/></primary><secondary><xsl:value-of select="$basename"/></secondary></indexterm>
+<programlisting>'<xsl:value-of select="@name"/>'<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="2"/></xsl:call-template>
+<xsl:call-template name="property-args"><xsl:with-param name="indent" select="string-length(@name) + 2"/></xsl:call-template></programlisting>
+  </refsect2>
+
+  <xsl:call-template name="property-doc"/>
+
+  </xsl:for-each>
+</xsl:template>
+
+<xsl:template name="signal-doc">
+  <xsl:apply-templates select="doc:doc/doc:description"/>
+
+  <variablelist role="params">
+    <xsl:for-each select="arg">
+<varlistentry><term><parameter><xsl:value-of select="@name"/></parameter>:</term>
+<listitem><simpara><xsl:value-of select="doc:doc/doc:summary"/></simpara></listitem>
+</varlistentry>
+    </xsl:for-each>
+  </variablelist>
+
+  <xsl:apply-templates select="doc:doc/doc:since"/>
+  <xsl:apply-templates select="doc:doc/doc:deprecated"/>
+  <xsl:apply-templates select="doc:doc/doc:permission"/>
+  <xsl:apply-templates select="doc:doc/doc:seealso"/>
+</xsl:template>
+
+<xsl:template name="signal-details">
+  <xsl:param name="basename"/>
+  <xsl:variable name="longest">
+    <xsl:call-template name="find-longest">
+      <xsl:with-param name="set" select="@name"/>
+    </xsl:call-template>
+  </xsl:variable>
+  <xsl:for-each select="///signal">
+  <refsect2>
+    <title><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</title>
+<indexterm><primary><xsl:value-of select="@name"/></primary><secondary><xsl:value-of select="$basename"/></secondary></indexterm>
+<programlisting><xsl:value-of select="@name"/> (<xsl:call-template name="signal-args"><xsl:with-param name="indent" select="string-length(@name) + 2"/><xsl:with-param name="prefix" select="."/></xsl:call-template>)</programlisting>
+  </refsect2>
+
+  <xsl:call-template name="signal-doc"/>
+
+  </xsl:for-each>
+</xsl:template>
+
+<xsl:template match="doc:code">
+<programlisting>
+<xsl:apply-templates />
+</programlisting>
+</xsl:template>
+
+<xsl:template match="doc:tt">
+  <literal>
+    <xsl:apply-templates />
+  </literal>
+</xsl:template>
+
+<xsl:template match="doc:i">
+  <emphasis>
+    <xsl:apply-templates />
+  </emphasis>
+</xsl:template>
+
+<xsl:template match="doc:b">
+  <emphasis role="bold">
+    <xsl:apply-templates />
+  </emphasis>
+</xsl:template>
+
+<xsl:template match="doc:ulink">
+  <ulink>
+    <xsl:attribute name="url"><xsl:value-of select="@url"/></xsl:attribute>
+    <xsl:value-of select="."/>
+  </ulink>
+</xsl:template>
+
+<xsl:template match="doc:summary">
+  <xsl:apply-templates />
+</xsl:template>
+
+<xsl:template match="doc:example">
+<informalexample>
+<xsl:apply-templates />
+</informalexample>
+</xsl:template>
+
+<xsl:template name="listitems-do-term">
+  <xsl:param name="str"/>
+  <xsl:choose>
+    <xsl:when test="string-length($str) > 0">
+      <emphasis role="bold"><xsl:value-of select="$str"/>: </emphasis>
+    </xsl:when>
+  </xsl:choose>
+</xsl:template>
+
+<xsl:template name="do-listitems">
+  <xsl:for-each select="doc:item">
+    <listitem>
+      <xsl:call-template name="listitems-do-term"><xsl:with-param name="str" select="doc:term"/></xsl:call-template>
+      <xsl:apply-templates select="doc:definition"/>
+    </listitem>
+  </xsl:for-each>
+</xsl:template>
+
+<xsl:template match="doc:list">
+  <para>
+    <xsl:choose>
+      <xsl:when test="contains(@type,'number')">
+        <orderedlist>
+          <xsl:call-template name="do-listitems"/>
+        </orderedlist>
+      </xsl:when>
+      <xsl:otherwise>
+        <itemizedlist>
+          <xsl:call-template name="do-listitems"/>
+        </itemizedlist>
+      </xsl:otherwise>
+    </xsl:choose>
+  </para>
+</xsl:template>
+
+<xsl:template match="doc:para">
+<para>
+<xsl:apply-templates />
+</para>
+</xsl:template>
+
+<xsl:template match="doc:description">
+<xsl:apply-templates />
+</xsl:template>
+
+<xsl:template match="doc:since">
+<para role="since">Since <xsl:value-of select="@version"/>
+</para>
+</xsl:template>
+
+<xsl:template match="doc:deprecated">
+  <xsl:variable name="name" select="../../@name"/>
+  <xsl:variable name="parent">
+    <xsl:call-template name="interface-basename">
+      <xsl:with-param name="str" select="../../../@name"/>/>
+    </xsl:call-template>
+  </xsl:variable>
+
+  <xsl:variable name="type" select="name(../..)"/>
+
+  <para role="deprecated">
+  <warning><para><literal><xsl:value-of select="$name"/></literal> is deprecated since version <xsl:value-of select="@version"/> and should not be used in newly-written code. Use
+
+  <xsl:variable name="to">
+  <xsl:choose>
+    <xsl:when test="contains($type,'property')">
+      <xsl:value-of select="$parent"/>:<xsl:value-of select="@instead"/>
+    </xsl:when>
+    <xsl:when test="contains($type,'signal')">
+      <xsl:value-of select="$parent"/>::<xsl:value-of select="@instead"/>
+    </xsl:when>
+    <xsl:when test="contains($type,'method')">
+      <xsl:value-of select="$parent"/>.<xsl:value-of select="@instead"/>
+    </xsl:when>
+    <xsl:when test="contains($type,'interface')">
+      <xsl:value-of select="@instead"/>
+    </xsl:when>
+    <xsl:otherwise>
+      <xsl:value-of select="@instead"/>
+    </xsl:otherwise>
+  </xsl:choose>
+  </xsl:variable>
+
+  <xsl:call-template name="create-link">
+    <xsl:with-param name="type" select="$type"/>
+    <xsl:with-param name="to" select="$to"/>
+    <xsl:with-param name="val" select="@instead"/>
+  </xsl:call-template>
+instead.</para></warning>
+</para>
+</xsl:template>
+
+<xsl:template match="doc:permission">
+<para role="permission">
+<xsl:apply-templates />
+</para>
+</xsl:template>
+
+<xsl:template match="doc:errors">
+<para role="errors">
+<xsl:apply-templates />
+</para>
+</xsl:template>
+
+<xsl:template match="doc:seealso">
+<para>
+See also:
+<xsl:apply-templates />
+
+</para>
+</xsl:template>
+
+<xsl:template name="create-link">
+  <xsl:param name="type"/>
+  <xsl:param name="to"/>
+  <xsl:param name="val"/>
+
+  <xsl:choose>
+    <xsl:when test="contains($type,'property')">
+      <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><literal><xsl:value-of select="$val"/></literal></link>
+    </xsl:when>
+    <xsl:when test="contains($type,'signal')">
+      <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><literal><xsl:value-of select="$val"/></literal></link>
+    </xsl:when>
+    <xsl:when test="contains($type,'method')">
+      <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><function><xsl:value-of select="$val"/></function></link>
+    </xsl:when>
+    <xsl:when test="contains($type,'interface')">
+      <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><xsl:value-of select="$val"/></link>
+    </xsl:when>
+  </xsl:choose>
+</xsl:template>
+
+<xsl:template match="doc:ref">
+  <xsl:call-template name="create-link">
+    <xsl:with-param name="type" select="@type"/>
+    <xsl:with-param name="to" select="@to"/>
+    <xsl:with-param name="val" select="."/>
+  </xsl:call-template>
+</xsl:template>
+
+<xsl:template name="method-doc">
+  <xsl:apply-templates select="doc:doc/doc:description"/>
+
+  <variablelist role="params">
+    <xsl:for-each select="arg">
+<varlistentry><term><parameter><xsl:value-of select="@name"/></parameter>:</term>
+<listitem><simpara><xsl:apply-templates select="doc:doc/doc:summary"/></simpara></listitem>
+</varlistentry>
+    </xsl:for-each>
+  </variablelist>
+
+  <xsl:apply-templates select="doc:doc/doc:since"/>
+  <xsl:apply-templates select="doc:doc/doc:deprecated"/>
+
+  <xsl:choose>
+    <xsl:when test="count(doc:doc/doc:errors) > 0">
+      <refsect3>
+        <title>Errors</title>
+        <variablelist role="errors">
+          <xsl:for-each select="doc:doc/doc:errors/doc:error">
+            <varlistentry>
+              <term><parameter><xsl:value-of select="@name"/></parameter>:</term>
+              <listitem><simpara><xsl:apply-templates select="."/></simpara></listitem>
+            </varlistentry>
+          </xsl:for-each>
+        </variablelist>
+      </refsect3>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:choose>
+    <xsl:when test="count(doc:doc/doc:permission) > 0">
+      <refsect3>
+        <title>Permissions</title>
+        <xsl:apply-templates select="doc:doc/doc:permission"/>
+      </refsect3>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:apply-templates select="doc:doc/doc:seealso"/>
+</xsl:template>
+
+<xsl:template name="method-details">
+  <xsl:param name="basename"/>
+  <xsl:variable name="longest">
+    <xsl:call-template name="find-longest">
+      <xsl:with-param name="set" select="@name"/>
+    </xsl:call-template>
+  </xsl:variable>
+  <xsl:for-each select="///method">
+    <refsect2>
+    <title><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"/> ()</title>
+<indexterm><primary><xsl:value-of select="@name"/></primary><secondary><xsl:value-of select="$basename"/></secondary></indexterm>
+<programlisting><xsl:value-of select="@name"/> (<xsl:call-template name="method-args"><xsl:with-param name="indent" select="string-length(@name) + 2"/><xsl:with-param name="prefix" select="."/></xsl:call-template>)</programlisting>
+    </refsect2>
+
+    <xsl:call-template name="method-doc"/>
+
+  </xsl:for-each>
+</xsl:template>
+
+
+<xsl:template name="properties-synopsis">
+  <xsl:param name="basename"/>
+  <xsl:variable name="longest">
+    <xsl:call-template name="find-longest">
+      <xsl:with-param name="set" select="///property/@name"/>
+    </xsl:call-template>
+  </xsl:variable>
+  <xsl:for-each select="///property">
+<link><xsl:attribute name="linkend"><xsl:value-of select="$basename"/>:<xsl:value-of select="@name"/></xsl:attribute>'<xsl:value-of select="@name"/>'</link><xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$longest - string-length(@name) + 1"/></xsl:call-template> <xsl:call-template name="property-args"><xsl:with-param name="indent" select="$longest + 2"/></xsl:call-template>
+</xsl:for-each>
+</xsl:template>
+
+
+<xsl:template name="signals-synopsis">
+  <xsl:param name="basename"/>
+  <xsl:variable name="longest">
+    <xsl:call-template name="find-longest">
+      <xsl:with-param name="set" select="///signal/@name"/>
+    </xsl:call-template>
+  </xsl:variable>
+  <xsl:for-each select="///signal">
+<link><xsl:attribute name="linkend"><xsl:value-of select="$basename"/>::<xsl:value-of select="@name"/></xsl:attribute><xsl:value-of select="@name"/></link><xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$longest - string-length(@name) + 1"/></xsl:call-template>(<xsl:call-template name="signal-args"><xsl:with-param name="indent" select="$longest + 2"/><xsl:with-param name="prefix" select="///signal"/></xsl:call-template>)
+</xsl:for-each>
+</xsl:template>
+
+
+<xsl:template name="methods-synopsis">
+  <xsl:param name="basename"/>
+  <xsl:variable name="longest">
+    <xsl:call-template name="find-longest">
+      <xsl:with-param name="set" select="///method/@name"/>
+    </xsl:call-template>
+  </xsl:variable>
+  <xsl:for-each select="///method">
+<link><xsl:attribute name="linkend"><xsl:value-of select="$basename"/>.<xsl:value-of select="@name"/></xsl:attribute><xsl:value-of select="@name"/></link><xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$longest - string-length(@name) + 1"/></xsl:call-template>(<xsl:call-template name="method-args"><xsl:with-param name="indent" select="$longest + 2"/><xsl:with-param name="prefix" select="///method"/></xsl:call-template>)
+</xsl:for-each>
+</xsl:template>
+
+
+<xsl:template name="method-args"><xsl:param name="indent"/><xsl:param name="prefix"/><xsl:variable name="longest"><xsl:call-template name="find-longest"><xsl:with-param name="set" select="$prefix/arg/@type"/></xsl:call-template></xsl:variable><xsl:for-each select="arg"><xsl:value-of select="@direction"/>
+<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="4 - string-length(@direction)"/></xsl:call-template>'<xsl:value-of select="@type"/>'<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$longest - string-length(@type) + 1"/></xsl:call-template>
+<xsl:value-of select="@name"/><xsl:if test="not(position() = last())">,
+<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$indent"/></xsl:call-template></xsl:if>
+</xsl:for-each>
+</xsl:template>
+
+
+<xsl:template name="signal-args"><xsl:param name="indent"/><xsl:param name="prefix"/><xsl:variable name="longest"><xsl:call-template name="find-longest"><xsl:with-param name="set" select="$prefix/arg/@type"/></xsl:call-template></xsl:variable><xsl:for-each select="arg">'<xsl:value-of select="@type"/>'<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$longest - string-length(@type) + 1"/></xsl:call-template>
+<xsl:value-of select="@name"/><xsl:if test="not(position() = last())">,
+<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$indent"/></xsl:call-template></xsl:if>
+</xsl:for-each>
+</xsl:template>
+
+
+<xsl:template name="property-args"><xsl:param name="indent"/>
+<xsl:value-of select="@access"/><xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="9 - string-length(@access) + 1"/></xsl:call-template>'<xsl:value-of select="@type"/>'
+</xsl:template>
+
+
+<xsl:template name="pad-spaces">
+  <xsl:param name="width"/>
+  <xsl:variable name="spaces" xml:space="preserve">                                                                        </xsl:variable>
+  <xsl:value-of select="substring($spaces,1,$width)"/>
+</xsl:template>
+
+
+<xsl:template name="find-longest">
+  <xsl:param name="set"/>
+  <xsl:param name="index" select="1"/>
+  <xsl:param name="longest" select="0"/>
+
+  <xsl:choose>
+    <xsl:when test="$index > count($set)">
+      <!--finished looking-->
+      <xsl:value-of select="$longest"/>
+    </xsl:when>
+    <xsl:when test="string-length($set[$index])>$longest">
+      <!--found new longest-->
+      <xsl:call-template name="find-longest">
+        <xsl:with-param name="set" select="$set"/>
+        <xsl:with-param name="index" select="$index + 1"/>
+        <xsl:with-param name="longest" select="string-length($set[$index])"/>
+      </xsl:call-template>
+    </xsl:when>
+    <xsl:otherwise>
+      <!--this isn't any longer-->
+      <xsl:call-template name="find-longest">
+        <xsl:with-param name="set" select="$set"/>
+        <xsl:with-param name="index" select="$index + 1"/>
+        <xsl:with-param name="longest" select="$longest"/>
+      </xsl:call-template>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
+
+<xsl:template name="interface-basename">
+  <xsl:param name="str"/>
+  <xsl:choose>
+    <xsl:when test="contains($str,'.')">
+      <xsl:call-template name="interface-basename">
+       <xsl:with-param name="str" select="substring-after($str,'.')"/>
+      </xsl:call-template>
+    </xsl:when>
+    <xsl:otherwise>
+      <xsl:value-of select="$str"/>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
+</xsl:stylesheet>
+