doc/docbook-xsl/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:db="http://docbook.org/ns/docbook"
   5                 exclude-result-prefixes="exsl"
   6                 version='1.0'>
   7
   8 <!-- ********************************************************************
   9      $Id: other.xsl,v 1.1 2007/03/10 05:15:34 scott Exp $
  10      ********************************************************************
  11
  12      This file is part of the XSL DocBook Stylesheet distribution.
  13      See ../README or http://docbook.sf.net/release/xsl/current/ for
  14      copyright and other information.
  15
  16      ******************************************************************** -->
  17
  18 <!-- * This file contains named templates related to things other than -->
  19 <!-- * just assembling the actual text of the main text flow of each man -->
  20 <!-- * page. This "other" stuff currently amounts to these steps: -->
  21 <!-- * -->
  22 <!-- *  - output boilerplate messages -->
  23 <!-- *  - add a comment to top part of roff source of each page -->
  24 <!-- *  - make a .TH title line (for controlling page header/footer) -->
  25 <!-- *  - set hyphenation, alignment, indent & line-breaking defaults -->
  26 <!-- *  - "prepare" the complete man page contents for final output -->
  27 <!-- *  - write the actual man file to the filesystem -->
  28 <!-- *  - write any "stub" pages to the filesystem -->
  29 <!-- * -->
  30 <!-- * The templates in this file are actually called only once per -->
  31 <!-- * each Refentry; they are just in a separate file for the purpose -->
  32 <!-- * of keeping things modular. -->
  33
  34 <!-- ==================================================================== -->
  35
  36 <xsl:preserve-space elements="*"/>
  37
  38 <xsl:strip-space elements="
  39 abstract affiliation anchor answer appendix area areaset areaspec
  40 artheader article audiodata audioobject author authorblurb authorgroup
  41 beginpage bibliodiv biblioentry bibliography biblioset blockquote book
  42 bookbiblio bookinfo callout calloutlist caption caution chapter
  43 citerefentry cmdsynopsis co collab colophon colspec confgroup
  44 copyright dedication docinfo editor entrytbl epigraph equation
  45 example figure footnote footnoteref formalpara funcprototype
  46 funcsynopsis glossary glossdef glossdiv glossentry glosslist graphicco
  47 group highlights imagedata imageobject imageobjectco important index
  48 indexdiv indexentry indexterm informalequation informalexample
  49 informalfigure informaltable inlineequation inlinemediaobject
  50 itemizedlist itermset keycombo keywordset legalnotice listitem lot
  51 mediaobject mediaobjectco menuchoice msg msgentry msgexplan msginfo
  52 msgmain msgrel msgset msgsub msgtext note objectinfo
  53 orderedlist othercredit part partintro preface printhistory procedure
  54 programlistingco publisher qandadiv qandaentry qandaset question
  55 refentry reference refmeta refnamediv refsection refsect1 refsect1info refsect2
  56 refsect2info refsect3 refsect3info refsynopsisdiv refsynopsisdivinfo
  57 revhistory revision row sbr screenco screenshot sect1 sect1info sect2
  58 sect2info sect3 sect3info sect4 sect4info sect5 sect5info section
  59 sectioninfo seglistitem segmentedlist seriesinfo set setindex setinfo
  60 shortcut sidebar simplelist simplesect spanspec step subject
  61 subjectset substeps synopfragment table tbody textobject tfoot tgroup
  62 thead tip toc tocchap toclevel1 toclevel2 toclevel3 toclevel4
  63 toclevel5 tocpart varargs variablelist varlistentry videodata
  64 videoobject void warning subjectset
  65
  66 classsynopsis
  67 constructorsynopsis
  68 destructorsynopsis
  69 fieldsynopsis
  70 methodparam
  71 methodsynopsis
  72 ooclass
  73 ooexception
  74 oointerface
  75 simplemsgentry
  76 manvolnum
  77
  78 db:abstract db:affiliation db:anchor db:answer db:appendix db:area db:areaset db:areaspec
  79 db:artheader db:article db:audiodata db:audioobject db:author db:authorblurb db:authorgroup
  80 db:beginpage db:bibliodiv db:biblioentry db:bibliography db:biblioset db:blockquote db:book
  81 db:bookbiblio db:bookinfo db:callout db:calloutlist db:caption db:caution db:chapter
  82 db:citerefentry db:cmdsynopsis db:co db:collab db:colophon db:colspec db:confgroup
  83 db:copyright db:dedication db:docinfo db:editor db:entrytbl db:epigraph db:equation
  84 db:example db:figure db:footnote db:footnoteref db:formalpara db:funcprototype
  85 db:funcsynopsis db:glossary db:glossdef db:glossdiv db:glossentry db:glosslist db:graphicco
  86 db:group db:highlights db:imagedata db:imageobject db:imageobjectco db:important db:index
  87 db:indexdiv db:indexentry db:indexterm db:informalequation db:informalexample
  88 db:informalfigure db:informaltable db:inlineequation db:inlinemediaobject
  89 db:itemizedlist db:itermset db:keycombo db:keywordset db:legalnotice db:listitem db:lot
  90 db:mediaobject db:mediaobjectco db:menuchoice db:msg db:msgentry db:msgexplan db:msginfo
  91 db:msgmain db:msgrel db:msgset db:msgsub db:msgtext db:note db:objectinfo
  92 db:orderedlist db:othercredit db:part db:partintro db:preface db:printhistory db:procedure
  93 db:programlistingco db:publisher db:qandadiv db:qandaentry db:qandaset db:question
  94 db:refentry db:reference db:refmeta db:refnamediv db:refsection db:refsect1 db:refsect1info
  95 db:refsect2
  96 db:refsect2info db:refsect3 db:refsect3info db:refsynopsisdiv db:refsynopsisdivinfo
  97 db:revhistory db:revision db:row db:sbr db:screenco db:screenshot db:sect1 db:sect1info db:sect2
  98 db:sect2info db:sect3 db:sect3info db:sect4 db:sect4info db:sect5 db:sect5info db:section
  99 db:sectioninfo db:seglistitem db:segmentedlist db:seriesinfo db:set db:setindex db:setinfo
 100 db:shortcut db:sidebar db:simplelist db:simplesect db:spanspec db:step db:subject
 101 db:subjectset db:substeps db:synopfragment db:table db:tbody db:textobject db:tfoot db:tgroup
 102 db:thead db:tip db:toc db:tocchap db:toclevel1 db:toclevel2 db:toclevel3 db:toclevel4
 103 db:toclevel5 db:tocpart db:varargs db:variablelist db:varlistentry db:videodata
 104 db:videoobject db:void db:warning db:subjectset
 105
 106 db:classsynopsis
 107 db:constructorsynopsis
 108 db:destructorsynopsis
 109 db:fieldsynopsis
 110 db:methodparam
 111 db:methodsynopsis
 112 db:ooclass
 113 db:ooexception
 114 db:oointerface
 115 db:simplemsgentry
 116 db:manvolnum
 117 "/>
 118
 119 <!-- ==================================================================== -->
 120 <!-- * Get character map contents -->
 121 <!-- ==================================================================== -->
 122
 123   <xsl:variable name="man.charmap.contents">
 124     <xsl:if test="$man.charmap.enabled != 0">
 125       <xsl:call-template name="read-character-map">
 126         <xsl:with-param name="use.subset" select="$man.charmap.use.subset"/>
 127         <xsl:with-param name="subset.profile" select="$man.charmap.subset.profile"/>
 128         <xsl:with-param name="uri">
 129           <xsl:choose>
 130             <xsl:when test="$man.charmap.uri != ''">
 131               <xsl:value-of select="$man.charmap.uri"/>
 132             </xsl:when>
 133             <xsl:otherwise>
 134               <xsl:value-of select="'../manpages/charmap.groff.xsl'"/>
 135             </xsl:otherwise>
 136           </xsl:choose>
 137         </xsl:with-param>
 138       </xsl:call-template>
 139     </xsl:if>
 140   </xsl:variable>
 141
 142 <!-- ==================================================================== -->
 143
 144 <xsl:template name="root.messages">
 145   <xsl:param name="refname"/>
 146   <!-- redefine this any way you'd like to output messages -->
 147   <!-- DO NOT OUTPUT ANYTHING FROM THIS TEMPLATE -->
 148   <!-- Example:
 149   <xsl:if test="//footnote">
 150     <xsl:call-template name="log.message">
 151       <xsl:with-param name="level">Warn</xsl:with-param>
 152       <xsl:with-param name="source" select="$refname"/>
 153       <xsl:with-param
 154           name="message"
 155           >Output for footnote element is not yet supported.</xsl:with-param>
 156     </xsl:call-template>
 157   </xsl:if>
 158   -->
 159 </xsl:template>
 160
 161 <!-- ==================================================================== -->
 162 <!-- * Escape roff special chars -->
 163 <!-- ==================================================================== -->
 164
 165 <!-- ******************************************************************** -->
 166 <!-- *  -->
 167 <!-- * The backslash, dot, dash, and apostrophe (\, ., -, ') characters -->
 168 <!-- * have special meaning for roff, so before we do any other -->
 169 <!-- * processing, we must escape those characters where they appear in -->
 170 <!-- * the source content. -->
 171 <!-- *  -->
 172 <!-- * Here we also deal with replacing U+00a0 (non-breaking space) with -->
 173 <!-- * its roff equivalent -->
 174 <!-- *  -->
 175 <!-- ******************************************************************** -->
 176
 177 <xsl:template match="//refentry//text()">
 178   <xsl:call-template name="escape.roff.specials">
 179     <xsl:with-param name="content">
 180       <xsl:value-of select="."/>
 181     </xsl:with-param>
 182   </xsl:call-template>
 183 </xsl:template>
 184
 185 <xsl:template name="escape.roff.specials">
 186   <xsl:param name="content"/>
 187   <xsl:call-template name="convert.nobreak-space">
 188     <xsl:with-param name="content">
 189       <xsl:call-template name="escape.apostrophe">
 190         <xsl:with-param name="content">
 191           <xsl:call-template name="escape.dash">
 192             <xsl:with-param name="content">
 193               <xsl:call-template name="escape.dot">
 194                 <xsl:with-param name="content">
 195                   <xsl:call-template name="escape.backslash">
 196                     <xsl:with-param name="content" select="$content"/>
 197                   </xsl:call-template>
 198                 </xsl:with-param>
 199               </xsl:call-template>
 200             </xsl:with-param>
 201           </xsl:call-template>
 202         </xsl:with-param>
 203       </xsl:call-template>
 204     </xsl:with-param>
 205   </xsl:call-template>
 206 </xsl:template>
 207
 208 <xsl:template name="escape.backslash">
 209   <xsl:param name="content"/>
 210   <xsl:call-template name="string.subst">
 211     <xsl:with-param name="string" select="$content"/>
 212     <xsl:with-param name="target">\</xsl:with-param>
 213     <!-- * we use "\e" instead of "\\" because the groff docs say -->
 214     <!-- * that's the correct thing to do; also because testing -->
 215     <!-- * shows that "\\" doesn't always work as expected; for -->
 216     <!-- * example, "\\" within a table seems to mess things up -->
 217     <xsl:with-param name="replacement">\e</xsl:with-param>
 218   </xsl:call-template>
 219 </xsl:template>
 220
 221 <xsl:template name="escape.dot">
 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">\.</xsl:with-param>
 227   </xsl:call-template>
 228 </xsl:template>
 229
 230 <xsl:template name="escape.dash">
 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">-</xsl:with-param>
 235     <xsl:with-param name="replacement">\-</xsl:with-param>
 236   </xsl:call-template>
 237 </xsl:template>
 238
 239 <xsl:template name="escape.apostrophe">
 240   <xsl:param name="content"/>
 241   <xsl:call-template name="string.subst">
 242     <xsl:with-param name="string" select="$content"/>
 243     <xsl:with-param name="target">'</xsl:with-param>
 244     <xsl:with-param name="replacement">\'</xsl:with-param>
 245   </xsl:call-template>
 246 </xsl:template>
 247
 248 <xsl:template name="convert.nobreak-space">
 249   <xsl:param name="content"/>
 250   <xsl:call-template name="string.subst">
 251     <xsl:with-param name="string" select="$content"/>
 252     <xsl:with-param name="target">&#x00a0;</xsl:with-param>
 253     <!-- * A no-break space can be written two ways in roff; the -->
 254     <!-- * difference, according to the "Page Motions" node in the -->
 255     <!-- * groff info page, is: -->
 256     <!-- *  -->
 257     <!-- *   "\ " = -->
 258     <!-- *   An unbreakable and unpaddable (i.e. not expanded -->
 259     <!-- *   during filling) space. -->
 260     <!-- *  -->
 261     <!-- *   "\~" = -->
 262     <!-- *   An unbreakable space that stretches like a normal -->
 263     <!-- *   inter-word space when a line is adjusted."  -->
 264     <!-- *  -->
 265     <!-- * Unfortunately, roff seems to do some weird things with -->
 266     <!-- * long lines that only have words separated by "\~" -->
 267     <!-- * spaces, so it's safer just to stick with the "\ " space -->
 268     <xsl:with-param name="replacement">\ </xsl:with-param>
 269   </xsl:call-template>
 270 </xsl:template>
 271
 272 <!-- ==================================================================== -->
 273
 274 <!-- * top.comment generates a comment containing metadata for the man -->
 275 <!-- * page; for example, Author, Generator, and Date information -->
 276
 277   <xsl:template name="top.comment">
 278     <xsl:param name="info"/>
 279     <xsl:param name="date"/>
 280     <xsl:param name="title"/>
 281     <xsl:param name="manual"/>
 282     <xsl:param name="source"/>
 283     <xsl:text>.\"     Title: </xsl:text>
 284     <xsl:call-template name="replace.dots.and.dashes">
 285       <xsl:with-param name="content" select="$title"/>
 286     </xsl:call-template>
 287     <xsl:text>&#10;</xsl:text>
 288     <xsl:text>.\"    Author: </xsl:text>
 289     <xsl:call-template name="replace.dots.and.dashes">
 290       <xsl:with-param name="content">
 291         <xsl:call-template name="make.roff.metadata.author">
 292           <xsl:with-param name="info" select="$info"/>
 293         </xsl:call-template>
 294       </xsl:with-param>
 295     </xsl:call-template>
 296     <xsl:text>&#10;</xsl:text>
 297     <xsl:text>.\" Generator: DocBook </xsl:text>
 298     <xsl:value-of select="$DistroTitle"/>
 299     <xsl:text> v</xsl:text>
 300     <xsl:call-template name="replace.dots.and.dashes">
 301       <xsl:with-param name="content" select="$VERSION"/>
 302     </xsl:call-template>
 303     <xsl:text> &lt;http://docbook.sf.net/></xsl:text>
 304     <xsl:text>&#10;</xsl:text>
 305     <xsl:text>.\"      Date: </xsl:text>
 306     <xsl:call-template name="replace.dots.and.dashes">
 307       <xsl:with-param name="content" select="$date"/>
 308     </xsl:call-template>
 309     <xsl:text>&#10;</xsl:text>
 310     <xsl:text>.\"    Manual: </xsl:text>
 311     <xsl:call-template name="replace.dots.and.dashes">
 312       <xsl:with-param name="content" select="$manual"/>
 313     </xsl:call-template>
 314     <xsl:text>&#10;</xsl:text>
 315     <xsl:text>.\"    Source: </xsl:text>
 316     <xsl:call-template name="replace.dots.and.dashes">
 317       <xsl:with-param name="content" select="$source"/>
 318     </xsl:call-template>
 319     <xsl:text>&#10;</xsl:text>
 320     <xsl:text>.\"</xsl:text>
 321     <xsl:text>&#10;</xsl:text>
 322   </xsl:template>
 323
 324 <!-- ==================================================================== -->
 325
 326   <xsl:template name="TH.title.line">
 327
 328     <!-- * The exact way that .TH contents are displayed is system- -->
 329     <!-- * dependent; it varies somewhat between OSes and roff -->
 330     <!-- * versions. Below is a description of how Linux systems with -->
 331     <!-- * a modern groff seem to render .TH contents. -->
 332     <!-- * -->
 333     <!-- *   title(section)  extra3  title(section)  <- page header -->
 334     <!-- *   extra2          extra1  title(section)  <- page footer-->
 335     <!-- * -->
 336     <!-- * Or, using the names with which the man(7) man page refers -->
 337     <!-- * to the various fields: -->
 338     <!-- * -->
 339     <!-- *   title(section)  manual  title(section)  <- page header -->
 340     <!-- *   source          date    title(section)  <- page footer-->
 341     <!-- * -->
 342     <!-- * Note that while extra1, extra2, and extra3 are all (nominally) -->
 343     <!-- * optional, in practice almost all pages include an "extra1" -->
 344     <!-- * field, which is, universally, a date (in some form), and it is -->
 345     <!-- * always rendered in the same place (the middle footer position) -->
 346     <!-- * -->
 347     <!-- * Here are a couple of examples of real-world man pages that -->
 348     <!-- * have somewhat useful page headers/footers: -->
 349     <!-- * -->
 350     <!-- *   gtk-options(7)    GTK+ User's Manual   gtk-options(7) -->
 351     <!-- *   GTK+ 1.2              2003-10-20       gtk-options(7) -->
 352     <!-- * -->
 353     <!-- *   svgalib(7)       Svgalib User Manual       svgalib(7) -->
 354     <!-- *   Svgalib 1.4.1      16 December 1999        svgalib(7) -->
 355     <!-- * -->
 356     <xsl:param name="title"/>
 357     <xsl:param name="section"/>
 358     <xsl:param name="extra1"/>
 359     <xsl:param name="extra2"/>
 360     <xsl:param name="extra3"/>
 361
 362     <xsl:call-template name="mark.subheading"/>
 363     <!-- * Note that we generate quotes around _every_ field in the -->
 364     <!-- * .TH title line, including the "title" and "section" -->
 365     <!-- * fields. That is because we use the contents of those "as -->
 366     <!-- * is", unchanged from the DocBook source; and DTD-based -->
 367     <!-- * validation does not provide a way to constrain them to be -->
 368     <!-- * "space free" -->
 369     <xsl:text>.TH "</xsl:text>
 370     <xsl:call-template name="string.upper">
 371       <xsl:with-param name="string">
 372         <xsl:choose>
 373           <xsl:when test="$man.th.title.max.length != ''">
 374             <xsl:value-of
 375                 select="normalize-space(substring($title, 1, $man.th.title.max.length))"/>
 376           </xsl:when>
 377           <xsl:otherwise>
 378             <xsl:value-of select="normalize-space($title)"/>
 379           </xsl:otherwise>
 380         </xsl:choose>
 381       </xsl:with-param>
 382     </xsl:call-template>
 383     <xsl:text>" "</xsl:text>
 384     <xsl:value-of select="normalize-space($section)"/>
 385     <xsl:text>" "</xsl:text>
 386     <xsl:if test="$man.th.extra1.suppress = 0">
 387       <!-- * there is no max.length for the extra1 field; the reason -->
 388       <!-- * is, it is almost always a date, and it is not possible -->
 389       <!-- * to truncate dates without changing their meaning -->
 390       <xsl:value-of select="normalize-space($extra1)"/>
 391     </xsl:if>
 392     <xsl:text>" "</xsl:text>
 393     <xsl:if test="$man.th.extra2.suppress = 0">
 394       <xsl:choose>
 395         <!-- * if max.length is non-empty, use value to truncate field -->
 396         <xsl:when test="$man.th.extra2.max.length != ''">
 397           <xsl:value-of
 398               select="normalize-space(substring($extra2, 1, $man.th.extra2.max.length))"/>
 399         </xsl:when>
 400         <xsl:otherwise>
 401           <xsl:value-of select="normalize-space($extra2)"/>
 402         </xsl:otherwise>
 403       </xsl:choose>
 404     </xsl:if>
 405     <xsl:text>" "</xsl:text>
 406     <xsl:if test="$man.th.extra3.suppress = 0">
 407       <xsl:choose>
 408         <!-- * if max.length is non-empty, use value to truncate field -->
 409         <xsl:when test="$man.th.extra3.max.length != ''">
 410           <xsl:value-of
 411               select="normalize-space(substring($extra3, 1, $man.th.extra3.max.length))"/>
 412         </xsl:when>
 413         <xsl:otherwise>
 414           <xsl:value-of select="normalize-space($extra3)"/>
 415         </xsl:otherwise>
 416       </xsl:choose>
 417     </xsl:if>
 418     <xsl:text>"&#10;</xsl:text>
 419     <xsl:call-template name="mark.subheading"/>
 420   </xsl:template>
 421
 422   <!-- ============================================================== -->
 423
 424   <xsl:template name="set.default.formatting">
 425     <!-- * Set default hyphenation, justification, indentation and -->
 426     <!-- * line-breaking -->
 427     <!-- * -->
 428     <!-- * If the value of man.hypenate is zero (the default), then -->
 429     <!-- * disable hyphenation (".nh" = "no hyphenation") -->
 430     <xsl:if test="$man.hyphenate = 0">
 431       <xsl:text>.\" disable hyphenation&#10;</xsl:text>
 432       <xsl:text>.nh&#10;</xsl:text>
 433     </xsl:if>
 434     <!-- * If the value of man.justify is zero (the default), then -->
 435     <!-- * disable justification (".ad l" means "adjust to left only") -->
 436     <xsl:if test="$man.justify = 0">
 437       <xsl:text>.\" disable justification</xsl:text>
 438       <xsl:text> (adjust text to left margin only)&#10;</xsl:text>
 439       <xsl:text>.ad l&#10;</xsl:text>
 440     </xsl:if>
 441     <xsl:if test="not($man.indent.refsect = 0)">
 442       <xsl:text>.\" store initial "default indentation value"&#10;</xsl:text>
 443       <xsl:text>.nr zq \n(IN&#10;</xsl:text>
 444       <xsl:text>.\" adjust default indentation&#10;</xsl:text>
 445       <xsl:text>.nr IN </xsl:text>
 446       <xsl:value-of select="$man.indent.width"/>
 447       <xsl:text>&#10;</xsl:text>
 448       <xsl:text>.\" adjust indentation of SS headings&#10;</xsl:text>
 449       <xsl:text>.nr SN \n(IN&#10;</xsl:text>
 450     </xsl:if>
 451     <!-- * Unless the value of man.break.after.slash is zero (the -->
 452     <!-- * default), tell groff that it is OK to break a line -->
 453     <!-- * after a slash when needed. -->
 454     <xsl:if test="$man.break.after.slash != 0">
 455       <xsl:text>.\" enable line breaks after slashes&#10;</xsl:text>
 456       <xsl:text>.cflags 4 /&#10;</xsl:text>
 457     </xsl:if>
 458   </xsl:template>
 459
 460   <!-- ================================================================== -->
 461
 462   <!-- * The prepare.manpage.contents template is called after all -->
 463   <!-- * other processing has been done, before serializing the -->
 464   <!-- * result of all the other processing. It basically works on -->
 465   <!-- * the result as one big string. -->
 466   <xsl:template name="prepare.manpage.contents">
 467     <xsl:param name="content" select="''"/>
 468
 469     <!-- * If user has provided a "local" string-substitution map to -->
 470     <!-- * be applied /before/ the standard string-substitution map, -->
 471     <!-- * apply it. -->
 472     <xsl:variable name="pre.adjusted.content">
 473       <xsl:choose>
 474         <xsl:when test="$man.string.subst.map.local.pre">
 475           <!-- * normalized value of man.string.subst.map.local.pre -->
 476           <!-- * is non-empty, so get contents of map and apply them -->
 477           <xsl:call-template name="apply-string-subst-map">
 478             <xsl:with-param name="content" select="$content"/>
 479             <xsl:with-param name="map.contents"
 480                             select="exsl:node-set($man.string.subst.map.local.pre)/*"/>
 481           </xsl:call-template>
 482         </xsl:when>
 483         <xsl:otherwise>
 484           <!-- * value of man.string.subst.map.local.pre is empty, -->
 485           <!-- * so just copy original contents -->
 486           <xsl:value-of select="$content"/>
 487         </xsl:otherwise>
 488       </xsl:choose>
 489     </xsl:variable>
 490
 491     <!-- * Apply standard string-substitution map. The main purpose -->
 492     <!-- * of this map is to escape certain characters that have -->
 493     <!-- * special meaning in roff, and to replace certain characters -->
 494     <!-- * used within the stylesheet internally to represent roff -->
 495     <!-- * markup characters. -->
 496     <xsl:variable name="adjusted.content">
 497       <xsl:call-template name="apply-string-subst-map">
 498         <xsl:with-param name="content" select="$pre.adjusted.content"/>
 499         <xsl:with-param name="map.contents"
 500                         select="exsl:node-set($man.string.subst.map)/*"/>
 501       </xsl:call-template>
 502     </xsl:variable>
 503
 504     <!-- * If user has provided a "local" string-substitution map to -->
 505     <!-- * be applied /after/ the standard string-substitution map, -->
 506     <!-- * apply it. -->
 507     <xsl:variable name="post.adjusted.content">
 508       <xsl:choose>
 509         <xsl:when test="$man.string.subst.map.local.post">
 510           <!-- * normalized value of man.string.subst.map.local.post -->
 511           <!-- * is non-empty, so get contents of map and apply them -->
 512           <xsl:call-template name="apply-string-subst-map">
 513             <xsl:with-param name="content" select="$adjusted.content"/>
 514             <xsl:with-param name="map.contents"
 515                             select="exsl:node-set($man.string.subst.map.local.post)/*"/>
 516           </xsl:call-template>
 517         </xsl:when>
 518         <xsl:otherwise>
 519           <!-- * value of man.string.subst.map.local.post is empty, -->
 520           <!-- * so just copy original contents -->
 521           <xsl:value-of select="$adjusted.content"/>
 522         </xsl:otherwise>
 523       </xsl:choose>
 524     </xsl:variable>
 525
 526     <!-- * Optionally, apply a character map to replace Unicode -->
 527     <!-- * symbols and special characters. -->
 528     <xsl:choose>
 529       <xsl:when test="$man.charmap.enabled != 0">
 530         <xsl:call-template name="apply-character-map">
 531           <xsl:with-param name="content" select="$post.adjusted.content"/>
 532           <xsl:with-param name="map.contents"
 533                           select="exsl:node-set($man.charmap.contents)/*"/>
 534         </xsl:call-template>
 535       </xsl:when>
 536       <xsl:otherwise>
 537         <!-- * if we reach here, value of $man.charmap.enabled is zero, -->
 538         <!-- * so we just pass the adjusted contents through "as is" -->
 539         <xsl:value-of select="$adjusted.content"/>
 540       </xsl:otherwise>
 541     </xsl:choose>
 542   </xsl:template>
 543
 544   <!-- ================================================================== -->
 545
 546   <xsl:template name="write.man.file">
 547     <xsl:param name="name"/>
 548     <xsl:param name="section"/>
 549     <xsl:param name="lang"/>
 550     <xsl:param name="content"/>
 551     <xsl:param name="filename">
 552       <xsl:call-template name="make.adjusted.man.filename">
 553         <xsl:with-param name="name" select="$name"/>
 554         <xsl:with-param name="section" select="$section"/>
 555         <xsl:with-param name="lang" select="$lang"/>
 556       </xsl:call-template>
 557     </xsl:param>
 558     <xsl:call-template name="write.text.chunk">
 559       <xsl:with-param name="filename" select="$filename"/>
 560       <xsl:with-param name="suppress-context-node-name" select="1"/>
 561       <xsl:with-param name="quiet" select="$man.output.quietly"/>
 562       <xsl:with-param
 563           name="message-prolog"
 564           >Note: </xsl:with-param>
 565       <xsl:with-param name="encoding" select="$man.output.encoding"/>
 566       <xsl:with-param name="content" select="$content"/>
 567     </xsl:call-template>
 568   </xsl:template>
 569
 570   <!-- ============================================================== -->
 571
 572   <!-- * A "stub" is sort of alias for another file, intended to be read -->
 573   <!-- * and expanded by soelim(1); it's simply a file whose complete -->
 574   <!-- * contents are just a single line of the following form: -->
 575   <!-- * -->
 576   <!-- *  .so manX/realname.X -->
 577   <!-- * -->
 578   <!-- * "realname" is a name of another man-page file. That .so line is -->
 579   <!-- * basically a roff "include" statement.  When the man command finds -->
 580   <!-- * it, it calls soelim(1) and includes and displays the contents of -->
 581   <!-- * the manX/realqname.X file. -->
 582   <!-- * -->
 583   <!-- * If a refentry has multiple refnames, we generate a "stub" page for -->
 584   <!-- * each refname found, except for the first one. -->
 585   <xsl:template name="write.stubs">
 586     <xsl:param name="first.refname"/>
 587     <xsl:param name="section"/>
 588     <xsl:param name="lang"/>
 589     <xsl:for-each select="refnamediv/refname">
 590       <xsl:if test=". != $first.refname">
 591         <xsl:call-template name="write.text.chunk">
 592           <xsl:with-param name="filename">
 593             <xsl:call-template name="make.adjusted.man.filename">
 594               <xsl:with-param name="name">
 595                 <xsl:apply-templates/>
 596               </xsl:with-param>
 597               <xsl:with-param name="section" select="$section"/>
 598               <xsl:with-param name="lang" select="$lang"/>
 599             </xsl:call-template>
 600           </xsl:with-param>
 601           <xsl:with-param name="quiet" select="$man.output.quietly"/>
 602           <xsl:with-param name="suppress-context-node-name" select="1"/>
 603           <xsl:with-param name="message-prolog">Note: </xsl:with-param>
 604           <xsl:with-param name="message-epilog"> (soelim stub)</xsl:with-param>
 605           <xsl:with-param name="content">
 606             <xsl:value-of select="concat('.so man', $section, '/')"/>
 607             <xsl:call-template name="make.adjusted.man.filename">
 608               <xsl:with-param name="name" select="$first.refname"/>
 609               <xsl:with-param name="section" select="$section"/>
 610             </xsl:call-template>
 611             <xsl:text>&#10;</xsl:text>
 612           </xsl:with-param>
 613         </xsl:call-template>
 614       </xsl:if>
 615     </xsl:for-each>
 616   </xsl:template>
 617
 618   <!-- ============================================================== -->
 619
 620   <!-- *  A manifest file is useful for doing "make clean" during -->
 621   <!-- *  builds and for other purposes. When we make the manifest -->
 622   <!-- *  file, we need to include in it a filename for each man-page -->
 623   <!-- *  generated, including any "stub" pages. -->
 624   <xsl:template name="generate.manifest">
 625     <xsl:variable name="filelist">
 626       <xsl:for-each select="//refentry">
 627         <!-- * all refname instances in a Refentry inherit their section -->
 628         <!-- * numbers from the parent Refentry; so we only need to get -->
 629         <!-- * the section once per Refentry, not once per Refname -->
 630         <xsl:variable name="section">
 631           <xsl:call-template name="get.refentry.section">
 632             <xsl:with-param name="quiet" select="1"/>
 633           </xsl:call-template>
 634         </xsl:variable>
 635         <xsl:variable name="lang">
 636           <xsl:call-template name="l10n.language"/>
 637         </xsl:variable>
 638         <xsl:for-each select="refnamediv/refname">
 639           <xsl:call-template name="make.adjusted.man.filename">
 640             <xsl:with-param name="name" select="."/>
 641             <xsl:with-param name="section" select="$section"/>
 642             <xsl:with-param name="lang" select="$lang"/>
 643           </xsl:call-template>
 644           <xsl:text>&#10;</xsl:text>
 645         </xsl:for-each>
 646       </xsl:for-each>
 647     </xsl:variable>
 648
 649     <!-- * we write the manifest file once per document, not once per -->
 650     <!-- * Refentry -->
 651     <xsl:call-template name="write.text.chunk">
 652       <xsl:with-param name="filename">
 653         <xsl:value-of select="$man.output.manifest.filename"/>
 654       </xsl:with-param>
 655       <xsl:with-param name="quiet" select="1"/>
 656       <xsl:with-param name="message-prolog">Note: </xsl:with-param>
 657       <xsl:with-param name="message-epilog"> (manifest file)</xsl:with-param>
 658       <xsl:with-param name="content">
 659         <xsl:value-of select="$filelist"/>
 660       </xsl:with-param>
 661     </xsl:call-template>
 662     <xsl:if test="$man.output.quietly = 0">
 663       <xsl:message><xsl:text>&#10;</xsl:text></xsl:message>
 664     </xsl:if>
 665   </xsl:template>
 666
 667 </xsl:stylesheet>