From 8b42a4928a0a266c3b3ae6bb13997764bc7f6405 Mon Sep 17 00:00:00 2001
From: William Jon McCann <mccann@jhu.edu>
Date: Tue, 13 Mar 2007 03:42:04 -0400
Subject: add the last bits of spec framework

The spec is the introspection format extended with
docs.  There are tools to build docbook and strip
the docs to make dbus introspect xml.
---
 doc/tools/spec-strip-docs     |  34 ++++
 doc/tools/spec-strip-docs.xsl |  36 ++++
 doc/tools/spec-to-docbook     |  34 ++++
 doc/tools/spec-to-docbook.xsl | 379 ++++++++++++++++++++++++++++++++++++++++++
 doc/tools/update-from-spec    |  25 +++
 5 files changed, 508 insertions(+)
 create mode 100755 doc/tools/spec-strip-docs
 create mode 100644 doc/tools/spec-strip-docs.xsl
 create mode 100755 doc/tools/spec-to-docbook
 create mode 100644 doc/tools/spec-to-docbook.xsl
 create mode 100755 doc/tools/update-from-spec

(limited to 'doc/tools')

diff --git a/doc/tools/spec-strip-docs b/doc/tools/spec-strip-docs
new file mode 100755
index 0000000..52d84bc
--- /dev/null
+++ b/doc/tools/spec-strip-docs
@@ -0,0 +1,34 @@
+#!/bin/sh
+
+DIST_BIN=`dirname "$0"`
+
+CMD=xsltproc
+XSL=${DIST_BIN}/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/doc/tools/spec-strip-docs.xsl b/doc/tools/spec-strip-docs.xsl
new file mode 100644
index 0000000..21ad558
--- /dev/null
+++ b/doc/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/doc/tools/spec-to-docbook b/doc/tools/spec-to-docbook
new file mode 100755
index 0000000..883e2ba
--- /dev/null
+++ b/doc/tools/spec-to-docbook
@@ -0,0 +1,34 @@
+#!/bin/sh
+
+DIST_BIN=`dirname "$0"`
+
+CMD=xsltproc
+XSL=${DIST_BIN}/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/doc/tools/spec-to-docbook.xsl b/doc/tools/spec-to-docbook.xsl
new file mode 100644
index 0000000..26b5937
--- /dev/null
+++ b/doc/tools/spec-to-docbook.xsl
@@ -0,0 +1,379 @@
+<?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"/>
+
+<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: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: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: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 match="doc:ref">
+  <xsl:choose>
+    <xsl:when test="contains(@type,'property')">
+      <link><xsl:attribute name="linkend"><xsl:value-of select="@to"/></xsl:attribute><literal><xsl:apply-templates /></literal></link>
+    </xsl:when>
+    <xsl:when test="contains(@type,'signal')">
+      <link><xsl:attribute name="linkend"><xsl:value-of select="@to"/></xsl:attribute><literal><xsl:apply-templates /></literal></link>
+    </xsl:when>
+    <xsl:when test="contains(@type,'method')">
+      <link><xsl:attribute name="linkend"><xsl:value-of select="@to"/></xsl:attribute><function><xsl:apply-templates /></function></link>
+    </xsl:when>
+    <xsl:when test="contains(@type,'interface')">
+      <link><xsl:attribute name="linkend"><xsl:value-of select="@to"/></xsl:attribute><xsl:apply-templates /></link>
+    </xsl:when>
+  </xsl:choose>
+</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: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>
diff --git a/doc/tools/update-from-spec b/doc/tools/update-from-spec
new file mode 100755
index 0000000..b20e875
--- /dev/null
+++ b/doc/tools/update-from-spec
@@ -0,0 +1,25 @@
+#!/bin/sh
+
+DIST_BIN=`dirname "$0"`
+
+cd ${DIST_BIN}
+cd ../xml
+../tools/spec-to-docbook ../spec/*.xml
+if [ $? -ne 0 ]; then
+    exit 1
+fi
+
+cd ../../src
+../doc/tools/spec-strip-docs ../doc/spec/*.xml
+if [ $? -ne 0 ]; then
+    exit 1
+fi
+
+for name in session seat manager; do
+    mv ck-${name}-no-docs.xml ck-${name}.xml
+    if [ $? -ne 0 ]; then
+        exit 1
+    fi
+done
+
+exit 0
-- 
cgit