Sync tools from telepathy-spec

20071123141727-53eee-42fdb5e7b9385290998ffd1c34c8e029dc63dd35.gz

3 files changed, 307 insertions, 18 deletions

diff --git a/tools/doc-generator.xsl b/tools/doc-generator.xsl
index 3b76d13..83b42dc 100644
--- a/tools/doc-generator.xsl
+++ b/tools/doc-generator.xsl
@@ -1,3 +1,24 @@
+<!-- Generate HTML documentation from the Telepathy specification.
+The master copy of this stylesheet is in the Telepathy spec repository -
+please make any changes there.
+
+Copyright (C) 2006, 2007 Collabora Limited
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Library General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+-->
+
 <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
   exclude-result-prefixes="tp">
@@ -20,6 +41,43 @@
     <xsl:apply-templates/>
   </xsl:template>
 
+  <xsl:template match="tp:generic-types">
+    <h1 xmlns="http://www.w3.org/1999/xhtml">Generic types</h1>
+    <xsl:call-template name="do-types"/>
+  </xsl:template>
+
+  <xsl:template name="do-types">
+    <xsl:if test="tp:simple-type">
+      <h2 xmlns="http://www.w3.org/1999/xhtml">Simple types</h2>
+      <xsl:apply-templates select="tp:simple-type"/>
+    </xsl:if>
+
+    <xsl:if test="tp:enum">
+      <h2 xmlns="http://www.w3.org/1999/xhtml">Enumerated types:</h2>
+      <xsl:apply-templates select="tp:enum"/>
+    </xsl:if>
+
+    <xsl:if test="tp:flags">
+      <h2 xmlns="http://www.w3.org/1999/xhtml">Sets of flags:</h2>
+      <xsl:apply-templates select="tp:flags"/>
+    </xsl:if>
+
+    <xsl:if test="tp:struct">
+      <h2 xmlns="http://www.w3.org/1999/xhtml">Structure types</h2>
+      <xsl:apply-templates select="tp:struct"/>
+    </xsl:if>
+
+    <xsl:if test="tp:mapping">
+      <h2 xmlns="http://www.w3.org/1999/xhtml">Mapping types</h2>
+      <xsl:apply-templates select="tp:mapping"/>
+    </xsl:if>
+
+    <xsl:if test="tp:external-type">
+      <h2 xmlns="http://www.w3.org/1999/xhtml">Types defined elsewhere</h2>
+      <dl><xsl:apply-templates select="tp:external-type"/></dl>
+    </xsl:if>
+  </xsl:template>
+
   <xsl:template match="tp:error">
     <h2 xmlns="http://www.w3.org/1999/xhtml"><a name="{concat(../@namespace, '.', translate(@name, ' ', ''))}"></a><xsl:value-of select="concat(../@namespace, '.', translate(@name, ' ', ''))"/></h2>
     <xsl:apply-templates select="tp:docstring"/>
@@ -42,6 +100,14 @@
   <xsl:template match="interface">
     <h1 xmlns="http://www.w3.org/1999/xhtml"><a name="{@name}"></a><xsl:value-of select="@name"/></h1>
 
+    <xsl:if test="@tp:causes-havoc">
+      <p xmlns="http://www.w3.org/1999/xhtml" class="causes-havoc">
+        This interface is <xsl:value-of select="@tp:causes-havoc"/>
+        and is likely to cause havoc to your API/ABI if bindings are generated.
+        Don't include it in libraries that care about compatibility.
+      </p>
+    </xsl:if>
+
     <xsl:if test="tp:requires">
       <p>Implementations of this interface must also implement:</p>
       <ul xmlns="http://www.w3.org/1999/xhtml">
@@ -85,20 +151,16 @@
       </xsl:otherwise>
     </xsl:choose>
 
-    <xsl:if test="tp:enum">
-      <h2 xmlns="http://www.w3.org/1999/xhtml">Enumerated types:</h2>
-      <xsl:apply-templates select="tp:enum"/>
-    </xsl:if>
-
-    <xsl:if test="tp:flags">
-      <h2 xmlns="http://www.w3.org/1999/xhtml">Sets of flags:</h2>
-      <xsl:apply-templates select="tp:flags"/>
-    </xsl:if>
+    <xsl:call-template name="do-types"/>
 
   </xsl:template>
 
   <xsl:template match="tp:flags">
