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