VirtualBox

source: vbox/trunk/doc/manual/docbook-refentry-to-manual-dita.xsl@ 99116

最後變更 在這個檔案從99116是 99101,由 vboxsync 提交於 2 年 前

manual: More work on the refentry to dita converter. bugref:10302

  • 屬性 svn:eol-style 設為 native
  • 屬性 svn:keywords 設為 Author Date Id Revision
檔案大小: 19.0 KB
 
1<?xml version="1.0"?>
2<!--
3 docbook-refentry-to-manual-sect1.xsl:
4 XSLT stylesheet for converting a refentry (manpage)
5 to dita for use in the user manual.
6-->
7<!--
8 Copyright (C) 2006-2023 Oracle and/or its affiliates.
9
10 This file is part of VirtualBox base platform packages, as
11 available from https://www.alldomusa.eu.org.
12
13 This program is free software; you can redistribute it and/or
14 modify it under the terms of the GNU General Public License
15 as published by the Free Software Foundation, in version 3 of the
16 License.
17
18 This program is distributed in the hope that it will be useful, but
19 WITHOUT ANY WARRANTY; without even the implied warranty of
20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21 General Public License for more details.
22
23 You should have received a copy of the GNU General Public License
24 along with this program; if not, see <https://www.gnu.org/licenses>.
25
26 SPDX-License-Identifier: GPL-3.0-only
27-->
28
29<xsl:stylesheet
30 version="1.0"
31 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
32 xmlns:str="http://xsltsl.org/string"
33 >
34
35 <xsl:import href="string.xsl"/>
36
37 <xsl:output method="xml" version="1.0" encoding="utf-8" indent="yes"/>
38 <xsl:strip-space elements="*"/>
39
40
41<!-- - - - - - - - - - - - - - - - - - - - - - -
42 global XSLT variables
43 - - - - - - - - - - - - - - - - - - - - - - -->
44
45
46
47<!-- - - - - - - - - - - - - - - - - - - - - - -
48 base operation is to fail on nodes w/o explicit matching.
49 - - - - - - - - - - - - - - - - - - - - - - -->
50
51<xsl:template match="*">
52 <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>unhandled element</xsl:message>
53</xsl:template>
54
55
56<!-- - - - - - - - - - - - - - - - - - - - - - -
57 transformations starting with root and going deeper.
58 - - - - - - - - - - - - - - - - - - - - - - -->
59
60<!-- Rename refentry to reference.
61 Also we need to wrap the refsync and refsect1 elements in a refbody. -->
62<xsl:template match="refentry">
63 <xsl:text disable-output-escaping='yes'>&lt;!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd"&gt;</xsl:text>
64
65 <xsl:element name="reference">
66 <xsl:if test="not(@id)">
67 <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>refentry must have an id attribute!</xsl:message>
68 </xsl:if>
69 <xsl:attribute name="rev">refentry</xsl:attribute>
70 <xsl:attribute name="id"><xsl:value-of select="@id"/></xsl:attribute>
71
72 <!-- Copy title element from refentryinfo -->
73 <xsl:if test="./refentryinfo/title">
74 <xsl:copy-of select="./refentryinfo/title"/>
75 </xsl:if>
76
77 <!-- Create a shortdesc element from the text in refnamediv/refpurpose -->
78 <xsl:if test="./refnamediv/refpurpose">
79 <xsl:element name="shortdesc">
80 <xsl:attribute name="rev">refnamediv/refpurpose</xsl:attribute>
81 <xsl:call-template name="capitalize">
82 <xsl:with-param name="text" select="normalize-space(./refnamediv/refpurpose)"/>
83 </xsl:call-template>
84 </xsl:element>
85 </xsl:if>
86
87 <!-- Put everything else side a refbody element -->
88 <xsl:element name="refbody">
89 <xsl:apply-templates />
90 </xsl:element>
91
92 </xsl:element>
93</xsl:template>
94
95<!-- Remove refentryinfo (we extracted the title element already). -->
96<xsl:template match="refentryinfo" />
97
98<!-- Remove refmeta (manpage info). -->
99<xsl:template match="refmeta"/>
100
101<!-- Remove the refnamediv (we extracted a shortdesc from it already). -->
102<xsl:template match="refnamediv"/>
103
104<!-- Morph the refsynopsisdiv part into a refsyn section. -->
105<xsl:template match="refsynopsisdiv">
106 <xsl:if test="name(*[1]) != 'cmdsynopsis'"><xsl:message terminate="yes">Expected refsynopsisdiv to start with cmdsynopsis</xsl:message></xsl:if>
107 <xsl:if test="title"><xsl:message terminate="yes">No title element supported in refsynopsisdiv</xsl:message></xsl:if>
108
109 <xsl:element name="refsyn">
110 <xsl:attribute name="rev">refsynopsisdiv</xsl:attribute>
111 <xsl:element name="title">
112 <xsl:text>Synopsis</xsl:text>
113 </xsl:element>
114 <xsl:apply-templates />
115 </xsl:element>
116
117</xsl:template>
118
119<!-- refsect1 -> section -->
120<xsl:template match="refsect1">
121 <xsl:if test="not(title)"><xsl:message terminate="yes">refsect1 requires title</xsl:message></xsl:if>
122 <xsl:element name="section">
123 <xsl:attribute name="rev">refsect1</xsl:attribute>
124 <xsl:if test="@id">
125 <xsl:attribute name="id"><xsl:value-of select="@id"/></xsl:attribute>
126 </xsl:if>
127 <xsl:apply-templates />
128 </xsl:element>
129</xsl:template>
130
131<!-- refsect2 -> sectiondiv. -->
132<xsl:template match="refsect2">
133 <xsl:if test="not(title)"><xsl:message terminate="yes">refsect2 requires title</xsl:message></xsl:if>
134 <xsl:element name="sectiondiv">
135 <xsl:attribute name="rev">refsect2</xsl:attribute>
136 <xsl:if test="@id">
137 <xsl:attribute name="id"><xsl:value-of select="@id"/></xsl:attribute>
138 </xsl:if>
139
140 <xsl:apply-templates />
141
142 </xsl:element>
143</xsl:template>
144
145<!-- refsect2/title -> b -->
146<xsl:template match="refsect2/title">
147 <xsl:element name="b">
148 <xsl:attribute name="rev">refsect2/title</xsl:attribute>
149 <xsl:apply-templates />
150 </xsl:element>
151</xsl:template>
152
153<!-- refsect1/title -> title -->
154<xsl:template match="refsect1/title">
155 <xsl:copy>
156 <xsl:apply-templates />
157 </xsl:copy>
158</xsl:template>
159
160<!-- para -> p -->
161<xsl:template match="para">
162 <xsl:element name="p">
163 <xsl:attribute name="rev">para</xsl:attribute>
164 <xsl:apply-templates />
165 </xsl:element>
166</xsl:template>
167
168<!-- note in a section -> note (no change needed) -->
169<xsl:template match="refsect1/note | refsect2/note">
170 <xsl:copy>
171 <xsl:apply-templates />
172 </xsl:copy>
173</xsl:template>
174
175<!-- variablelist -> dl -->
176<xsl:template match="variablelist">
177 <xsl:element name="dl">
178 <xsl:attribute name="rev">variablelist</xsl:attribute>
179 <xsl:apply-templates />
180 </xsl:element>
181</xsl:template>
182
183<!-- varlistentry -> dlentry -->
184<xsl:template match="varlistentry">
185 <xsl:element name="dlentry">
186 <xsl:attribute name="rev">varlistentry</xsl:attribute>
187 <xsl:apply-templates />
188 </xsl:element>
189</xsl:template>
190
191<!-- term (in varlistentry) -> dt -->
192<xsl:template match="varlistentry/term">
193 <xsl:element name="dt">
194 <xsl:attribute name="rev">term</xsl:attribute>
195 <xsl:apply-templates />
196 </xsl:element>
197</xsl:template>
198
199<!-- listitem (in varlistentry) -> dd -->
200<xsl:template match="varlistentry/listitem">
201 <xsl:element name="dd">
202 <xsl:attribute name="rev">listitem</xsl:attribute>
203 <xsl:apply-templates />
204 </xsl:element>
205</xsl:template>
206
207<!-- itemizedlist -> ul -->
208<xsl:template match="itemizedlist">
209 <xsl:element name="ul">
210 <xsl:attribute name="rev">itemizedlist</xsl:attribute>
211 <xsl:apply-templates />
212 </xsl:element>
213</xsl:template>
214
215<!-- listitem in itemizedlist -> li -->
216<xsl:template match="itemizedlist/listitem">
217 <xsl:element name="li">
218 <xsl:attribute name="rev">listitem</xsl:attribute>
219 <xsl:apply-templates />
220 </xsl:element>
221</xsl:template>
222
223<!-- command in cmdsynopsis -> syntaxdiagram
224 If sbr is used, this gets a bit more complicated... -->
225<xsl:template match="cmdsynopsis[not(sbr)]">
226 <xsl:element name="syntaxdiagram">
227 <xsl:attribute name="rev">cmdsynopsis</xsl:attribute>
228 <xsl:if test="@id">
229 <xsl:attribute name="id"><xsl:value-of select="@id"/></xsl:attribute>
230 </xsl:if>
231 <xsl:apply-templates />
232 </xsl:element>
233</xsl:template>
234
235<!-- This isn't working.
236<xsl:key name="G_keyUpToNextSbr"
237 match="cmdsynopsis/node()[not(self::sbr)]"
238 use="generate-id((..|preceding-sibling::sbr[1])[last()])"/>
239
240<xsl:template match="cmdsynopsis[sbr]">
241 <xsl:element name="syntaxdiagram">
242 <xsl:attribute name="rev">cmdsynopsis</xsl:attribute>
243 <xsl:if test="@id">
244 <xsl:attribute name="id"><xsl:value-of select="@id"/></xsl:attribute>
245 </xsl:if>
246 <xsl:element name="groupcomp">
247 <xsl:attribute name="rev">sbr/0</xsl:attribute>
248 <xsl:apply-templates select="key('G_keyUpToNextSbr', generate-id())"/>
249 </xsl:element>
250 <xsl:apply-templates select="sbr"/>
251 </xsl:element>
252</xsl:template>
253
254<xsl:template match="cmdsynopsis/sbr">
255 <xsl:element name="groupcomp">
256 <xsl:attribute name="rev">sbr/n</xsl:attribute>
257 <xsl:apply-templates select="key('G_keyUpToNextSbr', generate-id())"/>
258 </xsl:element>
259</xsl:template>
260-->
261<xsl:template match="cmdsynopsis[sbr]">
262 <xsl:if test="count(sbr) != 1">
263 <xsl:message terminate="yes">Currently only support a single sbr element in a cmdsynopsis. Sorry.</xsl:message>
264 </xsl:if>
265 <xsl:element name="syntaxdiagram">
266 <xsl:attribute name="rev">cmdsynopsis</xsl:attribute>
267 <xsl:if test="@id">
268 <xsl:attribute name="id"><xsl:value-of select="@id"/></xsl:attribute>
269 </xsl:if>
270 <xsl:element name="groupcomp">
271 <xsl:apply-templates select="sbr[1]/preceding-sibling::node()"/>
272 </xsl:element>
273 <xsl:apply-templates select="sbr[1]/following-sibling::node()"/>
274 </xsl:element>
275</xsl:template>
276
277
278<!-- command in cmdsynopsis -> groupseq + kwd -->
279<xsl:template match="cmdsynopsis/command | cmdsynopsis/*/command" >
280 <xsl:element name="groupseq">
281 <xsl:attribute name="rev">command</xsl:attribute>
282 <xsl:element name="kwd">
283 <xsl:attribute name="rev">command</xsl:attribute>
284 <xsl:apply-templates />
285 </xsl:element>
286 </xsl:element>
287</xsl:template>
288
289<!-- command in not cmdsynopsis -> userinput -->
290<xsl:template match="command">
291 <xsl:element name="userinput">
292 <xsl:attribute name="rev">command</xsl:attribute>
293 <xsl:apply-templates />
294 </xsl:element>
295</xsl:template>
296
297<!-- arg -->
298<xsl:template match="arg/text()">
299 <xsl:element name="kwd">
300 <xsl:attribute name="rev">arg</xsl:attribute>
301 <xsl:value-of select="."/>
302 </xsl:element>
303</xsl:template>
304
305<xsl:template match="arg[(not(@choice) or @choice='opt') and (not(@rep) or @rep='norepeat')]" >
306 <xsl:element name="groupseq">
307 <xsl:attribute name="rev">arg[opt,norepeat]</xsl:attribute>
308 <xsl:attribute name="importance">optional</xsl:attribute>
309 <xsl:apply-templates />
310 </xsl:element>
311</xsl:template>
312
313<xsl:template match="arg[@choice='req' and (not(@rep) or @rep='norepeat')]" >
314 <xsl:element name="groupseq">
315 <xsl:attribute name="rev">arg[req,norepeat]</xsl:attribute>
316 <xsl:attribute name="importance">required</xsl:attribute>
317 <xsl:apply-templates />
318 </xsl:element>
319</xsl:template>
320
321<xsl:template match="arg[not(*) and not(ancestor::group) and ancestor::cmdsynopsis and @choice='plain' and (not(@rep) or @rep='norepeat')]" >
322 <xsl:element name="kwd">
323 <xsl:attribute name="rev">arg[plain]</xsl:attribute>
324 <xsl:apply-templates />
325 </xsl:element>
326</xsl:template>
327
328<xsl:template match="group/arg[replaceable and @choice='plain' and (not(@rep) or @rep='norepeat')]" >
329 <xsl:if test="./*[not(self::replaceable)] or ./text()">
330 <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>
331 Did not expect group/arg[@choice=plain] to have children other than replaceable:
332 <xsl:for-each select="./*|./text()">
333 <xsl:value-of select="concat(', ', name(.))"/>
334 </xsl:for-each>
335 </xsl:message>
336 </xsl:if>
337 <xsl:element name="var">
338 <xsl:attribute name="rev">arg[plain]/replaceable</xsl:attribute>
339 <xsl:value-of select="."/>
340 </xsl:element>
341</xsl:template>
342
343<xsl:template match="group/arg[@choice='plain' and (not(@rep) or @rep='norepeat') and not(replaceable)]" >
344 <xsl:if test="./*">
345 <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Did not expect arg[@choice=plain] to have children
346 <xsl:for-each select="./*">
347 <xsl:text>
348 </xsl:text>
349 <xsl:value-of select="name()"/>
350 </xsl:for-each>
351 </xsl:message>
352 </xsl:if>
353 <xsl:element name="kwd">
354 <xsl:attribute name="rev">arg[plain]</xsl:attribute>
355 <xsl:value-of select="."/>
356 </xsl:element>
357</xsl:template>
358
359<xsl:template match="arg[(not(@choice) or @choice='opt') and @rep='repeat' and not(ancestor::group) and not(group)]" >
360 <xsl:element name="groupseq">
361 <xsl:attribute name="rev">arg[opt,repeat]</xsl:attribute>
362 <xsl:attribute name="importance">optional</xsl:attribute>
363 <xsl:apply-templates />
364 <xsl:element name="repsep">
365 <xsl:attribute name="rev">arg[opt,repeat]</xsl:attribute>
366 <xsl:text>...</xsl:text>
367 </xsl:element>
368 </xsl:element>
369</xsl:template>
370
371
372<!-- replaceable under arg -> var -->
373<xsl:template match="arg/replaceable" >
374 <xsl:element name="var">
375 <xsl:attribute name="rev">replaceable</xsl:attribute>
376 <xsl:apply-templates />
377 </xsl:element>
378</xsl:template>
379
380<!-- replaceable in para or term -> synph+var -->
381<xsl:template match="para/replaceable | term/replaceable | screen/replaceable" >
382 <xsl:element name="synph">
383 <xsl:attribute name="rev">replaceable</xsl:attribute>
384 <xsl:element name="var">
385 <xsl:attribute name="rev">replaceable</xsl:attribute>
386 <xsl:apply-templates />
387 </xsl:element>
388 </xsl:element>
389</xsl:template>
390
391<!-- replaceable in option -> var -->
392<xsl:template match="option/replaceable" >
393 <xsl:element name="var">
394 <xsl:attribute name="rev">option/replaceable</xsl:attribute>
395 <xsl:apply-templates />
396 </xsl:element>
397</xsl:template>
398
399<!-- replaceable in computeroutput -> varname -->
400<xsl:template match="computeroutput/replaceable" >
401 <xsl:element name="varname">
402 <xsl:attribute name="rev">computeroutput/replaceable</xsl:attribute>
403 <xsl:apply-templates />
404 </xsl:element>
405</xsl:template>
406
407<!-- group under arg and cmdsynopsis -> groupchoice -->
408<xsl:template match="arg/group[@choice='plain'] | cmdsynopsis/group[@choice='plain']">
409 <xsl:element name="groupchoice">
410 <xsl:attribute name="rev">group</xsl:attribute>
411 <xsl:apply-templates />
412 </xsl:element>
413</xsl:template>
414
415<xsl:template match="arg/group[@choice='req'] | cmdsynopsis/group[@choice='req']">
416 <xsl:element name="groupchoice">
417 <xsl:attribute name="rev">group</xsl:attribute>
418 <xsl:attribute name="importance">required</xsl:attribute>
419 <xsl:apply-templates />
420 </xsl:element>
421</xsl:template>
422
423<xsl:template match="cmdsynopsis/group[(@choice='opt' or not(@choice)) and (not(@rep) or @rep='norepeat')]" >
424 <xsl:if test="not(./arg[@choice='plain'])">
425 <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Did not expect group[@choice=opt] to have children other than arg[@choice=plain]:
426 <xsl:for-each select="node()"><xsl:value-of select="concat(' ', name())"/>[@choice=<xsl:value-of select="@choice"/>]</xsl:for-each>
427 </xsl:message>
428 </xsl:if>
429 <xsl:element name="groupchoice">
430 <xsl:attribute name="rev">group[opt]</xsl:attribute>
431 <xsl:attribute name="importance">optional</xsl:attribute>
432 <xsl:value-of select="."/>
433 </xsl:element>
434</xsl:template>
435
436<!-- option -->
437<xsl:template match="option/text()" >
438 <xsl:element name="kwd">
439 <xsl:attribute name="rev">option</xsl:attribute>
440 <xsl:value-of select="."/>
441 </xsl:element>
442</xsl:template>
443
444<xsl:template match="option" >
445 <xsl:element name="synph">
446 <xsl:attribute name="rev">option</xsl:attribute>
447 <xsl:apply-templates />
448 </xsl:element>
449</xsl:template>
450
451<!-- literal w/o sub-elements -> codeph -->
452<xsl:template match="literal[not(*)]" >
453 <xsl:element name="codeph">
454 <xsl:attribute name="rev">literal</xsl:attribute>
455 <xsl:apply-templates />
456 </xsl:element>
457</xsl:template>
458
459<!-- literal with replaceable sub-elements -> synph -->
460<xsl:template match="literal[replaceable]" >
461 <xsl:element name="synph">
462 <xsl:attribute name="rev">literal/replaceable</xsl:attribute>
463 <xsl:for-each select="node()">
464 <xsl:choose>
465 <xsl:when test="self::text()">
466 <xsl:element name="kwd">
467 <xsl:value-of select="."/>
468 </xsl:element>
469 </xsl:when>
470 <xsl:when test="self::replaceable">
471 <xsl:if test="./*">
472 <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Unexpected literal/replaceable child</xsl:message>
473 </xsl:if>
474 <xsl:element name="var">
475 <xsl:value-of select="."/>
476 </xsl:element>
477 </xsl:when>
478 <xsl:otherwise>
479 <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Unexpected literal child:
480 <xsl:value-of select="name(.)" />
481 </xsl:message>
482 </xsl:otherwise>
483 </xsl:choose>
484 </xsl:for-each>
485 </xsl:element>
486</xsl:template>
487
488<!-- filename -> filepath -->
489<xsl:template match="filename" >
490 <xsl:element name="filepath">
491 <xsl:attribute name="rev">filename</xsl:attribute>
492 <xsl:apply-templates />
493 </xsl:element>
494</xsl:template>
495
496<!-- screen - pass thru -->
497<xsl:template match="screen" >
498 <xsl:copy>
499 <xsl:apply-templates />
500 </xsl:copy>
501</xsl:template>
502
503<!-- computeroutput -> systemoutput-->
504<xsl:template match="computeroutput">
505 <xsl:element name="systemoutput">
506 <xsl:attribute name="rev">computeroutput</xsl:attribute>
507 <xsl:apply-templates />
508 </xsl:element>
509</xsl:template>
510
511<!-- xref -> xref, but attributes differ. -->
512<xsl:template match="xref">
513 <xsl:element name="xref">
514 <xsl:attribute name="href"><xsl:value-of select="@linkend"/></xsl:attribute>
515 <xsl:if test="contains(@linkend, 'http')">
516 <xsl:attribute name="scope">external</xsl:attribute>
517 <xsl:apply-templates />
518 </xsl:if>
519 </xsl:element>
520</xsl:template>
521
522<!-- emphasis -> i -->
523<xsl:template match="emphasis">
524 <xsl:if test="*">
525 <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Did not expect emphasis to have children!</xsl:message>
526 </xsl:if>
527 <xsl:element name="i">
528 <xsl:attribute name="rev">emphasis</xsl:attribute>
529 <xsl:apply-templates />
530 </xsl:element>
531</xsl:template>
532
533<!--
534 remark extensions:
535 -->
536<!-- Default: remove all remarks. -->
537<xsl:template match="remark"/>
538
539
540<!--
541 Captializes the given text.
542 -->
543<xsl:template name="capitalize">
544 <xsl:param name="text"/>
545 <xsl:call-template name="str:to-upper">
546 <xsl:with-param name="text" select="substring($text,1,1)"/>
547 </xsl:call-template>
548 <xsl:value-of select="substring($text,2)"/>
549</xsl:template>
550
551<!--
552 Debug/Diagnostics: Return the path to the specified node (by default the current).
553 -->
554<xsl:template name="get-node-path">
555 <xsl:param name="Node" select="."/>
556 <xsl:for-each select="$Node">
557 <xsl:for-each select="ancestor-or-self::node()">
558 <xsl:choose>
559 <xsl:when test="name(.) = ''">
560 <xsl:text>text()</xsl:text>
561 </xsl:when>
562 <xsl:otherwise>
563 <xsl:value-of select="concat('/', name(.))"/>
564 <xsl:choose>
565 <xsl:when test="@id">
566 <xsl:text>[@id=</xsl:text>
567 <xsl:value-of select="@id"/>
568 <xsl:text>]</xsl:text>
569 </xsl:when>
570 <xsl:when test="position() > 1">
571 <xsl:text>[</xsl:text><xsl:value-of select="position()"/><xsl:text>]</xsl:text>
572 </xsl:when>
573 </xsl:choose>
574 </xsl:otherwise>
575 </xsl:choose>
576 </xsl:for-each>
577 </xsl:for-each>
578</xsl:template>
579
580<!--
581 Debug/Diagnostics: Return error message prefix.
582 -->
583<xsl:template name="error-prefix">
584 <xsl:param name="Node" select="."/>
585 <xsl:text>error: </xsl:text>
586 <xsl:call-template name="get-node-path">
587 <xsl:with-param name="Node" select="$Node"/>
588 </xsl:call-template>
589 <xsl:text>: </xsl:text>
590</xsl:template>
591
592</xsl:stylesheet>
593
注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

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