-    <h3 xmlns="http://www.w3.org/1999/xhtml"><xsl:value-of select="@name"/></h3>
+    <h3>
+      <a name="type-{@name}">
+        <xsl:value-of select="@name"/>
+      </a>
+    </h3>
     <xsl:apply-templates select="tp:docstring" />
     <dl xmlns="http://www.w3.org/1999/xhtml">
         <xsl:variable name="value-prefix">
@@ -126,7 +188,11 @@
   </xsl:template>
 
   <xsl:template match="tp:enum">
-    <h3 xmlns="http://www.w3.org/1999/xhtml"><xsl:value-of select="@name"/></h3>
+    <h3 xmlns="http://www.w3.org/1999/xhtml">
+      <a name="type-{@name}">
+        <xsl:value-of select="@name"/>
+      </a>
+    </h3>
     <xsl:apply-templates select="tp:docstring" />
     <dl xmlns="http://www.w3.org/1999/xhtml">
         <xsl:variable name="value-prefix">
@@ -165,9 +231,120 @@
     </dd>
   </xsl:template>
 
+  <xsl:template match="tp:mapping">
+    <div xmlns="http://www.w3.org/1999/xhtml" class="struct">
+      <h3>
+        <a name="type-{@name}">
+          <xsl:value-of select="@name"/>
+        </a> - a{
+        <xsl:for-each select="tp:member">
+          <xsl:value-of select="@type"/>
+          <xsl:text>: </xsl:text>
+          <xsl:value-of select="@name"/>
+          <xsl:if test="position() != last()"> &#x2192; </xsl:if>
+        </xsl:for-each>
+        }
+      </h3>
+      <div class="docstring">
+        <xsl:apply-templates select="tp:docstring"/>
+      </div>
+      <div>
+        <h4>Members</h4>
+        <dl>
+          <xsl:apply-templates select="tp:member" mode="members-in-docstring"/>
+        </dl>
+      </div>
+    </div>
+  </xsl:template>
+
+  <xsl:template match="tp:docstring" mode="in-index"/>
+
+  <xsl:template match="tp:simple-type | tp:enum | tp:flags | tp:external-type"
+    mode="in-index">
+    - <xsl:value-of select="@type"/>
+  </xsl:template>
+
+  <xsl:template match="tp:simple-type">
+    <div xmlns="http://www.w3.org/1999/xhtml" class="simple-type">
+      <h3>
+        <a name="type-{@name}">
+          <xsl:value-of select="@name"/>
+        </a> - <xsl:value-of select="@type"/>
+      </h3>
+      <div class="docstring">
+        <xsl:apply-templates select="tp:docstring"/>
+      </div>
+    </div>
+  </xsl:template>
+
+  <xsl:template match="tp:external-type">
+    <div xmlns="http://www.w3.org/1999/xhtml" class="external-type">
+      <dt>
+        <a name="type-{@name}">
+          <xsl:value-of select="@name"/>
+        </a> - <xsl:value-of select="@type"/>
+      </dt>
+      <dd>Defined by: <xsl:value-of select="@from"/></dd>
+    </div>
+  </xsl:template>
+
+  <xsl:template match="tp:struct" mode="in-index">
+    - ( <xsl:for-each select="tp:member">
+          <xsl:value-of select="@type"/>
+          <xsl:if test="position() != last()">, </xsl:if>
+        </xsl:for-each> )
+  </xsl:template>
+
+  <xsl:template match="tp:mapping" mode="in-index">
+    - a{ <xsl:for-each select="tp:member">
+          <xsl:value-of select="@type"/>
+          <xsl:if test="position() != last()"> &#x2192; </xsl:if>
+        </xsl:for-each> }
+  </xsl:template>
+
+  <xsl:template match="tp:struct">
+    <div xmlns="http://www.w3.org/1999/xhtml" class="struct">
+      <h3>
+        <a name="type-{@name}">
+          <xsl:value-of select="@name"/>
+        </a> - (
+        <xsl:for-each select="tp:member">
+          <xsl:value-of select="@type"/>
+          <xsl:text>: </xsl:text>
+          <xsl:value-of select="@name"/>
+          <xsl:if test="position() != last()">, </xsl:if>
+        </xsl:for-each>
+        )
+      </h3>
+      <div class="docstring">
+        <xsl:apply-templates select="tp:docstring"/>
+      </div>
+      <xsl:choose>
+        <xsl:when test="string(@array-name) != ''">
+          <p>In bindings that need a separate name, arrays of
+            <xsl:value-of select="@name"/> should be called
+            <xsl:value-of select="@array-name"/>.</p>
+        </xsl:when>
+        <xsl:otherwise>
+          <p>Arrays of <xsl:value-of select="@name"/> don't generally
+            make sense.</p>
+        </xsl:otherwise>
+      </xsl:choose>
+      <div>
+        <h4>Members</h4>
+        <dl>
+          <xsl:apply-templates select="tp:member" mode="members-in-docstring"/>
+        </dl>
+      </div>
+    </div>
+  </xsl:template>
+
   <xsl:template match="method">
     <div xmlns="http://www.w3.org/1999/xhtml" class="method">
