src/extension/dbus/doc/spec-to-docbook.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   <xsl:choose>
  41     <xsl:when test="count(///signal) > 0">
  42       <refsect1 role="signal_proto">
  43         <title role="signal_proto.title">Signals</title>
  44         <synopsis>
  45           <xsl:call-template name="signals-synopsis">
  46             <xsl:with-param name="basename" select="$basename"/>
  47           </xsl:call-template>
  48         </synopsis>
  49       </refsect1>
  50     </xsl:when>
  51   </xsl:choose>
  52
  53   <refsect1 role="impl_interfaces">
  54     <title role="impl_interfaces.title">Implemented Interfaces</title>
  55     <para>
  56     Objects implementing <xsl:value-of select="$interface"/> also implements
  57     org.freedesktop.DBus.Introspectable,
  58     org.freedesktop.DBus.Properties
  59     </para>
  60   </refsect1>
  61
  62   <xsl:choose>
  63     <xsl:when test="count(///property) > 0">
  64       <refsect1 role="properties">
  65         <title role="properties.title">Properties</title>
  66         <synopsis>
  67           <xsl:call-template name="properties-synopsis">
  68             <xsl:with-param name="basename" select="$basename"/>
  69           </xsl:call-template>
  70         </synopsis>
  71       </refsect1>
  72     </xsl:when>
  73   </xsl:choose>
  74
  75   <refsect1 role="desc">
  76     <title role="desc.title">Description</title>
  77     <para>
  78       <xsl:apply-templates select="//interface/doc:doc"/>
  79     </para>
  80   </refsect1>
  81
  82   <refsect1 role="details">
  83     <title role="details.title">Details</title>
  84     <xsl:call-template name="method-details">
  85       <xsl:with-param name="basename" select="$basename"/>
  86     </xsl:call-template>
  87   </refsect1>
  88
  89   <xsl:choose>
  90     <xsl:when test="count(///signal) > 0">
  91       <refsect1 role="signals">
  92         <title role="signals.title">Signal Details</title>
  93         <xsl:call-template name="signal-details">
  94           <xsl:with-param name="basename" select="$basename"/>
  95         </xsl:call-template>
  96       </refsect1>
  97     </xsl:when>
  98   </xsl:choose>
  99
 100   <xsl:choose>
 101     <xsl:when test="count(///property) > 0">
 102       <refsect1 role="property_details">
 103         <title role="property_details.title">Property Details</title>
 104         <xsl:call-template name="property-details">
 105           <xsl:with-param name="basename" select="$basename"/>
 106         </xsl:call-template>
 107       </refsect1>
 108     </xsl:when>
 109   </xsl:choose>
 110
 111 </refentry>
 112 </xsl:template>
 113
 114
 115 <xsl:template name="property-doc">
 116   <xsl:apply-templates select="doc:doc/doc:description"/>
 117
 118   <variablelist role="params">
 119     <xsl:for-each select="arg">
 120 <varlistentry><term><parameter><xsl:value-of select="@name"/></parameter>:</term>
 121 <listitem><simpara><xsl:value-of select="doc:doc/doc:summary"/></simpara></listitem>
 122 </varlistentry>
 123     </xsl:for-each>
 124   </variablelist>
 125
 126   <xsl:apply-templates select="doc:doc/doc:since"/>
 127   <xsl:apply-templates select="doc:doc/doc:deprecated"/>
 128   <xsl:apply-templates select="doc:doc/doc:permission"/>
 129   <xsl:apply-templates select="doc:doc/doc:seealso"/>
 130 </xsl:template>
 131
 132
 133 <xsl:template name="property-details">
 134   <xsl:param name="basename"/>
 135   <xsl:variable name="longest">
 136     <xsl:call-template name="find-longest">
 137       <xsl:with-param name="set" select="@name"/>
 138     </xsl:call-template>
 139   </xsl:variable>
 140   <xsl:for-each select="///property">
 141   <refsect2>
 142     <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>
 143 <indexterm><primary><xsl:value-of select="@name"/></primary><secondary><xsl:value-of select="$basename"/></secondary></indexterm>
 144 <programlisting>'<xsl:value-of select="@name"/>'<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="2"/></xsl:call-template>
 145 <xsl:call-template name="property-args"><xsl:with-param name="indent" select="string-length(@name) + 2"/></xsl:call-template></programlisting>
 146   </refsect2>
 147
 148   <xsl:call-template name="property-doc"/>
 149
 150   </xsl:for-each>
 151 </xsl:template>
 152
 153 <xsl:template name="signal-doc">
 154   <xsl:apply-templates select="doc:doc/doc:description"/>
 155
 156   <variablelist role="params">
 157     <xsl:for-each select="arg">
 158 <varlistentry><term><parameter><xsl:value-of select="@name"/></parameter>:</term>
 159 <listitem><simpara><xsl:value-of select="doc:doc/doc:summary"/></simpara></listitem>
 160 </varlistentry>
 161     </xsl:for-each>
 162   </variablelist>
 163
 164   <xsl:apply-templates select="doc:doc/doc:since"/>
 165   <xsl:apply-templates select="doc:doc/doc:deprecated"/>
 166   <xsl:apply-templates select="doc:doc/doc:permission"/>
 167   <xsl:apply-templates select="doc:doc/doc:seealso"/>
 168 </xsl:template>
 169
 170 <xsl:template name="signal-details">
 171   <xsl:param name="basename"/>
 172   <xsl:variable name="longest">
 173     <xsl:call-template name="find-longest">
 174       <xsl:with-param name="set" select="@name"/>
 175     </xsl:call-template>
 176   </xsl:variable>
 177   <xsl:for-each select="///signal">
 178   <refsect2>
 179     <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>
 180 <indexterm><primary><xsl:value-of select="@name"/></primary><secondary><xsl:value-of select="$basename"/></secondary></indexterm>
 181 <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>
 182   </refsect2>
 183
 184   <xsl:call-template name="signal-doc"/>
 185
 186   </xsl:for-each>
 187 </xsl:template>
 188
 189 <xsl:template match="doc:code">
 190 <programlisting>
 191 <xsl:apply-templates />
 192 </programlisting>
 193 </xsl:template>
 194
 195 <xsl:template match="doc:tt">
 196   <literal>
 197     <xsl:apply-templates />
 198   </literal>
 199 </xsl:template>
 200
 201 <xsl:template match="doc:i">
 202   <emphasis>
 203     <xsl:apply-templates />
 204   </emphasis>
 205 </xsl:template>
 206
 207 <xsl:template match="doc:b">
 208   <emphasis role="bold">
 209     <xsl:apply-templates />
 210   </emphasis>
 211 </xsl:template>
 212
 213 <xsl:template match="doc:ulink">
 214   <ulink>
 215     <xsl:attribute name="url"><xsl:value-of select="@url"/></xsl:attribute>
 216     <xsl:value-of select="."/>
 217   </ulink>
 218 </xsl:template>
 219
 220 <xsl:template match="doc:summary">
 221   <xsl:apply-templates />
 222 </xsl:template>
 223
 224 <xsl:template match="doc:example">
 225 <informalexample>
 226 <xsl:apply-templates />
 227 </informalexample>
 228 </xsl:template>
 229
 230 <xsl:template name="listitems-do-term">
 231   <xsl:param name="str"/>
 232   <xsl:choose>
 233     <xsl:when test="string-length($str) > 0">
 234       <emphasis role="bold"><xsl:value-of select="$str"/>: </emphasis>
 235     </xsl:when>
 236   </xsl:choose>
 237 </xsl:template>
 238
 239 <xsl:template name="do-listitems">
 240   <xsl:for-each select="doc:item">
 241     <listitem>
 242       <xsl:call-template name="listitems-do-term"><xsl:with-param name="str" select="doc:term"/></xsl:call-template>
 243       <xsl:apply-templates select="doc:definition"/>
 244     </listitem>
 245   </xsl:for-each>
 246 </xsl:template>
 247
 248 <xsl:template match="doc:list">
 249   <para>
 250     <xsl:choose>
 251       <xsl:when test="contains(@type,'number')">
 252         <orderedlist>
 253           <xsl:call-template name="do-listitems"/>
 254         </orderedlist>
 255       </xsl:when>
 256       <xsl:otherwise>
 257         <itemizedlist>
 258           <xsl:call-template name="do-listitems"/>
 259         </itemizedlist>
 260       </xsl:otherwise>
 261     </xsl:choose>
 262   </para>
 263 </xsl:template>
 264
 265 <xsl:template match="doc:para">
 266 <para>
 267 <xsl:apply-templates />
 268 </para>
 269 </xsl:template>
 270
 271 <xsl:template match="doc:description">
 272 <xsl:apply-templates />
 273 </xsl:template>
 274
 275 <xsl:template match="doc:since">
 276 <para role="since">Since <xsl:value-of select="@version"/>
 277 </para>
 278 </xsl:template>
 279
 280 <xsl:template match="doc:deprecated">
 281   <xsl:variable name="name" select="../../@name"/>
 282   <xsl:variable name="parent">
 283     <xsl:call-template name="interface-basename">
 284       <xsl:with-param name="str" select="../../../@name"/>/>
 285     </xsl:call-template>
 286   </xsl:variable>
 287
 288   <xsl:variable name="type" select="name(../..)"/>
 289
 290   <para role="deprecated">
 291   <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
 292
 293   <xsl:variable name="to">
 294   <xsl:choose>
 295     <xsl:when test="contains($type,'property')">
 296       <xsl:value-of select="$parent"/>:<xsl:value-of select="@instead"/>
 297     </xsl:when>
 298     <xsl:when test="contains($type,'signal')">
 299       <xsl:value-of select="$parent"/>::<xsl:value-of select="@instead"/>
 300     </xsl:when>
 301     <xsl:when test="contains($type,'method')">
 302       <xsl:value-of select="$parent"/>.<xsl:value-of select="@instead"/>
 303     </xsl:when>
 304     <xsl:when test="contains($type,'interface')">
 305       <xsl:value-of select="@instead"/>
 306     </xsl:when>
 307     <xsl:otherwise>
 308       <xsl:value-of select="@instead"/>
 309     </xsl:otherwise>
 310   </xsl:choose>
 311   </xsl:variable>
 312
 313   <xsl:call-template name="create-link">
 314     <xsl:with-param name="type" select="$type"/>
 315     <xsl:with-param name="to" select="$to"/>
 316     <xsl:with-param name="val" select="@instead"/>
 317   </xsl:call-template>
 318 instead.</para></warning>
 319 </para>
 320 </xsl:template>
 321
 322 <xsl:template match="doc:permission">
 323 <para role="permission">
 324 <xsl:apply-templates />
 325 </para>
 326 </xsl:template>
 327
 328 <xsl:template match="doc:errors">
 329 <para role="errors">
 330 <xsl:apply-templates />
 331 </para>
 332 </xsl:template>
 333
 334 <xsl:template match="doc:seealso">
 335 <para>
 336 See also:
 337 <xsl:apply-templates />
 338
 339 </para>
 340 </xsl:template>
 341
 342 <xsl:template name="create-link">
 343   <xsl:param name="type"/>
 344   <xsl:param name="to"/>
 345   <xsl:param name="val"/>
 346
 347   <xsl:choose>
 348     <xsl:when test="contains($type,'property')">
 349       <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><literal><xsl:value-of select="$val"/></literal></link>
 350     </xsl:when>
 351     <xsl:when test="contains($type,'signal')">
 352       <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><literal><xsl:value-of select="$val"/></literal></link>
 353     </xsl:when>
 354     <xsl:when test="contains($type,'method')">
 355       <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><function><xsl:value-of select="$val"/></function></link>
 356     </xsl:when>
 357     <xsl:when test="contains($type,'interface')">
 358       <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><xsl:value-of select="$val"/></link>
 359     </xsl:when>
 360   </xsl:choose>
 361 </xsl:template>
 362
 363 <xsl:template match="doc:ref">
 364   <xsl:call-template name="create-link">
 365     <xsl:with-param name="type" select="@type"/>
 366     <xsl:with-param name="to" select="@to"/>
 367     <xsl:with-param name="val" select="."/>
 368   </xsl:call-template>
 369 </xsl:template>
 370
 371 <xsl:template name="method-doc">
 372   <xsl:apply-templates select="doc:doc/doc:description"/>
 373
 374   <variablelist role="params">
 375     <xsl:for-each select="arg">
 376 <varlistentry><term><parameter><xsl:value-of select="@name"/></parameter>:</term>
 377 <listitem><simpara><xsl:apply-templates select="doc:doc/doc:summary"/></simpara></listitem>
 378 </varlistentry>
 379     </xsl:for-each>
 380   </variablelist>
 381
 382   <xsl:apply-templates select="doc:doc/doc:since"/>
 383   <xsl:apply-templates select="doc:doc/doc:deprecated"/>
 384
 385   <xsl:choose>
 386     <xsl:when test="count(doc:doc/doc:errors) > 0">
 387       <refsect3>
 388         <title>Errors</title>
 389         <variablelist role="errors">
 390           <xsl:for-each select="doc:doc/doc:errors/doc:error">
 391             <varlistentry>
 392               <term><parameter><xsl:value-of select="@name"/></parameter>:</term>
 393               <listitem><simpara><xsl:apply-templates select="."/></simpara></listitem>
 394             </varlistentry>
 395           </xsl:for-each>
 396         </variablelist>
 397       </refsect3>
 398     </xsl:when>
 399   </xsl:choose>
 400
 401   <xsl:choose>
 402     <xsl:when test="count(doc:doc/doc:permission) > 0">
 403       <refsect3>
 404         <title>Permissions</title>
 405         <xsl:apply-templates select="doc:doc/doc:permission"/>
 406       </refsect3>
 407     </xsl:when>
 408   </xsl:choose>
 409
 410   <xsl:apply-templates select="doc:doc/doc:seealso"/>
 411 </xsl:template>
 412
 413 <xsl:template name="method-details">
 414   <xsl:param name="basename"/>
 415   <xsl:variable name="longest">
 416     <xsl:call-template name="find-longest">
 417       <xsl:with-param name="set" select="@name"/>
 418     </xsl:call-template>
 419   </xsl:variable>
 420   <xsl:for-each select="///method">
 421     <refsect2>
 422     <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>
 423 <indexterm><primary><xsl:value-of select="@name"/></primary><secondary><xsl:value-of select="$basename"/></secondary></indexterm>
 424 <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>
 425     </refsect2>
 426
 427     <xsl:call-template name="method-doc"/>
 428
 429   </xsl:for-each>
 430 </xsl:template>
 431
 432
 433 <xsl:template name="properties-synopsis">
 434   <xsl:param name="basename"/>
 435   <xsl:variable name="longest">
 436     <xsl:call-template name="find-longest">
 437       <xsl:with-param name="set" select="///property/@name"/>
 438     </xsl:call-template>
 439   </xsl:variable>
 440   <xsl:for-each select="///property">
 441 <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>
 442 </xsl:for-each>
 443 </xsl:template>
 444
 445
 446 <xsl:template name="signals-synopsis">
 447   <xsl:param name="basename"/>
 448   <xsl:variable name="longest">
 449     <xsl:call-template name="find-longest">
 450       <xsl:with-param name="set" select="///signal/@name"/>
 451     </xsl:call-template>
 452   </xsl:variable>
 453   <xsl:for-each select="///signal">
 454 <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>)
 455 </xsl:for-each>
 456 </xsl:template>
 457
 458
 459 <xsl:template name="methods-synopsis">
 460   <xsl:param name="basename"/>
 461   <xsl:variable name="longest">
 462     <xsl:call-template name="find-longest">
 463       <xsl:with-param name="set" select="///method/@name"/>
 464     </xsl:call-template>
 465   </xsl:variable>
 466   <xsl:for-each select="///method">
 467 <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>)
 468 </xsl:for-each>
 469 </xsl:template>
 470
 471
 472 <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"/>
 473 <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>
 474 <xsl:value-of select="@name"/><xsl:if test="not(position() = last())">,
 475 <xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$indent"/></xsl:call-template></xsl:if>
 476 </xsl:for-each>
 477 </xsl:template>
 478
 479
 480 <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>
 481 <xsl:value-of select="@name"/><xsl:if test="not(position() = last())">,
 482 <xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$indent"/></xsl:call-template></xsl:if>
 483 </xsl:for-each>
 484 </xsl:template>
 485
 486
 487 <xsl:template name="property-args"><xsl:param name="indent"/>
 488 <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"/>'
 489 </xsl:template>
 490
 491
 492 <xsl:template name="pad-spaces">
 493   <xsl:param name="width"/>
 494   <xsl:variable name="spaces" xml:space="preserve">                                                                        </xsl:variable>
 495   <xsl:value-of select="substring($spaces,1,$width)"/>
 496 </xsl:template>
 497
 498
 499 <xsl:template name="find-longest">
 500   <xsl:param name="set"/>
 501   <xsl:param name="index" select="1"/>
 502   <xsl:param name="longest" select="0"/>
 503
 504   <xsl:choose>
 505     <xsl:when test="$index > count($set)">
 506       <!--finished looking-->
 507       <xsl:value-of select="$longest"/>
 508     </xsl:when>
 509     <xsl:when test="string-length($set[$index])>$longest">
 510       <!--found new longest-->
 511       <xsl:call-template name="find-longest">
 512         <xsl:with-param name="set" select="$set"/>
 513         <xsl:with-param name="index" select="$index + 1"/>
 514         <xsl:with-param name="longest" select="string-length($set[$index])"/>
 515       </xsl:call-template>
 516     </xsl:when>
 517     <xsl:otherwise>
 518       <!--this isn't any longer-->
 519       <xsl:call-template name="find-longest">
 520         <xsl:with-param name="set" select="$set"/>
 521         <xsl:with-param name="index" select="$index + 1"/>
 522         <xsl:with-param name="longest" select="$longest"/>
 523       </xsl:call-template>
 524     </xsl:otherwise>
 525   </xsl:choose>
 526 </xsl:template>
 527
 528
 529 <xsl:template name="interface-basename">
 530   <xsl:param name="str"/>
 531   <xsl:choose>
 532     <xsl:when test="contains($str,'.')">
 533       <xsl:call-template name="interface-basename">
 534         <xsl:with-param name="str" select="substring-after($str,'.')"/>
 535       </xsl:call-template>
 536     </xsl:when>
 537     <xsl:otherwise>
 538       <xsl:value-of select="$str"/>
 539     </xsl:otherwise>
 540   </xsl:choose>
 541 </xsl:template>
 542
 543 </xsl:stylesheet>
 544