summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRob Taylor <rob.taylor@codethink.co.uk>2007-03-28 17:58:56 +0100
committerRob Taylor <rob.taylor@codethink.co.uk>2007-03-28 17:58:56 +0100
commit729fdf43b7a76d4861cdb28f1bc65be2bf8989f9 (patch)
tree72ce292bbcabc5665bebb64db6fd26874bbf61a5
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.
-rw-r--r--.gitignore16
-rw-r--r--AUTHORS2
l---------COPYING1
l---------INSTALL1
-rw-r--r--Makefile.am30
-rw-r--r--NEWS0
-rw-r--r--README148
-rw-r--r--TODO13
-rwxr-xr-xautogen.sh170
-rw-r--r--config.xsl6
-rw-r--r--configure.ac29
-rw-r--r--dbus-introspect-docs.dtd32
-rw-r--r--docbook.css78
-rw-r--r--examples/Makefile.am3
-rw-r--r--examples/ck-session.xml422
-rw-r--r--tools/Makefile.am19
-rwxr-xr-xtools/spec-strip-docs.in32
-rw-r--r--tools/spec-strip-docs.xsl36
-rwxr-xr-xtools/spec-to-docbook.in32
-rw-r--r--tools/spec-to-docbook.xsl436
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>