VirtualBox

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

Last change on this file since 99270 was 99270, checked in by vboxsync, 2 years ago

manual: More work on the refentry to dita converter. bugref:10302
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 37.6 KB
Line 
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.virtualbox.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 <xsl:import href="common-formatcfg.xsl"/>
37
38 <xsl:output method="xml" version="1.0" encoding="utf-8" indent="no"/>
39 <xsl:preserve-space elements="*"/>
40 <!-- xsl:strip-space elements="*"/ - never -->
41
42
43<!-- - - - - - - - - - - - - - - - - - - - - - -
44 parameters
45 - - - - - - - - - - - - - - - - - - - - - - -->
46<!-- Replace dashes with non-breaking dashes.
47 Note! If the monospace font used in the PDF doesn't support it,
48 then '#' shows up instead for instance. This is currently
49 the case, so it's disabled by default. When we switch to
50 4.0.x with the latest com.elovirta.pdf plugin (2023-03-xx
51 or later), we can enable this by default again. -->
52<xsl:param name="g_fReplaceHypens">false</xsl:param>
53
54<!-- Render the syntax diagram more as text than as proper markup. -->
55<xsl:param name="g_fRenderSyntaxAsText">true</xsl:param>
56
57
58<!-- - - - - - - - - - - - - - - - - - - - - - -
59 global XSLT variables
60 - - - - - - - - - - - - - - - - - - - - - - -->
61
62
63
64<!-- - - - - - - - - - - - - - - - - - - - - - -
65 base operation is to fail on nodes w/o explicit matching.
66 - - - - - - - - - - - - - - - - - - - - - - -->
67
68<xsl:template match="*">
69 <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>unhandled element</xsl:message>
70</xsl:template>
71
72
73<!-- - - - - - - - - - - - - - - - - - - - - - -
74 transformations starting with root and going deeper.
75 - - - - - - - - - - - - - - - - - - - - - - -->
76
77<!-- Rename refentry to reference.
78 Also we need to wrap the refsync and refsect1 elements in a refbody. -->
79<xsl:template match="refentry">
80 <xsl:text disable-output-escaping='yes'>&lt;!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd"&gt;
81</xsl:text>
82
83 <xsl:element name="reference">
84 <xsl:if test="not(@id)">
85 <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>refentry must have an id attribute!</xsl:message>
86 </xsl:if>
87 <xsl:attribute name="rev">refentry</xsl:attribute>
88 <xsl:attribute name="id"><xsl:value-of select="@id"/></xsl:attribute>
89
90 <!-- Copy title element from refentryinfo -->
91 <xsl:if test="./refentryinfo/title">
92 <xsl:copy-of select="./refentryinfo/title"/>
93 </xsl:if>
94
95 <!-- Create a shortdesc element from the text in refnamediv/refpurpose -->
96 <xsl:if test="./refnamediv/refpurpose">
97 <xsl:element name="shortdesc">
98 <xsl:attribute name="rev">refnamediv/refpurpose</xsl:attribute>
99 <xsl:call-template name="capitalize">
100 <xsl:with-param name="text" select="normalize-space(./refnamediv/refpurpose)"/>
101 </xsl:call-template>
102 </xsl:element>
103 </xsl:if>
104
105 <!-- Put everything else side a refbody element -->
106 <xsl:element name="refbody">
107 <xsl:apply-templates />
108 </xsl:element>
109
110 </xsl:element>
111</xsl:template>
112
113<!-- Remove refentryinfo (we extracted the title element already). -->
114<xsl:template match="refentryinfo" />
115
116<!-- Remove refmeta (manpage info). -->
117<xsl:template match="refmeta"/>
118
119<!-- Remove the refnamediv (we extracted a shortdesc from it already). -->
120<xsl:template match="refnamediv"/>
121
122<!-- Morph the refsynopsisdiv part into a refsyn section. -->
123<xsl:template match="refsynopsisdiv">
124 <xsl:if test="name(*[1]) != 'cmdsynopsis'"><xsl:message terminate="yes">Expected refsynopsisdiv to start with cmdsynopsis</xsl:message></xsl:if>
125 <xsl:if test="title"><xsl:message terminate="yes">No title element supported in refsynopsisdiv</xsl:message></xsl:if>
126
127 <xsl:element name="refsyn">
128 <xsl:attribute name="rev">refsynopsisdiv</xsl:attribute>
129 <xsl:element name="title">
130 <xsl:text>Synopsis</xsl:text>
131 </xsl:element>
132 <xsl:apply-templates />
133 </xsl:element>
134
135</xsl:template>
136
137<!-- refsect1 -> section -->
138<xsl:template match="refsect1">
139 <xsl:if test="not(title)"><xsl:message terminate="yes">refsect1 requires title</xsl:message></xsl:if>
140 <xsl:element name="section">
141 <xsl:attribute name="rev">refsect1</xsl:attribute>
142 <xsl:if test="@id">
143 <xsl:attribute name="id"><xsl:value-of select="@id"/></xsl:attribute>
144 </xsl:if>
145 <xsl:apply-templates />
146 </xsl:element>
147</xsl:template>
148
149<!-- refsect2 -> sectiondiv. -->
150<xsl:template match="refsect2">
151 <xsl:if test="not(title)"><xsl:message terminate="yes">refsect2 requires title</xsl:message></xsl:if>
152 <xsl:element name="sectiondiv">
153 <xsl:attribute name="rev">refsect2</xsl:attribute>
154 <xsl:attribute name="outputclass">refsect2</xsl:attribute> <!-- how to make xhtml pass these thru... -->
155 <xsl:if test="@id">
156 <xsl:attribute name="id"><xsl:value-of select="@id"/></xsl:attribute>
157 </xsl:if>
158
159 <xsl:apply-templates />
160
161 </xsl:element>
162</xsl:template>
163
164<!-- refsect2/title -> b -->
165<xsl:template match="refsect2/title">
166 <xsl:element name="b">
167 <xsl:attribute name="rev">refsect2/title</xsl:attribute>
168 <xsl:attribute name="outputclass">refsect2title</xsl:attribute> <!-- how to make xhtml pass these thru... -->
169 <xsl:apply-templates />
170 </xsl:element>
171</xsl:template>
172
173<!-- refsect1/title -> title -->
174<xsl:template match="refsect1/title">
175 <xsl:copy>
176 <xsl:apply-templates />
177 </xsl:copy>
178</xsl:template>
179
180<!-- para -> p -->
181<xsl:template match="para">
182 <xsl:element name="p">
183 <xsl:attribute name="rev">para</xsl:attribute>
184 <xsl:apply-templates />
185 </xsl:element>
186</xsl:template>
187
188<!-- note in a section -> note (no change needed) -->
189<xsl:template match="refsect1/note | refsect2/note">
190 <xsl:copy>
191 <xsl:apply-templates />
192 </xsl:copy>
193</xsl:template>
194
195<!-- variablelist -> parml -->
196<xsl:template match="variablelist">
197 <xsl:element name="parml">
198 <xsl:attribute name="rev">variablelist</xsl:attribute>
199 <xsl:apply-templates />
200 </xsl:element>
201</xsl:template>
202
203<!-- varlistentry -> plentry -->
204<xsl:template match="varlistentry">
205 <xsl:element name="plentry">
206 <xsl:attribute name="rev">varlistentry</xsl:attribute>
207 <xsl:apply-templates />
208 </xsl:element>
209</xsl:template>
210
211<!-- term (in varlistentry) -> pt -->
212<xsl:template match="varlistentry/term">
213 <xsl:element name="pt">
214 <xsl:attribute name="rev">term</xsl:attribute>
215 <xsl:apply-templates />
216 </xsl:element>
217</xsl:template>
218
219<!-- listitem (in varlistentry) -> pd -->
220<xsl:template match="varlistentry/listitem">
221 <xsl:element name="pd">
222 <xsl:attribute name="rev">listitem</xsl:attribute>
223 <xsl:apply-templates />
224 </xsl:element>
225</xsl:template>
226
227<!-- itemizedlist -> ul -->
228<xsl:template match="itemizedlist">
229 <xsl:element name="ul">
230 <xsl:attribute name="rev">itemizedlist</xsl:attribute>
231 <xsl:apply-templates />
232 </xsl:element>
233</xsl:template>
234
235<!-- listitem in itemizedlist -> li -->
236<xsl:template match="itemizedlist/listitem">
237 <xsl:element name="li">
238 <xsl:attribute name="rev">listitem</xsl:attribute>
239 <xsl:apply-templates />
240 </xsl:element>
241</xsl:template>
242
243<!-- orderedlist -> ol -->
244<xsl:template match="orderedlist">
245 <xsl:element name="ol">
246 <xsl:attribute name="rev">orderedlist</xsl:attribute>
247 <xsl:apply-templates />
248 </xsl:element>
249</xsl:template>
250
251<!-- listitem in orderedlist -> li -->
252<xsl:template match="orderedlist/listitem">
253 <xsl:element name="li">
254 <xsl:attribute name="rev">listitem</xsl:attribute>
255 <xsl:apply-templates />
256 </xsl:element>
257</xsl:template>
258
259<!-- cmdsynopsis -> syntaxdiagram
260 If sbr is used, this gets a bit more complicated... -->
261<xsl:template match="cmdsynopsis[not(sbr)]">
262 <xsl:element name="syntaxdiagram">
263 <xsl:attribute name="rev">cmdsynopsis</xsl:attribute>
264 <xsl:if test="@id">
265 <xsl:attribute name="id"><xsl:value-of select="@id"/></xsl:attribute>
266 </xsl:if>
267 <xsl:choose>
268 <xsl:when test="$g_fRenderSyntaxAsText = 'true'">
269 <xsl:element name="groupseq">
270 <xsl:apply-templates />
271 </xsl:element>
272 </xsl:when>
273
274 <xsl:otherwise>
275 <xsl:apply-templates />
276 </xsl:otherwise>
277 </xsl:choose>
278 </xsl:element>
279
280 <!-- HACK ALERT! Add an empty paragraph to keep syntax diagrams apart in the
281 PDF output, otherwise the commands becomes hard to tell apart. -->
282 <xsl:if test="position() &lt; last()">
283 <xsl:element name="p">
284 <xsl:attribute name="platform">ohc</xsl:attribute> <!-- 'och', so it gets filtered out from the html(help) docs. -->
285 <xsl:attribute name="rev">pdf space hack</xsl:attribute>
286 <xsl:text> </xsl:text>
287 </xsl:element>
288 </xsl:if>
289</xsl:template>
290
291<!-- TODO: sbr cannot be translated, it seems. Whether we wrap things in
292 synblk, groupcomp or groupseq elements, the result is always the same:
293 - HTML: ignored.
294 - PDF: condensed arguments w/o spaces between. 4.0.2 doesn't seem
295 to condense stuff any more inside synblk elements, but then the
296 rending isn't much changed for PDFs anyway since its one element
297 per line.
298 Update: Turns out the condensing was because we stripped element
299 whitespace instead of preserving it. svn copy. sigh. -->
300<xsl:template match="cmdsynopsis[sbr]">
301 <xsl:variable name="sWrapperElement">
302 <xsl:choose>
303 <xsl:when test="$g_fRenderSyntaxAsText = 'true'"><xsl:text>groupseq</xsl:text></xsl:when>
304 <xsl:otherwise><!--synblk--></xsl:otherwise>
305 </xsl:choose>
306 </xsl:variable>
307
308 <xsl:element name="syntaxdiagram">
309 <xsl:attribute name="rev">cmdsynopsis</xsl:attribute>
310 <xsl:if test="@id">
311 <xsl:attribute name="id"><xsl:value-of select="@id"/></xsl:attribute>
312 </xsl:if>
313 <xsl:for-each select="sbr">
314 <xsl:variable name="idxSbr" select="position()"/>
315
316 <xsl:choose>
317 <xsl:when test="$sWrapperElement != ''">
318 <xsl:element name="{$sWrapperElement}">
319 <xsl:attribute name="rev">sbr/<xsl:value-of select="position()"/></xsl:attribute>
320
321 <xsl:if test="$idxSbr = 1">
322 <xsl:apply-templates select="preceding-sibling::node()"/>
323 </xsl:if>
324 <xsl:if test="$idxSbr != 1">
325 <xsl:apply-templates select="preceding-sibling::node()[ count(. | ../sbr[$idxSbr - 1]/following-sibling::node())
326 = count(../sbr[$idxSbr - 1]/following-sibling::node())]"/>
327 </xsl:if>
328 </xsl:element>
329 </xsl:when>
330
331 <xsl:otherwise>
332 <xsl:if test="$idxSbr = 1">
333 <xsl:apply-templates select="preceding-sibling::node()"/>
334 </xsl:if>
335 <xsl:if test="$idxSbr != 1">
336 <xsl:apply-templates select="preceding-sibling::node()[ count(. | ../sbr[$idxSbr - 1]/following-sibling::node())
337 = count(../sbr[$idxSbr - 1]/following-sibling::node())]"/>
338 </xsl:if>
339 </xsl:otherwise>
340 </xsl:choose>
341
342 <!-- Ensure some space between these.-->
343 <xsl:text>
344 </xsl:text>
345
346 <xsl:if test="$idxSbr = last()">
347 <xsl:choose>
348 <xsl:when test="$sWrapperElement != ''">
349 <xsl:element name="{$sWrapperElement}">
350 <xsl:attribute name="rev">sbr/<xsl:value-of select="position()"/></xsl:attribute>
351 <xsl:apply-templates select="following-sibling::node()"/>
352 </xsl:element>
353 </xsl:when>
354
355 <xsl:otherwise>
356 <xsl:apply-templates select="following-sibling::node()"/>
357 </xsl:otherwise>
358 </xsl:choose>
359 </xsl:if>
360 </xsl:for-each>
361 </xsl:element>
362
363 <!-- HACK ALERT! Add an empty paragraph to keep syntax diagrams apart in the
364 PDF output, otherwise the commands becomes hard to tell apart. -->
365 <xsl:if test="position() &lt; last()">
366 <xsl:element name="p">
367 <xsl:attribute name="platform">ohc</xsl:attribute> <!-- 'och', so it gets filtered out from the html(help) docs. -->
368 <xsl:attribute name="rev">pdf space hack</xsl:attribute>
369 <xsl:text> </xsl:text>
370 </xsl:element>
371 </xsl:if>
372</xsl:template>
373
374<!-- text (whitespace) under synopsis may need removing. -->
375<xsl:template match="cmdsynopsis/text()">
376 <xsl:if test="normalize-space(.) != ''">
377 <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>text in cmdsynopsis '<xsl:value-of select="."/>'</xsl:message>
378 </xsl:if>
379
380 <xsl:choose>
381 <xsl:when test="$g_fRenderSyntaxAsText = 'true'">
382 </xsl:when>
383
384 <xsl:otherwise>
385 <xsl:value-of select="."/>
386 </xsl:otherwise>
387 </xsl:choose>
388</xsl:template>
389
390
391<!-- command with text and/or replaceable in cmdsynopsis -> groupseq + kwd -->
392<xsl:template match="cmdsynopsis/command | cmdsynopsis/*/command" >
393 <xsl:element name="groupseq">
394 <xsl:attribute name="rev">command</xsl:attribute>
395 <xsl:apply-templates />
396 </xsl:element>
397</xsl:template>
398
399<xsl:template match="cmdsynopsis/command/text() | cmdsynopsis/*/command/text()" >
400 <xsl:element name="kwd">
401 <xsl:attribute name="rev">command/text</xsl:attribute>
402 <xsl:call-template name="emit-text-with-replacements"/>
403 </xsl:element>
404</xsl:template>
405
406<xsl:template match="cmdsynopsis/command/replaceable | cmdsynopsis/*/command/replaceable" >
407 <xsl:call-template name="check-children"/>
408 <xsl:element name="var">
409 <xsl:attribute name="rev">command/replaceable</xsl:attribute>
410 <xsl:apply-templates />
411 </xsl:element>
412</xsl:template>
413
414<!-- command with text and/or replaceable in not cmdsynopsis -> userinput + cmdname -->
415<xsl:template match="command[not(ancestor::cmdsynopsis)]">
416 <xsl:element name="userinput">
417 <xsl:attribute name="rev">command</xsl:attribute>
418 <xsl:apply-templates />
419 </xsl:element>
420</xsl:template>
421
422<xsl:template match="command[not(ancestor::cmdsynopsis)]/text()">
423 <xsl:element name="cmdname">
424 <xsl:attribute name="rev">command/text</xsl:attribute>
425 <xsl:value-of select="."/>
426 </xsl:element>
427</xsl:template>
428
429<xsl:template match="command[not(ancestor::cmdsynopsis)]/replaceable">
430 <xsl:call-template name="check-children"/>
431 <xsl:element name="varname">
432 <xsl:attribute name="rev">command/replaceable</xsl:attribute>
433 <xsl:value-of select="."/>
434 </xsl:element>
435</xsl:template>
436
437<!--
438 arg -> groupseq; A bit complicated though, because text needs to be wrapping
439 in 'kwd' and any nested arguments needs explicit 'sep' elements containing a
440 space or the nested arguments gets bunched up tight.
441 Examples:
442 {arg}-output={replaceable}file{/replaceable}{/arg}
443 = {groupcomp importance="optional"}{kwd}-output{/kwd}{sep}={/sep}{var}file{/var}{/groupcomp}
444
445 {arg}-output {replaceable}file{/replaceable}{/arg}
446 = {groupcomp importance="optional"}{kwd}-output{/kwd}{sep} {/sep}{var}file{/var}{/groupcomp}
447
448 {arg}-R {arg}-L{/arg}{/arg}
449 = {groupseq importance="optional"}{groupcomp}{kwd}-R{/groupcomp}{sep} {/sep}
450 or {groupseq importance="optional"}{kwd}-R{sep} {/sep}{groupcomp}{kwd}-L{/groupcomp}{/groupseq}
451 note: Important to specify {sep} here as whitespace might otherwise be squashed.
452-->
453
454<!-- Plaintext within arg is generally translated to kwd, but value separators
455 like '=' and ',' should be wrapped in a delim element. -->
456<xsl:template match="arg/text()">
457 <xsl:choose>
458 <!-- put trailing '=' inside <sep> -->
459 <xsl:when test="substring(., string-length(.)) = '='">
460 <xsl:element name="kwd">
461 <xsl:attribute name="rev">arg=</xsl:attribute>
462 <xsl:call-template name="emit-text-with-replacements">
463 <xsl:with-param name="a_sText" select="substring(., 1, string-length(.) - 1)"/>
464 </xsl:call-template>
465 </xsl:element>
466 <xsl:element name="delim">
467 <xsl:attribute name="rev">arg=</xsl:attribute>
468 <xsl:text>=</xsl:text>
469 </xsl:element>
470 </xsl:when>
471
472 <!-- Special case, single space, assuming it's deliberate so put in inside a sep element. -->
473 <xsl:when test=". = ' '">
474 <xsl:element name="sep">
475 <xsl:attribute name="rev">arg-space</xsl:attribute>
476 <xsl:text> </xsl:text>
477 </xsl:element>
478 </xsl:when>
479
480 <!-- Don't wrap other pure whitespace kwd sequences, but emit single space 'sep'
481 element if a arg or groups follows. If the whitespace includes a newline
482 we'll emit it, but otherways we'll generally suppress it to avoid
483 accidentally padding spaces between arguments. -->
484 <xsl:when test="normalize-space(.) = ''">
485 <xsl:if test="following::*[position() = 1 and (self::arg or self::group)] and not(ancestor-or-self::*[@role='compact'])">
486 <xsl:element name="sep">
487 <xsl:attribute name="rev">arg-whitespace</xsl:attribute>
488 <xsl:text> </xsl:text>
489 </xsl:element>
490 </xsl:if>
491 <xsl:if test="contains(., '&#10;') and $g_fRenderSyntaxAsText != 'true'">
492 <xsl:value-of select="."/>
493 </xsl:if>
494 </xsl:when>
495
496 <!-- Remainder is all wrapped in kwd, after space normalization. -->
497 <xsl:otherwise>
498 <xsl:element name="kwd">
499 <xsl:attribute name="rev">arg</xsl:attribute>
500 <xsl:call-template name="emit-text-with-replacements">
501 <xsl:with-param name="a_sText" select="normalize-space(.)"/>
502 </xsl:call-template>
503 </xsl:element>
504 <xsl:if test="normalize-space(substring(., string-length(.), 1)) = ''
505 and following::*[position() = 1 and (self::arg or self::group)]
506 and not(ancestor-or-self::*[@role='compact'])">
507 <xsl:element name="sep">
508 <xsl:attribute name="rev">arg-trailing</xsl:attribute>
509 <xsl:text> </xsl:text>
510 </xsl:element>
511 </xsl:if>
512 </xsl:otherwise>
513 </xsl:choose>
514</xsl:template>
515
516<!-- arg -> groupseq or groupcomp and optionally a repsep element if repeatable. -->
517<xsl:template match="arg" >
518 <xsl:choose>
519 <xsl:when test="$g_fRenderSyntaxAsText = 'true'">
520 <xsl:call-template name="arg_or_group_as_text"/>
521 </xsl:when>
522
523 <xsl:otherwise>
524 <!-- If it's a tighly packed arg, we use groupcomp instead of groupseq to try
525 avoid it being split in the middle. -->
526 <xsl:variable name="sGroupType">
527 <xsl:call-template name="determine_arg_wrapper_element"/>
528 </xsl:variable>
529 <xsl:element name="{$sGroupType}">
530 <xsl:attribute name="rev">arg[<xsl:value-of select="concat(@choice,',',@rep)"/>]</xsl:attribute>
531 <xsl:choose>
532 <xsl:when test="not(@choice) or @choice = 'opt'">
533 <xsl:attribute name="importance">optional</xsl:attribute>
534 </xsl:when>
535 <xsl:when test="@choice = 'req'">
536 <xsl:attribute name="importance">required</xsl:attribute>
537 </xsl:when>
538 <xsl:when test="@choice = 'plain'"/>
539 <xsl:otherwise>
540 <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Unexpected @choice value: <xsl:value-of select="@choice"/></xsl:message>
541 </xsl:otherwise>
542 </xsl:choose>
543
544 <xsl:apply-templates />
545
546 <xsl:if test="@rep = 'repeat'">
547 <!-- repsep can only be placed at the start of a groupseq/whatever and
548 the documenation and examples of the element is very sparse. The
549 PDF output plugin will place the '...' where it finds it and do
550 nothing if it's empty. The XHTML output plugin ignores it, it seems. -->
551 <xsl:element name="sep">
552 <xsl:attribute name="rev">arg[<xsl:value-of select="@choice"/>,repeat]</xsl:attribute>
553 <xsl:text> </xsl:text>
554 </xsl:element>
555 <xsl:element name="groupcomp">
556 <xsl:attribute name="importance">optional</xsl:attribute>
557 <xsl:attribute name="rev">arg[<xsl:value-of select="@choice"/>,repeat]</xsl:attribute>
558 <xsl:attribute name="outputclass">repeatarg</xsl:attribute> <!-- how to make xhtml pass these thru... -->
559 <xsl:element name="repsep">
560 <xsl:attribute name="rev">arg[<xsl:value-of select="@choice"/>,repeat]</xsl:attribute>
561 <xsl:text>...</xsl:text>
562 </xsl:element>
563 </xsl:element>
564 </xsl:if>
565
566 </xsl:element>
567 </xsl:otherwise>
568 </xsl:choose>
569
570 <xsl:if test="parent::group and @choice != 'plain'">
571 <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Expected arg in group to be plain, not optional.</xsl:message>
572 </xsl:if>
573</xsl:template>
574
575<xsl:template name="determine_arg_wrapper_element">
576 <xsl:choose>
577 <xsl:when test="not(descendant::group) and not(descendant::text()[contains(.,' ') or normalize-space(.) != .])">
578 <xsl:text>groupcomp</xsl:text>
579 </xsl:when>
580 <xsl:otherwise>
581 <xsl:text>groupseq</xsl:text>
582 </xsl:otherwise>
583 </xsl:choose>
584</xsl:template>
585
586<!-- replaceable under arg -> var -->
587<xsl:template match="arg/replaceable" >
588 <xsl:element name="var">
589 <xsl:attribute name="rev">replaceable</xsl:attribute>
590 <xsl:apply-templates />
591 </xsl:element>
592</xsl:template>
593
594<!-- replaceable in para or term -> synph+var -->
595<xsl:template match="para/replaceable | term/replaceable | screen/replaceable" >
596 <xsl:element name="synph">
597 <xsl:attribute name="rev">replaceable</xsl:attribute>
598 <xsl:element name="var">
599 <xsl:attribute name="rev">replaceable</xsl:attribute>
600 <xsl:apply-templates />
601 </xsl:element>
602 </xsl:element>
603</xsl:template>
604
605<!-- replaceable in option -> var -->
606<xsl:template match="option/replaceable" >
607 <xsl:element name="var">
608 <xsl:attribute name="rev">option/replaceable</xsl:attribute>
609 <xsl:apply-templates />
610 </xsl:element>
611</xsl:template>
612
613<!-- replaceable in computeroutput or filename -> varname -->
614<xsl:template match="computeroutput/replaceable | filename/replaceable" >
615 <xsl:element name="varname">
616 <xsl:attribute name="rev">computeroutput/replaceable</xsl:attribute>
617 <xsl:apply-templates />
618 </xsl:element>
619</xsl:template>
620
621<!-- replaceable/text() in a cmdsynopsis should have hypens replaced. -->
622<xsl:template match="cmdsynopsis/*/replaceable/text()" >
623 <xsl:call-template name="emit-text-with-replacements"/>
624</xsl:template>
625
626<!--
627 DocBook 'group' elements are only ever used for multiple choice options
628 in our refentry XML, it is never used for argument groupings. For
629 grouping arguments we use nested 'arg' elements.
630
631 This is because 'group' with 'group' parent is poorly defned/handled.
632 Whether the DocBook HTML formatters uses ' | ' separators depends on what
633 other elements are in the group and their order. arg1+group2+group3 won't
634 get any, but group1+arg2+group3 will get one between the first two.
635-->
636
637<xsl:template match="group[group]" priority="3.0">
638 <xsl:message terminate="yes">
639 <xsl:call-template name="error-prefix"/>Immediate group nesting is not allowed! Put nested group inside arg element.
640 </xsl:message>
641</xsl:template>
642
643<xsl:template match="group[count(arg) &lt; 2]" priority="3.0">
644 <xsl:message terminate="yes">
645 <xsl:call-template name="error-prefix"/>Group with fewer than two 'arg' elements is not allowed!
646 </xsl:message>
647</xsl:template>
648
649<!-- group -> groupchoice w/attrib -->
650<xsl:template match="group">
651 <xsl:choose>
652 <xsl:when test="$g_fRenderSyntaxAsText = 'true'">
653 <xsl:call-template name="arg_or_group_as_text"/>
654 </xsl:when>
655 <xsl:otherwise>
656
657 <xsl:element name="groupchoice">
658 <xsl:choose>
659 <xsl:when test="@choice = 'req'">
660 <xsl:attribute name="rev">group[req]</xsl:attribute>
661 <xsl:attribute name="importance">required</xsl:attribute>
662 </xsl:when>
663 <xsl:when test="@choice = 'plain'">
664 <xsl:attribute name="rev">group[plain]</xsl:attribute>
665 <!-- We don't set the importance here. @todo Check what it does to the output formatting -->
666 </xsl:when>
667 <xsl:otherwise>
668 <xsl:attribute name="rev">group[opt]</xsl:attribute>
669 <xsl:attribute name="importance">optional</xsl:attribute>
670 </xsl:otherwise>
671 </xsl:choose>
672
673 <xsl:apply-templates />
674
675 <xsl:if test="@rep = 'repeat'">
676 <!-- repsep can only be placed at the start of a groupseq/whatever and
677 the documenation and examples of the element is very sparse. The
678 PDF output plugin will place the '...' where it finds it and do
679 nothing if it's empty. The XHTML output plugin ignores it, it seems. -->
680 <xsl:message terminate="no"><xsl:call-template name="error-prefix"/>Repeating group is not a good idea...</xsl:message>
681 <xsl:element name="sep">
682 <xsl:attribute name="rev">arg[<xsl:value-of select="@choice"/>,repeat]</xsl:attribute>
683 <xsl:text> </xsl:text>
684 </xsl:element>
685 <xsl:element name="groupcomp">
686 <xsl:attribute name="importance">optional</xsl:attribute>
687 <xsl:attribute name="rev">arg[<xsl:value-of select="@choice"/>,repeat]</xsl:attribute>
688 <xsl:attribute name="outputclass">repeatarg</xsl:attribute> <!-- how to make xhtml pass these thru... -->
689 <xsl:element name="repsep">
690 <xsl:attribute name="rev">arg[<xsl:value-of select="@choice"/>,repeat]</xsl:attribute>
691 <xsl:text>...</xsl:text>
692 </xsl:element>
693 </xsl:element>
694 </xsl:if>
695 </xsl:element>
696
697 </xsl:otherwise>
698 </xsl:choose>
699</xsl:template>
700
701<!-- text under a group may need removing. -->
702<xsl:template match="group/text()">
703 <xsl:if test="normalize-space(.) != ''">
704 <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>text in group: '<xsl:value-of select="."/>'</xsl:message>
705 </xsl:if>
706
707 <xsl:choose>
708 <xsl:when test="$g_fRenderSyntaxAsText = 'true'">
709 </xsl:when>
710
711 <xsl:otherwise>
712 <xsl:value-of select="."/>
713 </xsl:otherwise>
714 </xsl:choose>
715</xsl:template>
716
717
718<!--
719 arg or group -> kwd + text
720 (Code duplicated in docbook-refentry-to-C-help.xsl & docbook2latex.xsl, with local differences.)
721-->
722<xsl:template name="arg_or_group_as_text" >
723 <xsl:variable name="fWrappers" select="not(ancestor::group)"/>
724
725 <!-- lead separators -->
726 <xsl:variable name="sLeadSeps">
727 <xsl:call-template name="arg_or_group_as_text_calc_lead_seps">
728 <xsl:with-param name="a_fWrappers" select="$fWrappers"/>
729 </xsl:call-template>
730 </xsl:variable>
731 <xsl:if test="$sLeadSeps != ''">
732 <xsl:element name="sep">
733 <xsl:value-of select="$sLeadSeps"/>
734 </xsl:element>
735 </xsl:if>
736
737 <!-- render the arg (TODO: may need to do more work here) -->
738 <xsl:apply-templates />
739
740 <!-- repeat wrapping -->
741 <xsl:choose>
742 <xsl:when test="@rep = 'norepeat' or not(@rep) or @rep = ''"/>
743 <xsl:when test="@rep = 'repeat'"> <xsl:element name="sep"><xsl:value-of select="$arg.rep.repeat.str"/></xsl:element></xsl:when>
744 <xsl:otherwise><xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Invalid rep choice: "<xsl:value-of select="@rep"/>"</xsl:message></xsl:otherwise>
745 </xsl:choose>
746
747 <!-- close wrapping -->
748 <xsl:if test="$fWrappers">
749 <xsl:choose>
750 <xsl:when test="not(@choice) or @choice = ''"> <xsl:element name="sep"><xsl:value-of select="$arg.choice.def.close.str"/></xsl:element></xsl:when>
751 <xsl:when test="@choice = 'opt'"> <xsl:element name="sep"><xsl:value-of select="$arg.choice.opt.close.str"/></xsl:element></xsl:when>
752 <xsl:when test="@choice = 'req'"> <xsl:element name="sep"><xsl:value-of select="$arg.choice.req.close.str"/></xsl:element></xsl:when>
753 </xsl:choose>
754 <!-- Add a space padding if we're the last element in a repeating arg or group -->
755 <!-- 2023-03-22 bird: This is incorrectly written. Fix as needed...
756 <xsl:if test="(parent::arg or parent::group) and not(following-sibiling) and not(ancestor::*[@role='compact'])">
757 <xsl:text> </xsl:text>
758 </xsl:if>
759 -->
760 </xsl:if>
761
762</xsl:template>
763
764<!-- Helper for arg_or_group_as_text. -->
765<xsl:template name="arg_or_group_as_text_calc_lead_seps">
766 <xsl:param name="a_fWrappers"/>
767 <xsl:variable name="idSelf" select="generate-id(.)"/>
768
769 <!-- separator char if we're not the first child -->
770 <xsl:if test="../*[generate-id(.) = $idSelf and position() > 1]">
771 <!--<xsl:value-of select="concat('*',name(),'=', position(),'#')"/>-->
772 <xsl:choose>
773 <xsl:when test="parent::group and ancestor::*[@role='compact']"><xsl:value-of select="$arg.or.sep.compact"/></xsl:when>
774 <xsl:when test="parent::group"><xsl:value-of select="$arg.or.sep"/></xsl:when>
775 <xsl:when test="ancestor::*[@role='compact']"></xsl:when>
776 <xsl:when test="ancestor::*/@sepchar"><xsl:value-of select="ancestor::*/@sepchar"/></xsl:when>
777 <xsl:otherwise><xsl:text> </xsl:text></xsl:otherwise>
778 </xsl:choose>
779 </xsl:if>
780
781 <!-- open wrapping -->
782 <xsl:if test="$a_fWrappers">
783 <xsl:choose>
784 <xsl:when test="not(@choice) or @choice = ''"> <xsl:value-of select="$arg.choice.def.open.str"/></xsl:when>
785 <xsl:when test="@choice = 'opt'"> <xsl:value-of select="$arg.choice.opt.open.str"/></xsl:when>
786 <xsl:when test="@choice = 'req'"> <xsl:value-of select="$arg.choice.req.open.str"/></xsl:when>
787 <xsl:when test="@choice = 'plain'"/>
788 <xsl:otherwise><xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Invalid arg choice: "<xsl:value-of select="@choice"/>"</xsl:message></xsl:otherwise>
789 </xsl:choose>
790 </xsl:if>
791
792</xsl:template>
793
794
795<!-- option -->
796<xsl:template match="option/text()" >
797 <xsl:element name="kwd">
798 <xsl:attribute name="rev">option</xsl:attribute>
799 <xsl:value-of select="."/>
800 </xsl:element>
801</xsl:template>
802
803<xsl:template match="option" >
804 <xsl:element name="synph">
805 <xsl:attribute name="rev">option</xsl:attribute>
806 <xsl:apply-templates />
807 </xsl:element>
808</xsl:template>
809
810<!-- literal w/o sub-elements -> codeph -->
811<xsl:template match="literal[not(*)]" >
812 <xsl:element name="codeph">
813 <xsl:attribute name="rev">literal</xsl:attribute>
814 <xsl:apply-templates />
815 </xsl:element>
816</xsl:template>
817
818<!-- literal with replaceable sub-elements -> synph -->
819<xsl:template match="literal[replaceable]" >
820 <xsl:element name="synph">
821 <xsl:attribute name="rev">literal/replaceable</xsl:attribute>
822 <xsl:for-each select="node()">
823 <xsl:choose>
824 <xsl:when test="self::text()">
825 <xsl:element name="kwd">
826 <xsl:value-of select="."/>
827 </xsl:element>
828 </xsl:when>
829 <xsl:when test="self::replaceable">
830 <xsl:if test="./*">
831 <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Unexpected literal/replaceable child</xsl:message>
832 </xsl:if>
833 <xsl:element name="var">
834 <xsl:value-of select="."/>
835 </xsl:element>
836 </xsl:when>
837 <xsl:otherwise>
838 <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Unexpected literal child:
839 <xsl:value-of select="name(.)" />
840 </xsl:message>
841 </xsl:otherwise>
842 </xsl:choose>
843 </xsl:for-each>
844 </xsl:element>
845</xsl:template>
846
847<!-- filename -> filepath -->
848<xsl:template match="filename" >
849 <xsl:element name="filepath">
850 <xsl:attribute name="rev">filename</xsl:attribute>
851 <xsl:apply-templates />
852 </xsl:element>
853</xsl:template>
854
855<!-- screen - pass thru -->
856<xsl:template match="screen" >
857 <xsl:copy>
858 <xsl:apply-templates />
859 </xsl:copy>
860</xsl:template>
861
862<!-- computeroutput -> systemoutput-->
863<xsl:template match="computeroutput">
864 <xsl:element name="systemoutput">
865 <xsl:attribute name="rev">computeroutput</xsl:attribute>
866 <xsl:apply-templates />
867 </xsl:element>
868</xsl:template>
869
870<!-- xref -> xref, but attributes differ. -->
871<xsl:template match="xref">
872 <xsl:element name="xref">
873 <xsl:attribute name="href"><xsl:value-of select="@linkend"/></xsl:attribute>
874 <xsl:if test="contains(@linkend, 'http')"><xsl:message terminate="yes">xref/linkend with http</xsl:message></xsl:if>
875 </xsl:element>
876</xsl:template>
877
878<!-- ulink -> xref -->
879<xsl:template match="ulink">
880 <xsl:element name="xref">
881 <xsl:attribute name="rev">ulink</xsl:attribute>
882 <xsl:attribute name="scope">external</xsl:attribute> <!-- Just assumes this is external. -->
883 <xsl:attribute name="href"><xsl:value-of select="@url"/></xsl:attribute>
884 <xsl:attribute name="format">html</xsl:attribute>
885 <xsl:if test="not(starts-with(@url, 'http'))"><xsl:message terminate="yes">ulink url is not http: <xsl:value-of select="@url"/></xsl:message></xsl:if>
886 </xsl:element>
887</xsl:template>
888
889<!-- emphasis -> i -->
890<xsl:template match="emphasis">
891 <xsl:if test="*">
892 <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Did not expect emphasis to have children!</xsl:message>
893 </xsl:if>
894 <xsl:element name="i">
895 <xsl:attribute name="rev">emphasis</xsl:attribute>
896 <xsl:apply-templates />
897 </xsl:element>
898</xsl:template>
899
900<!-- note -> note -->
901<xsl:template match="note">
902 <xsl:copy>
903 <xsl:apply-templates />
904 </xsl:copy>
905</xsl:template>
906
907<!-- citetitle -> cite -->
908<xsl:template match="citetitle">
909 <xsl:element name="cite">
910 <xsl:attribute name="rev">citetitle</xsl:attribute>
911 <xsl:apply-templates />
912 </xsl:element>
913</xsl:template>
914
915<!--
916 remark extensions:
917 -->
918<!-- Default: remove all remarks. -->
919<xsl:template match="remark"/>
920
921
922<!--
923 Captializes the given text.
924 -->
925<xsl:template name="capitalize">
926 <xsl:param name="text"/>
927 <xsl:call-template name="str:to-upper">
928 <xsl:with-param name="text" select="substring($text,1,1)"/>
929 </xsl:call-template>
930 <xsl:value-of select="substring($text,2)"/>
931</xsl:template>
932
933
934<!--
935 Maybe replace hypens (dashes) with non-breaking ones.
936 -->
937<xsl:template name="emit-text-with-replacements">
938 <xsl:param name="a_sText" select="."/>
939 <xsl:choose>
940 <xsl:when test="$g_fReplaceHypens = 'true'">
941 <xsl:call-template name="str:subst">
942 <xsl:with-param name="text" select="$a_sText"/>
943 <xsl:with-param name="replace">-</xsl:with-param>
944 <xsl:with-param name="with">‑</xsl:with-param> <!-- U+2011 / &#8209; -->
945 </xsl:call-template>
946 </xsl:when>
947 <xsl:otherwise>
948 <xsl:value-of select="$a_sText"/>
949 </xsl:otherwise>
950 </xsl:choose>
951</xsl:template>
952
953
954<!--
955 Debug/Diagnostics: Return the path to the specified node (by default the current).
956 -->
957<xsl:template name="get-node-path">
958 <xsl:param name="Node" select="."/>
959 <xsl:for-each select="$Node">
960 <xsl:for-each select="ancestor-or-self::node()">
961 <xsl:choose>
962 <xsl:when test="name(.) = ''">
963 <xsl:value-of select="concat('/text(',')')"/>
964 </xsl:when>
965 <xsl:otherwise>
966 <xsl:value-of select="concat('/', name(.))"/>
967 <xsl:choose>
968 <xsl:when test="@id">
969 <xsl:text>[@id=</xsl:text>
970 <xsl:value-of select="@id"/>
971 <xsl:text>]</xsl:text>
972 </xsl:when>
973 <xsl:otherwise>
974 <!-- Use generate-id() to find the current node position among its siblings. -->
975 <xsl:variable name="id" select="generate-id(.)"/>
976 <xsl:for-each select="../node()">
977 <xsl:if test="generate-id(.) = $id">
978 <xsl:text>[</xsl:text><xsl:value-of select="position()"/><xsl:text>]</xsl:text>
979 </xsl:if>
980 </xsl:for-each>
981 </xsl:otherwise>
982 </xsl:choose>
983 </xsl:otherwise>
984 </xsl:choose>
985 </xsl:for-each>
986 </xsl:for-each>
987</xsl:template>
988
989<!--
990 Debug/Diagnostics: Return error message prefix.
991 -->
992<xsl:template name="error-prefix">
993 <xsl:param name="Node" select="."/>
994 <xsl:text>error: </xsl:text>
995 <xsl:call-template name="get-node-path">
996 <xsl:with-param name="Node" select="$Node"/>
997 </xsl:call-template>
998 <xsl:text>: </xsl:text>
999</xsl:template>
1000
1001<!--
1002 Debug/Diagnostics: Print list of nodes (by default all children of current node).
1003 -->
1004<xsl:template name="list-nodes">
1005 <xsl:param name="Nodes" select="node()"/>
1006 <xsl:for-each select="$Nodes">
1007 <xsl:if test="position() != 1">
1008 <xsl:text>, </xsl:text>
1009 </xsl:if>
1010 <xsl:choose>
1011 <xsl:when test="name(.) = ''">
1012 <xsl:text>text:text()</xsl:text>
1013 </xsl:when>
1014 <xsl:otherwise>
1015 <xsl:value-of select="name(.)"/>
1016 <xsl:if test="@id">
1017 <xsl:text>[@id=</xsl:text>
1018 <xsl:value-of select="@id"/>
1019 <xsl:text>]</xsl:text>
1020 </xsl:if>
1021 </xsl:otherwise>
1022 </xsl:choose>
1023 </xsl:for-each>
1024</xsl:template>
1025
1026<xsl:template name="check-children">
1027 <xsl:param name="Node" select="."/>
1028 <xsl:param name="UnsupportedNodes" select="*"/>
1029 <xsl:param name="SupportedNames" select="'none'"/>
1030 <xsl:if test="count($UnsupportedNodes) != 0">
1031 <xsl:message terminate="yes">
1032 <xsl:call-template name="get-node-path">
1033 <xsl:with-param name="Node" select="$Node"/>
1034 </xsl:call-template>
1035 <!-- -->: error: Only <xsl:value-of select="$SupportedNames"/> are supported as children to <!-- -->
1036 <xsl:value-of select="name($Node)"/>
1037 <!-- -->
1038Unsupported children: <!-- -->
1039 <xsl:call-template name="list-nodes">
1040 <xsl:with-param name="Nodes" select="$UnsupportedNodes"/>
1041 </xsl:call-template>
1042 </xsl:message>
1043 </xsl:if>
1044</xsl:template>
1045
1046</xsl:stylesheet>
1047
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