summaryrefslogtreecommitdiff
path: root/man/custom-html.xsl
diff options
context:
space:
mode:
Diffstat (limited to 'man/custom-html.xsl')
-rw-r--r--man/custom-html.xsl180
1 files changed, 116 insertions, 64 deletions
diff --git a/man/custom-html.xsl b/man/custom-html.xsl
index 2df12411c7..151276362c 100644
--- a/man/custom-html.xsl
+++ b/man/custom-html.xsl
@@ -22,6 +22,16 @@
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/>
+<!--
+ - The docbook stylesheet injects empty anchor tags into generated HTML, identified by an auto-generated ID.
+ - Ask the docbook stylesheet to generate reproducible output when generating (these) ID values.
+ - This makes the output of this stylesheet reproducible across identical invocations on the same input,
+ - which is an easy and significant win for achieving reproducible builds.
+ -
+ - It may be even better to strip the empty anchors from the document output in addition to turning on consistent IDs,
+ - for this stylesheet contains its own custom ID logic (for generating permalinks) already.
+ -->
+<xsl:param name="generate.consistent.ids" select="1"/>
<!-- translate man page references to links to html pages -->
<xsl:template match="citerefentry[not(@project)]">
@@ -113,80 +123,122 @@
</a>
</xsl:template>
-<xsl:template match="refsect1/title|refsect1/info/title">
- <!-- the ID is output in the block.object call for refsect1 -->
- <h2>
+<!--
+ - helper template to do conflict resolution between various headings with the same inferred ID attribute/tag from the headerlink template
+ - this conflict resolution is necessary to prevent malformed HTML ouput (multiple id attributes with the same value)
+ - and it fixes xsltproc warnings during compilation of HTML man pages
+ -
+ - A simple top-to-bottom numbering scheme is implemented for nodes with the same ID value to derive unique ID values for HTML output.
+ - It uses two parameters:
+ templateID the proposed ID string to use which must be checked for conflicts
+ keyNode the context node which 'produced' the given templateID.
+ -
+ - Conflicts are detected solely based on keyNode, templateID is not taken into account for that purpose.
+ -->
+<xsl:template name="generateID">
+ <!-- node which generatedID needs to assume as the 'source' of the ID -->
+ <xsl:param name="keyNode"/>
+ <!-- suggested value for generatedID output, a contextually meaningful ID string -->
+ <xsl:param name="templateID"/>
+ <xsl:variable name="conflictSource" select="preceding::refsect1/title|preceding::refsect1/info/title|
+ preceding::refsect2/title|preceding::refsect2/info/title|
+ preceding::varlistentry/term[1]"/>
+ <xsl:variable name="conflictCount" select="count($conflictSource[. = $keyNode])"/>
+ <xsl:choose>
+ <!-- special case conflictCount = 0 to preserve compatibility with URLs generated by previous versions of this XSL stylesheet where possible -->
+ <xsl:when test="$conflictCount = 0">
+ <xsl:value-of select="$templateID"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="concat($templateID, $conflictCount)"/>
+ </xsl:otherwise>
+ </xsl:choose>
+</xsl:template>
+
+<!--
+ - a helper template to abstract over the structure of generated subheading + permalink HTML output
+ - It helps reduce tedious repetition and groups all actual markup output (as opposed to URL/ID logic) in a single location.
+ -->
+<xsl:template name="permalink">
+ <xsl:param name="nodeType"/> <!-- local name of the element node to generate, e.g. 'h2' for <h2></h2> -->
+ <xsl:param name="nodeContent"/> <!-- nodeset to apply further templates to obtain the content of the subheading/term -->
+ <xsl:param name="linkTitle"/> <!-- value for title attribute of generated permalink, e.g. 'this is a permalink' -->
+
+ <!-- parameters passed to generateID template, otherwise unused. -->
+ <xsl:param name="keyNode"/>
+ <xsl:param name="templateID"/>
+
+ <!--
+ - If stable URLs with fragment markers (references to the ID) turn out not to be important:
+ - generatedID could simply take the value of generate-id(), and various other helper templates may be dropped entirely.
+ - Alternatively if xsltproc is patched to generate reproducible generate-id() output the same simplifications can be
+ - applied at the cost of breaking compatibility with URLs generated from output of previous versions of this stylesheet.
+ -->
+ <xsl:variable name="generatedID">
+ <xsl:call-template name="generateID">
+ <xsl:with-param name="keyNode" select="$keyNode"/>
+ <xsl:with-param name="templateID" select="$templateID"/>
+ </xsl:call-template>
+ </xsl:variable>
+
+ <xsl:element name="{$nodeType}">
<xsl:attribute name="id">
- <xsl:call-template name="inline.charseq"/>
+ <xsl:value-of select="$generatedID"/>
</xsl:attribute>
- <xsl:apply-templates/>
- <a>
- <xsl:attribute name="class">
- <xsl:text>headerlink</xsl:text>
- </xsl:attribute>
- <xsl:attribute name="title">
- <xsl:text>Permalink to this headline</xsl:text>
- </xsl:attribute>
- <xsl:attribute name="href">
- <xsl:text>#</xsl:text>
- <xsl:call-template name="inline.charseq"/>
- </xsl:attribute>
- <xsl:text>¶</xsl:text>
- </a>
- </h2>
+ <xsl:apply-templates select="$nodeContent"/>
+ <a class="headerlink" title="{$linkTitle}" href="#{$generatedID}">¶</a>
+ </xsl:element>
</xsl:template>
-<xsl:template match="refsect2/title|refsect2/info/title">
- <h3>
- <xsl:attribute name="id">
+<!-- simple wrapper around permalink to avoid repeating common info for each level of subheading covered by the permalink logic (h2, h3) -->
+<xsl:template name="headerlink">
+ <xsl:param name="nodeType"/>
+ <xsl:call-template name="permalink">
+ <xsl:with-param name="nodeType" select="$nodeType"/>
+ <xsl:with-param name="linkTitle" select="'Permalink to this headline'"/>
+ <xsl:with-param name="nodeContent" select="node()"/>
+ <xsl:with-param name="keyNode" select="."/>
+ <!--
+ - To retain compatibility with IDs generated by previous versions of the template, inline.charseq must be called.
+ - The purpose of that template is to generate markup (according to docbook documentation its purpose is to mark/format something as plain text).
+ - The only reason to call this template is to get the auto-generated text such as brackets ([]) before flattening it.
+ -->
+ <xsl:with-param name="templateID">
<xsl:call-template name="inline.charseq"/>
- </xsl:attribute>
- <xsl:apply-templates/>
- <a>
- <xsl:attribute name="class">
- <xsl:text>headerlink</xsl:text>
- </xsl:attribute>
- <xsl:attribute name="title">
- <xsl:text>Permalink to this headline</xsl:text>
- </xsl:attribute>
- <xsl:attribute name="href">
- <xsl:text>#</xsl:text>
- <xsl:call-template name="inline.charseq"/>
- </xsl:attribute>
- <xsl:text>¶</xsl:text>
- </a>
- </h3>
+ </xsl:with-param>
+ </xsl:call-template>
+</xsl:template>
+
+<xsl:template match="refsect1/title|refsect1/info/title">
+ <!-- the ID is output in the block.object call for refsect1 -->
+ <xsl:call-template name="headerlink">
+ <xsl:with-param name="nodeType" select="'h2'"/>
+ </xsl:call-template>
+</xsl:template>
+
+<xsl:template match="refsect2/title|refsect2/info/title">
+ <xsl:call-template name="headerlink">
+ <xsl:with-param name="nodeType" select="'h3'"/>
+ </xsl:call-template>
</xsl:template>
<xsl:template match="varlistentry">
- <dt>
- <xsl:attribute name="id">
+ <xsl:call-template name="permalink">
+ <xsl:with-param name="nodeType" select="'dt'"/>
+ <xsl:with-param name="linkTitle" select="'Permalink to this term'"/>
+ <xsl:with-param name="nodeContent" select="term"/>
+ <xsl:with-param name="keyNode" select="term[1]"/>
+ <!--
+ - To retain compatibility with IDs generated by previous versions of the template, inline.charseq must be called.
+ - The purpose of that template is to generate markup (according to docbook documentation its purpose is to mark/format something as plain text).
+ - The only reason to call this template is to get the auto-generated text such as brackets ([]) before flattening it.
+ -->
+ <xsl:with-param name="templateID">
<xsl:call-template name="inline.charseq">
- <xsl:with-param name="content">
- <xsl:copy-of select="term[position()=1]" />
- </xsl:with-param>
+ <xsl:with-param name="content" select="term[1]"/>
</xsl:call-template>
- </xsl:attribute>
- <xsl:apply-templates select="term"/>
- <a>
- <xsl:attribute name="class">
- <xsl:text>headerlink</xsl:text>
- </xsl:attribute>
- <xsl:attribute name="title">
- <xsl:text>Permalink to this term</xsl:text>
- </xsl:attribute>
- <xsl:attribute name="href">
- <!-- <xsl:call-template name="href.target.uri" /> -->
- <xsl:text>#</xsl:text>
- <xsl:call-template name="inline.charseq">
- <xsl:with-param name="content">
- <xsl:copy-of select="term[position()=1]" />
- </xsl:with-param>
- </xsl:call-template>
- </xsl:attribute>
- <xsl:text>¶</xsl:text>
- </a>
- </dt>
+ </xsl:with-param>
+ </xsl:call-template>
<dd>
<xsl:apply-templates select="listitem"/>
</dd>