diff options
| -rw-r--r-- | .gitignore | 16 | ||||
| -rw-r--r-- | AUTHORS | 2 | ||||
| l--------- | COPYING | 1 | ||||
| l--------- | INSTALL | 1 | ||||
| -rw-r--r-- | Makefile.am | 30 | ||||
| -rw-r--r-- | NEWS | 0 | ||||
| -rw-r--r-- | README | 148 | ||||
| -rw-r--r-- | TODO | 13 | ||||
| -rwxr-xr-x | autogen.sh | 170 | ||||
| -rw-r--r-- | config.xsl | 6 | ||||
| -rw-r--r-- | configure.ac | 29 | ||||
| -rw-r--r-- | dbus-introspect-docs.dtd | 32 | ||||
| -rw-r--r-- | docbook.css | 78 | ||||
| -rw-r--r-- | examples/Makefile.am | 3 | ||||
| -rw-r--r-- | examples/ck-session.xml | 422 | ||||
| -rw-r--r-- | tools/Makefile.am | 19 | ||||
| -rwxr-xr-x | tools/spec-strip-docs.in | 32 | ||||
| -rw-r--r-- | tools/spec-strip-docs.xsl | 36 | ||||
| -rwxr-xr-x | tools/spec-to-docbook.in | 32 | ||||
| -rw-r--r-- | tools/spec-to-docbook.xsl | 436 |
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 @@ -0,0 +1,2 @@ +William Jon McCann <mccann@jhu.edu> +Rob Taylor <rob.taylor@codethink.co.uk> @@ -0,0 +1 @@ +/usr/share/automake-1.9/COPYING
\ No newline at end of file @@ -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: + @@ -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> @@ -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> |