Debian Codegraph @

doc/dbus/spec-to-docbook.xsl

raw
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:title">
272 <refsect2><title role="title.description"><anchor role="description"><xsl:attribute name="id"><xsl:value-of select="@id"/></xsl:attribute></anchor><xsl:value-of select="."/></title></refsect2>
273 </xsl:template>
274
275 <xsl:template match="doc:description">
276 <xsl:apply-templates />
277 </xsl:template>
278
279 <xsl:template match="doc:since">
280 <para role="since">Since <xsl:value-of select="@version"/>
281 </para>
282 </xsl:template>
283
284 <xsl:template match="doc:deprecated">
285 <xsl:variable name="name" select="../../@name"/>
286 <xsl:variable name="parent">
287 <xsl:call-template name="interface-basename">
288 <xsl:with-param name="str" select="../../../@name"/>/>
289 </xsl:call-template>
290 </xsl:variable>
291
292 <xsl:variable name="type" select="name(../..)"/>
293
294 <para role="deprecated">
295 <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
296
297 <xsl:variable name="to">
298 <xsl:choose>
299 <xsl:when test="contains($type,'property')">
300 <xsl:value-of select="$parent"/>:<xsl:value-of select="@instead"/>
301 </xsl:when>
302 <xsl:when test="contains($type,'signal')">
303 <xsl:value-of select="$parent"/>::<xsl:value-of select="@instead"/>
304 </xsl:when>
305 <xsl:when test="contains($type,'method')">
306 <xsl:value-of select="$parent"/>.<xsl:value-of select="@instead"/>
307 </xsl:when>
308 <xsl:when test="contains($type,'interface')">
309 <xsl:value-of select="@instead"/>
310 </xsl:when>
311 <xsl:otherwise>
312 <xsl:value-of select="@instead"/>
313 </xsl:otherwise>
314 </xsl:choose>
315 </xsl:variable>
316
317 <xsl:call-template name="create-link">
318 <xsl:with-param name="type" select="$type"/>
319 <xsl:with-param name="to" select="$to"/>
320 <xsl:with-param name="val" select="@instead"/>
321 </xsl:call-template>
322 instead.</para></warning>
323 </para>
324 </xsl:template>
325
326 <xsl:template match="doc:permission">
327 <para role="permission">
328 <xsl:apply-templates />
329 </para>
330 </xsl:template>
331
332 <xsl:template match="doc:errors">
333 <para role="errors">
334 <xsl:apply-templates />
335 </para>
336 </xsl:template>
337
338 <xsl:template match="doc:seealso">
339 <para>
340 See also:
341 <xsl:apply-templates />
342
343 </para>
344 </xsl:template>
345
346 <xsl:template name="create-link">
347 <xsl:param name="type"/>
348 <xsl:param name="to"/>
349 <xsl:param name="val"/>
350
351 <xsl:choose>
352 <xsl:when test="contains($type,'property')">
353 <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><literal><xsl:value-of select="$val"/></literal></link>
354 </xsl:when>
355 <xsl:when test="contains($type,'signal')">
356 <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><literal><xsl:value-of select="$val"/></literal></link>
357 </xsl:when>
358 <xsl:when test="contains($type,'method')">
359 <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><function><xsl:value-of select="$val"/></function></link>
360 </xsl:when>
361 <xsl:when test="contains($type,'interface')">
362 <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><xsl:value-of select="$val"/></link>
363 </xsl:when>
364 <xsl:when test="contains($type,'description')">
365 <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><xsl:value-of select="$val"/></link>
366 </xsl:when>
367 </xsl:choose>
368 </xsl:template>
369
370 <xsl:template match="doc:ref">
371 <xsl:call-template name="create-link">
372 <xsl:with-param name="type" select="@type"/>
373 <xsl:with-param name="to" select="@to"/>
374 <xsl:with-param name="val" select="."/>
375 </xsl:call-template>
376 </xsl:template>
377
378 <xsl:template name="method-doc">
379 <xsl:apply-templates select="doc:doc/doc:description"/>
380
381 <variablelist role="params">
382 <xsl:for-each select="arg">
383 <varlistentry><term><parameter><xsl:value-of select="@name"/></parameter>:</term>
384 <listitem><simpara><xsl:apply-templates select="doc:doc/doc:summary"/></simpara></listitem>
385 </varlistentry>
386 </xsl:for-each>
387 </variablelist>
388
389 <xsl:apply-templates select="doc:doc/doc:since"/>
390 <xsl:apply-templates select="doc:doc/doc:deprecated"/>
391
392 <xsl:choose>
393 <xsl:when test="count(doc:doc/doc:errors) > 0">
394 <refsect3>
395 <title>Errors</title>
396 <variablelist role="errors">
397 <xsl:for-each select="doc:doc/doc:errors/doc:error">
398 <varlistentry>
399 <term><parameter><xsl:value-of select="@name"/></parameter>:</term>
400 <listitem><simpara><xsl:apply-templates select="."/></simpara></listitem>
401 </varlistentry>
402 </xsl:for-each>
403 </variablelist>
404 </refsect3>
405 </xsl:when>
406 </xsl:choose>
407
408 <xsl:choose>
409 <xsl:when test="count(doc:doc/doc:permission) > 0">
410 <refsect3>
411 <title>Permissions</title>
412 <xsl:apply-templates select="doc:doc/doc:permission"/>
413 </refsect3>
414 </xsl:when>
415 </xsl:choose>
416
417 <xsl:apply-templates select="doc:doc/doc:seealso"/>
418 </xsl:template>
419
420 <xsl:template name="method-details">
421 <xsl:param name="basename"/>
422 <xsl:variable name="longest">
423 <xsl:call-template name="find-longest">
424 <xsl:with-param name="set" select="@name"/>
425 </xsl:call-template>
426 </xsl:variable>
427 <xsl:for-each select="///method">
428 <refsect2>
429 <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>
430 <indexterm><primary><xsl:value-of select="@name"/></primary><secondary><xsl:value-of select="$basename"/></secondary></indexterm>
431 <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>
432 </refsect2>
433
434 <xsl:call-template name="method-doc"/>
435
436 </xsl:for-each>
437 </xsl:template>
438
439
440 <xsl:template name="properties-synopsis">
441 <xsl:param name="basename"/>
442 <xsl:variable name="longest">
443 <xsl:call-template name="find-longest">
444 <xsl:with-param name="set" select="///property/@name"/>
445 </xsl:call-template>
446 </xsl:variable>
447 <xsl:for-each select="///property">
448 <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>
449 </xsl:for-each>
450 </xsl:template>
451
452
453 <xsl:template name="signals-synopsis">
454 <xsl:param name="basename"/>
455 <xsl:variable name="longest">
456 <xsl:call-template name="find-longest">
457 <xsl:with-param name="set" select="///signal/@name"/>
458 </xsl:call-template>
459 </xsl:variable>
460 <xsl:for-each select="///signal">
461 <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>)
462 </xsl:for-each>
463 </xsl:template>
464
465
466 <xsl:template name="methods-synopsis">
467 <xsl:param name="basename"/>
468 <xsl:variable name="longest">
469 <xsl:call-template name="find-longest">
470 <xsl:with-param name="set" select="///method/@name"/>
471 </xsl:call-template>
472 </xsl:variable>
473 <xsl:for-each select="///method">
474 <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>)
475 </xsl:for-each>
476 </xsl:template>
477
478
479 <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"/>
480 <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>
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="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>
488 <xsl:value-of select="@name"/><xsl:if test="not(position() = last())">,
489 <xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$indent"/></xsl:call-template></xsl:if>
490 </xsl:for-each>
491 </xsl:template>
492
493
494 <xsl:template name="property-args"><xsl:param name="indent"/>
495 <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"/>'
496 </xsl:template>
497
498
499 <xsl:template name="pad-spaces">
500 <xsl:param name="width"/>
501 <xsl:variable name="spaces" xml:space="preserve"> </xsl:variable>
502 <xsl:value-of select="substring($spaces,1,$width)"/>
503 </xsl:template>
504
505
506 <xsl:template name="find-longest">
507 <xsl:param name="set"/>
508 <xsl:param name="index" select="1"/>
509 <xsl:param name="longest" select="0"/>
510
511 <xsl:choose>
512 <xsl:when test="$index > count($set)">
513 <!--finished looking-->
514 <xsl:value-of select="$longest"/>
515 </xsl:when>
516 <xsl:when test="string-length($set[$index])>$longest">
517 <!--found new longest-->
518 <xsl:call-template name="find-longest">
519 <xsl:with-param name="set" select="$set"/>
520 <xsl:with-param name="index" select="$index + 1"/>
521 <xsl:with-param name="longest" select="string-length($set[$index])"/>
522 </xsl:call-template>
523 </xsl:when>
524 <xsl:otherwise>
525 <!--this isn't any longer-->
526 <xsl:call-template name="find-longest">
527 <xsl:with-param name="set" select="$set"/>
528 <xsl:with-param name="index" select="$index + 1"/>
529 <xsl:with-param name="longest" select="$longest"/>
530 </xsl:call-template>
531 </xsl:otherwise>
532 </xsl:choose>
533 </xsl:template>
534
535
536 <xsl:template name="interface-basename">
537 <xsl:param name="str"/>
538 <xsl:choose>
539 <xsl:when test="contains($str,'.')">
540 <xsl:call-template name="interface-basename">
541 <xsl:with-param name="str" select="substring-after($str,'.')"/>
542 </xsl:call-template>
543 </xsl:when>
544 <xsl:otherwise>
545 <xsl:value-of select="$str"/>
546 </xsl:otherwise>
547 </xsl:choose>
548 </xsl:template>
549
550 </xsl:stylesheet>