]> git.stg.codes - stg.git/blob - doc/xslt/manpages/synop.xsl
Method GetParamValue
[stg.git] / doc / xslt / manpages / synop.xsl
1 <?xml version='1.0'?>
2 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
3                 xmlns:exsl="http://exslt.org/common"
4                 exclude-result-prefixes="exsl"
5                 version='1.0'>
6
7 <!-- ********************************************************************
8      $Id: synop.xsl 7956 2008-03-27 12:07:43Z xmldoc $
9      ********************************************************************
10
11      This file is part of the XSL DocBook Stylesheet distribution.
12      See ../README or http://docbook.sf.net/release/xsl/current/ for
13      copyright and other information.
14
15      ******************************************************************** -->
16
17 <xsl:variable name="arg.or.sep"> |</xsl:variable>
18
19 <!-- * Note: If you're looking for the *Synopsis* element, you won't -->
20 <!-- * find any code here for handling it. It's a "verbatim" -->
21 <!-- * environment; see the block.xsl file instead. -->
22
23 <xsl:template match="synopfragmentref">
24   <xsl:variable name="target" select="key('id',@linkend)"/>
25   <xsl:variable name="snum">
26     <xsl:apply-templates select="$target" mode="synopfragment.number"/>
27   </xsl:variable>
28   <xsl:text>(</xsl:text>
29   <xsl:value-of select="$snum"/>
30   <xsl:text>)</xsl:text>
31   <xsl:text>&#x2580;</xsl:text>
32   <xsl:call-template name="italic">
33     <xsl:with-param name="node" select="."/>
34     <xsl:with-param name="context" select="."/>
35   </xsl:call-template>
36 </xsl:template>
37
38 <xsl:template match="synopfragment" mode="synopfragment.number">
39   <xsl:number format="1"/>
40 </xsl:template>
41
42 <xsl:template match="synopfragment">
43   <xsl:variable name="snum">
44     <xsl:apply-templates select="." mode="synopfragment.number"/>
45   </xsl:variable>
46   <xsl:text>&#10;</xsl:text>
47   <!-- * If we have a group of Synopfragments, we only want to output a -->
48   <!-- * line of space before the first; so when we find a Synopfragment -->
49   <!-- * which has another Synopfragment as a following sibling, we use-->
50   <!-- * the pinch-together template to close up the line of space -->
51   <!-- * that would otherwise be generated by the .HP macro -->
52   <xsl:if test="following-sibling::*[self::synopfragment]">
53     <xsl:call-template name="pinch.together"/>
54   </xsl:if>
55   <xsl:text>.HP </xsl:text>
56   <xsl:text>\w'</xsl:text>
57   <xsl:text>(</xsl:text>
58   <xsl:value-of select="$snum"/>
59   <xsl:text>)</xsl:text>
60   <xsl:text>\ 'u</xsl:text>
61   <xsl:text>&#10;</xsl:text>
62   <xsl:text>(</xsl:text>
63   <xsl:value-of select="$snum"/>
64   <xsl:text>)</xsl:text>
65   <xsl:text>\ </xsl:text>
66   <xsl:apply-templates/>
67 </xsl:template>
68
69 <xsl:template match="group|arg" name="group-or-arg">
70   <xsl:variable name="choice" select="@choice"/>
71   <xsl:variable name="rep" select="@rep"/>
72   <xsl:variable name="sepchar">
73     <xsl:choose>
74       <xsl:when test="ancestor-or-self::*/@sepchar">
75         <xsl:value-of select="ancestor-or-self::*/@sepchar"/>
76       </xsl:when>
77       <xsl:otherwise>
78         <xsl:text> </xsl:text>
79       </xsl:otherwise>
80     </xsl:choose>
81   </xsl:variable>
82   <xsl:if test="position()>1 and
83                 not(preceding-sibling::*[1][self::sbr])"
84           ><xsl:value-of select="$sepchar"/></xsl:if>
85   <xsl:choose>
86     <xsl:when test="$choice='plain'">
87       <!-- * do nothing -->
88     </xsl:when>
89     <xsl:when test="$choice='req'">
90       <xsl:value-of select="$arg.choice.req.open.str"/>
91     </xsl:when>
92     <xsl:when test="$choice='opt'">
93       <xsl:value-of select="$arg.choice.opt.open.str"/>
94     </xsl:when>
95     <xsl:otherwise>
96       <xsl:value-of select="$arg.choice.def.open.str"/>
97     </xsl:otherwise>
98   </xsl:choose>
99   <xsl:variable name="arg">
100     <xsl:apply-templates/>
101   </xsl:variable>
102   <xsl:choose>
103     <xsl:when test="local-name(.) = 'arg' and not(ancestor::arg)">
104       <!-- * Prevent arg contents from getting wrapped and broken up -->
105       <xsl:variable name="arg.wrapper">
106         <Arg><xsl:value-of select="normalize-space($arg)"/></Arg>
107       </xsl:variable>
108       <xsl:apply-templates mode="prevent.line.breaking"
109                            select="exsl:node-set($arg.wrapper)"/>
110     </xsl:when>
111     <xsl:otherwise>
112       <xsl:value-of select="$arg"/>
113     </xsl:otherwise>
114   </xsl:choose>
115   <xsl:choose>
116     <xsl:when test="$rep='repeat'">
117       <xsl:value-of select="$arg.rep.repeat.str"/>
118     </xsl:when>
119     <xsl:when test="$rep='norepeat'">
120       <xsl:value-of select="$arg.rep.norepeat.str"/>
121     </xsl:when>
122     <xsl:otherwise>
123       <xsl:value-of select="$arg.rep.def.str"/>
124     </xsl:otherwise>
125   </xsl:choose>
126   <xsl:choose>
127     <xsl:when test="$choice='plain'">
128       <xsl:if test='arg'>
129       <xsl:value-of select="$arg.choice.plain.close.str"/>
130       </xsl:if>
131     </xsl:when>
132     <xsl:when test="$choice='req'">
133       <xsl:value-of select="$arg.choice.req.close.str"/>
134     </xsl:when>
135     <xsl:when test="$choice='opt'">
136       <xsl:value-of select="$arg.choice.opt.close.str"/>
137     </xsl:when>
138     <xsl:otherwise>
139       <xsl:value-of select="$arg.choice.def.close.str"/>
140     </xsl:otherwise>
141   </xsl:choose>
142 </xsl:template>
143
144 <xsl:template match="group/arg">
145   <xsl:variable name="choice" select="@choice"/>
146   <xsl:variable name="rep" select="@rep"/>
147   <xsl:if test="position()>1"><xsl:value-of select="$arg.or.sep"/></xsl:if>
148   <xsl:call-template name="group-or-arg"/>
149 </xsl:template>
150
151 <xsl:template match="sbr">
152   <xsl:text>&#x2592;</xsl:text>
153   <xsl:text>.br&#x2592;</xsl:text>
154 </xsl:template>
155
156 <xsl:template match="cmdsynopsis">
157   <!-- * if justification is enabled by default, turn it off temporarily -->
158   <xsl:if test="$man.justify != 0">
159     <xsl:text>.ad l&#10;</xsl:text>
160   </xsl:if>
161   <!-- * if hyphenation is enabled by default, turn it off temporarily -->
162   <xsl:if test="$man.hyphenate != 0">
163     <xsl:text>.hy 0&#10;</xsl:text>
164   </xsl:if>
165   <xsl:call-template name="synopsis-block-start"/>
166   <xsl:text>.HP </xsl:text>
167   <xsl:text>\w'</xsl:text>
168   <xsl:variable name="command">
169     <xsl:apply-templates select="command"/>
170   </xsl:variable>
171   <xsl:call-template name="string.subst">
172     <xsl:with-param name="string" select="normalize-space($command)"/>
173     <xsl:with-param name="target" select="' '"/>
174     <xsl:with-param name="replacement" select="'\ '"/>
175   </xsl:call-template>
176   <xsl:text>\ 'u</xsl:text>
177   <xsl:text>&#10;</xsl:text>
178   <xsl:apply-templates/>
179   <xsl:text>&#10;</xsl:text>
180   <xsl:call-template name="synopsis-block-end"/>
181   <!-- * if justification is enabled by default, turn it back on -->
182   <xsl:if test="$man.justify != 0">
183     <xsl:text>.ad&#10;</xsl:text>
184   </xsl:if>
185   <!-- * if hyphenation is enabled by default, turn it back on -->
186   <xsl:if test="$man.hyphenate != 0">
187     <xsl:text>.hy&#10;</xsl:text>
188   </xsl:if>
189 </xsl:template>
190
191 <!-- ==================================================================== -->
192 <!-- *  Funcsynopis hierarchy starts here -->
193 <!-- ==================================================================== -->
194
195 <!-- * Note: If you're looking for the *Funcsynopsisinfo* element, -->
196 <!-- * you won't find any code here for handling it. It's a "verbatim" -->
197 <!-- * environment; see the block.xsl file instead. -->
198
199 <!-- * Within funcsynopis output, disable hyphenation, and use -->
200 <!-- * left-aligned filling for the duration of the synopsis, so that -->
201 <!-- * line breaks only occur between separate paramdefs. -->
202 <xsl:template match="funcsynopsis">
203   <!-- * if justification is enabled by default, turn it off temporarily -->
204   <xsl:if test="$man.justify != 0">
205     <xsl:text>.ad l&#10;</xsl:text>
206   </xsl:if>
207   <!-- * if hyphenation is enabled by default, turn it off temporarily -->
208   <xsl:if test="$man.hyphenate != 0">
209     <xsl:text>.hy 0&#10;</xsl:text>
210   </xsl:if>
211   <xsl:apply-templates/>
212   <!-- * if justification is enabled by default, turn it back on -->
213   <xsl:if test="$man.justify != 0">
214     <xsl:text>.ad&#10;</xsl:text>
215   </xsl:if>
216   <!-- * if hyphenation is enabled by default, turn it back on -->
217   <xsl:if test="$man.hyphenate != 0">
218     <xsl:text>.hy&#10;</xsl:text>
219   </xsl:if>
220 </xsl:template>
221
222 <!-- * In HTML output, placing a dbfunclist PI as a child of a particular -->
223 <!-- * element creates a hyperlinked list of all funcsynopsis instances -->
224 <!-- * that are descendants of that element. But we can’t really do this -->
225 <!-- * kind of hyperlinked list in manpages output, so we just need to -->
226 <!-- * suppress it instead. -->
227 <xsl:template match="processing-instruction('dbfunclist')"/>
228
229 <!-- * ***************************************************************** -->
230 <!-- *           Note about boldface in funcprototype output -->
231 <!-- * ***************************************************************** -->
232 <!-- * All funcprototype content is by default rendered in bold, -->
233 <!-- * because the old man(7) man page, now man-pages(7) says this: -->
234 <!-- * -->
235 <!-- *   For functions, the arguments are always specified using -->
236 <!-- *   italics, even in the SYNOPSIS section, where the rest of -->
237 <!-- *   the function is specified in bold -->
238 <!-- * -->
239 <!-- * Look through the contents of the man/man2 and man3 directories -->
240 <!-- * on your system, and you'll see that most existing pages do follow -->
241 <!-- * this "bold everything in function synopsis" rule. -->
242 <!-- * -->
243 <!-- * Users who don't want the bold output can choose to adjust the -->
244 <!-- * man.font.funcprototype parameter on their own. So even if you -->
245 <!-- * don't personally like the way it looks, please don't change the -->
246 <!-- * default to be non-bold - because it's a convention that's -->
247 <!-- * followed is the vast majority of existing man pages that document -->
248 <!-- * functions, and we need to follow it by default, like it or no. -->
249 <!-- * ***************************************************************** -->
250
251 <xsl:template match="funcprototype">
252   <xsl:variable name="man-funcprototype-style">
253     <xsl:call-template name="pi.dbman_funcsynopsis-style">
254       <xsl:with-param name="node" select="ancestor::funcsynopsis/descendant-or-self::*"/>
255     </xsl:call-template>
256   </xsl:variable>
257   <xsl:variable name="style">
258     <xsl:choose>
259       <xsl:when test="not($man-funcprototype-style = '')">
260         <xsl:value-of select="$man-funcprototype-style"/>
261       </xsl:when>
262       <xsl:otherwise>
263         <xsl:value-of select="$man.funcsynopsis.style"/>
264       </xsl:otherwise>
265     </xsl:choose>
266   </xsl:variable>
267   <xsl:variable name="funcprototype.string.value">
268     <xsl:value-of select="funcdef"/>
269   </xsl:variable>
270   <xsl:variable name="funcprototype">
271     <xsl:apply-templates select="funcdef"/>
272   </xsl:variable>
273   <xsl:call-template name="synopsis-block-start"/>
274   <xsl:text>.HP </xsl:text>
275   <xsl:text>\w'</xsl:text>
276   <xsl:variable name="funcdef">
277     <xsl:apply-templates select="funcdef"/>
278   </xsl:variable>
279   <xsl:call-template name="string.subst">
280     <xsl:with-param name="string" select="normalize-space($funcdef)"/>
281     <xsl:with-param name="target" select="' '"/>
282     <xsl:with-param name="replacement" select="'\ '"/>
283   </xsl:call-template>
284   <xsl:text>('u</xsl:text>
285   <xsl:text>&#10;</xsl:text>
286   <xsl:text>.</xsl:text>
287   <xsl:value-of select="$man.font.funcprototype"/>
288   <xsl:text> </xsl:text>
289   <!-- * The following quotation mark (and the one further below) are -->
290   <!-- * needed to properly delimit the parts of the Funcprototype that -->
291   <!-- * should be rendered in the prevailing font (either Bold or Roman) -->
292   <!-- * from Parameter output that needs to be alternately rendered in -->
293   <!-- * italic. -->
294   <xsl:text>"</xsl:text>
295   <xsl:value-of select="normalize-space($funcprototype)"/>
296   <xsl:text>(</xsl:text>
297   <xsl:choose>
298     <xsl:when test="not($style = 'ansi')">
299       <xsl:apply-templates select="*[local-name() != 'funcdef']" mode="kr"/>
300     </xsl:when>
301     <xsl:otherwise>
302       <xsl:apply-templates select="*[local-name() != 'funcdef']" mode="ansi"/>
303     </xsl:otherwise>
304   </xsl:choose>
305   <xsl:text>"</xsl:text>
306   <xsl:text>&#10;</xsl:text>
307   <xsl:if test="paramdef and not($style = 'ansi')">
308     <!-- * if we have any paramdef instances in this funcprototype and -->
309     <!-- * the user has chosen K&R style output (by specifying some style -->
310     <!-- * value other than the default 'ansi'), then we need to generate -->
311     <!-- * the separate list of param definitions for this funcprototype -->
312     <!-- * -->
313     <!-- * we put a blank line after the prototype and before the list, -->
314     <!-- * and we indent the list by whatever width $list-indent is set -->
315     <!-- * to (4 spaces by default) -->
316     <xsl:text>.sp&#10;</xsl:text>
317     <xsl:text>.RS</xsl:text> 
318     <xsl:if test="not($list-indent = '')">
319       <xsl:text> </xsl:text>
320       <xsl:value-of select="$list-indent"/>
321     </xsl:if>
322     <xsl:text>&#10;</xsl:text>
323     <xsl:apply-templates select="paramdef" mode="kr-paramdef-list"/>
324     <xsl:text>.RE&#10;</xsl:text>
325   </xsl:if>
326   <xsl:call-template name="synopsis-block-end"/>
327 </xsl:template>
328
329 <xsl:template match="funcdef">
330   <xsl:apply-templates mode="prevent.line.breaking"/>
331 </xsl:template>
332
333 <xsl:template match="funcdef/function">
334   <xsl:apply-templates/>
335 </xsl:template>
336
337 <xsl:template match="void" mode="kr">
338   <xsl:text>);</xsl:text>
339 </xsl:template>
340
341 <xsl:template match="varargs" mode="kr">
342   <xsl:text>...);</xsl:text>
343 </xsl:template>
344
345 <xsl:template match="void" mode="ansi">
346   <xsl:text>void);</xsl:text>
347 </xsl:template>
348
349 <xsl:template match="varargs" mode="ansi">
350   <xsl:text>...);</xsl:text>
351 </xsl:template>
352
353 <xsl:template match="paramdef" mode="kr">
354   <!-- * in K&R-style output, the prototype just contains the parameter -->
355   <!-- * names - because the parameter definitions for each parameter -->
356   <!-- * (including the type information) are displayed in a separate -->
357   <!-- * list following the prototype; so in this mode (which is for the -->
358   <!-- * prototype, not the separate list), we first just want to grab -->
359   <!-- * the parameter for each paramdef -->
360   <xsl:variable name="contents">
361     <xsl:apply-templates select="parameter"/>
362   </xsl:variable>
363   <xsl:apply-templates mode="prevent.line.breaking" select="exsl:node-set($contents)"/>
364   <xsl:choose>
365     <xsl:when test="following-sibling::*">
366       <xsl:text>, </xsl:text>
367     </xsl:when>
368     <xsl:otherwise>
369       <xsl:text>);</xsl:text>
370     </xsl:otherwise>
371   </xsl:choose>
372 </xsl:template>
373
374 <xsl:template match="paramdef" mode="ansi">
375   <!-- * in ANSI-style output, the prototype contains the complete -->
376   <!-- * parameter definitions for each parameter (there is no separate -->
377   <!-- * list of parameter definitions like the one for K&R style -->
378   <xsl:apply-templates mode="prevent.line.breaking" select="."/>
379   <xsl:choose>
380     <xsl:when test="following-sibling::*">
381       <xsl:text>, </xsl:text>
382     </xsl:when>
383     <xsl:otherwise>
384       <xsl:text>);</xsl:text>
385     </xsl:otherwise>
386   </xsl:choose>
387 </xsl:template>
388
389 <xsl:template match="paramdef" mode="kr-paramdef-list">
390   <!-- * this mode is for generating the separate list of parameter -->
391   <!-- * definitions in K&R-style output -->
392   <xsl:text>.br&#10;</xsl:text>
393   <xsl:text>.</xsl:text>
394   <xsl:value-of select="$man.font.funcprototype"/>
395   <xsl:text> </xsl:text>
396   <!-- * The following quotation mark (and the one further below) are -->
397   <!-- * needed to properly delimit the parts of the Funcprototype that -->
398   <!-- * should be rendered in the prevailing font (either Bold or Roman) -->
399   <!-- * from Parameter output that needs to be alternately rendered in -->
400   <!-- * italic. -->
401   <xsl:text>"</xsl:text>
402   <xsl:variable name="contents">
403     <xsl:apply-templates/>
404   </xsl:variable>
405   <xsl:value-of select="normalize-space($contents)"/>
406   <xsl:text>;</xsl:text>
407   <xsl:text>"</xsl:text>
408   <xsl:text>&#10;</xsl:text>
409 </xsl:template>
410
411 <xsl:template match="paramdef/parameter">
412   <!-- * We use U+2591 here in place of a normal space, because if we -->
413   <!-- * were to just use a normal space, it would get replaced with a -->
414   <!-- * non-breaking space when we run the whole Paramdef through the -->
415   <!-- * prevent.line.breaking template. And as far as why we're -->
416   <!-- * inserting the space and quotation marks around each Parameter -->
417   <!-- * to begin with, the reason is that we need to because we are -->
418   <!-- * outputting Funcsynopsis in either the "BI" or "RI" font, and -->
419   <!-- * the space and quotation marks delimit the text as the -->
420   <!-- * "alternate" or "I" text that needs to be rendered in italic. -->
421   <xsl:text>"&#x2591;"</xsl:text>
422   <xsl:apply-templates/>
423   <xsl:text>"&#x2591;"</xsl:text>
424 </xsl:template>
425
426 <xsl:template match="funcparams">
427   <xsl:text>(</xsl:text>
428   <xsl:apply-templates/>
429   <xsl:text>)</xsl:text>
430 </xsl:template>
431
432 </xsl:stylesheet>