doc/xslt/manpages/utility.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:dyn="http://exslt.org/dynamic"
   5                 xmlns:saxon="http://icl.com/saxon"
   6                 exclude-result-prefixes="exsl dyn saxon"
   7                 version='1.0'>
   8
   9 <!-- ********************************************************************
  10      $Id: utility.xsl 8236 2009-02-09 17:44:52Z xmldoc $
  11      ********************************************************************
  12
  13      This file is part of the XSL DocBook Stylesheet distribution.
  14      See ../README or http://docbook.sf.net/release/xsl/current/ for
  15      copyright and other information.
  16
  17      ******************************************************************** -->
  18
  19 <!-- ==================================================================== -->
  20
  21 <!-- * This file contains "utility" templates that are called multiple -->
  22 <!-- * times per each Refentry. -->
  23
  24 <!-- ==================================================================== -->
  25
  26   <!-- * NOTE TO DEVELOPERS: For ease of maintenance, the current -->
  27   <!-- * manpages stylesheets use the "bold" and "italic" named -->
  28   <!-- * templates for anything and everything that needs to get -->
  29   <!-- * boldfaced or italicized. -->
  30   <!-- * -->
  31   <!-- * So if you add anything that needs bold or italic character -->
  32   <!-- * formatting, try to apply these templates to it rather than -->
  33   <!-- * writing separate code to format it. This can be a little odd if -->
  34   <!-- * the content you want to format is not element content; in those -->
  35   <!-- * cases, you need to turn it into element content before applying -->
  36   <!-- * the template; see examples of this in the existing code. -->
  37
  38   <xsl:template name="bold">
  39     <xsl:param name="node"/>
  40     <xsl:param name="context"/>
  41     <xsl:choose>
  42       <xsl:when test="not($context[ancestor::title])">
  43         <xsl:for-each select="$node/node()">
  44           <xsl:text>\fB</xsl:text>
  45           <xsl:apply-templates select="."/>
  46           <xsl:text>\fR</xsl:text>
  47         </xsl:for-each>
  48       </xsl:when>
  49       <xsl:otherwise>
  50         <xsl:apply-templates select="$node/node()"/>
  51       </xsl:otherwise>
  52     </xsl:choose>
  53   </xsl:template>
  54
  55   <xsl:template name="italic">
  56     <xsl:param name="node"/>
  57     <xsl:param name="context"/>
  58     <xsl:for-each select="$node/node()">
  59       <xsl:text>\fI</xsl:text>
  60       <xsl:apply-templates select="."/>
  61       <xsl:text>\fR</xsl:text>
  62     </xsl:for-each>
  63   </xsl:template>
  64
  65   <xsl:template name="inline.monoseq">
  66     <xsl:call-template name="code-inline-start"/>
  67     <xsl:apply-templates/>
  68     <xsl:call-template name="code-inline-end"/>
  69   </xsl:template>
  70
  71   <xsl:template name="code-inline-start">
  72     <xsl:if test="not($man.output.better.ps.enabled = 0)">
  73       <xsl:text>\FC</xsl:text>
  74     </xsl:if>
  75   </xsl:template>
  76
  77   <xsl:template name="code-inline-end">
  78     <xsl:if test="not($man.output.better.ps.enabled = 0)">
  79       <xsl:text>\F[]</xsl:text>
  80     </xsl:if>
  81   </xsl:template>
  82
  83   <!-- ================================================================== -->
  84
  85   <xsl:template name="verbatim-block-start">
  86     <xsl:if test="not($man.output.better.ps.enabled = 0)">
  87       <xsl:text>.fam C&#10;</xsl:text>
  88       <xsl:text>.ps -1&#10;</xsl:text>
  89     </xsl:if>
  90   </xsl:template>
  91
  92   <xsl:template name="verbatim-block-end">
  93     <xsl:if test="not($man.output.better.ps.enabled = 0)">
  94       <xsl:text>.fam&#10;</xsl:text>
  95       <xsl:text>.ps +1&#10;</xsl:text>
  96     </xsl:if>
  97   </xsl:template>
  98
  99   <xsl:template name="synopsis-block-start">
 100     <xsl:if test="not($man.output.better.ps.enabled = 0)">
 101       <xsl:text>.fam C&#10;</xsl:text>
 102     </xsl:if>
 103   </xsl:template>
 104
 105   <xsl:template name="synopsis-block-end">
 106     <xsl:if test="not($man.output.better.ps.enabled = 0)">
 107       <xsl:text>.fam&#10;</xsl:text>
 108     </xsl:if>
 109   </xsl:template>
 110
 111   <!-- ================================================================== -->
 112
 113   <!-- * NOTE TO DEVELOPERS: For ease of maintenance, the current -->
 114   <!-- * manpages stylesheets use the mode="prevent.line.breaking" -->
 115   <!-- * templates for anything and everything that needs to have -->
 116   <!-- * embedded spaces turned into no-break spaces in output - in -->
 117   <!-- * order to prevent that output from getting broken across lines -->
 118   <!-- * -->
 119   <!-- * So if you add anything that whose output, try to apply this -->
 120   <!-- * template to it rather than writing separate code to format -->
 121   <!-- * it. This can be a little odd if the content you want to -->
 122   <!-- * format is not element content; in those cases, you need to -->
 123   <!-- * turn it into element content before applying the template; -->
 124   <!-- * see examples of this in the existing code. -->
 125   <!-- * -->
 126   <!-- * This template is currently called by the funcdef and paramdef -->
 127   <!-- * and group/arg templates. -->
 128   <xsl:template mode="prevent.line.breaking" match="*">
 129     <xsl:variable name="rcontent">
 130       <xsl:apply-templates/>
 131     </xsl:variable>
 132     <xsl:variable name="content">
 133       <xsl:value-of select="normalize-space($rcontent)"/>
 134     </xsl:variable>
 135     <xsl:call-template name="string.subst">
 136       <xsl:with-param name="string" select="$content"/>
 137       <xsl:with-param name="target" select="' '"/>
 138       <!-- * U+2580 is a "UPPER HALF BLOCK"; we use it here because -->
 139       <!-- * if we were to just use a normal space, it would get -->
 140       <!-- * replaced when normalization is done. We replace it -->
 141       <!-- * later with the groff markup for non-breaking space. -->
 142       <xsl:with-param name="replacement" select="'&#x2580;'"/>
 143     </xsl:call-template>
 144   </xsl:template>
 145
 146   <!-- ================================================================== -->
 147
 148   <xsl:template name="suppress.hyphenation">
 149     <!-- * we need to suppress hyphenation inline only if hyphenation is -->
 150     <!-- * actually on, and even then only outside of Cmdsynopsis and -->
 151     <!-- * Funcsynopsis, where it is already always turned off -->
 152     <xsl:if test="$man.hyphenate != 0 and
 153                   not(ancestor::cmdsynopsis) and
 154                   not(ancestor::funcsynopsis)">
 155       <xsl:text>\%</xsl:text>
 156     </xsl:if>
 157   </xsl:template>
 158
 159   <!-- ================================================================== -->
 160
 161   <!-- * The replace.dots.and.dashes template is used to cause real -->
 162   <!-- * dots and dashes to be output in the top comment (instead of -->
 163   <!-- * escaped ones as in the source for the text displayed in the -->
 164   <!-- * body of the page) -->
 165   <xsl:template name="replace.dots.and.dashes">
 166     <xsl:param name="content">
 167       <xsl:apply-templates/>
 168     </xsl:param>
 169     <xsl:variable name="dot-content">
 170       <xsl:call-template name="string.subst">
 171         <xsl:with-param name="string" select="$content"/>
 172         <xsl:with-param name="target" select="'\&amp;.'"/>
 173         <xsl:with-param name="replacement" select="'.'"/>
 174       </xsl:call-template>
 175     </xsl:variable>
 176     <xsl:call-template name="string.subst">
 177       <xsl:with-param name="string" select="$dot-content"/>
 178       <xsl:with-param name="target" select="'\-'"/>
 179       <xsl:with-param name="replacement" select="'-'"/>
 180     </xsl:call-template>
 181   </xsl:template>
 182
 183   <!-- ================================================================== -->
 184
 185   <!-- * The nested-section-title template is called for refsect3, and any -->
 186   <!-- * refsection nested more than 2 levels deep. -->
 187   <xsl:template name="nested-section-title">
 188     <xsl:text>.sp&#10;</xsl:text>
 189     <xsl:call-template name="pinch.together"/>
 190     <xsl:text>.ps +1&#10;</xsl:text>
 191     <xsl:call-template name="make.bold.title"/>
 192   </xsl:template>
 193
 194   <xsl:template name="pinch.together">
 195     <!-- * arcane roff code to suppress line spacing after headings -->
 196     <xsl:text>.it 1 an-trap&#10;</xsl:text>
 197     <xsl:text>.nr an-no-space-flag 1&#10;</xsl:text>
 198     <xsl:text>.nr an-break-flag 1&#10;</xsl:text>
 199     <xsl:text>.br&#10;</xsl:text>
 200   </xsl:template>
 201
 202   <xsl:template name="make.bold.title">
 203     <!-- * make title wrapper so that we can use "bold" template to apply -->
 204     <!-- * character formatting to it -->
 205     <xsl:variable name="title.wrapper">
 206       <xsl:choose>
 207         <xsl:when test="title">
 208           <xsl:value-of select="normalize-space(title[1])"/>
 209         </xsl:when>
 210         <xsl:otherwise>
 211           <xsl:apply-templates select="." mode="object.title.markup.textonly"/>
 212         </xsl:otherwise>
 213       </xsl:choose>
 214     </xsl:variable>
 215     <xsl:call-template name="mark.subheading"/>
 216     <xsl:call-template name="bold">
 217       <xsl:with-param name="node" select="exsl:node-set($title.wrapper)"/>
 218       <xsl:with-param name="context" select="."/>
 219     </xsl:call-template>
 220     <xsl:text>&#10;</xsl:text>
 221     <xsl:call-template name="mark.subheading"/>
 222   </xsl:template>
 223
 224   <!-- ================================================================== -->
 225
 226   <!-- * The mixed-block template jumps through a few hoops to deal with -->
 227   <!-- * mixed-content blocks, so that we don't end up munging verbatim -->
 228   <!-- * environments or lists and so that we don't gobble up whitespace -->
 229   <!-- * when we shouldn't -->
 230   <xsl:template name="mixed-block">
 231     <xsl:for-each select="node()">
 232       <xsl:choose>
 233         <!-- * Check to see if this node is a verbatim environment. -->
 234         <!-- * If so, put a line of space before it. -->
 235         <!-- * -->
 236         <!-- * Yes, address and synopsis are vertabim environments. -->
 237         <!-- * -->
 238         <!-- * The code here previously also treated informaltable as a -->
 239         <!-- * verbatim, presumably to support some kludge; I removed it -->
 240         <xsl:when test="self::address|self::literallayout|self::programlisting|
 241                         self::screen|self::synopsis">
 242           <xsl:text>&#10;</xsl:text>
 243           <xsl:text>.sp&#10;</xsl:text>
 244           <xsl:call-template name="mark.up.block.start"/>
 245           <xsl:apply-templates select="."/>
 246         </xsl:when>
 247         <!-- * Check to see if this node is a list; if it is, we don't -->
 248         <!-- * want to normalize-space(), so we just apply-templates. -->
 249         <!-- * Do same for all admonitions -->
 250         <xsl:when test="(self::itemizedlist|self::orderedlist|
 251                         self::variablelist|self::glosslist|
 252                         self::simplelist[@type !='inline']|
 253                         self::segmentedlist|
 254                         self::caution|self::important|
 255                         self::note|self::tip|self::warning|
 256                         self::table|self::informaltable)">
 257           <xsl:call-template name="mark.up.block.start"/>
 258           <xsl:apply-templates select="."/>
 259         </xsl:when>
 260         <xsl:when test="self::text()">
 261           <!-- * Check to see if this is a text node. -->
 262           <!-- * -->
 263           <!-- * If so, replace all whitespace at the beginning or end of it -->
 264           <!-- * with a single linebreak. -->
 265           <!-- * -->
 266           <xsl:variable name="content">
 267             <xsl:apply-templates select="."/>
 268           </xsl:variable>
 269           <xsl:if
 270               test="starts-with(translate(.,'&#9;&#10;&#13; ','    '), ' ')
 271                     and preceding-sibling::node()[1][name(.)!='']
 272                     and normalize-space($content) != ''
 273                     and not(
 274                     preceding-sibling::*[1][
 275                     self::caution or
 276                     self::important or
 277                     self::note or
 278                     self::tip or
 279                     self::warning or
 280                     self::variablelist or
 281                     self::glosslist or
 282                     self::itemizedlist or
 283                     self::orderedlist or
 284                     self::segmentedlist or
 285                     self::procedure or
 286                     self::address or
 287                     self::literallayout or
 288                     self::programlisting or
 289                     self::screen or
 290                     self::table or
 291                     self::informaltable
 292                     ]
 293                     )
 294                     ">
 295             <xsl:text>&#10;</xsl:text>
 296           </xsl:if>
 297           <xsl:value-of select="normalize-space($content)"/>
 298           <xsl:if
 299               test="(translate(substring(., string-length(.), 1),'&#9;&#10;&#13; ','    ')  = ' '
 300                     and following-sibling::node()[1][name(.)!=''])
 301                     or following-sibling::node()[1][self::comment()]
 302                     or following-sibling::node()[1][self::processing-instruction()]
 303                     ">
 304             <xsl:if test="normalize-space($content) != ''
 305                           or concat(normalize-space($content), ' ') = ' '">
 306               <xsl:text>&#10;</xsl:text>
 307             </xsl:if>
 308           </xsl:if>
 309         </xsl:when>
 310         <xsl:otherwise>
 311           <!-- * At this point, we know that this node is not a verbatim -->
 312           <!-- * environment, list, admonition, or text node; so we can -->
 313           <!-- * safely normalize-space() it. -->
 314           <xsl:variable name="content">
 315             <xsl:apply-templates select="."/>
 316           </xsl:variable>
 317           <xsl:value-of select="normalize-space($content)"/>
 318         </xsl:otherwise>
 319       </xsl:choose>
 320     </xsl:for-each>
 321     <xsl:call-template name="mark.up.block.end"/>
 322   </xsl:template>
 323
 324   <!-- ================================================================== -->
 325
 326   <!-- * Footnote and annotation contents are displayed using a hanging -->
 327   <!-- * indent out to $man.indent.width If a paragraph-level block -->
 328   <!-- * element (verbatim, list, or admonition) is the first block -->
 329   <!-- * element nested at its same level within the same footnote or -->
 330   <!-- * annotation, then we push it over by the same indent width. -->
 331   <!-- * -->
 332   <!-- * We don't reset the indent for each following sibling, but -->
 333   <!-- * instead do it after for-eaching over all block siblings at -->
 334   <!-- * the same level. So the effect is that if there are any -->
 335   <!-- * following-sibling blocks after the block that starts this -->
 336   <!-- * indent, then they just retain the indent that was already set -->
 337
 338   <xsl:template name="mark.up.block.start">
 339     <xsl:choose>
 340       <xsl:when test="(ancestor::footnote
 341                       or ancestor::annotation)">
 342         <xsl:if test="not(preceding-sibling::address|
 343                       preceding-sibling::literallayout|
 344                       preceding-sibling::programlisting|
 345                       preceding-sibling::screen|
 346                       preceding-sibling::synopsis|
 347                       preceding-sibling::itemizedlist|
 348                       preceding-sibling::orderedlist|
 349                       preceding-sibling::variablelist|
 350                       preceding-sibling::glosslist|
 351                       preceding-sibling::simplelist[@type !='inline']|
 352                       preceding-sibling::segmentedlist|
 353                       preceding-sibling::caution|
 354                       preceding-sibling::important|
 355                       preceding-sibling::note|
 356                       preceding-sibling::tip|
 357                       preceding-sibling::warning|
 358                       preceding-sibling::table|
 359                       preceding-sibling::informaltable
 360                       )">
 361           <xsl:text>.RS</xsl:text>
 362           <xsl:if test="not($list-indent = '')">
 363             <xsl:text> </xsl:text>
 364             <xsl:value-of select="$list-indent"/>
 365           </xsl:if>
 366           <xsl:text>&#10;</xsl:text>
 367         </xsl:if>
 368       </xsl:when>
 369     </xsl:choose>
 370   </xsl:template>
 371
 372   <!-- * Check to see if we were called from a block within a footnote or -->
 373   <!-- * annotation; if so, and the block contains any nested block -->
 374   <!-- * content, then we know the mark.up.block.end template was already -->
 375   <!-- * called to generate a .RS macro to indent that nested block -->
 376   <!-- * content; so we need to generate a .RE to set the margin back to -->
 377   <!-- * where it was prior to the .RS call. -->
 378   <xsl:template name="mark.up.block.end">
 379     <xsl:if test="(ancestor::footnote
 380                   or ancestor::annotation)">
 381       <xsl:if test="address|
 382                     literallayout|
 383                     programlisting|
 384                     screen|
 385                     synopsis|
 386                     itemizedlist|
 387                     orderedlist|
 388                     variablelist|
 389                     glosslist|
 390                     simplelist[@type !='inline']|
 391                     segmentedlist|
 392                     caution|
 393                     important|
 394                     note|
 395                     tip|
 396                     warning|
 397                     table|
 398                     informaltable">
 399         <xsl:text>&#10;</xsl:text>
 400         <xsl:text>.RE</xsl:text>
 401       <xsl:text>&#10;</xsl:text>
 402       </xsl:if>
 403     </xsl:if>
 404   </xsl:template>
 405
 406   <!-- ================================================================== -->
 407
 408   <!-- * The person.name template in the HTML stylesheets outputs extra -->
 409   <!-- * spaces that we need to strip out for manpages output. This -->
 410   <!-- * template calls person.name, then tries to do some smart -->
 411   <!-- * normalization of the result tree fragment from that. -->
 412   <xsl:template name="person.name.normalized">
 413     <xsl:variable name="contents">
 414       <xsl:call-template name="person.name"/>
 415     </xsl:variable>
 416     <!-- * We put the output of person.name into a node-set and then we -->
 417     <!-- * check it node-by-node and strip out space only where needed. -->
 418     <xsl:variable name="contents.tree" select="exsl:node-set($contents)"/>
 419     <xsl:for-each select="$contents.tree/node()">
 420       <xsl:choose>
 421         <!-- * We don't want to monkey with single spaces or commas/periods -->
 422         <!-- * followed by spaces, because those are bits of text that are -->
 423         <!-- * actually generated by the person.name template itself (that -->
 424         <!-- * is, they're not in the source). So, we preserve them. -->
 425         <xsl:when test=". = ' ' or . = ', ' or . = '. '">
 426           <xsl:value-of select="."/>
 427         </xsl:when>
 428         <xsl:otherwise>
 429           <xsl:value-of select="normalize-space(.)"/>
 430         </xsl:otherwise>
 431       </xsl:choose>
 432     </xsl:for-each>
 433   </xsl:template>
 434
 435   <!-- ================================================================== -->
 436
 437   <xsl:template name="make.adjusted.man.filename">
 438     <xsl:param name="name"/>
 439     <xsl:param name="lang"/>
 440     <xsl:param name="name.with.lang">
 441       <xsl:choose>
 442         <xsl:when test="$lang != 'en'
 443           and not($man.output.lang.in.name.enabled = 0)
 444           and ($man.output.subdirs.enabled = 0 or
 445           $man.output.in.separate.dir = 0)">
 446           <!-- * $lang is not en (English) -->
 447           <!-- * AND user has specified man.output.lang.in.name.enabled -->
 448           <!-- * AND doesn't want output going into separate dirs, -->
 449           <!-- * SO... we include the $lang value in the filename; e.g., -->
 450           <!-- * foo.ja.1 -->
 451           <xsl:value-of select="concat($name, '.', $lang)"/>
 452         </xsl:when>
 453         <xsl:otherwise>
 454           <!-- * user either has man.output.lang.in.name.enabled unset -->
 455           <!-- * or has set it but also has man.output.subdirs.enabled -->
 456           <!-- * set (in which case the $lang value is used to add a -->
 457           <!-- * $lang subdir in the pathname); in either case, we don't -->
 458           <!-- * want to include the $lang in the filename -->
 459           <xsl:value-of select="$name"/>
 460         </xsl:otherwise>
 461       </xsl:choose>
 462     </xsl:param>
 463     <xsl:param name="section"/>
 464     <xsl:param name="dirname">
 465       <xsl:if test="not($man.output.in.separate.dir = 0)">
 466         <xsl:choose>
 467           <xsl:when test="not($man.output.subdirs.enabled = 0)">
 468             <xsl:variable name="lang.subdir">
 469               <xsl:if test="not($man.output.lang.in.name.enabled = 0)">
 470                 <!-- * user has man.output.lang.in.name.enabled set, so -->
 471                 <!-- * we need to add a $lang subdir -->
 472                 <xsl:value-of select="concat($lang, '/')"/>
 473               </xsl:if>
 474             </xsl:variable>
 475             <xsl:value-of
 476                 select="concat($man.output.base.dir, $lang.subdir,
 477                         'man', normalize-space($section), '/')"/>
 478           </xsl:when>
 479           <xsl:otherwise>
 480             <xsl:value-of select="$man.output.base.dir"/>
 481           </xsl:otherwise>
 482         </xsl:choose>
 483       </xsl:if>
 484     </xsl:param>
 485     <xsl:call-template name="string.subst">
 486       <!-- * To create the man filename, replace any spaces in filename with -->
 487       <!-- * underscores and then append a dot plus a section number. -->
 488       <xsl:with-param name="string"
 489                       select="concat($dirname,
 490                               normalize-space($name.with.lang),
 491                               '.', normalize-space($section))"/>
 492       <xsl:with-param name="target" select="' '"/>
 493       <xsl:with-param name="replacement" select="'_'"/>
 494     </xsl:call-template>
 495   </xsl:template>
 496
 497   <!-- ================================================================== -->
 498
 499   <xsl:template name="make.subheading">
 500     <xsl:param name="title"/>
 501     <xsl:call-template name="mark.subheading"/>
 502     <xsl:text>.SH</xsl:text>
 503     <xsl:text> </xsl:text>
 504     <xsl:text>"</xsl:text>
 505     <xsl:choose>
 506       <xsl:when test="not($man.output.better.ps.enabled = 0)">
 507         <xsl:value-of select="$title"/>
 508       </xsl:when>
 509       <xsl:otherwise>
 510         <xsl:call-template name="string.upper">
 511           <xsl:with-param name="string" select="$title"/>
 512         </xsl:call-template>
 513       </xsl:otherwise>
 514     </xsl:choose>
 515     <xsl:text>"</xsl:text>
 516     <xsl:text>&#10;</xsl:text>
 517     <xsl:call-template name="mark.subheading"/>
 518   </xsl:template>
 519
 520   <!-- * Put a horizontal rule or other divider around section titles -->
 521   <!-- * in roff source (just to make things easier to read). -->
 522   <xsl:template name="mark.subheading">
 523     <xsl:if test="$man.subheading.divider.enabled != 0">
 524       <xsl:text>.\" </xsl:text>
 525       <xsl:value-of select="$man.subheading.divider"/>
 526       <xsl:text>&#10;</xsl:text>
 527     </xsl:if>
 528   </xsl:template>
 529
 530   <!-- ================================================================== -->
 531
 532   <xsl:template name="roff-if-else-start">
 533     <xsl:param name="condition">n</xsl:param>
 534     <xsl:text>.ie </xsl:text>
 535     <xsl:value-of select="$condition"/>
 536     <xsl:text> \{\&#10;</xsl:text>
 537   </xsl:template>
 538
 539   <xsl:template name="roff-if-start">
 540     <xsl:param name="condition">n</xsl:param>
 541     <xsl:text>.if </xsl:text>
 542     <xsl:value-of select="$condition"/>
 543     <xsl:text> \{\&#10;</xsl:text>
 544   </xsl:template>
 545
 546   <xsl:template name="roff-else">
 547     <xsl:text>.\}&#10;</xsl:text>
 548     <xsl:text>.el \{\&#10;</xsl:text>
 549   </xsl:template>
 550
 551   <xsl:template name="roff-if-end">
 552     <xsl:text>.\}&#10;</xsl:text>
 553   </xsl:template>
 554
 555 </xsl:stylesheet>