From 729fdf43b7a76d4861cdb28f1bc65be2bf8989f9 Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Wed, 28 Mar 2007 17:58:56 +0100 Subject: Initial Commit of dbus-doc 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. --- .gitignore | 16 ++ AUTHORS | 2 + COPYING | 1 + INSTALL | 1 + Makefile.am | 30 ++++ NEWS | 0 README | 148 ++++++++++++++++ TODO | 13 ++ autogen.sh | 170 ++++++++++++++++++ config.xsl | 6 + configure.ac | 29 +++ dbus-introspect-docs.dtd | 32 ++++ docbook.css | 78 +++++++++ examples/Makefile.am | 3 + examples/ck-session.xml | 422 ++++++++++++++++++++++++++++++++++++++++++++ tools/Makefile.am | 19 ++ tools/spec-strip-docs.in | 32 ++++ tools/spec-strip-docs.xsl | 36 ++++ tools/spec-to-docbook.in | 32 ++++ tools/spec-to-docbook.xsl | 436 ++++++++++++++++++++++++++++++++++++++++++++++ 20 files changed, 1506 insertions(+) create mode 100644 .gitignore create mode 100644 AUTHORS create mode 120000 COPYING create mode 120000 INSTALL create mode 100644 Makefile.am create mode 100644 NEWS create mode 100644 README create mode 100644 TODO create mode 100755 autogen.sh create mode 100644 config.xsl create mode 100644 configure.ac create mode 100644 dbus-introspect-docs.dtd create mode 100644 docbook.css create mode 100644 examples/Makefile.am create mode 100644 examples/ck-session.xml create mode 100644 tools/Makefile.am create mode 100755 tools/spec-strip-docs.in create mode 100644 tools/spec-strip-docs.xsl create mode 100755 tools/spec-to-docbook.in create mode 100644 tools/spec-to-docbook.xsl 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 +Rob Taylor 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 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 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 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 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 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 @@ + + + + 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 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 @@ + + + + + + + Session objects represent and store information + related to a user session. + + The properties associated with the Session + specifically refer to the properties of the "session leader". + + + + + + + Session ID + + + + Returns the ID for Session. + + + + + + + Seat ID + + + + Returns the ID for the Seat the Session is + attached to. + + org.freedesktop.ConsoleKit.Seat + + + + + + Session type + + + + + Returns the type of the session. + Warning: we haven't yet defined the allowed values for this property. + It is probably best to avoid this until we do. + + + session-type + + + + + + User ID + + + + Returns the user that the session belongs to. + + + user + + + + + + POSIX User ID + + + + Returns the POSIX user ID that the session belongs to. + + unix-user + + + + + + The value of the X11 display + + + + Returns the value of the X11 DISPLAY for this session + if one is present. + + x11-display + + + + + + The value of the X11 display device + + + + 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. + + x11-display-device + + + + + + The value of the display device + + + + Returns the value of the display device (aka TTY) that the + session is connected to. + + display-device + + + + + + The remote host name + + + + Returns the value of the remote host name for the session. + + + remote-host-name + + + + + + TRUE if the session is active, otherwise FALSE + + + + Returns whether the session is active on the Seat that + it is attached to. + If the session is not attached to a seat this value is undefined. + + + active + + + + + + TRUE if the session is local, otherwise FALSE + + + + Returns whether the session is local + 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. + + + is-local + + + + + + An ISO 8601 format date-type string + + + + + Returns an ISO 8601 date-time string that corresponds to + the time that the session was opened. + + + + + + + + + + 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. + + Seat.ActivateSession() + + + + + + + This will cause a Lock + signal to be emitted for this session. + + + This method is restricted to privileged users by D-Bus policy. + Lock signal + + + + + + + This will cause an Unlock + signal to be emitted for this session. + + This can be used by login managers to unlock a session before it is + re-activated during fast-user-switching. + + + This method is restricted to privileged users by D-Bus policy. + Unlock signal + + + + + + + The value of the idle-hint + + + + + Gets the value of the idle-hint + property. + + + idle-hint + + + + + + An ISO 8601 format date-type string + + + + + Returns an ISO 8601 date-time string that corresponds to + the time of the last change of the idle-hint. + + + + + + + + + boolean value to set the idle-hint to + + + + + This may be used by the session to indicate that + it is idle. + + Use of this method is restricted to the user + that owns the session. + + + + + + + + TRUE if the session is active, otherwise FALSE + + + + + Emitted when the active property has changed. + + + + + + + the new value of idle-hint + + + + + Emitted when the idle-hint property has changed. + + + + + + + Emitted in response to a call to the Lock() method. + It is intended that the screensaver for the session should lock the screen in response to this signal. + + + + + + + Emitted in response to a call to the Unlock() method. + It is intended that the screensaver for the session should unlock the screen in response to this signal. + + + + + + + + The user assigned to the session. + + + + + + + The user assigned to the session. + + + + + + + + The type of the session. + Warning: we haven't yet defined the allowed values for this property. + It is probably best to avoid this until we do. + + + + + + + + The remote host name for the session. + + This will be set in situations where the session is + opened and controlled from a remote system. + + For example, this value will be set when the + session is created from an SSH or XDMCP connection. + + + + + + + + The display device (aka TTY) that the + session is connected to. + + + + + + + + Value of the X11 DISPLAY for this session + if one is present. + + + + + + + + + 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. + + + + + + + + + Whether the session is active on the Seat that + it is attached to. + If the session is not attached to a seat this value is undefined. + + + + + + + + + Whether the session is local + 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. + + + + + + + + + This is a hint used to indicate that the session may be idle. + + + For sessions with a x11-display set (ie. graphical + sessions), it is up to each session to delegate the + responsibility for updating this value. Typically, the + screensaver will set this. + + However, for non-graphical sessions with a display-device set + the Session object itself will periodically update this value based + on the activity detected on the display-device itself. + + + This should not be considered authoritative. + + + + + + + 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 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 @@ + + + + + + + + + + + + + + + + + + + + + + interface + + + + Methods + + + + + + + + + Signals + + + + + + + + + Implemented Interfaces + + implements + org.freedesktop.DBus.Introspectable, + org.freedesktop.DBus.Properties + + + + + Properties + + + + + + + + + Description + + + + + + + Details + + + + + + + Signal Details + + + + + + + Property Details + + + + + + + + + + + + + + +: + + + + + + + + + + + + + + + + + + + + + + <anchor role="function"><xsl:attribute name="id"><xsl:value-of select="$basename"/>:<xsl:value-of select="@name"/></xsl:attribute></anchor>The "<xsl:value-of select="@name"/>" property + +'' + + + + + + + + + + + + + +: + + + + + + + + + + + + + + + + + + + + + <anchor role="function"><xsl:attribute name="id"><xsl:value-of select="$basename"/>::<xsl:value-of select="@name"/></xsl:attribute></anchor>The <xsl:value-of select="@name"/> signal + + () + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Since + + + + + + + + /> + + + + + + + is deprecated since version and should not be used in newly-written code. Use + + + + + : + + + :: + + + . + + + + + + + + + + + + + + + +instead. + + + + + + + + + + + +See also: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +: + + + + + + + + + + + + + + + + + + + + + <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"/> () + + () + + + + + + + + + + + + + + + + +:'' + + + + + + + + + + + + +::() + + + + + + + + + + + + +.() + + + + + +'' +, + + + + + +'' +, + + + + + + +'' + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -- cgit v1.2.3