[PATCH] Use "generate.consistent.ids" for DocBook HTML documentation

[edmonds at mycre.ws]

From: Robert Edmonds <edmonds at mycre.ws>

BIND's HTML documentation is generated by DocBook, and each section in
the documentation gets an automatically generated HTML anchor
identifier. These IDs are not consistent between runs, and because the
DocBook output is committed back into the BIND source tree, this results
in very large, noisy diffs.

For instance, commit 5091a6fe adds a few dozen lines of substantive
changes, but the unified diff with the default amount of context
generated by Git is 3000 lines long. There are many such commits in the
BIND source repository.

This patch enables the "generate.consistent.ids" option in the DocBook
HTML stylesheet, which is documented in the release notes as:

  Generate consistent id attributes

    New generate.consistent.ids parameter which allows generating a more
    stable id values based on XPath rather than the generate-id() function,
    which may not produce consistent values between runs. Stable output ids
    allow you to make stable links to generated content from the outside.

However, the DocBook documentation cautions:

    This param does not associate permanent unique id values with
    particular elements. The id values are consistent only as long as
    the document structure does not change. If the document structure
    changes, then the counting of elements changes, and all id values
    after the first such change may be different, even when there is no
    change to the element itself or its output.

That would still be an improvement over the status quo.

Unfortunately, this option was introduced in version 1.77.1 of the
DocBook XSL stylesheets (released June 2012), while the automated
process that regenerates the documentation output in the BIND source
repository appears to be running version 1.71.1 (released October 2006).
The DocBook installation for that process would need to be updated to
take advantage of this option.
---
 doc/xsl/isc-docbook-chunk.xsl.in | 3 +++
 doc/xsl/isc-docbook-html.xsl.in  | 3 +++
 doc/xsl/isc-notes-html.xsl.in    | 3 +++
 3 files changed, 9 insertions(+)

diff --git a/doc/xsl/isc-docbook-chunk.xsl.in b/doc/xsl/isc-docbook-chunk.xsl.in
index f87b7c1..281d343 100644
--- a/doc/xsl/isc-docbook-chunk.xsl.in
+++ b/doc/xsl/isc-docbook-chunk.xsl.in
@@ -45,6 +45,9 @@
   <!-- Set comment convention for this output format -->
   <xsl:param name="isc.copyright.leader"> - </xsl:param>
 
+  <!-- Generate consistent id attributes -->
+  <xsl:param name="generate.consistent.ids" select="1"/>
+
   <!-- Override Docbook template to insert copyright -->
   <xsl:template name="user.preroot">
     <xsl:comment>
diff --git a/doc/xsl/isc-docbook-html.xsl.in b/doc/xsl/isc-docbook-html.xsl.in
index 6efd5dd..e424b9b 100644
--- a/doc/xsl/isc-docbook-html.xsl.in
+++ b/doc/xsl/isc-docbook-html.xsl.in
@@ -38,6 +38,9 @@
   <!-- Set comment convention for this output format -->
   <xsl:param name="isc.copyright.leader"> - </xsl:param>
 
+  <!-- Generate consistent id attributes -->
+  <xsl:param name="generate.consistent.ids" select="1"/>
+
   <!-- Override Docbook template to insert copyright -->
   <xsl:template name="user.preroot">
     <xsl:comment>
diff --git a/doc/xsl/isc-notes-html.xsl.in b/doc/xsl/isc-notes-html.xsl.in
index a9b7e29..6648c8f 100644
--- a/doc/xsl/isc-notes-html.xsl.in
+++ b/doc/xsl/isc-notes-html.xsl.in
@@ -36,6 +36,9 @@
   <!-- Set comment convention for this output format -->
   <xsl:param name="isc.copyright.leader"> - </xsl:param>
 
+  <!-- Generate consistent id attributes -->
+  <xsl:param name="generate.consistent.ids" select="1"/>
+
   <!-- Override Docbook template to insert copyright -->
   <xsl:template name="user.preroot">
     <xsl:comment>
-- 
2.5.1