VirtualBox

source: vbox/trunk/doc/manual/xidl2docbook.xsl@ 54558

Last change on this file since 54558 was 46213, checked in by vboxsync, 11 years ago

doc/manual: move id= to the chapter tags, the PDF conversion expects them to be there (and it avoids dangling links with HTML, see previous doc/manual change)
File size: 19.1 KB
Line 
1<?xml version="1.0"?>
2
3<!--
4 xidl2docbook.xsl:
5 XSLT stylesheet that generates docbook from
6 VirtualBox.xidl.
7
8 Copyright (C) 2006-2012 Oracle Corporation
9
10 This file is part of VirtualBox Open Source Edition (OSE), as
11 available from http://www.virtualbox.org. This file is free software;
12 you can redistribute it and/or modify it under the terms of the GNU
13 General Public License (GPL) as published by the Free Software
14 Foundation, in version 2 as it comes in the "COPYING" file of the
15 VirtualBox OSE distribution. VirtualBox OSE is distributed in the
16 hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
17-->
18
19<xsl:stylesheet
20 version="1.0"
21 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
22 xmlns:exsl="http://exslt.org/common"
23 extension-element-prefixes="exsl">
24
25 <xsl:output
26 method="xml"
27 version="1.0"
28 encoding="utf-8"
29 indent="yes"/>
30
31 <xsl:strip-space elements="*"/>
32
33<!-- - - - - - - - - - - - - - - - - - - - - - -
34 global XSLT variables
35 - - - - - - - - - - - - - - - - - - - - - - -->
36
37<xsl:variable name="G_xsltFilename" select="'glue-jaxws.xsl'" />
38
39<!-- collect all interfaces with "wsmap='suppress'" in a global variable for
40 quick lookup -->
41<xsl:variable name="G_setSuppressedInterfaces"
42 select="//interface[@wsmap='suppress']" />
43
44<xsl:template name="makeLinkId">
45 <xsl:param name="ifname" />
46 <xsl:param name="member" />
47 <xsl:value-of select="concat($ifname, '__', $member)"/>
48</xsl:template>
49
50<xsl:template name="emitType">
51 <xsl:param name="type" />
52 <xsl:choose>
53 <xsl:when test="$type">
54 <xsl:choose>
55 <xsl:when test="//interface[@name=$type]">
56 <xref>
57 <xsl:attribute name="apiref">yes</xsl:attribute>
58 <xsl:attribute name="linkend">
59 <xsl:value-of select="translate($type, ':', '_')" />
60 </xsl:attribute>
61 <xsl:value-of select="$type" />
62 </xref>
63 </xsl:when>
64 <xsl:when test="//enum[@name=$type]">
65 <xref>
66 <xsl:attribute name="apiref">yes</xsl:attribute>
67 <xsl:attribute name="linkend">
68 <xsl:value-of select="translate($type, ':', '_')" />
69 </xsl:attribute>
70 <xsl:value-of select="$type" />
71 </xref>
72 </xsl:when>
73 <xsl:otherwise>
74 <xsl:value-of select="$type" />
75 </xsl:otherwise>
76 </xsl:choose>
77 </xsl:when>
78 <xsl:otherwise>
79 <xsl:value-of select="'void'" />
80 </xsl:otherwise>
81 </xsl:choose>
82</xsl:template>
83
84<xsl:template name="isWebserviceOnly">
85 <xsl:for-each select="ancestor-or-self::*">
86 <xsl:if test="(name()='if') and (@target='wsdl')">
87 <xsl:text>yes</xsl:text>
88 </xsl:if>
89 </xsl:for-each>
90</xsl:template>
91
92
93<!-- - - - - - - - - - - - - - - - - - - - - - -
94 root match
95 - - - - - - - - - - - - - - - - - - - - - - -->
96
97<xsl:template match="/idl">
98 <chapter id="sdkref_classes">
99 <title>Classes (interfaces)</title>
100 <xsl:for-each select="//interface">
101 <xsl:sort select="@name"/>
102
103 <!-- ignore those interfaces within module sections; they don't have uuid -->
104 <xsl:if test="@uuid">
105 <xsl:variable name="ifname" select="@name" />
106 <xsl:variable name="wsmap" select="@wsmap" />
107 <xsl:variable name="wscpp" select="@wscpp" />
108 <xsl:variable name="wsonly"><xsl:call-template name="isWebserviceOnly" /></xsl:variable>
109 <xsl:variable name="extends" select="@extends" />
110 <xsl:variable name="reportExtends" select="not($extends='$unknown') and not($extends='$errorinfo')" />
111
112 <sect1>
113 <xsl:attribute name="id">
114 <xsl:value-of select="$ifname" />
115 </xsl:attribute>
116 <title><xsl:value-of select="$ifname" />
117 <xsl:if test="$reportExtends">
118 <xsl:value-of select="concat(' (', @extends, ')')" />
119 </xsl:if>
120 </title>
121
122 <xsl:choose>
123 <xsl:when test="$wsmap='suppress'">
124 <note>
125 This interface is not supported in the web service.
126 </note>
127 </xsl:when>
128 <xsl:when test="$wsmap='struct'">
129 <note>With the web service, this interface is mapped to a structure. Attributes that return this interface will not return an object, but a complete structure
130 containing the attributes listed below as structure members.</note>
131 </xsl:when>
132 <xsl:when test="$wsonly='yes'">
133 <note>This interface is supported in the web service only, not in COM/XPCOM.</note>
134 </xsl:when>
135 </xsl:choose>
136
137 <xsl:if test="$reportExtends">
138 <note>
139 This interface extends
140 <xref>
141 <xsl:attribute name="apiref">yes</xsl:attribute>
142 <xsl:attribute name="linkend"><xsl:value-of select="$extends" /></xsl:attribute>
143 <xsl:value-of select="$extends" />
144 </xref>
145 and therefore supports all its methods and attributes as well.
146 </note>
147 </xsl:if>
148
149 <xsl:apply-templates select="desc" />
150
151 <xsl:if test="attribute">
152 <sect2>
153 <title>Attributes</title>
154 <xsl:for-each select="attribute">
155 <xsl:variable name="attrtype" select="@type" />
156 <sect3>
157 <xsl:attribute name="id">
158 <xsl:call-template name="makeLinkId">
159 <xsl:with-param name="ifname" select="$ifname" />
160 <xsl:with-param name="member" select="@name" />
161 </xsl:call-template>
162 </xsl:attribute>
163 <title>
164 <xsl:choose>
165 <xsl:when test="@readonly='yes'">
166 <xsl:value-of select="concat(@name, ' (read-only)')" />
167 </xsl:when>
168 <xsl:otherwise>
169 <xsl:value-of select="concat(@name, ' (read/write)')" />
170 </xsl:otherwise>
171 </xsl:choose>
172 </title>
173 <programlisting>
174 <xsl:call-template name="emitType">
175 <xsl:with-param name="type" select="$attrtype" />
176 </xsl:call-template>
177 <xsl:value-of select="concat(' ', $ifname, '::', @name)" />
178 <xsl:if test="(@array='yes') or (@safearray='yes')">
179 <xsl:text>[]</xsl:text>
180 </xsl:if>
181 </programlisting>
182 <xsl:if test="( ($attrtype=($G_setSuppressedInterfaces/@name)) )">
183 <note>
184 This attribute is not supported in the web service.
185 </note>
186 </xsl:if>
187 <xsl:apply-templates select="desc" />
188 </sect3>
189 </xsl:for-each>
190 </sect2>
191 </xsl:if>
192
193 <xsl:if test="method">
194<!-- <sect2> -->
195<!-- <title>Methods</title> -->
196 <xsl:for-each select="method">
197 <xsl:sort select="@name" />
198 <xsl:variable name="returnidltype" select="param[@dir='return']/@type" />
199 <sect2>
200 <xsl:attribute name="id">
201 <xsl:call-template name="makeLinkId">
202 <xsl:with-param name="ifname" select="$ifname" />
203 <xsl:with-param name="member" select="@name" />
204 </xsl:call-template>
205 </xsl:attribute>
206 <title>
207 <xsl:value-of select="@name" />
208 </title>
209 <xsl:if test=" (param[@type=($G_setSuppressedInterfaces/@name)])
210 or (param[@mod='ptr'])" >
211 <note>
212 This method is not supported in the web service.
213 </note>
214 </xsl:if>
215 <!-- make a set of all parameters with in and out direction -->
216 <xsl:variable name="paramsinout" select="param[@dir='in' or @dir='out']" />
217 <programlisting>
218 <!--emit return type-->
219 <xsl:call-template name="emitType">
220 <xsl:with-param name="type" select="$returnidltype" />
221 </xsl:call-template>
222 <xsl:if test="(param[@dir='return']/@array='yes') or (param[@dir='return']/@safearray='yes')">
223 <xsl:text>[]</xsl:text>
224 </xsl:if>
225 <xsl:value-of select="concat(' ', $ifname, '::', @name, '(')" />
226 <xsl:if test="$paramsinout">
227 <xsl:for-each select="$paramsinout">
228 <xsl:text>&#10;</xsl:text>
229 <xsl:value-of select="concat(' [', @dir, '] ')" />
230 <xsl:if test="@mod = 'ptr'">
231 <xsl:text>[ptr] </xsl:text>
232 </xsl:if>
233 <xsl:call-template name="emitType">
234 <xsl:with-param name="type" select="@type" />
235 </xsl:call-template>
236 <emphasis role="bold">
237 <xsl:value-of select="concat(' ', @name)" />
238 </emphasis>
239 <xsl:if test="(@array='yes') or (@safearray='yes')">
240 <xsl:text>[]</xsl:text>
241 </xsl:if>
242 <xsl:if test="not(position()=last())">
243 <xsl:text>, </xsl:text>
244 </xsl:if>
245 </xsl:for-each>
246 </xsl:if>
247 <xsl:text>)</xsl:text>
248 </programlisting>
249
250 <xsl:if test="$paramsinout">
251 <glosslist>
252 <xsl:for-each select="$paramsinout">
253 <glossentry>
254 <glossterm>
255 <xsl:value-of select="@name" />
256 </glossterm>
257 <glossdef>
258 <para>
259 <xsl:apply-templates select="desc" />
260 </para>
261 </glossdef>
262 </glossentry>
263 </xsl:for-each>
264 </glosslist>
265 </xsl:if>
266
267 <!-- dump the description here -->
268 <xsl:apply-templates select="desc" />
269
270 <xsl:if test="desc/result">
271 <para>If this method fails, the following error codes may be reported:</para>
272 <itemizedlist>
273 <xsl:for-each select="desc/result">
274 <listitem>
275 <para><code><xsl:value-of select="@name" />: </code>
276 <xsl:apply-templates />
277 </para>
278 </listitem>
279 </xsl:for-each>
280 </itemizedlist>
281 </xsl:if>
282 </sect2>
283 </xsl:for-each>
284<!-- </sect2> -->
285 </xsl:if>
286
287 </sect1>
288 </xsl:if>
289 </xsl:for-each>
290 </chapter>
291
292 <chapter id="sdkref_enums">
293 <title>Enumerations (enums)</title>
294 <xsl:for-each select="//enum">
295 <xsl:sort select="@name"/>
296
297 <xsl:variable name="ifname" select="@name" />
298 <xsl:variable name="wsmap" select="@wsmap" />
299 <xsl:variable name="wscpp" select="@wscpp" />
300
301 <sect1>
302 <xsl:attribute name="id">
303 <xsl:value-of select="$ifname" />
304 </xsl:attribute>
305 <title><xsl:value-of select="$ifname" /></title>
306
307 <xsl:apply-templates select="desc" />
308
309 <glosslist>
310 <xsl:for-each select="const">
311 <glossentry>
312 <glossterm>
313 <xsl:attribute name="id">
314 <xsl:call-template name="makeLinkId">
315 <xsl:with-param name="ifname" select="$ifname" />
316 <xsl:with-param name="member" select="@name" />
317 </xsl:call-template>
318 </xsl:attribute>
319 <xsl:value-of select="@name" />
320 </glossterm>
321 <glossdef>
322 <xsl:apply-templates select="desc" />
323 </glossdef>
324 </glossentry>
325 </xsl:for-each>
326 </glosslist>
327 </sect1>
328 </xsl:for-each>
329 </chapter>
330
331</xsl:template>
332
333<!-- - - - - - - - - - - - - - - - - - - - - - -
334 if
335 - - - - - - - - - - - - - - - - - - - - - - -->
336
337<!--
338 * ignore all |if|s except those for WSDL target
339-->
340<xsl:template match="if">
341 <xsl:if test="@target='wsdl'">
342 <xsl:apply-templates/>
343 </xsl:if>
344</xsl:template>
345
346<!-- - - - - - - - - - - - - - - - - - - - - - -
347 cpp
348 - - - - - - - - - - - - - - - - - - - - - - -->
349
350<xsl:template match="cpp">
351<!-- ignore this -->
352</xsl:template>
353
354<!-- - - - - - - - - - - - - - - - - - - - - - -
355 result
356 - - - - - - - - - - - - - - - - - - - - - - -->
357
358<xsl:template match="result">
359 <!-- ignore this, we handle them explicitly in method loops -->
360</xsl:template>
361
362<!-- - - - - - - - - - - - - - - - - - - - - - -
363 library
364 - - - - - - - - - - - - - - - - - - - - - - -->
365
366<xsl:template match="library">
367 <xsl:apply-templates />
368</xsl:template>
369
370<!-- - - - - - - - - - - - - - - - - - - - - - -
371 class
372 - - - - - - - - - - - - - - - - - - - - - - -->
373
374<xsl:template match="module/class">
375<!-- TODO swallow for now -->
376</xsl:template>
377
378<!-- - - - - - - - - - - - - - - - - - - - - - -
379 enum
380 - - - - - - - - - - - - - - - - - - - - - - -->
381
382<xsl:template match="enum">
383</xsl:template>
384
385<!-- - - - - - - - - - - - - - - - - - - - - - -
386 const
387 - - - - - - - - - - - - - - - - - - - - - - -->
388
389<!--
390<xsl:template match="const">
391 <xsl:apply-templates />
392</xsl:template>
393-->
394
395<!-- - - - - - - - - - - - - - - - - - - - - - -
396 desc
397 - - - - - - - - - - - - - - - - - - - - - - -->
398
399<xsl:template match="desc">
400 <xsl:apply-templates />
401</xsl:template>
402
403<xsl:template name="getCurrentInterface">
404 <xsl:for-each select="ancestor-or-self::*">
405 <xsl:if test="name()='interface'">
406 <xsl:value-of select="@name"/>
407 </xsl:if>
408 </xsl:for-each>
409</xsl:template>
410
411<!-- <link to="DeviceType::HardDisk"/> -->
412<xsl:template match="link">
413 <xref>
414 <xsl:attribute name="apiref">yes</xsl:attribute>
415 <xsl:variable name="tmp" select="@to" />
416 <xsl:variable name="enumNameFromCombinedName">
417 <xsl:value-of select="substring-before($tmp, '_')" />
418 </xsl:variable>
419 <xsl:variable name="enumValueFromCombinedName">
420 <xsl:value-of select="substring-after($tmp, '_')" />
421 </xsl:variable>
422 <xsl:choose>
423 <xsl:when test="//interface[@name=$tmp] or //enum[@name=$tmp]"><!-- link to interface only -->
424 <xsl:attribute name="linkend"><xsl:value-of select="@to" /></xsl:attribute>
425 <xsl:value-of select="$tmp" />
426 </xsl:when>
427 <xsl:when test="//enum[@name=$enumNameFromCombinedName]">
428 <xsl:attribute name="linkend">
429 <xsl:value-of select="concat($enumNameFromCombinedName, '__', $enumValueFromCombinedName)" />
430 </xsl:attribute>
431 <xsl:value-of select="$enumValueFromCombinedName" />
432 </xsl:when>
433 <xsl:otherwise>
434 <xsl:variable name="currentif">
435 <xsl:call-template name="getCurrentInterface" />
436 </xsl:variable>
437 <xsl:variable name="if"><!-- interface -->
438 <xsl:choose>
439 <xsl:when test="contains(@to, '#')">
440 <xsl:value-of select="$currentif" />
441 </xsl:when>
442 <xsl:otherwise>
443 <xsl:value-of select="substring-before(@to, '::')" />
444 </xsl:otherwise>
445 </xsl:choose>
446 </xsl:variable>
447 <xsl:variable name="member"><!-- member in that interface -->
448 <xsl:choose>
449 <xsl:when test="contains(@to, '#')">
450 <xsl:value-of select="substring-after(@to, '#')" />
451 </xsl:when>
452 <xsl:otherwise>
453 <xsl:value-of select="substring-after(@to, '::')" />
454 </xsl:otherwise>
455 </xsl:choose>
456 </xsl:variable>
457
458 <xsl:attribute name="linkend"><xsl:value-of select="concat($if, '__', $member)" /></xsl:attribute>
459 <xsl:variable name="autotextsuffix">
460 <xsl:choose>
461 <!-- if link points to a method, append "()" -->
462 <xsl:when test="//interface[@name=$if]/method[@name=$member]">
463 <xsl:value-of select="'()'" />
464 </xsl:when>
465 <!-- if link points to a safearray attribute, append "[]" -->
466 <xsl:when test="//interface[@name=$if]/attribute[@name=$member]/@safearray = 'yes'">
467 <xsl:value-of select="'[]'" />
468 </xsl:when>
469 <xsl:when test="//interface[@name=$if]/attribute[@name=$member]">
470 </xsl:when>
471 <xsl:when test="//enum[@name=$if]/const[@name=$member]">
472 </xsl:when>
473 <xsl:when test="//result[@name=$tmp]">
474 </xsl:when>
475 <xsl:otherwise>
476 <xsl:message terminate="yes">
477 <xsl:value-of select="concat('Invalid link pointing to &quot;', $tmp, '&quot;')" />
478 </xsl:message>
479 </xsl:otherwise>
480 </xsl:choose>
481 </xsl:variable>
482 <xsl:choose>
483 <xsl:when test="./text()"><!-- link text given in source -->
484 <xsl:apply-templates />
485 </xsl:when>
486 <xsl:when test="$if=$currentif"><!-- "near" link to method or attribute in current interface -->
487 <xsl:value-of select="concat($member, $autotextsuffix)" />
488 </xsl:when>
489 <xsl:otherwise><!-- "far" link to other method or attribute -->
490 <xsl:value-of select="concat($if, '::', $member, $autotextsuffix)" />
491 </xsl:otherwise>
492 </xsl:choose>
493 </xsl:otherwise>
494 </xsl:choose>
495 </xref>
496</xsl:template>
497
498<!-- - - - - - - - - - - - - - - - - - - - - - -
499 note
500 - - - - - - - - - - - - - - - - - - - - - - -->
501
502<xsl:template match="note">
503 <xsl:if test="not(@internal='yes')">
504 <note>
505 <xsl:apply-templates />
506 </note>
507 </xsl:if>
508</xsl:template>
509
510<xsl:template match="tt">
511 <computeroutput>
512 <xsl:apply-templates />
513 </computeroutput>
514</xsl:template>
515
516<xsl:template match="b">
517 <emphasis role="bold">
518 <xsl:apply-templates />
519 </emphasis>
520</xsl:template>
521
522<xsl:template match="i">
523 <emphasis>
524 <xsl:apply-templates />
525 </emphasis>
526</xsl:template>
527
528<xsl:template match="see">
529 <xsl:text>See also: </xsl:text>
530 <xsl:apply-templates />
531</xsl:template>
532
533<xsl:template match="ul">
534 <itemizedlist>
535 <xsl:apply-templates />
536 </itemizedlist>
537</xsl:template>
538
539<xsl:template match="ol">
540 <orderedlist>
541 <xsl:apply-templates />
542 </orderedlist>
543</xsl:template>
544
545<xsl:template match="li">
546 <listitem>
547 <xsl:apply-templates />
548 </listitem>
549</xsl:template>
550
551<xsl:template match="h3">
552 <emphasis role="bold">
553 <xsl:apply-templates />
554 </emphasis>
555</xsl:template>
556
557<xsl:template match="pre">
558 <screen><xsl:apply-templates /></screen>
559</xsl:template>
560
561<xsl:template match="table">
562 <xsl:apply-templates /> <!-- todo -->
563</xsl:template>
564
565</xsl:stylesheet>
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette