git.maemo.org Git - connman/blob - doc/dbus-introspection.xsl

   1 <?xml version='1.0'?>
   2 <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   3   xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd"
   4   exclude-result-prefixes="doc">
   5 <!--
   6      Convert D-Bus GLib XML into DocBook refentries
   7      Copyright (C) 2007 William Jon McCann
   8      License: GPL
   9 -->
  10 <xsl:output method="xml" indent="yes" encoding="UTF-8"/>
  11
  12 <xsl:template match="/">
  13
  14 <xsl:variable name="interface" select="//interface/@name"/>
  15 <xsl:variable name="basename">
  16   <xsl:call-template name="interface-basename">
  17     <xsl:with-param name="str" select="$interface"/>
  18   </xsl:call-template>
  19 </xsl:variable>
  20
  21 <refentry><xsl:attribute name="id"><xsl:value-of select="$basename"/></xsl:attribute>
  22   <refmeta>
  23     <refentrytitle role="top_of_page"><xsl:value-of select="//interface/@name"/></refentrytitle>
  24   </refmeta>
  25
  26   <refnamediv>
  27     <refname><xsl:value-of select="//interface/@name"/></refname>
  28     <refpurpose><xsl:value-of select="$basename"/> interface</refpurpose>
  29   </refnamediv>
  30
  31   <refsynopsisdiv role="synopsis">
  32     <title role="synopsis.title">Methods</title>
  33     <synopsis>
  34   <xsl:call-template name="methods-synopsis">
  35     <xsl:with-param name="basename" select="$basename"/>
  36   </xsl:call-template>
  37     </synopsis>
  38   </refsynopsisdiv>
  39
  40   <refsect1 role="signal_proto">
  41     <title role="signal_proto.title">Signals</title>
  42     <synopsis>
  43   <xsl:call-template name="signals-synopsis">
  44     <xsl:with-param name="basename" select="$basename"/>
  45   </xsl:call-template>
  46     </synopsis>
  47   </refsect1>
  48
  49   <refsect1 role="impl_interfaces">
  50     <title role="impl_interfaces.title">Implemented Interfaces</title>
  51     <para>
  52     <xsl:value-of select="$interface"/> implements
  53     org.freedesktop.DBus.Introspectable,
  54     org.freedesktop.DBus.Properties
  55     </para>
  56   </refsect1>
  57
  58   <refsect1 role="properties">
  59     <title role="properties.title">Properties</title>
  60     <synopsis>
  61   <xsl:call-template name="properties-synopsis">
  62     <xsl:with-param name="basename" select="$basename"/>
  63   </xsl:call-template>
  64     </synopsis>
  65   </refsect1>
  66
  67   <refsect1 role="desc">
  68     <title role="desc.title">Description</title>
  69     <para>
  70       <xsl:apply-templates select="//interface/doc:doc"/>
  71     </para>
  72   </refsect1>
  73
  74   <refsect1 role="details">
  75     <title role="details.title">Details</title>
  76     <xsl:call-template name="method-details">
  77       <xsl:with-param name="basename" select="$basename"/>
  78     </xsl:call-template>
  79   </refsect1>
  80
  81   <refsect1 role="signals">
  82     <title role="signals.title">Signal Details</title>
  83     <xsl:call-template name="signal-details">
  84       <xsl:with-param name="basename" select="$basename"/>
  85     </xsl:call-template>
  86   </refsect1>
  87
  88   <refsect1 role="property_details">
  89     <title role="property_details.title">Property Details</title>
  90     <xsl:call-template name="property-details">
  91       <xsl:with-param name="basename" select="$basename"/>
  92     </xsl:call-template>
  93   </refsect1>
  94
  95 </refentry>
  96 </xsl:template>
  97
  98
  99 <xsl:template name="property-doc">
 100   <xsl:apply-templates select="doc:doc/doc:description"/>
 101
 102   <variablelist role="params">
 103     <xsl:for-each select="arg">
 104 <varlistentry><term><parameter><xsl:value-of select="@name"/></parameter>:</term>
 105 <listitem><simpara><xsl:value-of select="doc:doc/doc:summary"/></simpara></listitem>
 106 </varlistentry>
 107     </xsl:for-each>
 108   </variablelist>
 109
 110   <xsl:apply-templates select="doc:doc/doc:since"/>
 111   <xsl:apply-templates select="doc:doc/doc:deprecated"/>
 112   <xsl:apply-templates select="doc:doc/doc:permission"/>
 113   <xsl:apply-templates select="doc:doc/doc:seealso"/>
 114 </xsl:template>
 115
 116
 117 <xsl:template name="property-details">
 118   <xsl:param name="basename"/>
 119   <xsl:variable name="longest">
 120     <xsl:call-template name="find-longest">
 121       <xsl:with-param name="set" select="@name"/>
 122     </xsl:call-template>
 123   </xsl:variable>
 124   <xsl:for-each select="///property">
 125   <refsect2>
 126     <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>
 127 <indexterm><primary><xsl:value-of select="@name"/></primary><secondary><xsl:value-of select="$basename"/></secondary></indexterm>
 128 <programlisting>'<xsl:value-of select="@name"/>'<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="2"/></xsl:call-template>
 129 <xsl:call-template name="property-args"><xsl:with-param name="indent" select="string-length(@name) + 2"/></xsl:call-template></programlisting>
 130   </refsect2>
 131
 132   <xsl:call-template name="property-doc"/>
 133
 134   </xsl:for-each>
 135 </xsl:template>
 136
 137 <xsl:template name="signal-doc">
 138   <xsl:apply-templates select="doc:doc/doc:description"/>
 139
 140   <variablelist role="params">
 141     <xsl:for-each select="arg">
 142 <varlistentry><term><parameter><xsl:value-of select="@name"/></parameter>:</term>
 143 <listitem><simpara><xsl:value-of select="doc:doc/doc:summary"/></simpara></listitem>
 144 </varlistentry>
 145     </xsl:for-each>
 146   </variablelist>
 147
 148   <xsl:apply-templates select="doc:doc/doc:since"/>
 149   <xsl:apply-templates select="doc:doc/doc:deprecated"/>
 150   <xsl:apply-templates select="doc:doc/doc:permission"/>
 151   <xsl:apply-templates select="doc:doc/doc:seealso"/>
 152 </xsl:template>
 153
 154 <xsl:template name="signal-details">
 155   <xsl:param name="basename"/>
 156   <xsl:variable name="longest">
 157     <xsl:call-template name="find-longest">
 158       <xsl:with-param name="set" select="@name"/>
 159     </xsl:call-template>
 160   </xsl:variable>
 161   <xsl:for-each select="///signal">
 162   <refsect2>
 163     <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>
 164 <indexterm><primary><xsl:value-of select="@name"/></primary><secondary><xsl:value-of select="$basename"/></secondary></indexterm>
 165 <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>
 166   </refsect2>
 167
 168   <xsl:call-template name="signal-doc"/>
 169
 170   </xsl:for-each>
 171 </xsl:template>
 172
 173 <xsl:template match="doc:code">
 174 <programlisting>
 175 <xsl:apply-templates />
 176 </programlisting>
 177 </xsl:template>
 178
 179 <xsl:template match="doc:summary">
 180 <!-- by default don't display -->
 181 </xsl:template>
 182
 183 <xsl:template match="doc:example">
 184 <informalexample>
 185 <xsl:apply-templates />
 186 </informalexample>
 187 </xsl:template>
 188
 189 <xsl:template match="doc:para">
 190 <para>
 191 <xsl:apply-templates />
 192 </para>
 193 </xsl:template>
 194
 195 <xsl:template match="doc:description">
 196 <xsl:apply-templates />
 197 </xsl:template>
 198
 199 <xsl:template match="doc:since">
 200 <para role="since">Since <xsl:value-of select="@version"/>
 201 </para>
 202 </xsl:template>
 203
 204 <xsl:template match="doc:deprecated">
 205   <xsl:variable name="name" select="../../@name"/>
 206   <xsl:variable name="parent">
 207     <xsl:call-template name="interface-basename">
 208       <xsl:with-param name="str" select="../../../@name"/>/>
 209     </xsl:call-template>
 210   </xsl:variable>
 211
 212   <xsl:variable name="type" select="name(../..)"/>
 213
 214   <para role="deprecated">
 215   <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
 216
 217   <xsl:variable name="to">
 218   <xsl:choose>
 219     <xsl:when test="contains($type,'property')">
 220       <xsl:value-of select="$parent"/>:<xsl:value-of select="@instead"/>
 221     </xsl:when>
 222     <xsl:when test="contains($type,'signal')">
 223       <xsl:value-of select="$parent"/>::<xsl:value-of select="@instead"/>
 224     </xsl:when>
 225     <xsl:when test="contains($type,'method')">
 226       <xsl:value-of select="$parent"/>.<xsl:value-of select="@instead"/>
 227     </xsl:when>
 228     <xsl:when test="contains($type,'interface')">
 229       <xsl:value-of select="@instead"/>
 230     </xsl:when>
 231     <xsl:otherwise>
 232       <xsl:value-of select="@instead"/>
 233     </xsl:otherwise>
 234   </xsl:choose>
 235   </xsl:variable>
 236
 237   <xsl:call-template name="create-link">
 238     <xsl:with-param name="type" select="$type"/>
 239     <xsl:with-param name="to" select="$to"/>
 240     <xsl:with-param name="val" select="@instead"/>
 241   </xsl:call-template>
 242 instead.</para></warning>
 243 </para>
 244 </xsl:template>
 245
 246 <xsl:template match="doc:permission">
 247 <para role="permission">
 248 <xsl:apply-templates />
 249 </para>
 250 </xsl:template>
 251
 252 <xsl:template match="doc:seealso">
 253 <para>
 254 See also:
 255 <xsl:apply-templates />
 256
 257 </para>
 258 </xsl:template>
 259
 260 <xsl:template name="create-link">
 261   <xsl:param name="type"/>
 262   <xsl:param name="to"/>
 263   <xsl:param name="val"/>
 264
 265   <xsl:choose>
 266     <xsl:when test="contains($type,'property')">
 267       <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><literal><xsl:value-of select="$val"/></literal></link>
 268     </xsl:when>
 269     <xsl:when test="contains($type,'signal')">
 270       <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><literal><xsl:value-of select="$val"/></literal></link>
 271     </xsl:when>
 272     <xsl:when test="contains($type,'method')">
 273       <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><function><xsl:value-of select="$val"/></function></link>
 274     </xsl:when>
 275     <xsl:when test="contains($type,'interface')">
 276       <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><xsl:value-of select="$val"/></link>
 277     </xsl:when>
 278   </xsl:choose>
 279 </xsl:template>
 280
 281 <xsl:template match="doc:ref">
 282   <xsl:call-template name="create-link">
 283     <xsl:with-param name="type" select="@type"/>
 284     <xsl:with-param name="to" select="@to"/>
 285     <xsl:with-param name="val" select="."/>
 286   </xsl:call-template>
 287 </xsl:template>
 288
 289 <xsl:template name="method-doc">
 290   <xsl:apply-templates select="doc:doc/doc:description"/>
 291
 292   <variablelist role="params">
 293     <xsl:for-each select="arg">
 294 <varlistentry><term><parameter><xsl:value-of select="@name"/></parameter>:</term>
 295 <listitem><simpara><xsl:value-of select="doc:doc/doc:summary"/></simpara></listitem>
 296 </varlistentry>
 297     </xsl:for-each>
 298   </variablelist>
 299
 300   <xsl:apply-templates select="doc:doc/doc:since"/>
 301   <xsl:apply-templates select="doc:doc/doc:deprecated"/>
 302   <xsl:apply-templates select="doc:doc/doc:permission"/>
 303   <xsl:apply-templates select="doc:doc/doc:seealso"/>
 304 </xsl:template>
 305
 306 <xsl:template name="method-details">
 307   <xsl:param name="basename"/>
 308   <xsl:variable name="longest">
 309     <xsl:call-template name="find-longest">
 310       <xsl:with-param name="set" select="@name"/>
 311     </xsl:call-template>
 312   </xsl:variable>
 313   <xsl:for-each select="///method">
 314     <refsect2>
 315     <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>
 316 <indexterm><primary><xsl:value-of select="@name"/></primary><secondary><xsl:value-of select="$basename"/></secondary></indexterm>
 317 <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>
 318     </refsect2>
 319
 320     <xsl:call-template name="method-doc"/>
 321
 322   </xsl:for-each>
 323 </xsl:template>
 324
 325
 326 <xsl:template name="properties-synopsis">
 327   <xsl:param name="basename"/>
 328   <xsl:variable name="longest">
 329     <xsl:call-template name="find-longest">
 330       <xsl:with-param name="set" select="///property/@name"/>
 331     </xsl:call-template>
 332   </xsl:variable>
 333   <xsl:for-each select="///property">
 334 <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>
 335 </xsl:for-each>
 336 </xsl:template>
 337
 338
 339 <xsl:template name="signals-synopsis">
 340   <xsl:param name="basename"/>
 341   <xsl:variable name="longest">
 342     <xsl:call-template name="find-longest">
 343       <xsl:with-param name="set" select="///signal/@name"/>
 344     </xsl:call-template>
 345   </xsl:variable>
 346   <xsl:for-each select="///signal">
 347 <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>)
 348 </xsl:for-each>
 349 </xsl:template>
 350
 351
 352 <xsl:template name="methods-synopsis">
 353   <xsl:param name="basename"/>
 354   <xsl:variable name="longest">
 355     <xsl:call-template name="find-longest">
 356       <xsl:with-param name="set" select="///method/@name"/>
 357     </xsl:call-template>
 358   </xsl:variable>
 359   <xsl:for-each select="///method">
 360 <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>)
 361 </xsl:for-each>
 362 </xsl:template>
 363
 364
 365 <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"/>
 366 <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>
 367 <xsl:value-of select="@name"/><xsl:if test="not(position() = last())">,
 368 <xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$indent"/></xsl:call-template></xsl:if>
 369 </xsl:for-each>
 370 </xsl:template>
 371
 372
 373 <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>
 374 <xsl:value-of select="@name"/><xsl:if test="not(position() = last())">,
 375 <xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$indent"/></xsl:call-template></xsl:if>
 376 </xsl:for-each>
 377 </xsl:template>
 378
 379
 380 <xsl:template name="property-args"><xsl:param name="indent"/>
 381 <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"/>'
 382 </xsl:template>
 383
 384
 385 <xsl:template name="pad-spaces">
 386   <xsl:param name="width"/>
 387   <xsl:variable name="spaces" xml:space="preserve">                                                                        </xsl:variable>
 388   <xsl:value-of select="substring($spaces,1,$width)"/>
 389 </xsl:template>
 390
 391
 392 <xsl:template name="find-longest">
 393   <xsl:param name="set"/>
 394   <xsl:param name="index" select="1"/>
 395   <xsl:param name="longest" select="0"/>
 396
 397   <xsl:choose>
 398     <xsl:when test="$index > count($set)">
 399       <!--finished looking-->
 400       <xsl:value-of select="$longest"/>
 401     </xsl:when>
 402     <xsl:when test="string-length($set[$index])>$longest">
 403       <!--found new longest-->
 404       <xsl:call-template name="find-longest">
 405         <xsl:with-param name="set" select="$set"/>
 406         <xsl:with-param name="index" select="$index + 1"/>
 407         <xsl:with-param name="longest" select="string-length($set[$index])"/>
 408       </xsl:call-template>
 409     </xsl:when>
 410     <xsl:otherwise>
 411       <!--this isn't any longer-->
 412       <xsl:call-template name="find-longest">
 413         <xsl:with-param name="set" select="$set"/>
 414         <xsl:with-param name="index" select="$index + 1"/>
 415         <xsl:with-param name="longest" select="$longest"/>
 416       </xsl:call-template>
 417     </xsl:otherwise>
 418   </xsl:choose>
 419 </xsl:template>
 420
 421
 422 <xsl:template name="interface-basename">
 423   <xsl:param name="str"/>
 424   <xsl:choose>
 425     <xsl:when test="contains($str,'.')">
 426       <xsl:call-template name="interface-basename">
 427         <xsl:with-param name="str" select="substring-after($str,'.')"/>
 428       </xsl:call-template>
 429     </xsl:when>
 430     <xsl:otherwise>
 431       <xsl:value-of select="$str"/>
 432     </xsl:otherwise>
 433   </xsl:choose>
 434 </xsl:template>
 435
 436 </xsl:stylesheet>