From: Peter Eisentraut <peter@eisentraut.org>
Date: Mon, 22 Jan 2024 09:41:33 +0000 (+0100)
Subject: Make documentation builds reproducible
X-Git-Tag: REL_17_BETA1~1049
X-Git-Url: http://git.postgresql.org/gitweb/?a=commitdiff_plain;h=b0f0a9432d0b6f53634a96715f2666f6d4ea25a1;p=postgresql.git

Make documentation builds reproducible

Currently, the documentation builds are not fully reproducible (in the
sense of https://reproducible-builds.org/).  A fix is available
upstream (https://github.com/docbook/xslt10-stylesheets/issues/54) but
not released.  This commit patches the upstream fix into our
customization layer.

This patch addresses both the HTML and the FO output.  The man output
is already reproducible.

Discussion: https://www.postgresql.org/message-id/flat/9077b779-a9f8-09c8-6e85-da1ebfba15af@eisentraut.org
---

diff --git a/doc/src/sgml/stylesheet-fo.xsl b/doc/src/sgml/stylesheet-fo.xsl
index 5e7e1324803..aff717ddbc7 100644
--- a/doc/src/sgml/stylesheet-fo.xsl
+++ b/doc/src/sgml/stylesheet-fo.xsl
@@ -1,4 +1,8 @@
 <?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE xsl:stylesheet [
+<!ENTITY % common.entities SYSTEM "http://docbook.sourceforge.net/release/xsl/current/common/entities.ent">
+%common.entities;
+]>
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                 version="1.0"
                 xmlns:fo="http://www.w3.org/1999/XSL/Format">
@@ -138,4 +142,259 @@
   </fo:bookmark>
 </xsl:template>
 
+<!-- make generated ids reproducible
+     (https://github.com/docbook/xslt10-stylesheets/issues/54) -->
+
+<!-- from fo/autoidx.xsl -->
+
+<xsl:template match="indexterm" mode="index-primary">
+  <xsl:param name="scope" select="."/>
+  <xsl:param name="role" select="''"/>
+  <xsl:param name="type" select="''"/>
+
+  <xsl:variable name="key" select="&primary;"/>
+  <xsl:variable name="refs" select="key('primary', $key)[&scope;]"/>
+
+  <xsl:variable name="term.separator">
+    <xsl:call-template name="index.separator">
+      <xsl:with-param name="key" select="'index.term.separator'"/>
+    </xsl:call-template>
+  </xsl:variable>
+
+  <xsl:variable name="range.separator">
+    <xsl:call-template name="index.separator">
+      <xsl:with-param name="key" select="'index.range.separator'"/>
+    </xsl:call-template>
+  </xsl:variable>
+
+  <xsl:variable name="number.separator">
+    <xsl:call-template name="index.separator">
+      <xsl:with-param name="key" select="'index.number.separator'"/>
+    </xsl:call-template>
+  </xsl:variable>
+
+  <fo:block xmlns:rx="http://www.renderx.com/XSL/Extensions" xmlns:axf="http://www.antennahouse.com/names/XSL/Extensions">
+    <xsl:if test="$autolink.index.see != 0">
+      <xsl:attribute name="id">
+        <!-- pgsql-docs: begin -->
+        <xsl:text>ientry-</xsl:text>
+        <xsl:call-template name="object.id"/>
+        <!-- pgsql-docs: end -->
+      </xsl:attribute>
+    </xsl:if>
+    <xsl:if test="$axf.extensions != 0">
+      <xsl:attribute name="axf:suppress-duplicate-page-number">true</xsl:attribute>
+    </xsl:if>
+
+    <xsl:for-each select="$refs/primary">
+      <xsl:if test="@id or @xml:id">
+        <fo:inline id="{(@id|@xml:id)[1]}"/>
+      </xsl:if>
+    </xsl:for-each>
+
+    <xsl:value-of select="primary"/>
+
+    <xsl:choose>
+      <xsl:when test="$xep.extensions != 0">
+        <xsl:if test="$refs[not(see) and not(secondary)]">
+          <xsl:copy-of select="$term.separator"/>
+          <xsl:variable name="primary" select="&primary;"/>
+          <xsl:variable name="primary.significant" select="concat(&primary;, $significant.flag)"/>
+          <rx:page-index list-separator="{$number.separator}"
+                         range-separator="{$range.separator}">
+            <xsl:if test="$refs[@significance='preferred'][not(see) and not(secondary)]">
+              <rx:index-item xsl:use-attribute-sets="index.preferred.page.properties xep.index.item.properties"
+                ref-key="{$primary.significant}"/>
+            </xsl:if>
+            <xsl:if test="$refs[not(@significance) or @significance!='preferred'][not(see) and not(secondary)]">
+              <rx:index-item xsl:use-attribute-sets="xep.index.item.properties"
+                ref-key="{$primary}"/>
+            </xsl:if>
+          </rx:page-index>
+        </xsl:if>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:variable name="page-number-citations">
+          <xsl:for-each select="$refs[not(see)
+                                and not(secondary)]">
+            <xsl:apply-templates select="." mode="reference">
+              <xsl:with-param name="scope" select="$scope"/>
+              <xsl:with-param name="role" select="$role"/>
+              <xsl:with-param name="type" select="$type"/>
+              <xsl:with-param name="position" select="position()"/>
+            </xsl:apply-templates>
+          </xsl:for-each>
+        </xsl:variable>
+
+        <xsl:copy-of select="$page-number-citations"/>
+      </xsl:otherwise>
+    </xsl:choose>
+
+    <xsl:if test="$refs[not(secondary)]/*[self::see]">
+      <xsl:apply-templates select="$refs[generate-id() = generate-id(key('see', concat(&primary;, &sep;, &sep;, &sep;, see))[&scope;][1])]"
+                           mode="index-see">
+         <xsl:with-param name="scope" select="$scope"/>
+         <xsl:with-param name="role" select="$role"/>
+         <xsl:with-param name="type" select="$type"/>
+         <xsl:sort select="translate(see, &lowercase;, &uppercase;)"/>
+      </xsl:apply-templates>
+    </xsl:if>
+
+  </fo:block>
+
+  <xsl:if test="$refs/secondary or $refs[not(secondary)]/*[self::seealso]">
+    <fo:block start-indent="1pc">
+      <xsl:apply-templates select="$refs[generate-id() = generate-id(key('see-also', concat(&primary;, &sep;, &sep;, &sep;, seealso))[&scope;][1])]"
+                           mode="index-seealso">
+         <xsl:with-param name="scope" select="$scope"/>
+         <xsl:with-param name="role" select="$role"/>
+         <xsl:with-param name="type" select="$type"/>
+         <xsl:sort select="translate(seealso, &lowercase;, &uppercase;)"/>
+      </xsl:apply-templates>
+      <xsl:apply-templates select="$refs[secondary and count(.|key('secondary', concat($key, &sep;, &secondary;))[&scope;][1]) = 1]"
+                           mode="index-secondary">
+       <xsl:with-param name="scope" select="$scope"/>
+       <xsl:with-param name="role" select="$role"/>
+       <xsl:with-param name="type" select="$type"/>
+       <xsl:sort select="translate(&secondary;, &lowercase;, &uppercase;)"/>
+      </xsl:apply-templates>
+    </fo:block>
+  </xsl:if>
+</xsl:template>
+
+<xsl:template match="indexterm" mode="index-see">
+  <xsl:param name="scope" select="."/>
+  <xsl:param name="role" select="''"/>
+  <xsl:param name="type" select="''"/>
+
+  <xsl:variable name="see" select="normalize-space(see)"/>
+
+  <!-- can only link to primary, which should appear before comma
+  in see "primary, secondary" entry -->
+  <xsl:variable name="seeprimary">
+    <xsl:choose>
+      <xsl:when test="contains($see, ',')">
+        <xsl:value-of select="substring-before($see, ',')"/>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:value-of select="$see"/>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:variable>
+
+  <xsl:variable name="seetarget" select="key('primaryonly', $seeprimary)[1]"/>
+
+  <xsl:variable name="linkend">
+    <xsl:if test="$seetarget">
+      <!-- pgsql-docs: begin -->
+      <xsl:text>ientry-</xsl:text>
+      <xsl:call-template name="object.id">
+        <xsl:with-param name="object" select="$seetarget"/>
+      </xsl:call-template>
+      <!-- pgsql-docs: end -->
+    </xsl:if>
+  </xsl:variable>
+
+  <fo:inline xmlns:xlink='http://www.w3.org/1999/xlink'>
+    <xsl:text> (</xsl:text>
+    <xsl:call-template name="gentext">
+      <xsl:with-param name="key" select="'see'"/>
+    </xsl:call-template>
+    <xsl:text> </xsl:text>
+    <xsl:choose>
+      <!-- manual links have precedence -->
+      <xsl:when test="see/@linkend or see/@xlink:href">
+        <xsl:call-template name="simple.xlink">
+          <xsl:with-param name="node" select="see"/>
+          <xsl:with-param name="content" select="$see"/>
+        </xsl:call-template>
+      </xsl:when>
+      <xsl:when test="$autolink.index.see = 0">
+         <xsl:value-of select="$see"/>
+      </xsl:when>
+      <xsl:when test="$seetarget">
+        <fo:basic-link internal-destination="{$linkend}"
+                       xsl:use-attribute-sets="xref.properties">
+          <xsl:value-of select="$see"/>
+        </fo:basic-link>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:value-of select="$see"/>
+      </xsl:otherwise>
+    </xsl:choose>
+    <xsl:text>)</xsl:text>
+  </fo:inline>
+</xsl:template>
+
+<xsl:template match="indexterm" mode="index-seealso">
+   <xsl:param name="scope" select="."/>
+  <xsl:param name="role" select="''"/>
+  <xsl:param name="type" select="''"/>
+
+  <xsl:for-each select="seealso">
+    <xsl:sort select="translate(., &lowercase;, &uppercase;)"/>
+
+    <xsl:variable name="seealso" select="normalize-space(.)"/>
+
+    <!-- can only link to primary, which should appear before comma
+    in seealso "primary, secondary" entry -->
+    <xsl:variable name="seealsoprimary">
+      <xsl:choose>
+        <xsl:when test="contains($seealso, ',')">
+          <xsl:value-of select="substring-before($seealso, ',')"/>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:value-of select="$seealso"/>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+
+    <xsl:variable name="seealsotarget" select="key('primaryonly', $seealsoprimary)[1]"/>
+
+    <xsl:variable name="linkend">
+      <xsl:if test="$seealsotarget">
+        <!-- pgsql-docs: begin -->
+        <xsl:text>ientry-</xsl:text>
+        <xsl:call-template name="object.id">
+          <xsl:with-param name="object" select="$seealsotarget"/>
+        </xsl:call-template>
+        <!-- pgsql-docs: end -->
+      </xsl:if>
+    </xsl:variable>
+
+    <fo:block xmlns:xlink='http://www.w3.org/1999/xlink'>
+      <xsl:text>(</xsl:text>
+      <xsl:call-template name="gentext">
+        <xsl:with-param name="key" select="'seealso'"/>
+      </xsl:call-template>
+      <xsl:text> </xsl:text>
+      <xsl:choose>
+        <!-- manual links have precedence -->
+        <xsl:when test="@linkend or see/@xlink:href">
+          <xsl:call-template name="simple.xlink">
+            <xsl:with-param name="node" select="."/>
+            <xsl:with-param name="content" select="$seealso"/>
+          </xsl:call-template>
+        </xsl:when>
+        <xsl:when test="$autolink.index.see = 0">
+          <xsl:value-of select="$seealso"/>
+        </xsl:when>
+        <xsl:when test="$seealsotarget">
+          <fo:basic-link internal-destination="{$linkend}"
+                         xsl:use-attribute-sets="xref.properties">
+            <xsl:value-of select="$seealso"/>
+          </fo:basic-link>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:value-of select="$seealso"/>
+        </xsl:otherwise>
+      </xsl:choose>
+      <xsl:text>)</xsl:text>
+    </fo:block>
+
+  </xsl:for-each>
+
+</xsl:template>
+
+
 </xsl:stylesheet>
diff --git a/doc/src/sgml/stylesheet-html-common.xsl b/doc/src/sgml/stylesheet-html-common.xsl
index a368e0e1990..7f541c09885 100644
--- a/doc/src/sgml/stylesheet-html-common.xsl
+++ b/doc/src/sgml/stylesheet-html-common.xsl
@@ -436,4 +436,238 @@ set       toc,title
   </xsl:choose>
 </xsl:template>
 
+<!-- make generated ids reproducible
+     (https://github.com/docbook/xslt10-stylesheets/issues/54) -->
+
+<!-- from html/autoidx.xsl -->
+
+<xsl:template match="indexterm" mode="index-primary">
+  <xsl:param name="scope" select="."/>
+  <xsl:param name="role" select="''"/>
+  <xsl:param name="type" select="''"/>
+
+  <xsl:variable name="key" select="&primary;"/>
+  <xsl:variable name="refs" select="key('primary', $key)[&scope;]"/>
+  <dt>
+    <xsl:if test="$autolink.index.see != 0">
+      <!-- add internal id attribute to form see and seealso links -->
+      <xsl:attribute name="id">
+        <!-- pgsql-docs: begin -->
+        <xsl:text>ientry-</xsl:text>
+        <xsl:call-template name="object.id"/>
+        <!-- pgsql-docs: end -->
+      </xsl:attribute>
+    </xsl:if>
+    <xsl:for-each select="$refs/primary">
+      <xsl:if test="@id or @xml:id">
+        <xsl:choose>
+          <xsl:when test="$generate.id.attributes = 0">
+            <a name="{(@id|@xml:id)[1]}"/>
+          </xsl:when>
+          <xsl:otherwise>
+            <span>
+              <xsl:call-template name="id.attribute"/>
+            </span>
+          </xsl:otherwise>
+        </xsl:choose>
+      </xsl:if>
+    </xsl:for-each>
+    <xsl:value-of select="primary"/>
+    <xsl:choose>
+      <xsl:when test="$index.links.to.section = 1">
+        <xsl:for-each select="$refs[@zone != '' or generate-id() = generate-id(key('primary-section', concat($key, &sep;, &section.id;))[&scope;][1])]">
+          <xsl:apply-templates select="." mode="reference">
+            <xsl:with-param name="position" select="position()"/>
+            <xsl:with-param name="scope" select="$scope"/>
+            <xsl:with-param name="role" select="$role"/>
+            <xsl:with-param name="type" select="$type"/>
+          </xsl:apply-templates>
+        </xsl:for-each>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:for-each select="$refs[not(see)
+                              and not(secondary)][&scope;]">
+          <xsl:apply-templates select="." mode="reference">
+            <xsl:with-param name="position" select="position()"/>
+            <xsl:with-param name="scope" select="$scope"/>
+            <xsl:with-param name="role" select="$role"/>
+            <xsl:with-param name="type" select="$type"/>
+          </xsl:apply-templates>
+        </xsl:for-each>
+      </xsl:otherwise>
+    </xsl:choose>
+
+    <xsl:if test="$refs[not(secondary)]/*[self::see]">
+      <xsl:apply-templates select="$refs[generate-id() = generate-id(key('see', concat(&primary;, &sep;, &sep;, &sep;, see))[&scope;][1])]"
+                           mode="index-see">
+        <xsl:with-param name="position" select="position()"/>
+        <xsl:with-param name="scope" select="$scope"/>
+        <xsl:with-param name="role" select="$role"/>
+        <xsl:with-param name="type" select="$type"/>
+        <xsl:sort select="translate(see, &lowercase;, &uppercase;)"/>
+      </xsl:apply-templates>
+    </xsl:if>
+  </dt>
+  <xsl:choose>
+    <xsl:when test="$refs/secondary or $refs[not(secondary)]/*[self::seealso]">
+      <dd>
+        <dl>
+          <xsl:apply-templates select="$refs[generate-id() = generate-id(key('see-also', concat(&primary;, &sep;, &sep;, &sep;, seealso))[&scope;][1])]"
+                               mode="index-seealso">
+            <xsl:with-param name="position" select="position()"/>
+            <xsl:with-param name="scope" select="$scope"/>
+            <xsl:with-param name="role" select="$role"/>
+            <xsl:with-param name="type" select="$type"/>
+            <xsl:sort select="translate(seealso, &lowercase;, &uppercase;)"/>
+          </xsl:apply-templates>
+          <xsl:apply-templates select="$refs[secondary and count(.|key('secondary', concat($key, &sep;, &secondary;))[&scope;][1]) = 1]"
+                               mode="index-secondary">
+            <xsl:with-param name="position" select="position()"/>
+            <xsl:with-param name="scope" select="$scope"/>
+            <xsl:with-param name="role" select="$role"/>
+            <xsl:with-param name="type" select="$type"/>
+            <xsl:sort select="translate(&secondary;, &lowercase;, &uppercase;)"/>
+          </xsl:apply-templates>
+        </dl>
+      </dd>
+    </xsl:when>
+    <!-- HTML5 requires dd for each dt -->
+    <xsl:when test="$div.element = 'section'">
+      <dd></dd>
+    </xsl:when>
+  </xsl:choose>
+</xsl:template>
+
+<xsl:template match="indexterm" mode="index-see" xmlns:xlink='http://www.w3.org/1999/xlink'>
+  <xsl:param name="scope" select="."/>
+  <xsl:param name="role" select="''"/>
+  <xsl:param name="type" select="''"/>
+
+  <xsl:variable name="see" select="normalize-space(see)"/>
+
+  <!-- can only link to primary, which should appear before comma
+  in see "primary, secondary" entry -->
+  <xsl:variable name="seeprimary">
+    <xsl:choose>
+      <xsl:when test="contains($see, ',')">
+        <xsl:value-of select="substring-before($see, ',')"/>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:value-of select="$see"/>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:variable>
+
+  <xsl:variable name="seetarget" select="key('primaryonly', $seeprimary)[1]"/>
+
+  <xsl:variable name="linkend">
+    <xsl:if test="$seetarget">
+      <!-- pgsql-docs: begin -->
+      <xsl:text>#ientry-</xsl:text>
+      <xsl:call-template name="object.id">
+        <xsl:with-param name="object" select="$seetarget"/>
+      </xsl:call-template>
+      <!-- pgsql-docs: end -->
+    </xsl:if>
+  </xsl:variable>
+
+  <xsl:text> (</xsl:text>
+  <xsl:call-template name="gentext">
+    <xsl:with-param name="key" select="'see'"/>
+  </xsl:call-template>
+  <xsl:text> </xsl:text>
+  <xsl:choose>
+    <!-- manual links have precedence -->
+    <xsl:when test="see/@linkend or see/@xlink:href">
+      <xsl:call-template name="simple.xlink">
+        <xsl:with-param name="node" select="see"/>
+        <xsl:with-param name="content" select="$see"/>
+      </xsl:call-template>
+    </xsl:when>
+    <xsl:when test="$autolink.index.see = 0">
+      <xsl:value-of select="$see"/>
+    </xsl:when>
+    <xsl:when test="$seetarget">
+      <a href="{$linkend}">
+        <xsl:value-of select="$see"/>
+      </a>
+    </xsl:when>
+    <xsl:otherwise>
+      <xsl:value-of select="$see"/>
+    </xsl:otherwise>
+  </xsl:choose>
+  <xsl:text>)</xsl:text>
+</xsl:template>
+
+<xsl:template match="indexterm" mode="index-seealso" xmlns:xlink='http://www.w3.org/1999/xlink'>
+  <xsl:param name="scope" select="."/>
+  <xsl:param name="role" select="''"/>
+  <xsl:param name="type" select="''"/>
+
+  <xsl:for-each select="seealso">
+    <xsl:sort select="translate(., &lowercase;, &uppercase;)"/>
+
+    <xsl:variable name="seealso" select="normalize-space(.)"/>
+
+    <!-- can only link to primary, which should appear before comma
+    in seealso "primary, secondary" entry -->
+    <xsl:variable name="seealsoprimary">
+      <xsl:choose>
+        <xsl:when test="contains($seealso, ',')">
+          <xsl:value-of select="substring-before($seealso, ',')"/>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:value-of select="$seealso"/>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+
+    <xsl:variable name="seealsotarget" select="key('primaryonly', $seealsoprimary)[1]"/>
+
+    <xsl:variable name="linkend">
+      <xsl:if test="$seealsotarget">
+        <!-- pgsql-docs: begin -->
+        <xsl:text>#ientry-</xsl:text>
+        <xsl:call-template name="object.id">
+          <xsl:with-param name="object" select="$seealsotarget"/>
+        </xsl:call-template>
+        <!-- pgsql-docs: end -->
+      </xsl:if>
+    </xsl:variable>
+
+    <dt>
+      <xsl:text>(</xsl:text>
+      <xsl:call-template name="gentext">
+        <xsl:with-param name="key" select="'seealso'"/>
+      </xsl:call-template>
+      <xsl:text> </xsl:text>
+      <xsl:choose>
+        <!-- manual links have precedence -->
+        <xsl:when test="@linkend or see/@xlink:href">
+          <xsl:call-template name="simple.xlink">
+            <xsl:with-param name="node" select="."/>
+            <xsl:with-param name="content" select="$seealso"/>
+          </xsl:call-template>
+        </xsl:when>
+        <xsl:when test="$autolink.index.see = 0">
+          <xsl:value-of select="$seealso"/>
+        </xsl:when>
+        <xsl:when test="$seealsotarget">
+          <a href="{$linkend}">
+            <xsl:value-of select="$seealso"/>
+          </a>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:value-of select="$seealso"/>
+        </xsl:otherwise>
+      </xsl:choose>
+      <xsl:text>)</xsl:text>
+    </dt>
+
+    <xsl:if test="$div.element = 'section'">
+      <dd></dd>
+    </xsl:if>
+  </xsl:for-each>
+</xsl:template>
+
 </xsl:stylesheet>