-      <h3 xmlns="http://www.w3.org/1999/xhtml"><xsl:value-of select="@name"/> (
+      <h3 xmlns="http://www.w3.org/1999/xhtml">
+        <a name="{concat(../@name, concat('.', @name))}">
+          <xsl:value-of select="@name"/>
+        </a> (
         <xsl:for-each xmlns="" select="arg[@direction='in']">
           <xsl:value-of select="@type"/>: <xsl:value-of select="@name"/>
           <xsl:if test="position() != last()">, </xsl:if>
@@ -219,10 +396,66 @@
     </div>
   </xsl:template>
 
+  <xsl:template name="parenthesized-tp-type">
+    <xsl:if test="@tp:type">
+      <xsl:variable name="tp-type" select="@tp:type"/>
+      <xsl:variable name="single-type">
+        <xsl:choose>
+          <xsl:when test="contains($tp-type, '[]')">
+            <xsl:value-of select="substring-before($tp-type, '[]')"/>
+          </xsl:when>
+          <xsl:otherwise>
+            <xsl:value-of select="$tp-type"/>
+          </xsl:otherwise>
+        </xsl:choose>
+      </xsl:variable>
+      <xsl:choose>
+        <xsl:when test="//tp:simple-type[@name=$tp-type]" />
+        <xsl:when test="//tp:simple-type[concat(@name, '[]')=$tp-type]" />
+        <xsl:when test="//tp:struct[concat(@name, '[]')=$tp-type][string(@array-name) != '']" />
+        <xsl:when test="//tp:struct[@name=$tp-type]" />
+        <xsl:when test="//tp:enum[@name=$tp-type]" />
+        <xsl:when test="//tp:enum[concat(@name, '[]')=$tp-type]" />
+        <xsl:when test="//tp:flags[@name=$tp-type]" />
+        <xsl:when test="//tp:flags[concat(@name, '[]')=$tp-type]" />
+        <xsl:when test="//tp:mapping[@name=$tp-type]" />
+        <xsl:when test="//tp:external-type[concat(@name, '[]')=$tp-type]" />
+        <xsl:when test="//tp:external-type[@name=$tp-type]" />
+        <xsl:otherwise>
+          <xsl:message terminate="yes">
+            <xsl:text>ERR: Unable to find type '</xsl:text>
+            <xsl:value-of select="$tp-type"/>
+            <xsl:text>'&#10;</xsl:text>
+          </xsl:message>
+        </xsl:otherwise>
+      </xsl:choose>
+      (<a href="#type-{$single-type}"><xsl:value-of select="$tp-type"/></a>)
+    </xsl:if>
+  </xsl:template>
+
+  <xsl:template match="tp:member" mode="members-in-docstring">
+    <dt xmlns="http://www.w3.org/1999/xhtml">
+      <code><xsl:value-of select="@name"/></code> -
+      <code><xsl:value-of select="@type"/></code>
+      <xsl:call-template name="parenthesized-tp-type"/>
+    </dt>
+    <dd xmlns="http://www.w3.org/1999/xhtml">
+      <xsl:choose>
+        <xsl:when test="tp:docstring">
+          <xsl:apply-templates select="tp:docstring" />
+        </xsl:when>
+        <xsl:otherwise>
+          <em>(undocumented)</em>
+        </xsl:otherwise>
+      </xsl:choose>
+    </dd>
+  </xsl:template>
+
   <xsl:template match="arg" mode="parameters-in-docstring">
     <dt xmlns="http://www.w3.org/1999/xhtml">
       <code><xsl:value-of select="@name"/></code> -
       <code><xsl:value-of select="@type"/></code>
+      <xsl:call-template name="parenthesized-tp-type"/>
     </dt>
     <dd xmlns="http://www.w3.org/1999/xhtml">
       <xsl:apply-templates select="tp:docstring" />
@@ -235,6 +468,7 @@
         <code><xsl:value-of select="@name"/></code> -
       </xsl:if>
       <code><xsl:value-of select="@type"/></code>
+      <xsl:call-template name="parenthesized-tp-type"/>
     </dt>
     <dd xmlns="http://www.w3.org/1999/xhtml">
       <xsl:apply-templates select="tp:docstring"/>
@@ -263,7 +497,10 @@
 
   <xsl:template match="signal">
     <div xmlns="http://www.w3.org/1999/xhtml" class="signal">
-      <h3 xmlns="http://www.w3.org/1999/xhtml"><xsl:value-of select="@name"/> ( 
+      <h3 xmlns="http://www.w3.org/1999/xhtml">
+        <a name="{concat(../@name, concat('.', @name))}">
+          <xsl:value-of select="@name"/>
+        </a> (
         <xsl:for-each xmlns="" select="arg">
           <xsl:value-of select="@type"/>: <xsl:value-of select="@name"/>
           <xsl:if test="position() != last()">, </xsl:if>
@@ -410,14 +647,39 @@
         <xsl:apply-templates select="tp:copyright"/>
         <xsl:apply-templates select="tp:license"/>
         <xsl:apply-templates select="tp:docstring"/>
-	<h2>Interfaces</h2>
-	<ul>
-	  <xsl:for-each select="node/interface">
+
+        <h2>Interfaces</h2>
+        <ul>
+        <xsl:for-each select="node/interface">
             <li><code><a href="#{@name}"><xsl:value-of select="@name"/></a></code></li>
-	  </xsl:for-each>
-	</ul>
+          </xsl:for-each>
+        </ul>
+
         <xsl:apply-templates select="node"/>
+        <xsl:apply-templates select="tp:generic-types"/>
         <xsl:apply-templates select="tp:errors"/>
+
+        <h1>Index</h1>
+        <h2>Index of interfaces</h2>
+        <ul>
+        <xsl:for-each select="node/interface">
+            <li><code><a href="#{@name}"><xsl:value-of select="@name"/></a></code></li>
+          </xsl:for-each>
+        </ul>
+        <h2>Index of types</h2>
+        <ul>
+          <xsl:for-each select="//tp:simple-type | //tp:enum | //tp:flags | //tp:mapping | //tp:struct | //tp:external-type">
+            <xsl:sort select="@name"/>
+            <li>
+              <code>
+                <a href="#type-{@name}">
+                  <xsl:value-of select="@name"/>
+                </a>
+              </code>
+              <xsl:apply-templates mode="in-index" select="."/>
+            </li>
+          </xsl:for-each>
+        </ul>
       </body>
     </html>
   </xsl:template>
diff --git a/tools/ls-interfaces.xsl b/tools/ls-interfaces.xsl
index 7b970ce..efb76b9 100644
--- a/tools/ls-interfaces.xsl
+++ b/tools/ls-interfaces.xsl
@@ -1,5 +1,7 @@
 <!--
 Extract a space-separated list of interface classnames from the Telepathy spec.
+The master copy of this stylesheet is in the Telepathy spec repository -
+please make any changes there.
 
 Copyright (C) 2006, 2007 Collabora Limited
 
diff --git a/tools/spec-to-introspect.xsl b/tools/spec-to-introspect.xsl
index 1eefd3d..3def766 100644
--- a/tools/spec-to-introspect.xsl
+++ b/tools/spec-to-introspect.xsl
@@ -1,3 +1,28 @@
+<!-- Remove Telepathy extensions from a D-Bus interface, trying to leave only
+DTD-compliant introspection XML. The output still needs to be subjected to the
+following sed filter:
+sed -e 's@xmlns:tp="http://telepathy\.freedesktop\.org/wiki/DbusSpec.extensions-v0"@@g'
+
+The master copy of this stylesheet is in the Telepathy spec repository -
+please make any changes there.
+
+Copyright (C) 2006, 2007 Collabora Limited
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Library General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+-->
+
 <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
   exclude-result-prefixes="tp">