VirtualBox

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

Last change on this file since 103131 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

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