man/custom-html.xsl

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   3
   4 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
   5
   6 <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/>
   7 <!--
   8   - The docbook stylesheet injects empty anchor tags into generated HTML, identified by an auto-generated ID.
   9   - Ask the docbook stylesheet to generate reproducible output when generating (these) ID values.
  10   - This makes the output of this stylesheet reproducible across identical invocations on the same input,
  11   - which is an easy and significant win for achieving reproducible builds.
  12   -
  13   - It may be even better to strip the empty anchors from the document output in addition to turning on consistent IDs,
  14   - for this stylesheet contains its own custom ID logic (for generating permalinks) already.
  15  -->
  16 <xsl:param name="generate.consistent.ids" select="1"/>
  17
  18 <!-- translate man page references to links to html pages -->
  19 <xsl:template match="citerefentry[not(@project)]">
  20   <a>
  21     <xsl:attribute name="href">
  22       <xsl:value-of select="refentrytitle"/><xsl:text>.html#</xsl:text>
  23       <xsl:value-of select="refentrytitle/@target"/>
  24     </xsl:attribute>
  25     <xsl:call-template name="inline.charseq"/>
  26   </a>
  27 </xsl:template>
  28
  29 <xsl:template match="citerefentry[@project='man-pages'] | citerefentry[manvolnum='2'] | citerefentry[manvolnum='4']">
  30   <a>
  31     <xsl:attribute name="href">
  32       <xsl:text>http://man7.org/linux/man-pages/man</xsl:text>
  33       <xsl:value-of select="manvolnum"/>
  34       <xsl:text>/</xsl:text>
  35       <xsl:value-of select="refentrytitle"/>
  36       <xsl:text>.</xsl:text>
  37       <xsl:value-of select="manvolnum"/>
  38       <xsl:text>.html</xsl:text>
  39     </xsl:attribute>
  40     <xsl:call-template name="inline.charseq"/>
  41   </a>
  42 </xsl:template>
  43
  44 <xsl:template match="citerefentry[@project='die-net']">
  45   <a>
  46     <xsl:attribute name="href">
  47       <xsl:text>http://linux.die.net/man/</xsl:text>
  48       <xsl:value-of select="manvolnum"/>
  49       <xsl:text>/</xsl:text>
  50       <xsl:value-of select="refentrytitle"/>
  51     </xsl:attribute>
  52     <xsl:call-template name="inline.charseq"/>
  53   </a>
  54 </xsl:template>
  55
  56 <xsl:template match="citerefentry[@project='wireguard']">
  57   <a>
  58     <xsl:attribute name="href">
  59       <xsl:text>https://git.zx2c4.com/WireGuard/about/src/tools/</xsl:text>
  60       <xsl:value-of select="refentrytitle"/>
  61       <xsl:text>.</xsl:text>
  62       <xsl:value-of select="manvolnum"/>
  63     </xsl:attribute>
  64     <xsl:call-template name="inline.charseq"/>
  65   </a>
  66 </xsl:template>
  67
  68 <xsl:template match="citerefentry[@project='mankier']">
  69   <a>
  70     <xsl:attribute name="href">
  71       <xsl:text>https://www.mankier.com/</xsl:text>
  72       <xsl:value-of select="manvolnum"/>
  73       <xsl:text>/</xsl:text>
  74       <xsl:value-of select="refentrytitle"/>
  75     </xsl:attribute>
  76     <xsl:call-template name="inline.charseq"/>
  77   </a>
  78 </xsl:template>
  79
  80 <xsl:template match="citerefentry[@project='archlinux']">
  81   <a>
  82     <xsl:attribute name="href">
  83       <xsl:text>https://www.archlinux.org/</xsl:text>
  84       <xsl:value-of select="refentrytitle"/>
  85       <xsl:text>/</xsl:text>
  86       <xsl:value-of select="refentrytitle"/>
  87       <xsl:text>.</xsl:text>
  88       <xsl:value-of select="manvolnum"/>
  89       <xsl:text>.html</xsl:text>
  90     </xsl:attribute>
  91     <xsl:call-template name="inline.charseq"/>
  92   </a>
  93 </xsl:template>
  94
  95 <xsl:template match="citerefentry[@project='debian']">
  96   <a>
  97     <xsl:attribute name="href">
  98       <xsl:text>https://manpages.debian.org/unstable/</xsl:text>
  99       <xsl:value-of select="refentrytitle"/>
 100       <xsl:text>/</xsl:text>
 101       <xsl:value-of select="refentrytitle"/>
 102       <xsl:text>.</xsl:text>
 103       <xsl:value-of select="manvolnum"/>
 104       <xsl:text>.en.html</xsl:text>
 105     </xsl:attribute>
 106     <xsl:call-template name="inline.charseq"/>
 107   </a>
 108 </xsl:template>
 109
 110 <xsl:template match="citerefentry[@project='freebsd']">
 111   <a>
 112     <xsl:attribute name="href">
 113       <xsl:text>https://www.freebsd.org/cgi/man.cgi?</xsl:text>
 114       <xsl:value-of select="refentrytitle"/>
 115       <xsl:text>(</xsl:text>
 116       <xsl:value-of select="manvolnum"/>
 117       <xsl:text>)</xsl:text>
 118     </xsl:attribute>
 119     <xsl:call-template name="inline.charseq"/>
 120   </a>
 121 </xsl:template>
 122
 123 <xsl:template match="citerefentry[@project='dbus']">
 124   <a>
 125     <xsl:attribute name="href">
 126       <xsl:text>http://dbus.freedesktop.org/doc/</xsl:text>
 127       <xsl:value-of select="refentrytitle"/>
 128       <xsl:text>.</xsl:text>
 129       <xsl:value-of select="manvolnum"/>
 130       <xsl:text>.html</xsl:text>
 131     </xsl:attribute>
 132     <xsl:call-template name="inline.charseq"/>
 133   </a>
 134 </xsl:template>
 135
 136 <!--
 137   - helper template to do conflict resolution between various headings with the same inferred ID attribute/tag from the headerlink template
 138   - this conflict resolution is necessary to prevent malformed HTML output (multiple ID attributes with the same value)
 139   - and it fixes xsltproc warnings during compilation of HTML man pages
 140   -
 141   - A simple top-to-bottom numbering scheme is implemented for nodes with the same ID value to derive unique ID values for HTML output.
 142   - It uses two parameters:
 143       templateID  the proposed ID string to use which must be checked for conflicts
 144       keyNode     the context node which 'produced' the given templateID.
 145   -
 146   - Conflicts are detected solely based on keyNode, templateID is not taken into account for that purpose.
 147  -->
 148 <xsl:template name="generateID">
 149   <!-- node which generatedID needs to assume as the 'source' of the ID -->
 150   <xsl:param name="keyNode"/>
 151   <!-- suggested value for generatedID output, a contextually meaningful ID string -->
 152   <xsl:param name="templateID"/>
 153   <xsl:variable name="conflictSource" select="preceding::refsect1/title|preceding::refsect1/info/title|
 154                                               preceding::refsect2/title|preceding::refsect2/info/title|
 155                                               preceding::varlistentry/term[1]"/>
 156   <xsl:variable name="conflictCount" select="count($conflictSource[. = $keyNode])"/>
 157   <xsl:choose>
 158     <!-- special case conflictCount = 0 to preserve compatibility with URLs generated by previous versions of this XSL stylesheet where possible -->
 159     <xsl:when test="$conflictCount = 0">
 160       <xsl:value-of select="$templateID"/>
 161     </xsl:when>
 162     <xsl:otherwise>
 163       <xsl:value-of select="concat($templateID, $conflictCount)"/>
 164     </xsl:otherwise>
 165   </xsl:choose>
 166 </xsl:template>
 167
 168 <!--
 169   - a helper template to abstract over the structure of generated subheading + permalink HTML output
 170   - It helps reduce tedious repetition and groups all actual markup output (as opposed to URL/ID logic) in a single location.
 171  -->
 172 <xsl:template name="permalink">
 173   <xsl:param name="nodeType"/> <!-- local name of the element node to generate, e.g. 'h2' for <h2></h2> -->
 174   <xsl:param name="nodeContent"/> <!-- nodeset to apply further templates to obtain the content of the subheading/term -->
 175   <xsl:param name="linkTitle"/> <!-- value for title attribute of generated permalink, e.g. 'this is a permalink' -->
 176
 177   <!-- parameters passed to generateID template, otherwise unused. -->
 178   <xsl:param name="keyNode"/>
 179   <xsl:param name="templateID"/>
 180
 181   <!--
 182     - If stable URLs with fragment markers (references to the ID) turn out not to be important:
 183     - generatedID could simply take the value of generate-id(), and various other helper templates may be dropped entirely.
 184     - Alternatively, if xsltproc is patched to generate reproducible generate-id() output, the same simplifications can be
 185     - applied at the cost of breaking compatibility with URLs generated from output of previous versions of this stylesheet.
 186    -->
 187   <xsl:variable name="generatedID">
 188     <xsl:call-template name="generateID">
 189       <xsl:with-param name="keyNode" select="$keyNode"/>
 190       <xsl:with-param name="templateID" select="$templateID"/>
 191     </xsl:call-template>
 192   </xsl:variable>
 193
 194   <xsl:element name="{$nodeType}">
 195     <xsl:attribute name="id">
 196       <xsl:value-of select="$generatedID"/>
 197     </xsl:attribute>
 198     <xsl:apply-templates select="$nodeContent"/>
 199     <a class="headerlink" title="{$linkTitle}" href="#{$generatedID}">¶</a>
 200   </xsl:element>
 201 </xsl:template>
 202
 203 <!-- simple wrapper around permalink to avoid repeating common info for each level of subheading covered by the permalink logic (h2, h3) -->
 204 <xsl:template name="headerlink">
 205   <xsl:param name="nodeType"/>
 206   <xsl:call-template name="permalink">
 207     <xsl:with-param name="nodeType" select="$nodeType"/>
 208     <xsl:with-param name="linkTitle" select="'Permalink to this headline'"/>
 209     <xsl:with-param name="nodeContent" select="node()"/>
 210     <xsl:with-param name="keyNode" select="."/>
 211     <!--
 212       - To retain compatibility with IDs generated by previous versions of the template, inline.charseq must be called.
 213       - The purpose of that template is to generate markup (according to docbook documentation its purpose is to mark/format something as plain text).
 214       - The only reason to call this template is to get the auto-generated text such as brackets ([]) before flattening it.
 215      -->
 216     <xsl:with-param name="templateID">
 217       <xsl:call-template name="inline.charseq"/>
 218     </xsl:with-param>
 219   </xsl:call-template>
 220 </xsl:template>
 221
 222 <xsl:template match="refsect1/title|refsect1/info/title">
 223   <!-- the ID is output in the block.object call for refsect1 -->
 224   <xsl:call-template name="headerlink">
 225     <xsl:with-param name="nodeType" select="'h2'"/>
 226   </xsl:call-template>
 227 </xsl:template>
 228
 229 <xsl:template match="refsect2/title|refsect2/info/title">
 230   <xsl:call-template name="headerlink">
 231     <xsl:with-param name="nodeType" select="'h3'"/>
 232   </xsl:call-template>
 233 </xsl:template>
 234
 235 <xsl:template match="varlistentry">
 236   <xsl:call-template name="permalink">
 237     <xsl:with-param name="nodeType" select="'dt'"/>
 238     <xsl:with-param name="linkTitle" select="'Permalink to this term'"/>
 239     <xsl:with-param name="nodeContent" select="term"/>
 240     <xsl:with-param name="keyNode" select="term[1]"/>
 241     <!--
 242       - To retain compatibility with IDs generated by previous versions of the template, inline.charseq must be called.
 243       - The purpose of that template is to generate markup (according to docbook documentation its purpose is to mark/format something as plain text).
 244       - The only reason to call this template is to get the auto-generated text such as brackets ([]) before flattening it.
 245      -->
 246     <xsl:with-param name="templateID">
 247       <xsl:call-template name="inline.charseq">
 248         <xsl:with-param name="content" select="term[1]"/>
 249       </xsl:call-template>
 250     </xsl:with-param>
 251   </xsl:call-template>
 252   <dd>
 253     <xsl:apply-templates select="listitem"/>
 254   </dd>
 255 </xsl:template>
 256
 257
 258 <!-- add Index link at top of page -->
 259 <xsl:template name="user.header.content">
 260   <style>
 261     a.headerlink {
 262       color: #c60f0f;
 263       font-size: 0.8em;
 264       padding: 0 4px 0 4px;
 265       text-decoration: none;
 266       visibility: hidden;
 267     }
 268
 269     a.headerlink:hover {
 270       background-color: #c60f0f;
 271       color: white;
 272     }
 273
 274     h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
 275       visibility: visible;
 276     }
 277   </style>
 278
 279   <a>
 280     <xsl:attribute name="href">
 281       <xsl:text>index.html</xsl:text>
 282     </xsl:attribute>
 283     <xsl:text>Index </xsl:text>
 284   </a>·
 285   <a>
 286     <xsl:attribute name="href">
 287       <xsl:text>systemd.directives.html</xsl:text>
 288     </xsl:attribute>
 289     <xsl:text>Directives </xsl:text>
 290   </a>
 291
 292   <span style="float:right">
 293     <xsl:text>systemd </xsl:text>
 294     <xsl:value-of select="$systemd.version"/>
 295   </span>
 296   <hr/>
 297 </xsl:template>
 298
 299 <xsl:template match="literal">
 300   <xsl:text>"</xsl:text>
 301   <xsl:call-template name="inline.monoseq"/>
 302   <xsl:text>"</xsl:text>
 303 </xsl:template>
 304
 305 <!-- Switch things to UTF-8, ISO-8859-1 is soo yesteryear -->
 306 <xsl:output method="html" encoding="UTF-8" indent="no"/>
 307
 308 </xsl:stylesheet>