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>