root/docs/docbook-xsl/manpages/other.xsl

Revision 23dea7e00df87480acb58bb3398283c2bb227949, 12.7 kB (checked in by Theo Schlossnagle <jesus@omniti.com>, 7 years ago)

pull docs into master

  • Property mode set to 100644
Line 
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: other.xsl,v 1.11 2005/07/09 07:41:58 xmldoc Exp $
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 <!-- * This file contains named templates that are related to things -->
18 <!-- * other than just assembling the actual text of the main text flow -->
19 <!-- * of each man page. This "other" stuff currently amounts to: -->
20 <!-- * -->
21 <!-- *  - adding a comment to top part of roff source of each page -->
22 <!-- *  - making a .TH title line (for controlling page header/footer) -->
23 <!-- *  - setting hyphenation, alignment, & line-breaking defaults -->
24 <!-- *  - "preparing" the complete man page contents for final output -->
25 <!-- *  - writing the actual man file to the filesystem -->
26 <!-- *  - writing any "stub" pages to the filesystem -->
27 <!-- * -->
28 <!-- * The templates in this file are actually called only once per -->
29 <!-- * each Refentry; they are just in a separate file for the purpose -->
30 <!-- * of keeping things modular. -->
31
32 <!-- ==================================================================== -->
33 <!-- * Get character map contents -->
34 <!-- ==================================================================== -->
35
36   <xsl:variable name="man.charmap.contents">
37     <xsl:if test="$man.charmap.enabled != 0">
38       <xsl:call-template name="read-character-map">
39         <xsl:with-param name="use.subset" select="$man.charmap.use.subset"/>
40         <xsl:with-param name="subset.profile" select="$man.charmap.subset.profile"/>
41         <xsl:with-param name="uri">
42           <xsl:choose>
43             <xsl:when test="$man.charmap.uri != ''">
44               <xsl:value-of select="$man.charmap.uri"/>
45             </xsl:when>
46             <xsl:otherwise>
47               <xsl:value-of select="'../manpages/charmap.groff.xsl'"/>
48             </xsl:otherwise>
49           </xsl:choose>
50         </xsl:with-param>
51       </xsl:call-template>
52     </xsl:if>
53   </xsl:variable>
54
55 <!-- ==================================================================== -->
56
57   <xsl:template name="top.comment">
58     <xsl:text>.\" ** You probably do not want to</xsl:text>
59     <xsl:text> edit this file directly **&#10;</xsl:text>
60     <xsl:text>.\" It was generated using the DocBook</xsl:text>
61     <xsl:text> XSL Stylesheets (version </xsl:text>
62     <xsl:value-of select="$VERSION"/>
63     <xsl:text>).&#10;</xsl:text>
64     <xsl:text>.\" Instead of manually editing it, you</xsl:text>
65     <xsl:text> probably should edit the DocBook XML&#10;</xsl:text>
66     <xsl:text>.\" source for it and then use the DocBook</xsl:text>
67     <xsl:text> XSL Stylesheets to regenerate it.&#10;</xsl:text>
68   </xsl:template>
69
70 <!-- ==================================================================== -->
71
72   <xsl:template name="TH.title.line">
73
74     <!-- * The exact way that .TH contents are displayed is system- -->
75     <!-- * dependent; it varies somewhat between OSes and roff -->
76     <!-- * versions. Below is a description of how Linux systems with -->
77     <!-- * a modern groff seem to render .TH contents. -->
78     <!-- * -->
79     <!-- *   title(section)  extra3  title(section)  <- page header -->
80     <!-- *   extra2          extra1  title(section)  <- page footer-->
81     <!-- * -->
82     <!-- * Or, using the names with which the man(7) man page refers -->
83     <!-- * to the various fields: -->
84     <!-- * -->
85     <!-- *   title(section)  manual  title(section)  <- page header -->
86     <!-- *   source          date    title(section)  <- page footer-->
87     <!-- * -->
88     <!-- * Note that while extra1, extra2, and extra3 are all (nominally) -->
89     <!-- * optional, in practice almost all pages include an "extra1" -->
90     <!-- * field, which is, universally, a date (in some form), and it is -->
91     <!-- * always rendered in the same place (the middle footer position) -->
92     <!-- * -->
93     <!-- * Here are a couple of examples of real-world man pages that -->
94     <!-- * have somewhat useful page headers/footers: -->
95     <!-- * -->
96     <!-- *   gtk-options(7)    GTK+ User's Manual   gtk-options(7) -->
97     <!-- *   GTK+ 1.2              2003-10-20       gtk-options(7) -->
98     <!-- * -->
99     <!-- *   svgalib(7)       Svgalib User Manual       svgalib(7) -->
100     <!-- *   Svgalib 1.4.1      16 December 1999        svgalib(7) -->
101     <!-- * -->
102     <xsl:param name="title"/>
103     <xsl:param name="section"/>
104     <xsl:param name="extra1"/>
105     <xsl:param name="extra2"/>
106     <xsl:param name="extra3"/>
107
108     <xsl:call-template name="mark.subheading"/>
109     <!-- * Note that we generate quotes around _every_ field in the -->
110     <!-- * .TH title line, including the "title" and "section" -->
111     <!-- * fields. That is because we use the contents of those "as -->
112     <!-- * is", unchanged from the DocBook source; and DTD-based -->
113     <!-- * validation does not provide a way to constrain them to be -->
114     <!-- * "space free" -->
115     <xsl:text>.TH "</xsl:text>
116     <xsl:call-template name="string.upper">
117       <xsl:with-param name="string">
118         <xsl:choose>
119           <xsl:when test="$man.th.title.max.length != ''">
120             <xsl:value-of
121                 select="normalize-space(substring($title, 1, $man.th.title.max.length))"/>
122           </xsl:when>
123           <xsl:otherwise>
124             <xsl:value-of select="normalize-space($title)"/>
125           </xsl:otherwise>
126         </xsl:choose>
127       </xsl:with-param>
128     </xsl:call-template>
129     <xsl:text>" "</xsl:text>
130     <xsl:value-of select="normalize-space($section)"/>
131     <xsl:text>" "</xsl:text>
132     <xsl:if test="$man.th.extra1.suppress = 0">
133       <!-- * there is no max.length for the extra1 field; the reason -->
134       <!-- * is, it is almost always a date, and it is not possible -->
135       <!-- * to truncate dates without changing their meaning -->
136       <xsl:value-of select="normalize-space($extra1)"/>
137     </xsl:if>
138     <xsl:text>" "</xsl:text>
139     <xsl:if test="$man.th.extra2.suppress = 0">
140       <xsl:choose>
141         <!-- * if max.length is non-empty, use value to truncate field -->
142         <xsl:when test="$man.th.extra2.max.length != ''">
143           <xsl:value-of
144               select="normalize-space(substring($extra2, 1, $man.th.extra2.max.length))"/>
145         </xsl:when>
146         <xsl:otherwise>
147           <xsl:value-of select="normalize-space($extra2)"/>
148         </xsl:otherwise>
149       </xsl:choose>
150     </xsl:if>
151     <xsl:text>" "</xsl:text>
152     <xsl:if test="$man.th.extra3.suppress = 0">
153       <xsl:choose>
154         <!-- * if max.length is non-empty, use value to truncate field -->
155         <xsl:when test="$man.th.extra3.max.length != ''">
156           <xsl:value-of
157               select="normalize-space(substring($extra3, 1, $man.th.extra3.max.length))"/>
158         </xsl:when>
159         <xsl:otherwise>
160           <xsl:value-of select="normalize-space($extra3)"/>
161         </xsl:otherwise>
162       </xsl:choose>
163     </xsl:if>
164     <xsl:text>"&#10;</xsl:text>
165     <xsl:call-template name="mark.subheading"/>
166   </xsl:template>
167
168   <!-- ============================================================== -->
169
170   <xsl:template name="set.default.formatting">
171     <!-- * Set default hyphenation, justification, and line-breaking -->
172     <!-- * -->
173     <!-- * If the value of man.hypenate is zero (the default), then -->
174     <!-- * disable hyphenation (".nh" = "no hyphenation") -->
175     <xsl:if test="$man.hyphenate = 0">
176       <xsl:text>.\" disable hyphenation&#10;</xsl:text>
177       <xsl:text>.nh&#10;</xsl:text>
178     </xsl:if>
179     <!-- * If the value of man.justify is zero (the default), then -->
180     <!-- * disable justification (".ad l" means "adjust to left only") -->
181     <xsl:if test="$man.justify = 0">
182       <xsl:text>.\" disable justification</xsl:text>
183       <xsl:text> (adjust text to left margin only)&#10;</xsl:text>
184       <xsl:text>.ad l&#10;</xsl:text>
185     </xsl:if>
186     <!-- * Unless the value of man.break.after.slash is zero (the -->
187     <!-- * default), tell groff that it is OK to break a line -->
188     <!-- * after a slash when needed. -->
189     <xsl:if test="$man.break.after.slash != 0">
190       <xsl:text>.\" enable line breaks after slashes&#10;</xsl:text>
191       <xsl:text>.cflags 4 /&#10;</xsl:text>
192     </xsl:if>
193   </xsl:template>
194
195   <!-- ================================================================== -->
196
197   <!-- * The prepare.manpage.contents template is called after -->
198   <!-- * everything else has been done, just before writing the actual -->
199   <!-- * man-page files to the filesystem. It works on the entire roff -->
200   <!-- * source for each man page (not just the visible contents). -->
201   <xsl:template name="prepare.manpage.contents">
202     <xsl:param name="content" select="''"/>
203
204     <!-- * First do "essential" string/character substitutions; for -->
205     <!-- * example, the backslash character _must_ be substituted with -->
206     <!-- * a double backslash, to prevent it from being interpreted as -->
207     <!-- * a roff escape -->
208     <xsl:variable name="adjusted.content">
209       <xsl:call-template name="apply-string-subst-map">
210         <xsl:with-param name="content" select="$content"/>
211         <xsl:with-param name="map.contents"
212                         select="exsl:node-set($man.string.subst.map)/*"/>
213       </xsl:call-template>
214     </xsl:variable>
215
216     <!-- * Optionally, apply a character map to replace Unicode -->
217     <!-- * symbols and special characters. -->
218     <xsl:choose>
219       <xsl:when test="$man.charmap.enabled != 0">
220         <xsl:call-template name="apply-character-map">
221           <xsl:with-param name="content" select="$adjusted.content"/>
222           <xsl:with-param name="map.contents"
223                           select="exsl:node-set($man.charmap.contents)/*"/>
224         </xsl:call-template>
225       </xsl:when>
226       <xsl:otherwise>
227         <!-- * if we reach here, value of $man.charmap.enabled is zero, -->
228         <!-- * so we just pass the adjusted contents through "as is" -->
229         <xsl:value-of select="$adjusted.content"/>
230       </xsl:otherwise>
231     </xsl:choose>
232   </xsl:template>
233
234   <!-- ================================================================== -->
235  
236   <xsl:template name="write.man.file">
237     <xsl:param name="name"/>
238     <xsl:param name="section"/>
239     <xsl:param name="content"/>
240     <xsl:param name="filename">
241       <xsl:call-template name="string.subst">
242         <!-- replace spaces in source filename with underscores in output filename -->
243         <xsl:with-param name="string"
244                         select="concat(normalize-space($name), '.', normalize-space($section))"/>
245         <xsl:with-param name="target" select="' '"/>
246         <xsl:with-param name="replacement" select="'_'"/>
247       </xsl:call-template>
248     </xsl:param>
249     <xsl:call-template name="write.text.chunk">
250       <xsl:with-param name="filename" select="$filename"/>
251       <xsl:with-param name="quiet" select="$man.output.quietly"/>
252       <xsl:with-param name="encoding" select="$man.output.encoding"/>
253       <xsl:with-param name="content" select="$content"/>
254     </xsl:call-template>
255   </xsl:template>
256
257   <!-- ============================================================== -->
258
259   <!-- * A "stub" is sort of alias for another file, intended to be read -->
260   <!-- * and expanded by soelim(1); it's simply a file whose complete -->
261   <!-- * contents are just a single line of the following form: -->
262   <!-- * -->
263   <!-- *  .so manX/realname.X -->
264   <!-- * -->
265   <!-- * "realname" is a name of another man-page file. That .so line is -->
266   <!-- * basically a roff "include" statement.  When the man command finds -->
267   <!-- * it, it calls soelim(1) and includes and displays the contents of -->
268   <!-- * the manX/realqname.X file. -->
269   <!-- * -->
270   <!-- * If a refentry has multiple refnames, we generate a "stub" page for -->
271   <!-- * each refname found, except for the first one. -->
272   <xsl:template name="write.stubs">
273     <xsl:param name="first.refname"/>
274     <xsl:param name="section"/>
275     <xsl:for-each select="refnamediv/refname">
276       <xsl:if test=". != $first.refname">
277         <xsl:call-template name="write.text.chunk">
278           <xsl:with-param name="filename"
279                           select="concat(normalize-space(.), '.',
280                                   $section)"/>
281           <xsl:with-param name="quiet" select="$man.output.quietly"/>
282           <xsl:with-param
283               name="content"
284               select="concat('.so man', $section, '/',
285                       $first.refname, '.', $section, '&#10;')"/>
286         </xsl:call-template>
287       </xsl:if>
288     </xsl:for-each>
289   </xsl:template>
290
291 </xsl:stylesheet>
Note: See TracBrowser for help on using the browser.