Initial Commit of dbus-docHEADmaster

Creates seperate D-Bus intropsection documentation project from Jon McCann's documentation tools in ConsoleKit. README and TODO are from his posts to the D-Bus mailing list.

20 files changed, 1506 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..b7650fe
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,16 @@
+Makefile
+Makefile.in
+aclocal.m4
+autom4te.cache
+config.cache
+config.guess
+config.log
+config.status
+config.sub
+configure
+install-sh
+libtool
+ltmain.sh
+missing
+tools/spec-strip-docs
+tools/spec-to-docbook
diff --git a/AUTHORS b/AUTHORS
new file mode 100644
index 0000000..a2813a9
--- /dev/null
+++ b/AUTHORS
@@ -0,0 +1,2 @@
+William Jon McCann <mccann@jhu.edu>
+Rob Taylor <rob.taylor@codethink.co.uk>
diff --git a/COPYING b/COPYING
new file mode 120000
index 0000000..7153769
--- /dev/null
+++ b/COPYING
@@ -0,0 +1 @@
+/usr/share/automake-1.9/COPYING
\ No newline at end of file
diff --git a/INSTALL b/INSTALL
new file mode 120000
index 0000000..81fa6ff
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1 @@
+/usr/share/automake-1.9/INSTALL
\ No newline at end of file
diff --git a/Makefile.am b/Makefile.am
new file mode 100644
index 0000000..87d6075
--- /dev/null
+++ b/Makefile.am
@@ -0,0 +1,30 @@
+SUBDIRS = tools examples
+
+EXTRA_DIST = \
+    config.xsl \
+    dbus-introspect-docs.dtd \
+    docbook.css
+
+# Creating ChangeLog from git log:
+
+MAINTAINERCLEANFILES = ChangeLog
+
+EXTRA_DIST += ChangeLog
+
+ChangeLog: $(srcdir)/ChangeLog
+$(srcdir)/ChangeLog: FORCE
+	@if test -d "$(srcdir)/.git"; then \
+	  (cd "$(srcdir)" && \
+	  ./missing --run git-log --stat) | fmt --split-only > $@.tmp \
+	  && mv -f $@.tmp $@ \
+	  || ($(RM) $@.tmp; \
+	      echo Failed to generate ChangeLog, your ChangeLog may be outdated >&2; \
+	      (test -f $@ || echo git-log is required to generate this file >> $@)); \
+	else \
+	  test -f $@ || \
+	  (echo A git checkout and git-log is required to generate ChangeLog >&2 && \
+	  echo A git checkout and git-log is required to generate this file >> $@); \
+	fi
+
+FORCE:
+
diff --git a/NEWS b/NEWS
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/NEWS
diff --git a/README b/README
new file mode 100644
index 0000000..d30390a
--- /dev/null
+++ b/README
@@ -0,0 +1,148 @@
+Problem
+=======
+
+The initial goal was simply to create a docbook reference for each
+interface - because it is standard and it is easy to convert into just
+about anything else.  After having hand coded docbook for few projects
+and finding that difficult to maintain, I looked at some alternatives.
+
+It was a specific non-goal to any docbook markup directly.
+
+Relevant Art
+==========
+
+[many probably already know this already, but for completeness]
+
+1. gtk-doc
+
+I particularly like the output and ease of use of gtk-doc.  It is
+pretty powerful because it uses a simple semantic markup and is
+contextual.  The contextual part is interesting to me for a few
+reasons:
+a) you can use the structure of project instead of duplicating the
+structure in another format
+ b) related to a. - you may be able to pull from the context content
+implicitly instead of documenting it explicitly (ie. determine the
+class name when documenting a method)
+c) documentation is in proximity to the code that it describes which
+makes it easier to maintain and view
+
+For example, with C code gtk-doc scans for things like:
+/**
+* g_markup_parse_context_new:
+ * @parser: a #GMarkupParser
+ * @flags: one or more #GMarkupParseFlags
+ * @user_data: user data to pass to #GMarkupParser functions
+* @user_data_dnotify: user data destroy notifier called when the
+parse context is freed
+*
+* Creates a new parse context. A parse context is used to parse
+* marked-up documents. You can feed any number of documents into
+* a context, as long as no errors occur; once an error occurs,
+* the parse context can't continue to parse text (you have to free it
+* and create a new parse context).
+*
+ * Return value: a new #GMarkupParseContext
+**/
+
+As you can see this uses an efficient markup that is described here:
+http://svn.gnome.org/viewcvs/gtk-doc/trunk/doc/gnome.txt?revision=349&view=markup
+
+2. C# documentation
+
+Apparently, C# has a convention for adding contextual documentation
+too.  It is described here:
+http://msdn.microsoft.com/msdnmag/issues/02/06/XMLC/
+and
+http://msdn.microsoft.com/library/default.asp?url=/library/en-us/csref/html/vclrfTagsForDocumentationComments.asp
+
+It is similar to gtk-doc in that it is contextual and is usually
+contained in source code.  However, instead of brewing its own kind of
+markup it uses XML.
+
+3. Java Doc
+
+Quite similar to gtk-doc (or perhaps I have that reversed)
+http://en.wikipedia.org/wiki/Javadoc
+
+4. Telepathy spec
+
+It extends the D-Bus introspection format to include documentation.
+It does this by adding a <tp:docstring> element that may contain
+XHTML.  It too is contextual since the docstring may be added as a
+child of any element.  There are also tags defined for providing
+copyright, etc
+
+http://telepathy.freedesktop.org/wiki/DbusSpec
+
+
+Review
+======
+
+I didn't know about the Telepathy docs initially - so it wasn't in the mix.
+
+I valued:
+ * the capabilities of the gtk-doc and javadoc systems
+ * the high semantic value of the gtk-doc, javadoc, and C# doc systems
+* the ability to extend/enrich the C# docs
+ * the ability to use XSLT etc to easily translate the C# docs
+* the language/location independence of the C# docs (can be used in
+source code or separately)
+
+I didn't like:
+ * gtk-doc and javadoc relied on a custom markup
+ * that gtk-doc and javadoc aren't useful outside of source code
+* that the XML tags used by C# docs were pretty specific to the language
+ * that with gtk-doc and javadoc you must duplicate some information that
+  can be found using the context (ie. function names etc)
+
+And I prototyped few different things.
+
+Results
+======
+
+So, there are really two separate but highly related problems.  One is
+defining a markup specification and the other is determining the
+integration point.
+
+This presumes that the two can be separated and so this became a
+design goal.  D-Bus different in this respect - all the other
+contextual documentation is to some degree language specific.
+
+- Markup
+
+The C# docs use a clearly superior markup.  However, it is somewhat C#
+language specific.  So, I tried to define a new set of elements that
+would closely match the capabilities of the various systems.
+
+In the process of actually producing docbook with it I came up with this:
+http://gitweb.freedesktop.org/?p=ConsoleKit.git;a=blob;hb=HEAD;f=doc/dbus-introspect-docs.dtd
+
+You may notice that there is one detail that makes it not orthogonal to...
+
+- Integration point
+
+The markup assumes that the integration point is capable of somehow
+providing context.
+
+I took it as a given that D-Bus already has a well defined (and
+deployed) structural markup in the Introspect format.  And that this
+is in principle the common factor between all implementations and
+bindings.
+
+So, this seems to be the most likely point for documentation
+integration.  Even if it is a trade-off because it is more separated
+from the code at least it is integrated with the "interface".  And at
+the end of the day, that may be more important and useful.
+
+That said, the C# docs show that this doesn't preclude one from using
+this same markup in source code.  And so it should still be possible
+to autogenerate from inline comments.  The only difficulty would be
+figuring out how to provide the <arg> context.
+
+In the end I came to a conclusion that was similar to the Telepathy
+spec but differed slightly due to the goal.  I wanted to create a
+docbook and thus needed to retain more semantic information.  So, I
+didn't use xhtml directly but defined a new DTD.
+
+ -- Jon McCann <mccann@jhu.edu>
diff --git a/TODO b/TODO
new file mode 100644
index 0000000..64e465f
--- /dev/null
+++ b/TODO
@@ -0,0 +1,13 @@
+* Translation - should be possible by having a lang="" attribute on
+the <doc> element but I'm not sure this is desirable.  Perhaps using
+some kind of ...
+
+* Include mechanism - toyed with the idea of using an include
+mechanism to pull in the docs from an external file.
+
+* Does this make sense for D-Bus - maybe?  Wasn't a specific goal but
+might be useful.
+
+* Can we turn this into a mechanism for getting documentation on
+services automatically:
+  % dbus-man Hal.Manager 
diff --git a/autogen.sh b/autogen.sh
new file mode 100755
index 0000000..63a59fb
--- /dev/null
+++ b/autogen.sh
@@ -0,0 +1,170 @@
+#!/bin/sh
+# Run this to generate all the initial makefiles, etc.
+set -e
+
+PACKAGE=dbus-doc
+
+LIBTOOLIZE=${LIBTOOLIZE-libtoolize}
+LIBTOOLIZE_FLAGS="--copy --force"
+AUTOMAKE_FLAGS="--add-missing --gnu"
+AUTOCONF=${AUTOCONF-autoconf}
+
+automake_min_vers=1.9
+aclocal_min_vers=$automake_min_vers
+autoconf_min_vers=2.59
+libtoolize_min_vers=1.4
+
+# The awk-based string->number conversion we use needs a C locale to work 
+# as expected. Setting LC_ALL overrides whether the user set LC_ALL,
+# LC_NUMERIC, or LANG.
+LC_ALL=C
+
+ARGV0=$0
+
+# Allow invocation from a separate build directory; in that case, we change
+# to the source directory to run the auto*, then change back before running configure
+srcdir=`dirname $ARGV0`
+test -z "$srcdir" && srcdir=.
+
+ORIGDIR=`pwd`
+
+cd $srcdir
+
+if ($AUTOCONF --version) < /dev/null > /dev/null 2>&1 ; then
+    if ($AUTOCONF --version | head -n 1 | awk 'NR==1 { if( $(NF) >= '$autoconf_min_vers') \
+			       exit 1; exit 0; }');
+    then
+       echo "$ARGV0: ERROR: \`$AUTOCONF' is too old."
+       $AUTOCONF --version
+       echo "           (version $autoconf_min_vers or newer is required)"
+       DIE="yes"
+    fi
+else
+    echo $AUTOCONF: command not found
+    echo
+    echo "$ARGV0: ERROR: You must have \`autoconf' installed to compile $PACKAGE."
+    echo "           (version $autoconf_min_vers or newer is required)"
+    DIE="yes"
+fi
+
+#
+# Hunt for an appropriate version of automake and aclocal; we can't
+# assume that 'automake' is necessarily the most recent installed version
+#
+# We check automake first to allow it to be a newer version than we know about.
+#
+if test x"$AUTOMAKE" = x || test x"$ACLOCAL" = x ; then
+  am_ver=""
+  for ver in "" "-1.9" "-1.8" "-1.7" ; do
+    am="automake$ver"
+    if ($am --version) < /dev/null > /dev/null 2>&1 ; then
+      if ($am --version | head -n 1 | awk 'NR==1 { if( $(NF) >= '$automake_min_vers') \
+	  		 exit 1; exit 0; }'); then : ; else
+         am_ver=$ver
+         break;
+      fi
+    fi
+  done
+
+  AUTOMAKE=${AUTOMAKE-automake$am_ver}
+  ACLOCAL=${ACLOCAL-aclocal$am_ver}
+fi
+
+#
+# Now repeat the tests with the copies we decided upon and error out if they
+# aren't sufficiently new.
+#
+if ($AUTOMAKE --version) < /dev/null > /dev/null 2>&1 ; then
+  if ($AUTOMAKE --version | head -n 1 | awk 'NR==1 { if( $(NF) >= '$automake_min_vers') \
+			     exit 1; exit 0; }');
+     then
+     echo "$ARGV0: ERROR: \`$AUTOMAKE' is too old."
+     $AUTOMAKE --version
+     echo "           (version $automake_min_vers or newer is required)"
+     DIE="yes"
+  fi
+  if ($ACLOCAL --version) < /dev/null > /dev/null 2>&1; then
+    if ($ACLOCAL --version | head -n 1 | awk 'NR==1 { if( $(NF) >= '$aclocal_min_vers' ) \
+						exit 1; exit 0; }' );
+    then
+      echo "$ARGV0: ERROR: \`$ACLOCAL' is too old."
+      $ACLOCAL --version
+      echo "           (version $aclocal_min_vers or newer is required)"
+      DIE="yes"
+    fi
+  else
+    echo $ACLOCAL: command not found
+    echo
+    echo "$ARGV0: ERROR: Missing \`$ACLOCAL'"
+    echo "           The version of $AUTOMAKE installed doesn't appear recent enough."
+    DIE="yes"
+  fi
+else
+    echo $AUTOMAKE: command not found
+    echo
+    echo "$ARGV0: ERROR: You must have \`automake' installed to compile $PACKAGE."
+    echo "           (version $automake_min_vers or newer is required)"
+    DIE="yes"
+fi
+
+if ($LIBTOOLIZE --version) < /dev/null > /dev/null 2>&1 ; then
+    if ($LIBTOOLIZE --version | awk 'NR==1 { if( $4 >= '$libtoolize_min_vers') \
+			       exit 1; exit 0; }');
+    then
+       echo "$ARGV0: ERROR: \`$LIBTOOLIZE' is too old."
+       echo "           (version $libtoolize_min_vers or newer is required)"
+       DIE="yes"
+    fi
+else
+    echo $LIBTOOLIZE: command not found
+    echo
+    echo "$ARGV0: ERROR: You must have \`libtoolize' installed to compile $PACKAGE."
+    echo "           (version $libtoolize_min_vers or newer is required)"
+    DIE="yes"
+fi
+
+if test -z "$ACLOCAL_FLAGS"; then
+    acdir=`$ACLOCAL --print-ac-dir`
+    if [ ! -f $acdir/pkg.m4 ]; then
+	echo "$ARGV0: Error: Could not find pkg-config macros."
+	echo "        (Looked in $acdir/pkg.m4)"
+	echo "        If pkg.m4 is available in /another/directory, please set"
+	echo "        ACLOCAL_FLAGS=\"-I /another/directory\""
+	echo "        Otherwise, please install pkg-config."
+	echo ""
+	echo "pkg-config is available from:"
+	echo "http://www.freedesktop.org/software/pkgconfig/"
+	DIE=yes
+    fi
+fi
+
+if test "X$DIE" != X; then
+  exit 1
+fi
+
+
+if test -z "$*"; then
+  echo "$ARGV0:	Note: \`./configure' will be run with no arguments."
+  echo "		If you wish to pass any to it, please specify them on the"
+  echo "		\`$0' command line."
+  echo
+fi
+
+do_cmd() {
+    echo "$ARGV0: running \`$@'"
+    $@
+}
+
+do_cmd $LIBTOOLIZE $LIBTOOLIZE_FLAGS
+
+do_cmd $ACLOCAL $ACLOCAL_FLAGS
+
+do_cmd $AUTOMAKE $AUTOMAKE_FLAGS
+
+do_cmd $AUTOCONF
+
+cd $ORIGDIR || exit 1
+
+rm -f config.cache
+
+do_cmd $srcdir/configure --cache-file=config.cache --disable-static --enable-maintainer-mode --enable-gtk-doc ${1+"$@"} && echo "Now type \`make' to compile" || exit 1
diff --git a/config.xsl b/config.xsl
new file mode 100644
index 0000000..7aa9def
--- /dev/null
+++ b/config.xsl
@@ -0,0 +1,6 @@
+<?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/configure.ac b/configure.ac
new file mode 100644
index 0000000..0f9836c
--- /dev/null
+++ b/configure.ac
@@ -0,0 +1,29 @@
+dnl -*- mode: m4 -*-
+
+AC_INIT([dbus-doc],
+        [0.0.1],
+        [rob.taylor@codethink.co.uk])
+
+AM_INIT_AUTOMAKE([1.9])
+
+AM_MAINTAINER_MODE
+
+AC_ISC_POSIX
+AC_PROG_CC
+AC_STDC_HEADERS
+AC_PROG_LIBTOOL
+
+AC_HEADER_STDC
+
+AC_SUBST(VERSION)
+
+# Save flags to aclocal
+ACLOCAL="$ACLOCAL $ACLOCAL_FLAGS"
+
+# Dependencies
+
+AC_OUTPUT([
+Makefile
+tools/Makefile
+examples/Makefile
+])
diff --git a/dbus-introspect-docs.dtd b/dbus-introspect-docs.dtd
new file mode 100644
index 0000000..5fe508e
--- /dev/null
+++ b/dbus-introspect-docs.dtd
@@ -0,0 +1,32 @@
+<!-- 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 (listheader?, item*)>
+<!ATTLIST list type (bullet|number|table) #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/docbook.css b/docbook.css
new file mode 100644
index 0000000..6a7373e
--- /dev/null
+++ b/docbook.css
@@ -0,0 +1,78 @@
+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/examples/Makefile.am b/examples/Makefile.am
new file mode 100644
index 0000000..e000f3b
--- /dev/null
+++ b/examples/Makefile.am
@@ -0,0 +1,3 @@
+examplesdir = $(docdir)/dbus-doc
+
+examples_DATA = ck-session.xml
diff --git a/examples/ck-session.xml b/examples/ck-session.xml
new file mode 100644
index 0000000..f531ead
--- /dev/null
+++ b/examples/ck-session.xml
@@ -0,0 +1,422 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<node xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
+
+  <interface name="org.freedesktop.ConsoleKit.Session">
+    <doc:doc>
+      <doc:description>
+        <doc:para>Session objects represent and store information
+        related to a user session.
+        </doc:para>
+        <doc:para>The properties associated with the Session
+        specifically refer to the properties of the "session leader".
+        </doc:para>
+      </doc:description>
+    </doc:doc>
+    <method name="GetId">
+      <arg name="ssid" direction="out" type="o">
+        <doc:doc>
+          <doc:summary>Session ID</doc:summary>
+        </doc:doc>
+      </arg>
+      <doc:doc>
+        <doc:description><doc:para>Returns the ID for Session.</doc:para>
+        </doc:description>
+      </doc:doc>
+    </method>
+    <method name="GetSeatId">
+      <arg name="sid" direction="out" type="o">
+        <doc:doc>
+          <doc:summary>Seat ID</doc:summary>
+        </doc:doc>
+      </arg>
+      <doc:doc>
+        <doc:description><doc:para>Returns the ID for the Seat the Session is
+        attached to.</doc:para>
+        </doc:description>
+        <doc:seealso><doc:ref type="interface" to="Seat">org.freedesktop.ConsoleKit.Seat</doc:ref></doc:seealso>
+      </doc:doc>
+    </method>
+    <method name="GetSessionType">
+      <arg name="type" direction="out" type="s">
+        <doc:doc>
+          <doc:summary>Session type</doc:summary>
+        </doc:doc>
+      </arg>
+      <doc:doc>
+        <doc:description>
+          <doc:para>Returns the type of the session.</doc:para>
+          <doc:para>Warning: we haven't yet defined the allowed values for this property.
+          It is probably best to avoid this until we do.
+          </doc:para>
+        </doc:description>
+        <doc:seealso><doc:ref type="property" to="Session:session-type">session-type</doc:ref></doc:seealso>
+      </doc:doc>
+    </method>
+    <method name="GetUser">
+      <arg name="uid" direction="out" type="i">
+        <doc:doc>
+          <doc:summary>User ID</doc:summary>
+        </doc:doc>
+      </arg>
+      <doc:doc>
+        <doc:description><doc:para>Returns the user that the session belongs to.</doc:para>
+        </doc:description>
+        <doc:deprecated version="0.1.3" instead="GetUnixUser"/>
+        <doc:seealso><doc:ref type="property" to="Session:user">user</doc:ref></doc:seealso>
+      </doc:doc>
+    </method>
+    <method name="GetUnixUser">
+      <arg name="uid" direction="out" type="i">
+        <doc:doc>
+          <doc:summary>POSIX User ID</doc:summary>
+        </doc:doc>
+      </arg>
+      <doc:doc>
+        <doc:description><doc:para>Returns the POSIX user ID that the session belongs to.</doc:para>
+        </doc:description>
+        <doc:seealso><doc:ref type="property" to="Session:unix-user">unix-user</doc:ref></doc:seealso>
+      </doc:doc>
+    </method>
+    <method name="GetX11Display">
+      <arg name="display" direction="out" type="s">
+        <doc:doc>
+          <doc:summary>The value of the X11 display</doc:summary>
+        </doc:doc>
+      </arg>
+      <doc:doc>
+        <doc:description><doc:para>Returns the value of the X11 DISPLAY for this session
+        if one is present.</doc:para>
+        </doc:description>
+        <doc:seealso><doc:ref type="property" to="Session:x11-display">x11-display</doc:ref></doc:seealso>
+      </doc:doc>
+    </method>
+    <method name="GetX11DisplayDevice">
+       <arg name="x11_display_device" direction="out" type="s">
+        <doc:doc>
+          <doc:summary>The value of the X11 display device</doc:summary>
+        </doc:doc>
+      </arg>
+      <doc:doc>
+        <doc:description><doc:para>Returns the value of the display device (aka TTY) that the
+        X11 display for the session is connected to.  If there is no x11-display set then this value
+        is undefined.</doc:para>
+        </doc:description>
+        <doc:seealso><doc:ref type="property" to="Session:x11-display-device">x11-display-device</doc:ref></doc:seealso>
+      </doc:doc>
+    </method>
+    <method name="GetDisplayDevice">
+      <arg name="display_device" direction="out" type="s">
+        <doc:doc>
+          <doc:summary>The value of the display device</doc:summary>
+        </doc:doc>
+      </arg>
+      <doc:doc>
+        <doc:description><doc:para>Returns the value of the display device (aka TTY) that the
+        session is connected to.</doc:para>
+        </doc:description>
+        <doc:seealso><doc:ref type="property" to="Session:display-device">display-device</doc:ref></doc:seealso>
+      </doc:doc>
+    </method>
+    <method name="GetRemoteHostName">
+      <arg name="remote_host_name" direction="out" type="s">
+        <doc:doc>
+          <doc:summary>The remote host name</doc:summary>
+        </doc:doc>
+      </arg>
+      <doc:doc>
+        <doc:description><doc:para>Returns the value of the remote host name for the session.
+        </doc:para>
+        </doc:description>
+        <doc:seealso><doc:ref type="property" to="Session:remote-host-name">remote-host-name</doc:ref></doc:seealso>
+      </doc:doc>
+    </method>
+    <method name="IsActive">
+      <arg name="active" direction="out" type="b">
+        <doc:doc>
+          <doc:summary>TRUE if the session is active, otherwise FALSE</doc:summary>
+        </doc:doc>
+      </arg>
+      <doc:doc>
+        <doc:description><doc:para>Returns whether the session is active on the Seat that
+        it is attached to.</doc:para>
+        <doc:para>If the session is not attached to a seat this value is undefined.
+        </doc:para>
+        </doc:description>
+        <doc:seealso><doc:ref type="property" to="Session:active">active</doc:ref></doc:seealso>
+      </doc:doc>
+    </method>
+    <method name="IsLocal">
+      <arg name="local" direction="out" type="b">
+        <doc:doc>
+          <doc:summary>TRUE if the session is local, otherwise FALSE</doc:summary>
+        </doc:doc>
+      </arg>
+      <doc:doc>
+        <doc:description><doc:para>Returns whether the session is local</doc:para>
+        <doc:para>FIXME: we need to come up with a concrete definition for this value.
+        It was originally used as a way to identify XDMCP sessions that originate
+        from a remote system.
+        </doc:para>
+        </doc:description>
+        <doc:seealso><doc:ref type="property" to="Session:is-local">is-local</doc:ref></doc:seealso>
+      </doc:doc>
+    </method>
+    <method name="GetCreationTime">
+      <arg name="iso8601_datetime" type="s" direction="out">
+        <doc:doc>
+          <doc:summary>An ISO 8601 format date-type string</doc:summary>
+        </doc:doc>
+      </arg>
+      <doc:doc>
+        <doc:description>
+          <doc:para>Returns an ISO 8601 date-time string that corresponds to
+          the time that the session was opened.
+          </doc:para>
+        </doc:description>
+      </doc:doc>
+    </method>
+
+    <method name="Activate">
+      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
+      <doc:doc>
+        <doc:description>
+          <doc:para>Attempt to activate the this session.  In most
+          cases, if successful, this will cause the session to
+          become visible and become active on the seat that it
+          is attached to.</doc:para>
+        </doc:description>
+        <doc:seealso><doc:ref type="method" to="Seat.ActivateSession">Seat.ActivateSession()</doc:ref></doc:seealso>
+      </doc:doc>
+    </method>
+    <method name="Lock">
+      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
+      <doc:doc>
+        <doc:description>
+          <doc:para>This will cause a <doc:ref type="signal" to="Session::Lock">Lock</doc:ref>
+          signal to be emitted for this session.
+          </doc:para>
+        </doc:description>
+        <doc:permission>This method is restricted to privileged users by D-Bus policy.</doc:permission>
+        <doc:seealso><doc:ref type="signal" to="Session::Lock">Lock signal</doc:ref></doc:seealso>
+      </doc:doc>
+    </method>
+    <method name="Unlock">
+      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
+      <doc:doc>
+        <doc:description>
+          <doc:para>This will cause an <doc:ref type="signal" to="Session::Unlock">Unlock</doc:ref>
+          signal to be emitted for this session.
+          </doc:para>
+          <doc:para>This can be used by login managers to unlock a session before it is
+          re-activated during fast-user-switching.
+          </doc:para>
+        </doc:description>
+        <doc:permission>This method is restricted to privileged users by D-Bus policy.</doc:permission>
+        <doc:seealso><doc:ref type="signal" to="Session::Unlock">Unlock signal</doc:ref></doc:seealso>
+      </doc:doc>
+    </method>
+
+    <method name="GetIdleHint">
+      <arg name="idle_hint" type="b" direction="out">
+        <doc:doc>
+          <doc:summary>The value of the idle-hint</doc:summary>
+        </doc:doc>
+      </arg>
+      <doc:doc>
+        <doc:description>
+          <doc:para>Gets the value of the <doc:ref type="property" to="Session:idle-hint">idle-hint</doc:ref>
+          property.
+          </doc:para>
+        </doc:description>
+        <doc:seealso><doc:ref type="property" to="Session:idle-hint">idle-hint</doc:ref></doc:seealso>
+      </doc:doc>
+    </method>
+    <method name="GetIdleSinceHint">
+      <arg name="iso8601_datetime" type="s" direction="out">
+        <doc:doc>
+          <doc:summary>An ISO 8601 format date-type string</doc:summary>
+        </doc:doc>
+      </arg>
+      <doc:doc>
+        <doc:description>
+          <doc:para>Returns an ISO 8601 date-time string that corresponds to
+          the time of the last change of the idle-hint.
+          </doc:para>
+        </doc:description>
+      </doc:doc>
+    </method>
+    <method name="SetIdleHint">
+      <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
+      <arg name="idle_hint" type="b" direction="in">
+        <doc:doc>
+          <doc:summary>boolean value to set the idle-hint to</doc:summary>
+        </doc:doc>
+      </arg>
+      <doc:doc>
+        <doc:description>
+          <doc:para>This may be used by the session to indicate that
+          it is idle.
+          </doc:para>
+          <doc:para>Use of this method is restricted to the user
+          that owns the session.</doc:para>
+        </doc:description>
+      </doc:doc>
+    </method>
+
+    <signal name="ActiveChanged">
+      <arg name="is_active" type="b">
+        <doc:doc>
+          <doc:summary>TRUE if the session is active, otherwise FALSE</doc:summary>
+        </doc:doc>
+      </arg>
+      <doc:doc>
+        <doc:description>
+          <doc:para>Emitted when the active property has changed.</doc:para>
+        </doc:description>
+      </doc:doc>
+    </signal>
+    <signal name="IdleHintChanged">
+      <arg name="hint" type="b">
+        <doc:doc>
+          <doc:summary>the new value of idle-hint</doc:summary>
+        </doc:doc>
+      </arg>
+      <doc:doc>
+        <doc:description>
+          <doc:para>Emitted when the idle-hint property has changed.</doc:para>
+        </doc:description>
+      </doc:doc>
+    </signal>
+    <signal name="Lock">
+      <doc:doc>
+        <doc:description>
+          <doc:para>Emitted in response to a call to the <doc:ref type="method" to="Session.Lock">Lock()</doc:ref> method.</doc:para>
+          <doc:para>It is intended that the screensaver for the session should lock the screen in response to this signal.</doc:para>
+        </doc:description>
+      </doc:doc>
+    </signal>
+    <signal name="Unlock">
+      <doc:doc>
+        <doc:description>
+          <doc:para>Emitted in response to a call to the <doc:ref type="method" to="Session.Unlock">Unlock()</doc:ref> method.</doc:para>
+          <doc:para>It is intended that the screensaver for the session should unlock the screen in response to this signal.</doc:para>
+        </doc:description>
+      </doc:doc>
+    </signal>
+
+    <property name="unix-user" type="u" access="readwrite">
+      <doc:doc>
+        <doc:description>
+          <doc:para>The user assigned to the session.</doc:para>
+        </doc:description>
+      </doc:doc>
+    </property>
+    <property name="user" type="u" access="readwrite">
+      <doc:doc>
+        <doc:description>
+          <doc:para>The user assigned to the session.</doc:para>
+        </doc:description>
+        <doc:deprecated version="0.1.3" instead="unix-user"/>
+      </doc:doc>
+    </property>
+    <property name="session-type" type="s" access="readwrite">
+      <doc:doc>
+        <doc:description>
+          <doc:para>The type of the session.</doc:para>
+          <doc:para>Warning: we haven't yet defined the allowed values for this property.
+          It is probably best to avoid this until we do.
+          </doc:para>
+        </doc:description>
+      </doc:doc>
+    </property>
+    <property name="remote-host-name" type="s" access="readwrite">
+      <doc:doc>
+        <doc:description>
+          <doc:para>The remote host name for the session.
+          </doc:para>
+          <doc:para>This will be set in situations where the session is
+          opened and controlled from a remote system.
+          </doc:para>
+          <doc:para>For example, this value will be set when the
+          session is created from an SSH or XDMCP connection.
+          </doc:para>
+        </doc:description>
+      </doc:doc>
+    </property>
+    <property name="display-device" type="s" access="readwrite">
+      <doc:doc>
+        <doc:description>
+          <doc:para>The display device (aka TTY) that the
+          session is connected to.
+          </doc:para>
+        </doc:description>
+      </doc:doc>
+    </property>
+    <property name="x11-display" type="s" access="readwrite">
+      <doc:doc>
+        <doc:description>
+          <doc:para>Value of the X11 DISPLAY for this session
+          if one is present.
+          </doc:para>
+        </doc:description>
+      </doc:doc>
+    </property>
+    <property name="x11-display-device" type="s" access="readwrite">
+      <doc:doc>
+        <doc:description>
+          <doc:para>
+          The display device (aka TTY) that the X11 display for the
+          session is connected to.  If there is no x11-display set then
+          this value is undefined.
+          </doc:para>
+        </doc:description>
+      </doc:doc>
+    </property>
+    <property name="active" type="b" access="readwrite">
+      <doc:doc>
+        <doc:description>
+          <doc:para>
+          Whether the session is active on the Seat that
+          it is attached to.</doc:para>
+          <doc:para>If the session is not attached to a seat this value is undefined.
+          </doc:para>
+        </doc:description>
+      </doc:doc>
+    </property>
+    <property name="is-local" type="b" access="readwrite">
+      <doc:doc>
+        <doc:description>
+          <doc:para>
+          Whether the session is local</doc:para>
+          <doc:para>FIXME: we need to come up with a concrete definition for this value.
+          It was originally used as a way to identify XDMCP sessions that originate
+          from a remote system.
+          </doc:para>
+        </doc:description>
+      </doc:doc>
+    </property>
+    <property name="idle-hint" type="b" access="readwrite">
+      <doc:doc>
+        <doc:description>
+          <doc:para>
+          This is a hint used to indicate that the session may be idle.
+          </doc:para>
+          <doc:para>
+          For sessions with a <doc:ref type="property" to="Session:x11-display">x11-display</doc:ref> set (ie. graphical
+          sessions), it is up to each session to delegate the
+          responsibility for updating this value.  Typically, the
+          screensaver will set this.
+          </doc:para>
+          <doc:para>However, for non-graphical sessions with a <doc:ref type="property" to="Session:display-device">display-device</doc:ref> set
+          the Session object itself will periodically update this value based
+          on the activity detected on the display-device itself.
+          </doc:para>
+          <doc:para>
+          This should not be considered authoritative.
+          </doc:para>
+        </doc:description>
+      </doc:doc>
+    </property>
+
+  </interface>
+</node>
diff --git a/tools/Makefile.am b/tools/Makefile.am
new file mode 100644
index 0000000..d5b124c
--- /dev/null
+++ b/tools/Makefile.am
@@ -0,0 +1,19 @@
+doctoolsdir = $(bindir)
+
+doctools_SCRIPTS = \
+    spec-strip-docs \
+    spec-to-docbook
+
+docxsldir = $(datadir)/dbus-doc/xsl
+
+docxsl_DATA = \
+    spec-strip-docs.xsl \
+    spec-to-docbook.xsl
+
+do_subst = sed -e 's,[@xsldir[@],$(xsldir),g'
+
+spec-strip-docs: spec-strip-docs.in
+	$(do_subst) <  $(srcdir)/spec-strip-docs.in > spec-strip-docs
+
+spec-to-docbook: spec-to-docbook.in
+	$(do_subst) <  $(srcdir)/spec-to-docbook.in > spec-to-docbook
diff --git a/tools/spec-strip-docs.in b/tools/spec-strip-docs.in
new file mode 100755
index 0000000..563f3f3
--- /dev/null
+++ b/tools/spec-strip-docs.in
@@ -0,0 +1,32 @@
+#!/bin/sh
+
+CMD=xsltproc
+XSL=@xsldir@/spec-strip-docs.xsl
+
+if test "x$1" = "x" -o  "x$1" = "x-h" -o "x$1" = "x--help"; then
+    echo "usage: $0 [file] ..."
+    exit 1
+fi
+
+if [ ! -r ${XSL} ]; then
+    echo "Cannot find XSLT file"
+    exit 1
+fi
+
+FILES="$@"
+for FILE in $FILES; do
+    echo "${FILE}" | grep ".xml$" > /dev/null
+    if [ $? -ne 0 ]; then
+        echo "Skipping non-xml file: ${FILE}"
+        continue
+    fi
+
+    d=`dirname ${FILE}`
+    b=`basename ${FILE} .xml`
+
+    outfile="${b}-no-docs.xml"
+    echo "Creating: ${outfile}"
+    ${CMD} ${XSL} ${FILE} | tail -n +2  > ${outfile}
+done
+
+exit 0
diff --git a/tools/spec-strip-docs.xsl b/tools/spec-strip-docs.xsl
new file mode 100644
index 0000000..21ad558
--- /dev/null
+++ b/tools/spec-strip-docs.xsl
@@ -0,0 +1,36 @@
+<?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">
+
+  <xsl:output method="xml" indent="yes" encoding="UTF-8"
+    omit-xml-declaration="no"
+    doctype-system="http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"
+    doctype-public="-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" />
+
+  <xsl:template match="*">
+    <xsl:copy>
+      <xsl:for-each select="@*">
+        <xsl:if test="not(starts-with(name(.), 'doc:'))">
+          <xsl:copy/>
+        </xsl:if>
+      </xsl:for-each>
+      <xsl:apply-templates/>
+    </xsl:copy>
+  </xsl:template>
+
+  <xsl:template match="node">
+    <node>
+      <xsl:for-each select="@*">
+        <xsl:if test="not(starts-with(name(.), 'xmlns'))">
+          <xsl:copy/>
+        </xsl:if>
+      </xsl:for-each>
+      <xsl:apply-templates/>
+    </node>
+  </xsl:template>
+
+  <xsl:template match="doc:*"/>
+  <xsl:template match="text()"/>
+
+</xsl:stylesheet>
diff --git a/tools/spec-to-docbook.in b/tools/spec-to-docbook.in
new file mode 100755
index 0000000..e78d1f7
--- /dev/null
+++ b/tools/spec-to-docbook.in
@@ -0,0 +1,32 @@
+#!/bin/sh
+
+CMD=xsltproc
+XSL=@xsldir@/spec-to-docbook.xsl
+
+if test "x$1" = "x" -o  "x$1" = "x-h" -o "x$1" = "x--help"; then
+    echo "usage: $0 [file] ..."
+    exit 1
+fi
+
+if [ ! -r ${XSL} ]; then
+    echo "Cannot find XSLT file"
+    exit 1
+fi
+
+FILES="$@"
+for FILE in $FILES; do
+    echo "${FILE}" | grep ".xml$" > /dev/null
+    if [ $? -ne 0 ]; then
+        echo "Skipping non-xml file: ${FILE}"
+        continue
+    fi
+
+    d=`dirname ${FILE}`
+    b=`basename ${FILE} .xml`
+
+    outfile="ref-${b}.xml"
+    echo "Creating: ${outfile}"
+    ${CMD} ${XSL} ${FILE} | tail -n +2  > ${outfile}
+done
+
+exit 0
diff --git a/tools/spec-to-docbook.xsl b/tools/spec-to-docbook.xsl
new file mode 100644
index 0000000..fccf887
--- /dev/null
+++ b/tools/spec-to-docbook.xsl
@@ -0,0 +1,436 @@
+<?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>
+
+  <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>
+
+  <refsect1 role="impl_interfaces">
+    <title role="impl_interfaces.title">Implemented Interfaces</title>
+    <para>
+    <xsl:value-of select="$interface"/> implements
+    org.freedesktop.DBus.Introspectable,
+    org.freedesktop.DBus.Properties
+    </para>
+  </refsect1>
+
+  <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>
+
+  <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>
+
+  <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>
+
+  <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>
+
+</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:summary">
+<!-- by default don't display -->
+</xsl:template>
+
+<xsl:template match="doc:example">
+<informalexample>
+<xsl:apply-templates />
+</informalexample>
+</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: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: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="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>