]> git.stg.codes - stg.git/blob - doc/xslt/manpages/other.xsl
Help book chapter 3 complete
[stg.git] / doc / xslt / manpages / other.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                 xmlns:ng="http://docbook.org/docbook-ng"
5                 xmlns:db="http://docbook.org/ns/docbook"
6                 xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0"
7                 exclude-result-prefixes="exsl"
8                 version='1.0'>
9
10 <!-- ********************************************************************
11      $Id: other.xsl 8865 2010-08-20 18:22:06Z mzjn $
12      ********************************************************************
13
14      This file is part of the XSL DocBook Stylesheet distribution.
15      See ../README or http://docbook.sf.net/release/xsl/current/ for
16      copyright and other information.
17
18      ******************************************************************** -->
19
20 <!-- * This file contains named templates related to things other than -->
21 <!-- * just assembling the actual text of the main text flow of each man -->
22 <!-- * page. This "other" stuff currently amounts to these steps: -->
23 <!-- * -->
24 <!-- *  - get contents of the "map" used to convert special characters -->
25 <!-- *  - output boilerplate messages -->
26 <!-- *  - escape backslash, dot, dash, and apostrophe characters -->
27 <!-- *  - convert non-breaking spaces -->
28 <!-- *  - add a comment to top part of roff source of each page -->
29 <!-- *  - make a .TH title line (for controlling page header/footer) -->
30 <!-- *  - set hyphenation, alignment, indent & line-breaking defaults -->
31 <!-- *  - "prepare" the complete man page contents for final output -->
32 <!-- *  - write the actual man file to the filesystem -->
33 <!-- *  - write any "stub" pages to the filesystem -->
34 <!-- * -->
35 <!-- * The templates in this file are actually called only once per -->
36 <!-- * each Refentry; they are just in a separate file for the purpose -->
37 <!-- * of keeping things modular. -->
38
39 <!-- ==================================================================== -->
40
41 <xsl:preserve-space elements="*"/>
42
43 <xsl:strip-space elements="
44 abstract affiliation anchor answer appendix area areaset areaspec
45 artheader article audiodata audioobject author authorblurb authorgroup
46 beginpage bibliodiv biblioentry bibliography biblioset blockquote book
47 bookbiblio bookinfo callout calloutlist caption caution chapter
48 citerefentry cmdsynopsis co collab colophon colspec confgroup
49 copyright dedication docinfo editor entrytbl epigraph equation
50 example figure footnote footnoteref formalpara funcprototype
51 funcsynopsis glossary glossdef glossdiv glossentry glosslist graphicco
52 group highlights imagedata imageobject imageobjectco important index
53 indexdiv indexentry indexterm informalequation informalexample
54 informalfigure informaltable inlineequation inlinemediaobject
55 itemizedlist itermset keycombo keywordset legalnotice listitem lot
56 mediaobject mediaobjectco menuchoice msg msgentry msgexplan msginfo
57 msgmain msgrel msgset msgsub msgtext note objectinfo
58 orderedlist othercredit part partintro preface printhistory procedure
59 programlistingco publisher qandadiv qandaentry qandaset question
60 refentry reference refmeta refnamediv refsection refsect1 refsect1info refsect2
61 refsect2info refsect3 refsect3info refsynopsisdiv refsynopsisdivinfo
62 revhistory revision row sbr screenco screenshot sect1 sect1info sect2
63 sect2info sect3 sect3info sect4 sect4info sect5 sect5info section
64 sectioninfo seglistitem segmentedlist seriesinfo set setindex setinfo
65 shortcut sidebar simplelist simplesect spanspec step subject
66 subjectset substeps synopfragment table tbody textobject tfoot tgroup
67 thead tip toc tocchap toclevel1 toclevel2 toclevel3 toclevel4
68 toclevel5 tocpart varargs variablelist varlistentry videodata
69 videoobject void warning subjectset
70
71 classsynopsis
72 constructorsynopsis
73 destructorsynopsis
74 fieldsynopsis
75 methodparam
76 methodsynopsis
77 ooclass
78 ooexception
79 oointerface
80 simplemsgentry
81 manvolnum
82 "/>
83
84 <!-- ==================================================================== -->
85 <!-- * Get character map contents -->
86 <!-- ==================================================================== -->
87
88   <xsl:variable name="man.charmap.contents">
89     <xsl:if test="$man.charmap.enabled != 0">
90       <xsl:variable name="lang">
91         <xsl:call-template name="l10n.language">
92           <xsl:with-param name="target" select="//refentry[1]"/>
93         </xsl:call-template>
94       </xsl:variable>
95       <xsl:call-template name="read-character-map">
96         <xsl:with-param name="use.subset" select="$man.charmap.use.subset"/>
97         <xsl:with-param name="subset.profile">
98           <xsl:choose>
99             <xsl:when test="$lang = 'en'">
100               <xsl:value-of select="$man.charmap.subset.profile.english"/>
101             </xsl:when>
102             <xsl:otherwise>
103               <xsl:value-of select="$man.charmap.subset.profile"/>
104             </xsl:otherwise>
105           </xsl:choose>
106         </xsl:with-param>
107         <xsl:with-param name="uri">
108           <xsl:choose>
109             <xsl:when test="$man.charmap.uri != ''">
110               <xsl:value-of select="$man.charmap.uri"/>
111             </xsl:when>
112             <xsl:otherwise>
113               <xsl:value-of select="'../manpages/charmap.groff.xsl'"/>
114             </xsl:otherwise>
115           </xsl:choose>
116         </xsl:with-param>
117       </xsl:call-template>
118     </xsl:if>
119   </xsl:variable>
120
121 <!-- ==================================================================== -->
122
123 <xsl:template name="root.messages">
124   <xsl:param name="refname"/>
125   <!-- redefine this any way you'd like to output messages -->
126   <!-- DO NOT OUTPUT ANYTHING FROM THIS TEMPLATE -->
127   <!-- Example:
128   <xsl:if test="//foo">
129     <xsl:call-template name="log.message">
130       <xsl:with-param name="level">Warn</xsl:with-param>
131       <xsl:with-param name="source" select="$refname"/>
132       <xsl:with-param name="context-desc">
133         <xsl:text>limitation</xsl:text>
134       </xsl:with-param>
135       <xsl:with-param name="message">
136         <xsl:text>Output for foo element is not yet supported.</xsl:text>
137       </xsl:with-param>
138     </xsl:call-template>
139   </xsl:if>
140   -->
141 </xsl:template>
142
143 <!-- ==================================================================== -->
144 <!-- * Escape roff special chars -->
145 <!-- ==================================================================== -->
146
147 <!-- ******************************************************************** -->
148 <!-- *  -->
149 <!-- * The backslash, dot, dash, and apostrophe (\, ., -, ') characters -->
150 <!-- * have special meaning for roff, so before we do any other -->
151 <!-- * processing, we must escape those characters where they appear in -->
152 <!-- * the source content. -->
153 <!-- *  -->
154 <!-- * Here we also deal with replacing U+00a0 (non-breaking space) with -->
155 <!-- * its roff equivalent -->
156 <!-- *  -->
157 <!-- ******************************************************************** -->
158
159 <xsl:template match="//refentry//text()">
160   <xsl:call-template name="escape.roff.specials">
161     <xsl:with-param name="content">
162       <xsl:value-of select="."/>
163     </xsl:with-param>
164   </xsl:call-template>
165 </xsl:template>
166
167 <xsl:template name="escape.roff.specials">
168   <xsl:param name="content"/>
169   <xsl:call-template name="convert.nobreak-space">
170     <xsl:with-param name="content">
171       <xsl:call-template name="escape.apostrophe">
172         <xsl:with-param name="content">
173           <xsl:call-template name="escape.dash">
174             <xsl:with-param name="content">
175               <xsl:call-template name="escape.dot">
176                 <xsl:with-param name="content">
177                   <xsl:call-template name="escape.backslash">
178                     <xsl:with-param name="content" select="$content"/>
179                   </xsl:call-template>
180                 </xsl:with-param>
181               </xsl:call-template>
182             </xsl:with-param>
183           </xsl:call-template>
184         </xsl:with-param>
185       </xsl:call-template>
186     </xsl:with-param>
187   </xsl:call-template>
188 </xsl:template>
189
190 <xsl:template name="escape.backslash">
191   <xsl:param name="content"/>
192   <xsl:call-template name="string.subst">
193     <xsl:with-param name="string" select="$content"/>
194     <xsl:with-param name="target">\</xsl:with-param>
195     <!-- * we use "\e" instead of "\\" because the groff docs say -->
196     <!-- * that's the correct thing to do; also because testing -->
197     <!-- * shows that "\\" doesn't always work as expected; for -->
198     <!-- * example, "\\" within a table seems to mess things up -->
199     <xsl:with-param name="replacement">\e</xsl:with-param>
200   </xsl:call-template>
201 </xsl:template>
202
203 <xsl:template name="escape.dot">
204   <xsl:param name="content"/>
205   <xsl:call-template name="string.subst">
206     <xsl:with-param name="string" select="$content"/>
207     <xsl:with-param name="target">.</xsl:with-param>
208     <xsl:with-param name="replacement">\&amp;.</xsl:with-param>
209   </xsl:call-template>
210 </xsl:template>
211
212 <xsl:template name="escape.dash">
213   <xsl:param name="content"/>
214   <xsl:call-template name="string.subst">
215     <xsl:with-param name="string" select="$content"/>
216     <xsl:with-param name="target">-</xsl:with-param>
217     <xsl:with-param name="replacement">\-</xsl:with-param>
218   </xsl:call-template>
219 </xsl:template>
220
221 <xsl:template name="escape.apostrophe">
222   <xsl:param name="content"/>
223   <xsl:call-template name="string.subst">
224     <xsl:with-param name="string" select="$content"/>
225     <xsl:with-param name="target">'</xsl:with-param>
226     <xsl:with-param name="replacement">\*(Aq</xsl:with-param>
227   </xsl:call-template>
228 </xsl:template>
229
230 <xsl:template name="convert.nobreak-space">
231   <xsl:param name="content"/>
232   <xsl:call-template name="string.subst">
233     <xsl:with-param name="string" select="$content"/>
234     <xsl:with-param name="target">&#x00a0;</xsl:with-param>
235     <!-- * A no-break space can be written two ways in roff; the -->
236     <!-- * difference, according to the "Page Motions" node in the -->
237     <!-- * groff info page, is: -->
238     <!-- *  -->
239     <!-- *   "\ " = -->
240     <!-- *   An unbreakable and unpaddable (i.e. not expanded -->
241     <!-- *   during filling) space. -->
242     <!-- *  -->
243     <!-- *   "\~" = -->
244     <!-- *   An unbreakable space that stretches like a normal -->
245     <!-- *   inter-word space when a line is adjusted."  -->
246     <!-- *  -->
247     <!-- * Unfortunately, roff seems to do some weird things with -->
248     <!-- * long lines that only have words separated by "\~" -->
249     <!-- * spaces, so it's safer just to stick with the "\ " space -->
250     <!-- *  -->
251     <!-- * We append a "\&" to handle the case of a no-break space that -->
252     <!-- * appears at the end of a line - because later processing will -->
253     <!-- * cause that space to get eaten otherwise. -->
254     <xsl:with-param name="replacement">\ \&amp;</xsl:with-param>
255   </xsl:call-template>
256 </xsl:template>
257
258 <!-- ==================================================================== -->
259
260 <!-- * top.comment generates a comment containing metadata for the man -->
261 <!-- * page; for example, Author, Generator, and Date information -->
262
263   <xsl:template name="top.comment">
264     <xsl:param name="info"/>
265     <xsl:param name="date"/>
266     <xsl:param name="title"/>
267     <xsl:param name="manual"/>
268     <xsl:param name="source"/>
269     <xsl:param name="refname"/>
270     <xsl:text>.\"     Title: </xsl:text>
271     <xsl:call-template name="replace.dots.and.dashes">
272       <xsl:with-param name="content" select="$title"/>
273     </xsl:call-template>
274     <xsl:text>&#10;</xsl:text>
275     <xsl:text>.\"    Author: </xsl:text>
276     <xsl:call-template name="replace.dots.and.dashes">
277       <xsl:with-param name="content">
278         <xsl:call-template name="make.roff.metadata.author">
279           <xsl:with-param name="info" select="$info"/>
280           <xsl:with-param name="refname" select="$refname"/>
281         </xsl:call-template>
282       </xsl:with-param>
283     </xsl:call-template>
284     <xsl:text>&#10;</xsl:text>
285     <xsl:text>.\" Generator: DocBook </xsl:text>
286     <xsl:value-of select="$DistroTitle"/>
287     <xsl:text> v</xsl:text>
288     <xsl:call-template name="replace.dots.and.dashes">
289       <xsl:with-param name="content" select="$VERSION"/>
290     </xsl:call-template>
291     <xsl:text> &lt;http://docbook.sf.net/></xsl:text>
292     <xsl:text>&#10;</xsl:text>
293     <xsl:text>.\"      Date: </xsl:text>
294     <xsl:call-template name="replace.dots.and.dashes">
295       <xsl:with-param name="content" select="$date"/>
296     </xsl:call-template>
297     <xsl:text>&#10;</xsl:text>
298     <xsl:text>.\"    Manual: </xsl:text>
299     <xsl:call-template name="replace.dots.and.dashes">
300       <xsl:with-param name="content" select="$manual"/>
301     </xsl:call-template>
302     <xsl:text>&#10;</xsl:text>
303     <xsl:text>.\"    Source: </xsl:text>
304     <xsl:call-template name="replace.dots.and.dashes">
305       <xsl:with-param name="content" select="$source"/>
306     </xsl:call-template>
307     <xsl:text>&#10;</xsl:text>
308     <xsl:text>.\"  Language: </xsl:text>
309     <xsl:call-template name="l10n.language.name"/>
310     <xsl:text>&#10;</xsl:text>
311     <xsl:text>.\"</xsl:text>
312     <xsl:text>&#10;</xsl:text>
313   </xsl:template>
314
315 <!-- ==================================================================== -->
316
317   <xsl:template name="TH.title.line">
318
319     <!-- * The exact way that .TH contents are displayed is system- -->
320     <!-- * dependent; it varies somewhat between OSes and roff -->
321     <!-- * versions. Below is a description of how Linux systems with -->
322     <!-- * a modern groff seem to render .TH contents. -->
323     <!-- * -->
324     <!-- *   title(section)  extra3  title(section)  <- page header -->
325     <!-- *   extra2          extra1  title(section)  <- page footer-->
326     <!-- * -->
327     <!-- * Or, using the names with which the man(7) man page refers -->
328     <!-- * to the various fields: -->
329     <!-- * -->
330     <!-- *   title(section)  manual  title(section)  <- page header -->
331     <!-- *   source          date    title(section)  <- page footer-->
332     <!-- * -->
333     <!-- * Note that while extra1, extra2, and extra3 are all (nominally) -->
334     <!-- * optional, in practice almost all pages include an "extra1" -->
335     <!-- * field, which is, universally, a date (in some form), and it is -->
336     <!-- * always rendered in the same place (the middle footer position) -->
337     <!-- * -->
338     <!-- * Here are a couple of examples of real-world man pages that -->
339     <!-- * have somewhat useful page headers/footers: -->
340     <!-- * -->
341     <!-- *   gtk-options(7)    GTK+ User's Manual   gtk-options(7) -->
342     <!-- *   GTK+ 1.2              2003-10-20       gtk-options(7) -->
343     <!-- * -->
344     <!-- *   svgalib(7)       Svgalib User Manual       svgalib(7) -->
345     <!-- *   Svgalib 1.4.1      16 December 1999        svgalib(7) -->
346     <!-- * -->
347     <xsl:param name="title"/>
348     <xsl:param name="section"/>
349     <xsl:param name="extra1"/>
350     <xsl:param name="extra2"/>
351     <xsl:param name="extra3"/>
352
353     <xsl:call-template name="mark.subheading"/>
354     <!-- * Note that we generate quotes around _every_ field in the -->
355     <!-- * .TH title line, including the "title" and "section" -->
356     <!-- * fields. That is because we use the contents of those "as -->
357     <!-- * is", unchanged from the DocBook source; and DTD-based -->
358     <!-- * validation does not provide a way to constrain them to be -->
359     <!-- * "space free" -->
360     <xsl:text>.TH "</xsl:text>
361     <xsl:call-template name="string.upper">
362       <xsl:with-param name="string">
363         <xsl:choose>
364           <xsl:when test="$man.th.title.max.length != ''">
365             <xsl:value-of
366                 select="normalize-space(substring($title, 1, $man.th.title.max.length))"/>
367           </xsl:when>
368           <xsl:otherwise>
369             <xsl:value-of select="normalize-space($title)"/>
370           </xsl:otherwise>
371         </xsl:choose>
372       </xsl:with-param>
373     </xsl:call-template>
374     <xsl:text>" "</xsl:text>
375     <xsl:value-of select="normalize-space($section)"/>
376     <xsl:text>" "</xsl:text>
377     <xsl:if test="$man.th.extra1.suppress = 0">
378       <!-- * there is no max.length for the extra1 field; the reason -->
379       <!-- * is, it is almost always a date, and it is not possible -->
380       <!-- * to truncate dates without changing their meaning -->
381       <xsl:value-of select="normalize-space($extra1)"/>
382     </xsl:if>
383     <xsl:text>" "</xsl:text>
384     <xsl:if test="$man.th.extra2.suppress = 0">
385       <xsl:choose>
386         <!-- * if max.length is non-empty, use value to truncate field -->
387         <xsl:when test="$man.th.extra2.max.length != ''">
388           <xsl:value-of
389               select="normalize-space(substring($extra2, 1, $man.th.extra2.max.length))"/>
390         </xsl:when>
391         <xsl:otherwise>
392           <xsl:value-of select="normalize-space($extra2)"/>
393         </xsl:otherwise>
394       </xsl:choose>
395     </xsl:if>
396     <xsl:text>" "</xsl:text>
397     <xsl:if test="$man.th.extra3.suppress = 0">
398       <xsl:choose>
399         <!-- * if max.length is non-empty, use value to truncate field -->
400         <xsl:when test="$man.th.extra3.max.length != ''">
401           <xsl:value-of
402               select="normalize-space(substring($extra3, 1, $man.th.extra3.max.length))"/>
403         </xsl:when>
404         <xsl:otherwise>
405           <xsl:value-of select="normalize-space($extra3)"/>
406         </xsl:otherwise>
407       </xsl:choose>
408     </xsl:if>
409     <xsl:text>"&#10;</xsl:text>
410     <xsl:call-template name="mark.subheading"/>
411   </xsl:template>
412
413   <!-- ============================================================== -->
414
415   <xsl:template name="set.default.formatting">
416     <!-- * Set default hyphenation, justification, indentation and -->
417     <!-- * line-breaking -->
418     <!-- * -->
419     <!-- * If the value of man.hypenate is zero (the default), then -->
420     <!-- * disable hyphenation (".nh" = "no hyphenation") -->
421     <xsl:text>.\" -----------------------------------------------------------------&#10;</xsl:text>
422     <xsl:text>.\" * set default formatting&#10;</xsl:text>
423     <xsl:text>.\" -----------------------------------------------------------------&#10;</xsl:text>
424     <xsl:if test="$man.hyphenate = 0">
425       <xsl:text>.\" disable hyphenation&#10;</xsl:text>
426       <xsl:text>.nh&#10;</xsl:text>
427     </xsl:if>
428     <!-- * If the value of man.justify is zero (the default), then -->
429     <!-- * disable justification (".ad l" means "adjust to left only") -->
430     <xsl:if test="$man.justify = 0">
431       <xsl:text>.\" disable justification</xsl:text>
432       <xsl:text> (adjust text to left margin only)&#10;</xsl:text>
433       <xsl:text>.ad l&#10;</xsl:text>
434     </xsl:if>
435     <xsl:if test="not($man.indent.refsect = 0)">
436       <xsl:text>.\" store initial "default indentation value"&#10;</xsl:text>
437       <xsl:text>.nr zq \n(IN&#10;</xsl:text>
438       <xsl:text>.\" adjust default indentation&#10;</xsl:text>
439       <xsl:text>.nr IN </xsl:text>
440       <xsl:value-of select="$man.indent.width"/>
441       <xsl:text>&#10;</xsl:text>
442       <xsl:text>.\" adjust indentation of SS headings&#10;</xsl:text>
443       <xsl:text>.nr SN \n(IN&#10;</xsl:text>
444     </xsl:if>
445     <!-- * Unless the value of man.break.after.slash is zero (the -->
446     <!-- * default), tell groff that it is OK to break a line -->
447     <!-- * after a slash when needed. -->
448     <xsl:if test="$man.break.after.slash != 0">
449       <xsl:text>.\" enable line breaks after slashes&#10;</xsl:text>
450       <xsl:text>.cflags 4 /&#10;</xsl:text>
451     </xsl:if>
452   </xsl:template>
453
454   <!-- ================================================================== -->
455
456   <!-- * The prepare.manpage.contents template is called after all -->
457   <!-- * other processing has been done, before serializing the -->
458   <!-- * result of all the other processing. It basically works on -->
459   <!-- * the result as one big string. -->
460   <xsl:template name="prepare.manpage.contents">
461     <xsl:param name="content" select="''"/>
462
463     <!-- * If user has provided a "local" string-substitution map to -->
464     <!-- * be applied /before/ the standard string-substitution map, -->
465     <!-- * apply it. -->
466     <xsl:variable name="pre.adjusted.content">
467       <xsl:choose>
468         <xsl:when test="$man.string.subst.map.local.pre">
469           <!-- * normalized value of man.string.subst.map.local.pre -->
470           <!-- * is non-empty, so get contents of map and apply them -->
471           <xsl:call-template name="apply-string-subst-map">
472             <xsl:with-param name="content" select="$content"/>
473             <xsl:with-param name="map.contents"
474                             select="exsl:node-set($man.string.subst.map.local.pre)/*"/>
475           </xsl:call-template>
476         </xsl:when>
477         <xsl:otherwise>
478           <!-- * value of man.string.subst.map.local.pre is empty, -->
479           <!-- * so just copy original contents -->
480           <xsl:value-of select="$content"/>
481         </xsl:otherwise>
482       </xsl:choose>
483     </xsl:variable>
484
485     <!-- * Apply standard string-substitution map. The main purpose -->
486     <!-- * of this map is to escape certain characters that have -->
487     <!-- * special meaning in roff, and to replace certain characters -->
488     <!-- * used within the stylesheet internally to represent roff -->
489     <!-- * markup characters. -->
490     <xsl:variable name="adjusted.content">
491       <xsl:call-template name="apply-string-subst-map">
492         <xsl:with-param name="content" select="$pre.adjusted.content"/>
493         <xsl:with-param name="map.contents"
494                         select="exsl:node-set($man.string.subst.map)/*"/>
495       </xsl:call-template>
496     </xsl:variable>
497
498     <!-- * If user has provided a "local" string-substitution map to -->
499     <!-- * be applied /after/ the standard string-substitution map, -->
500     <!-- * apply it. -->
501     <xsl:variable name="post.adjusted.content">
502       <xsl:choose>
503         <xsl:when test="$man.string.subst.map.local.post">
504           <!-- * normalized value of man.string.subst.map.local.post -->
505           <!-- * is non-empty, so get contents of map and apply them -->
506           <xsl:call-template name="apply-string-subst-map">
507             <xsl:with-param name="content" select="$adjusted.content"/>
508             <xsl:with-param name="map.contents"
509                             select="exsl:node-set($man.string.subst.map.local.post)/*"/>
510           </xsl:call-template>
511         </xsl:when>
512         <xsl:otherwise>
513           <!-- * value of man.string.subst.map.local.post is empty, -->
514           <!-- * so just copy original contents -->
515           <xsl:value-of select="$adjusted.content"/>
516         </xsl:otherwise>
517       </xsl:choose>
518     </xsl:variable>
519
520     <!-- * Optionally, apply a character map to replace Unicode -->
521     <!-- * symbols and special characters. -->
522     <xsl:choose>
523       <xsl:when test="$man.charmap.enabled != 0">
524         <xsl:call-template name="apply-character-map">
525           <xsl:with-param name="content" select="$post.adjusted.content"/>
526           <xsl:with-param name="map.contents"
527                           select="exsl:node-set($man.charmap.contents)/*"/>
528         </xsl:call-template>
529       </xsl:when>
530       <xsl:otherwise>
531         <!-- * if we reach here, value of $man.charmap.enabled is zero, -->
532         <!-- * so we just pass the adjusted contents through "as is" -->
533         <xsl:value-of select="$adjusted.content"/>
534       </xsl:otherwise>
535     </xsl:choose>
536   </xsl:template>
537
538   <!-- ================================================================== -->
539   
540   <xsl:template name="write.man.file">
541     <xsl:param name="name"/>
542     <xsl:param name="section"/>
543     <xsl:param name="lang"/>
544     <xsl:param name="content"/>
545     <xsl:param name="filename">
546       <xsl:call-template name="make.adjusted.man.filename">
547         <xsl:with-param name="name" select="$name"/>
548         <xsl:with-param name="section" select="$section"/>
549         <xsl:with-param name="lang" select="$lang"/>
550       </xsl:call-template>
551     </xsl:param>
552     <xsl:call-template name="write.text.chunk">
553       <xsl:with-param name="filename" select="$filename"/>
554       <xsl:with-param name="suppress-context-node-name" select="1"/>
555       <xsl:with-param name="quiet" select="$man.output.quietly"/>
556       <xsl:with-param
557           name="message-prolog"
558           >Note: </xsl:with-param>
559       <xsl:with-param name="encoding" select="$man.output.encoding"/>
560       <xsl:with-param name="content" select="$content"/>
561     </xsl:call-template>
562   </xsl:template>
563
564   <!-- ============================================================== -->
565
566   <!-- * A "stub" is sort of alias for another file, intended to be read -->
567   <!-- * and expanded by soelim(1); it's simply a file whose complete -->
568   <!-- * contents are just a single line of the following form: -->
569   <!-- * -->
570   <!-- *  .so manX/realname.X -->
571   <!-- * -->
572   <!-- * "realname" is a name of another man-page file. That .so line is -->
573   <!-- * basically a roff "include" statement.  When the man command finds -->
574   <!-- * it, it calls soelim(1) and includes and displays the contents of -->
575   <!-- * the manX/realqname.X file. -->
576   <!-- * -->
577   <!-- * If a refentry has multiple refnames, we generate a "stub" page for -->
578   <!-- * each refname found, except for the first one. -->
579   <xsl:template name="write.stubs">
580     <xsl:param name="first.refname"/>
581     <xsl:param name="section"/>
582     <xsl:param name="lang"/>
583     <xsl:for-each select="refnamediv/refname">
584       <xsl:if test=". != $first.refname">
585         <xsl:call-template name="write.text.chunk">
586           <xsl:with-param name="filename">
587             <xsl:call-template name="make.adjusted.man.filename">
588               <xsl:with-param name="name" select="."/>
589               <xsl:with-param name="section" select="$section"/>
590               <xsl:with-param name="lang" select="$lang"/>
591             </xsl:call-template>
592           </xsl:with-param>
593           <xsl:with-param name="quiet" select="$man.output.quietly"/>
594           <xsl:with-param name="suppress-context-node-name" select="1"/>
595           <xsl:with-param name="message-prolog">Note: </xsl:with-param>
596           <xsl:with-param name="message-epilog"> (soelim stub)</xsl:with-param>
597           <xsl:with-param name="content">
598             <xsl:value-of select="'.so '"/>
599             <xsl:call-template name="make.adjusted.man.filename">
600               <xsl:with-param name="name" select="$first.refname"/>
601               <xsl:with-param name="section" select="$section"/>
602               <xsl:with-param name="lang" select="$lang"/>
603             </xsl:call-template>
604             <xsl:text>&#10;</xsl:text>
605           </xsl:with-param>
606         </xsl:call-template>
607       </xsl:if>
608     </xsl:for-each>
609   </xsl:template>
610
611   <!-- ============================================================== -->
612
613   <!-- *  A manifest file is useful for doing "make clean" during -->
614   <!-- *  builds and for other purposes. When we make the manifest -->
615   <!-- *  file, we need to include in it a filename for each man-page -->
616   <!-- *  generated, including any "stub" pages. -->
617   <xsl:template name="generate.manifest">
618     <xsl:variable name="filelist">
619       <xsl:for-each select="//refentry">
620         <!-- * all refname instances in a Refentry inherit their section -->
621         <!-- * numbers from the parent Refentry; so we only need to get -->
622         <!-- * the section once per Refentry, not once per Refname -->
623         <xsl:variable name="section">
624           <xsl:call-template name="get.refentry.section">
625             <xsl:with-param name="quiet" select="1"/>
626           </xsl:call-template>
627         </xsl:variable>
628         <xsl:variable name="lang">
629           <xsl:call-template name="l10n.language"/>
630         </xsl:variable>
631         <xsl:for-each select="refnamediv/refname">
632           <xsl:call-template name="make.adjusted.man.filename">
633             <xsl:with-param name="name" select="."/>
634             <xsl:with-param name="section" select="$section"/>
635             <xsl:with-param name="lang" select="$lang"/>
636           </xsl:call-template>
637           <xsl:text>&#10;</xsl:text>
638         </xsl:for-each>
639       </xsl:for-each>
640     </xsl:variable>
641
642     <!-- * we write the manifest file once per document, not once per -->
643     <!-- * Refentry -->
644     <xsl:call-template name="write.text.chunk">
645       <xsl:with-param name="filename">
646         <xsl:value-of select="$man.output.manifest.filename"/>
647       </xsl:with-param>
648       <xsl:with-param name="quiet" select="1"/>
649       <xsl:with-param name="message-prolog">Note: </xsl:with-param>
650       <xsl:with-param name="message-epilog"> (manifest file)</xsl:with-param>
651       <xsl:with-param name="content">
652         <xsl:value-of select="$filelist"/>
653       </xsl:with-param>
654     </xsl:call-template>
655     <xsl:if test="$man.output.quietly = 0">
656       <xsl:message><xsl:text>&#10;</xsl:text></xsl:message>
657     </xsl:if>
658   </xsl:template>
659
660   <!-- ============================================================== -->
661
662   <!-- There is some stuff, that is not portable between groff/troff. -->
663   <xsl:template name="define.portability.macros">
664     <xsl:text>.\" -----------------------------------------------------------------&#10;</xsl:text>
665     <xsl:text>.\" * Define some portability stuff&#10;</xsl:text>
666     <xsl:text>.\" -----------------------------------------------------------------&#10;</xsl:text>
667     <xsl:text>.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~&#10;</xsl:text>
668     <xsl:text>.\" http://bugs.debian.org/507673&#10;</xsl:text>
669     <xsl:text>.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html&#10;</xsl:text>
670     <xsl:text>.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~&#10;</xsl:text>
671     <xsl:text>&#10;</xsl:text>
672     <xsl:text>.ie \n(.g .ds Aq \(aq</xsl:text>
673     <xsl:text>&#10;</xsl:text>
674     <xsl:text>.el       .ds Aq '</xsl:text>
675     <xsl:text>&#10;</xsl:text>
676   </xsl:template>
677
678   <!-- ============================================================== -->
679
680   <xsl:template name="define.macros">
681     <xsl:text>.\" -----------------------------------------------------------------&#10;</xsl:text>
682     <xsl:text>.\" * (re)Define some macros&#10;</xsl:text>
683     <xsl:text>.\" -----------------------------------------------------------------&#10;</xsl:text>
684     <xsl:text>.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~&#10;</xsl:text>
685     <xsl:text>.\" toupper - uppercase a string (locale-aware)&#10;</xsl:text>
686     <xsl:text>.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~&#10;</xsl:text>
687     <xsl:text>.de toupper&#10;</xsl:text>
688     <xsl:text>.tr</xsl:text>
689     <xsl:text> </xsl:text>
690     <xsl:call-template name="make.tr.uppercase.arg"/>
691     <xsl:text>\\$*&#10;</xsl:text>
692     <xsl:text>.tr</xsl:text>
693     <xsl:text> </xsl:text>
694     <xsl:call-template name="make.tr.normalcase.arg"/>
695     <xsl:text>..&#10;</xsl:text>
696     <xsl:text>.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~&#10;</xsl:text>
697     <xsl:text>.\" SH-xref - format a cross-reference to an SH section&#10;</xsl:text>
698     <xsl:text>.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~&#10;</xsl:text>
699     <xsl:text>.de SH-xref
700 .ie n \{\
701 .\}
702 .toupper \\$*
703 .el \{\
704 \\$*
705 .\}
706 ..&#10;</xsl:text>
707     <xsl:text>.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~&#10;</xsl:text>
708     <xsl:text>.\" SH - level-one heading that works better for non-TTY output&#10;</xsl:text>
709     <xsl:text>.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~&#10;</xsl:text>
710     <xsl:text>.de1 SH&#10;</xsl:text>
711     <xsl:text>.\" put an extra blank line of space above the head in non-TTY output&#10;</xsl:text>
712     <xsl:call-template name="roff-if-start">
713       <xsl:with-param name="condition">t</xsl:with-param>
714     </xsl:call-template>
715     <xsl:text>.sp 1&#10;</xsl:text>
716     <xsl:call-template name="roff-if-end"/>
717     <xsl:text>.sp \\n[PD]u
718 .nr an-level 1
719 .set-an-margin
720 .nr an-prevailing-indent \\n[IN]
721 .fi
722 .in \\n[an-margin]u
723 .ti 0
724 .HTML-TAG ".NH \\n[an-level]"
725 .it 1 an-trap
726 .nr an-no-space-flag 1
727 .nr an-break-flag 1
728 \." make the size of the head bigger
729 .ps +3
730 .ft B
731 .ne (2v + 1u)
732 .ie n \{\
733 .\" if n (TTY output), use uppercase
734 .toupper \\$*
735 .\}
736 .el \{\
737 .nr an-break-flag 0
738 .\" if not n (not TTY), use normal case (not uppercase)
739 \\$1
740 .in \\n[an-margin]u
741 .ti 0
742 .\" if not n (not TTY), put a border/line under subheading
743 .sp -.6
744 \l'\n(.lu'
745 .\}
746 ..&#10;</xsl:text>
747     <xsl:text>.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~&#10;</xsl:text>
748     <xsl:text>.\" SS - level-two heading that works better for non-TTY output&#10;</xsl:text>
749     <xsl:text>.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~&#10;</xsl:text>
750     <xsl:text>.de1 SS
751 .sp \\n[PD]u
752 .nr an-level 1
753 .set-an-margin
754 .nr an-prevailing-indent \\n[IN]
755 .fi
756 .in \\n[IN]u
757 .ti \\n[SN]u
758 .it 1 an-trap
759 .nr an-no-space-flag 1
760 .nr an-break-flag 1
761 .ps \\n[PS-SS]u
762 \." make the size of the head bigger
763 .ps +2
764 .ft B
765 .ne (2v + 1u)
766 .if \\n[.$] \&amp;\\$*
767 ..&#10;</xsl:text>
768     <xsl:text>.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~&#10;</xsl:text>
769     <xsl:text>.\" BB/EB - put background/screen (filled box) around block of text&#10;</xsl:text>
770     <xsl:text>.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~&#10;</xsl:text>
771     <xsl:text>.de BB
772 .if t \{\
773 .sp -.5
774 .br
775 .in +2n
776 .ll -2n
777 .gcolor red
778 .di BX
779 .\}
780 ..
781 .de EB
782 .if t \{\
783 .if "\\$2"adjust-for-leading-newline" \{\
784 .sp -1
785 .\}
786 .br
787 .di
788 .in
789 .ll
790 .gcolor
791 .nr BW \\n(.lu-\\n(.i
792 .nr BH \\n(dn+.5v
793 .ne \\n(BHu+.5v
794 .ie "\\$2"adjust-for-leading-newline" \{\
795 \M[\\$1]\h'1n'\v'+.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
796 .\}
797 .el \{\
798 \M[\\$1]\h'1n'\v'-.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
799 .\}
800 .in 0
801 .sp -.5v
802 .nf
803 .BX
804 .in
805 .sp .5v
806 .fi
807 .\}
808 ..&#10;</xsl:text>
809     <xsl:text>.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~&#10;</xsl:text>
810     <xsl:text>.\" BM/EM - put colored marker in margin next to block of text&#10;</xsl:text>
811     <xsl:text>.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~&#10;</xsl:text>
812     <xsl:text>.de BM
813 .if t \{\
814 .br
815 .ll -2n
816 .gcolor red
817 .di BX
818 .\}
819 ..
820 .de EM
821 .if t \{\
822 .br
823 .di
824 .ll
825 .gcolor
826 .nr BH \\n(dn
827 .ne \\n(BHu
828 \M[\\$1]\D'P -.75n 0 0 \\n(BHu -(\\n[.i]u - \\n(INu - .75n) 0 0 -\\n(BHu'\M[]
829 .in 0
830 .nf
831 .BX
832 .in
833 .fi
834 .\}
835 ..&#10;</xsl:text>
836 </xsl:template>
837
838 <xsl:template name="make.tr.uppercase.arg">
839   <xsl:call-template name="string.shuffle">
840     <xsl:with-param name="string1">
841       <xsl:call-template name="gentext">
842         <xsl:with-param name="key" select="'lowercase.alpha'"/>
843       </xsl:call-template>
844     </xsl:with-param>
845     <xsl:with-param name="string2">
846       <xsl:call-template name="gentext">
847         <xsl:with-param name="key" select="'uppercase.alpha'"/>
848       </xsl:call-template>
849     </xsl:with-param>
850   </xsl:call-template>
851   <xsl:text>&#10;</xsl:text>
852 </xsl:template>
853
854 <xsl:template name="make.tr.normalcase.arg">
855   <xsl:call-template name="string.shuffle">
856     <xsl:with-param name="string1">
857       <xsl:call-template name="gentext">
858         <xsl:with-param name="key" select="'lowercase.alpha'"/>
859       </xsl:call-template>
860     </xsl:with-param>
861     <xsl:with-param name="string2">
862       <xsl:call-template name="gentext">
863         <xsl:with-param name="key" select="'lowercase.alpha'"/>
864       </xsl:call-template>
865     </xsl:with-param>
866   </xsl:call-template>
867   <xsl:text>&#10;</xsl:text>
868 </xsl:template>
869
870 <xsl:template name="string.shuffle">
871   <!-- * given two strings, "shuffle" them together into one -->
872   <xsl:param name="string1"/>
873   <xsl:param name="string2"/>
874   <xsl:value-of select="substring($string1, 1, 1)"/>
875   <xsl:value-of select="substring($string2, 1, 1)"/>
876   <xsl:if test="string-length($string1) > 1">
877     <xsl:call-template name="string.shuffle">
878       <xsl:with-param name="string1">
879         <xsl:value-of select="substring($string1, 2)"/>
880       </xsl:with-param>
881       <xsl:with-param name="string2">
882         <xsl:value-of select="substring($string2, 2)"/>
883       </xsl:with-param>
884     </xsl:call-template>
885   </xsl:if>
886 </xsl:template>
887
888 </xsl:stylesheet>