doc/xslt/manpages/synop.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                 exclude-result-prefixes="exsl"
   5                 version='1.0'>
   6
   7 <!-- ********************************************************************
   8      $Id: synop.xsl 7956 2008-03-27 12:07:43Z xmldoc $
   9      ********************************************************************
  10
  11      This file is part of the XSL DocBook Stylesheet distribution.
  12      See ../README or http://docbook.sf.net/release/xsl/current/ for
  13      copyright and other information.
  14
  15      ******************************************************************** -->
  16
  17 <xsl:variable name="arg.or.sep"> |</xsl:variable>
  18
  19 <!-- * Note: If you're looking for the *Synopsis* element, you won't -->
  20 <!-- * find any code here for handling it. It's a "verbatim" -->
  21 <!-- * environment; see the block.xsl file instead. -->
  22
  23 <xsl:template match="synopfragmentref">
  24   <xsl:variable name="target" select="key('id',@linkend)"/>
  25   <xsl:variable name="snum">
  26     <xsl:apply-templates select="$target" mode="synopfragment.number"/>
  27   </xsl:variable>
  28   <xsl:text>(</xsl:text>
  29   <xsl:value-of select="$snum"/>
  30   <xsl:text>)</xsl:text>
  31   <xsl:text>&#x2580;</xsl:text>
  32   <xsl:call-template name="italic">
  33     <xsl:with-param name="node" select="."/>
  34     <xsl:with-param name="context" select="."/>
  35   </xsl:call-template>
  36 </xsl:template>
  37
  38 <xsl:template match="synopfragment" mode="synopfragment.number">
  39   <xsl:number format="1"/>
  40 </xsl:template>
  41
  42 <xsl:template match="synopfragment">
  43   <xsl:variable name="snum">
  44     <xsl:apply-templates select="." mode="synopfragment.number"/>
  45   </xsl:variable>
  46   <xsl:text>&#10;</xsl:text>
  47   <!-- * If we have a group of Synopfragments, we only want to output a -->
  48   <!-- * line of space before the first; so when we find a Synopfragment -->
  49   <!-- * which has another Synopfragment as a following sibling, we use-->
  50   <!-- * the pinch-together template to close up the line of space -->
  51   <!-- * that would otherwise be generated by the .HP macro -->
  52   <xsl:if test="following-sibling::*[self::synopfragment]">
  53     <xsl:call-template name="pinch.together"/>
  54   </xsl:if>
  55   <xsl:text>.HP </xsl:text>
  56   <xsl:text>\w'</xsl:text>
  57   <xsl:text>(</xsl:text>
  58   <xsl:value-of select="$snum"/>
  59   <xsl:text>)</xsl:text>
  60   <xsl:text>\ 'u</xsl:text>
  61   <xsl:text>&#10;</xsl:text>
  62   <xsl:text>(</xsl:text>
  63   <xsl:value-of select="$snum"/>
  64   <xsl:text>)</xsl:text>
  65   <xsl:text>\ </xsl:text>
  66   <xsl:apply-templates/>
  67 </xsl:template>
  68
  69 <xsl:template match="group|arg" name="group-or-arg">
  70   <xsl:variable name="choice" select="@choice"/>
  71   <xsl:variable name="rep" select="@rep"/>
  72   <xsl:variable name="sepchar">
  73     <xsl:choose>
  74       <xsl:when test="ancestor-or-self::*/@sepchar">
  75         <xsl:value-of select="ancestor-or-self::*/@sepchar"/>
  76       </xsl:when>
  77       <xsl:otherwise>
  78         <xsl:text> </xsl:text>
  79       </xsl:otherwise>
  80     </xsl:choose>
  81   </xsl:variable>
  82   <xsl:if test="position()>1 and
  83                 not(preceding-sibling::*[1][self::sbr])"
  84           ><xsl:value-of select="$sepchar"/></xsl:if>
  85   <xsl:choose>
  86     <xsl:when test="$choice='plain'">
  87       <!-- * do nothing -->
  88     </xsl:when>
  89     <xsl:when test="$choice='req'">
  90       <xsl:value-of select="$arg.choice.req.open.str"/>
  91     </xsl:when>
  92     <xsl:when test="$choice='opt'">
  93       <xsl:value-of select="$arg.choice.opt.open.str"/>
  94     </xsl:when>
  95     <xsl:otherwise>
  96       <xsl:value-of select="$arg.choice.def.open.str"/>
  97     </xsl:otherwise>
  98   </xsl:choose>
  99   <xsl:variable name="arg">
 100     <xsl:apply-templates/>
 101   </xsl:variable>
 102   <xsl:choose>
 103     <xsl:when test="local-name(.) = 'arg' and not(ancestor::arg)">
 104       <!-- * Prevent arg contents from getting wrapped and broken up -->
 105       <xsl:variable name="arg.wrapper">
 106         <Arg><xsl:value-of select="normalize-space($arg)"/></Arg>
 107       </xsl:variable>
 108       <xsl:apply-templates mode="prevent.line.breaking"
 109                            select="exsl:node-set($arg.wrapper)"/>
 110     </xsl:when>
 111     <xsl:otherwise>
 112       <xsl:value-of select="$arg"/>
 113     </xsl:otherwise>
 114   </xsl:choose>
 115   <xsl:choose>
 116     <xsl:when test="$rep='repeat'">
 117       <xsl:value-of select="$arg.rep.repeat.str"/>
 118     </xsl:when>
 119     <xsl:when test="$rep='norepeat'">
 120       <xsl:value-of select="$arg.rep.norepeat.str"/>
 121     </xsl:when>
 122     <xsl:otherwise>
 123       <xsl:value-of select="$arg.rep.def.str"/>
 124     </xsl:otherwise>
 125   </xsl:choose>
 126   <xsl:choose>
 127     <xsl:when test="$choice='plain'">
 128       <xsl:if test='arg'>
 129       <xsl:value-of select="$arg.choice.plain.close.str"/>
 130       </xsl:if>
 131     </xsl:when>
 132     <xsl:when test="$choice='req'">
 133       <xsl:value-of select="$arg.choice.req.close.str"/>
 134     </xsl:when>
 135     <xsl:when test="$choice='opt'">
 136       <xsl:value-of select="$arg.choice.opt.close.str"/>
 137     </xsl:when>
 138     <xsl:otherwise>
 139       <xsl:value-of select="$arg.choice.def.close.str"/>
 140     </xsl:otherwise>
 141   </xsl:choose>
 142 </xsl:template>
 143
 144 <xsl:template match="group/arg">
 145   <xsl:variable name="choice" select="@choice"/>
 146   <xsl:variable name="rep" select="@rep"/>
 147   <xsl:if test="position()>1"><xsl:value-of select="$arg.or.sep"/></xsl:if>
 148   <xsl:call-template name="group-or-arg"/>
 149 </xsl:template>
 150
 151 <xsl:template match="sbr">
 152   <xsl:text>&#x2592;</xsl:text>
 153   <xsl:text>.br&#x2592;</xsl:text>
 154 </xsl:template>
 155
 156 <xsl:template match="cmdsynopsis">
 157   <!-- * if justification is enabled by default, turn it off temporarily -->
 158   <xsl:if test="$man.justify != 0">
 159     <xsl:text>.ad l&#10;</xsl:text>
 160   </xsl:if>
 161   <!-- * if hyphenation is enabled by default, turn it off temporarily -->
 162   <xsl:if test="$man.hyphenate != 0">
 163     <xsl:text>.hy 0&#10;</xsl:text>
 164   </xsl:if>
 165   <xsl:call-template name="synopsis-block-start"/>
 166   <xsl:text>.HP </xsl:text>
 167   <xsl:text>\w'</xsl:text>
 168   <xsl:variable name="command">
 169     <xsl:apply-templates select="command"/>
 170   </xsl:variable>
 171   <xsl:call-template name="string.subst">
 172     <xsl:with-param name="string" select="normalize-space($command)"/>
 173     <xsl:with-param name="target" select="' '"/>
 174     <xsl:with-param name="replacement" select="'\ '"/>
 175   </xsl:call-template>
 176   <xsl:text>\ 'u</xsl:text>
 177   <xsl:text>&#10;</xsl:text>
 178   <xsl:apply-templates/>
 179   <xsl:text>&#10;</xsl:text>
 180   <xsl:call-template name="synopsis-block-end"/>
 181   <!-- * if justification is enabled by default, turn it back on -->
 182   <xsl:if test="$man.justify != 0">
 183     <xsl:text>.ad&#10;</xsl:text>
 184   </xsl:if>
 185   <!-- * if hyphenation is enabled by default, turn it back on -->
 186   <xsl:if test="$man.hyphenate != 0">
 187     <xsl:text>.hy&#10;</xsl:text>
 188   </xsl:if>
 189 </xsl:template>
 190
 191 <!-- ==================================================================== -->
 192 <!-- *  Funcsynopis hierarchy starts here -->
 193 <!-- ==================================================================== -->
 194
 195 <!-- * Note: If you're looking for the *Funcsynopsisinfo* element, -->
 196 <!-- * you won't find any code here for handling it. It's a "verbatim" -->
 197 <!-- * environment; see the block.xsl file instead. -->
 198
 199 <!-- * Within funcsynopis output, disable hyphenation, and use -->
 200 <!-- * left-aligned filling for the duration of the synopsis, so that -->
 201 <!-- * line breaks only occur between separate paramdefs. -->
 202 <xsl:template match="funcsynopsis">
 203   <!-- * if justification is enabled by default, turn it off temporarily -->
 204   <xsl:if test="$man.justify != 0">
 205     <xsl:text>.ad l&#10;</xsl:text>
 206   </xsl:if>
 207   <!-- * if hyphenation is enabled by default, turn it off temporarily -->
 208   <xsl:if test="$man.hyphenate != 0">
 209     <xsl:text>.hy 0&#10;</xsl:text>
 210   </xsl:if>
 211   <xsl:apply-templates/>
 212   <!-- * if justification is enabled by default, turn it back on -->
 213   <xsl:if test="$man.justify != 0">
 214     <xsl:text>.ad&#10;</xsl:text>
 215   </xsl:if>
 216   <!-- * if hyphenation is enabled by default, turn it back on -->
 217   <xsl:if test="$man.hyphenate != 0">
 218     <xsl:text>.hy&#10;</xsl:text>
 219   </xsl:if>
 220 </xsl:template>
 221
 222 <!-- * In HTML output, placing a dbfunclist PI as a child of a particular -->
 223 <!-- * element creates a hyperlinked list of all funcsynopsis instances -->
 224 <!-- * that are descendants of that element. But we can’t really do this -->
 225 <!-- * kind of hyperlinked list in manpages output, so we just need to -->
 226 <!-- * suppress it instead. -->
 227 <xsl:template match="processing-instruction('dbfunclist')"/>
 228
 229 <!-- * ***************************************************************** -->
 230 <!-- *           Note about boldface in funcprototype output -->
 231 <!-- * ***************************************************************** -->
 232 <!-- * All funcprototype content is by default rendered in bold, -->
 233 <!-- * because the old man(7) man page, now man-pages(7) says this: -->
 234 <!-- * -->
 235 <!-- *   For functions, the arguments are always specified using -->
 236 <!-- *   italics, even in the SYNOPSIS section, where the rest of -->
 237 <!-- *   the function is specified in bold -->
 238 <!-- * -->
 239 <!-- * Look through the contents of the man/man2 and man3 directories -->
 240 <!-- * on your system, and you'll see that most existing pages do follow -->
 241 <!-- * this "bold everything in function synopsis" rule. -->
 242 <!-- * -->
 243 <!-- * Users who don't want the bold output can choose to adjust the -->
 244 <!-- * man.font.funcprototype parameter on their own. So even if you -->
 245 <!-- * don't personally like the way it looks, please don't change the -->
 246 <!-- * default to be non-bold - because it's a convention that's -->
 247 <!-- * followed is the vast majority of existing man pages that document -->
 248 <!-- * functions, and we need to follow it by default, like it or no. -->
 249 <!-- * ***************************************************************** -->
 250
 251 <xsl:template match="funcprototype">
 252   <xsl:variable name="man-funcprototype-style">
 253     <xsl:call-template name="pi.dbman_funcsynopsis-style">
 254       <xsl:with-param name="node" select="ancestor::funcsynopsis/descendant-or-self::*"/>
 255     </xsl:call-template>
 256   </xsl:variable>
 257   <xsl:variable name="style">
 258     <xsl:choose>
 259       <xsl:when test="not($man-funcprototype-style = '')">
 260         <xsl:value-of select="$man-funcprototype-style"/>
 261       </xsl:when>
 262       <xsl:otherwise>
 263         <xsl:value-of select="$man.funcsynopsis.style"/>
 264       </xsl:otherwise>
 265     </xsl:choose>
 266   </xsl:variable>
 267   <xsl:variable name="funcprototype.string.value">
 268     <xsl:value-of select="funcdef"/>
 269   </xsl:variable>
 270   <xsl:variable name="funcprototype">
 271     <xsl:apply-templates select="funcdef"/>
 272   </xsl:variable>
 273   <xsl:call-template name="synopsis-block-start"/>
 274   <xsl:text>.HP </xsl:text>
 275   <xsl:text>\w'</xsl:text>
 276   <xsl:variable name="funcdef">
 277     <xsl:apply-templates select="funcdef"/>
 278   </xsl:variable>
 279   <xsl:call-template name="string.subst">
 280     <xsl:with-param name="string" select="normalize-space($funcdef)"/>
 281     <xsl:with-param name="target" select="' '"/>
 282     <xsl:with-param name="replacement" select="'\ '"/>
 283   </xsl:call-template>
 284   <xsl:text>('u</xsl:text>
 285   <xsl:text>&#10;</xsl:text>
 286   <xsl:text>.</xsl:text>
 287   <xsl:value-of select="$man.font.funcprototype"/>
 288   <xsl:text> </xsl:text>
 289   <!-- * The following quotation mark (and the one further below) are -->
 290   <!-- * needed to properly delimit the parts of the Funcprototype that -->
 291   <!-- * should be rendered in the prevailing font (either Bold or Roman) -->
 292   <!-- * from Parameter output that needs to be alternately rendered in -->
 293   <!-- * italic. -->
 294   <xsl:text>"</xsl:text>
 295   <xsl:value-of select="normalize-space($funcprototype)"/>
 296   <xsl:text>(</xsl:text>
 297   <xsl:choose>
 298     <xsl:when test="not($style = 'ansi')">
 299       <xsl:apply-templates select="*[local-name() != 'funcdef']" mode="kr"/>
 300     </xsl:when>
 301     <xsl:otherwise>
 302       <xsl:apply-templates select="*[local-name() != 'funcdef']" mode="ansi"/>
 303     </xsl:otherwise>
 304   </xsl:choose>
 305   <xsl:text>"</xsl:text>
 306   <xsl:text>&#10;</xsl:text>
 307   <xsl:if test="paramdef and not($style = 'ansi')">
 308     <!-- * if we have any paramdef instances in this funcprototype and -->
 309     <!-- * the user has chosen K&R style output (by specifying some style -->
 310     <!-- * value other than the default 'ansi'), then we need to generate -->
 311     <!-- * the separate list of param definitions for this funcprototype -->
 312     <!-- * -->
 313     <!-- * we put a blank line after the prototype and before the list, -->
 314     <!-- * and we indent the list by whatever width $list-indent is set -->
 315     <!-- * to (4 spaces by default) -->
 316     <xsl:text>.sp&#10;</xsl:text>
 317     <xsl:text>.RS</xsl:text>
 318     <xsl:if test="not($list-indent = '')">
 319       <xsl:text> </xsl:text>
 320       <xsl:value-of select="$list-indent"/>
 321     </xsl:if>
 322     <xsl:text>&#10;</xsl:text>
 323     <xsl:apply-templates select="paramdef" mode="kr-paramdef-list"/>
 324     <xsl:text>.RE&#10;</xsl:text>
 325   </xsl:if>
 326   <xsl:call-template name="synopsis-block-end"/>
 327 </xsl:template>
 328
 329 <xsl:template match="funcdef">
 330   <xsl:apply-templates mode="prevent.line.breaking"/>
 331 </xsl:template>
 332
 333 <xsl:template match="funcdef/function">
 334   <xsl:apply-templates/>
 335 </xsl:template>
 336
 337 <xsl:template match="void" mode="kr">
 338   <xsl:text>);</xsl:text>
 339 </xsl:template>
 340
 341 <xsl:template match="varargs" mode="kr">
 342   <xsl:text>...);</xsl:text>
 343 </xsl:template>
 344
 345 <xsl:template match="void" mode="ansi">
 346   <xsl:text>void);</xsl:text>
 347 </xsl:template>
 348
 349 <xsl:template match="varargs" mode="ansi">
 350   <xsl:text>...);</xsl:text>
 351 </xsl:template>
 352
 353 <xsl:template match="paramdef" mode="kr">
 354   <!-- * in K&R-style output, the prototype just contains the parameter -->
 355   <!-- * names - because the parameter definitions for each parameter -->
 356   <!-- * (including the type information) are displayed in a separate -->
 357   <!-- * list following the prototype; so in this mode (which is for the -->
 358   <!-- * prototype, not the separate list), we first just want to grab -->
 359   <!-- * the parameter for each paramdef -->
 360   <xsl:variable name="contents">
 361     <xsl:apply-templates select="parameter"/>
 362   </xsl:variable>
 363   <xsl:apply-templates mode="prevent.line.breaking" select="exsl:node-set($contents)"/>
 364   <xsl:choose>
 365     <xsl:when test="following-sibling::*">
 366       <xsl:text>, </xsl:text>
 367     </xsl:when>
 368     <xsl:otherwise>
 369       <xsl:text>);</xsl:text>
 370     </xsl:otherwise>
 371   </xsl:choose>
 372 </xsl:template>
 373
 374 <xsl:template match="paramdef" mode="ansi">
 375   <!-- * in ANSI-style output, the prototype contains the complete -->
 376   <!-- * parameter definitions for each parameter (there is no separate -->
 377   <!-- * list of parameter definitions like the one for K&R style -->
 378   <xsl:apply-templates mode="prevent.line.breaking" select="."/>
 379   <xsl:choose>
 380     <xsl:when test="following-sibling::*">
 381       <xsl:text>, </xsl:text>
 382     </xsl:when>
 383     <xsl:otherwise>
 384       <xsl:text>);</xsl:text>
 385     </xsl:otherwise>
 386   </xsl:choose>
 387 </xsl:template>
 388
 389 <xsl:template match="paramdef" mode="kr-paramdef-list">
 390   <!-- * this mode is for generating the separate list of parameter -->
 391   <!-- * definitions in K&R-style output -->
 392   <xsl:text>.br&#10;</xsl:text>
 393   <xsl:text>.</xsl:text>
 394   <xsl:value-of select="$man.font.funcprototype"/>
 395   <xsl:text> </xsl:text>
 396   <!-- * The following quotation mark (and the one further below) are -->
 397   <!-- * needed to properly delimit the parts of the Funcprototype that -->
 398   <!-- * should be rendered in the prevailing font (either Bold or Roman) -->
 399   <!-- * from Parameter output that needs to be alternately rendered in -->
 400   <!-- * italic. -->
 401   <xsl:text>"</xsl:text>
 402   <xsl:variable name="contents">
 403     <xsl:apply-templates/>
 404   </xsl:variable>
 405   <xsl:value-of select="normalize-space($contents)"/>
 406   <xsl:text>;</xsl:text>
 407   <xsl:text>"</xsl:text>
 408   <xsl:text>&#10;</xsl:text>
 409 </xsl:template>
 410
 411 <xsl:template match="paramdef/parameter">
 412   <!-- * We use U+2591 here in place of a normal space, because if we -->
 413   <!-- * were to just use a normal space, it would get replaced with a -->
 414   <!-- * non-breaking space when we run the whole Paramdef through the -->
 415   <!-- * prevent.line.breaking template. And as far as why we're -->
 416   <!-- * inserting the space and quotation marks around each Parameter -->
 417   <!-- * to begin with, the reason is that we need to because we are -->
 418   <!-- * outputting Funcsynopsis in either the "BI" or "RI" font, and -->
 419   <!-- * the space and quotation marks delimit the text as the -->
 420   <!-- * "alternate" or "I" text that needs to be rendered in italic. -->
 421   <xsl:text>"&#x2591;"</xsl:text>
 422   <xsl:apply-templates/>
 423   <xsl:text>"&#x2591;"</xsl:text>
 424 </xsl:template>
 425
 426 <xsl:template match="funcparams">
 427   <xsl:text>(</xsl:text>
 428   <xsl:apply-templates/>
 429   <xsl:text>)</xsl:text>
 430 </xsl:template>
 431
 432 </xsl:stylesheet>