On 06.04.2023 at 11:06, Peter Eisentraut wrote:
On 04.04.23 21:52, Brar Piening wrote:
The XSLT implementation looks sound to me. It would be a touch better
if it had some comments about which parts of the templates were copied
from upstream stylesheets and which were changed. There are examples
of such commenting in the existing customization layer. Also, avoid
introducing whitespace differences during said copying.
I will amend the patch if we agree that this is the way forward.
Ok, it appears everyone agrees that this is the correct approach.
Please post an updated patch. There have been so many partial patches
posted recently, I'm not sure which one is the most current one and
who is really the author.
Attached are two patches:
001-make_html_ids_discoverable_v5.postgresql.patch which needs to be
applied to the postgresql repository. It adds the XSLT to generate the
id links and the CSS to hide/display them. I've added comments as
suggested above.
002-add-discoverable-id-style_v1.pgweb.patch which needs to be applied
to the pgweb repository. It adds the CSS to the offical documentation site.
At the moment (commit 983ec23007) there are no missing ids, so the build
should just work after applying the patch but, as we already know, this
may change with every commit that gets added.
Reviewer is Karl O. Pink
Author is Brar Piening (with some additions from Karl O. Pink)
Best regards,
Brar
diff --git a/media/css/main.css b/media/css/main.css
index 5f8bfdd5..c3464cd0 100644
--- a/media/css/main.css
+++ b/media/css/main.css
@@ -1175,6 +1175,16 @@ code,
padding-right: 2em;
}
+/** Links to ids of headers and definition terms */
+#docContent a.id_link {
+ color: inherit;
+ visibility: hidden;
+}
+
+#docContent *:hover > a.id_link {
+ visibility: visible;
+}
+
/**
* Various callout boxes for docs, including warning, caution, note, tip
*/
diff --git a/doc/src/sgml/stylesheet-html-common.xsl
b/doc/src/sgml/stylesheet-html-common.xsl
index bb6429ef7c..8e5d9912d5 100644
--- a/doc/src/sgml/stylesheet-html-common.xsl
+++ b/doc/src/sgml/stylesheet-html-common.xsl
@@ -309,4 +309,137 @@ set toc,title
</xsl:choose>
</xsl:template>
+
+<!-- Override the standard section heading generation in /xhtml/sections.xsl
+ to add an id link to each section heading. -->
+<xsl:template name="section.heading">
+ <xsl:param name="section" select="."/>
+ <xsl:param name="level" select="1"/>
+ <xsl:param name="allow-anchors" select="1"/>
+ <xsl:param name="title"/>
+ <xsl:param name="class" select="'title'"/>
+
+ <xsl:variable name="id">
+ <xsl:choose>
+ <!-- Make sure the subtitle doesn't get the same id as the title -->
+ <xsl:when test="self::subtitle">
+ <xsl:call-template name="object.id">
+ <xsl:with-param name="object" select="."/>
+ </xsl:call-template>
+ </xsl:when>
+ <!-- if title is in an *info wrapper, get the grandparent -->
+ <xsl:when test="contains(local-name(..), 'info')">
+ <xsl:call-template name="object.id">
+ <xsl:with-param name="object" select="../.."/>
+ </xsl:call-template>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:call-template name="object.id">
+ <xsl:with-param name="object" select=".."/>
+ </xsl:call-template>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:variable>
+
+ <!-- HTML H level is one higher than section level -->
+ <xsl:variable name="hlevel">
+ <xsl:choose>
+ <!-- highest valid HTML H level is H6; so anything nested deeper
+ than 5 levels down just becomes H6 -->
+ <xsl:when test="$level > 5">6</xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="$level + 1"/>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:variable>
+ <xsl:element name="h{$hlevel}" namespace="http://www.w3.org/1999/xhtml";>
+ <xsl:attribute name="class"><xsl:value-of select="$class"/></xsl:attribute>
+ <xsl:if test="$css.decoration != '0'">
+ <xsl:if test="$hlevel<3">
+ <xsl:attribute name="style">clear: both</xsl:attribute>
+ </xsl:if>
+ </xsl:if>
+ <xsl:if test="$allow-anchors != 0">
+ <xsl:call-template name="anchor">
+ <xsl:with-param name="node" select="$section"/>
+ <xsl:with-param name="conditional" select="0"/>
+ </xsl:call-template>
+ </xsl:if>
+ <xsl:copy-of select="$title"/>
+
+ <!--
+ The following code calls the template adding the links.
+ Everything else is copied from the original template.
+ -->
+ <xsl:call-template name="pg.id.link">
+ <xsl:with-param name="object" select="$section"/>
+ </xsl:call-template>
+
+ </xsl:element>
+</xsl:template>
+
+
+<!-- Override the standard template for varlistentry/term in /xhtml/lists.xsl
+ to add an id link after the last term. -->
+<xsl:template match="varlistentry/term">
+ <!-- Apply the original template -->
+ <xsl:apply-imports/>
+
+ <!-- Add the link after the last term -->
+ <xsl:if test="position() = last()">
+ <xsl:call-template name="pg.id.link">
+ <xsl:with-param name="object" select="parent::varlistentry"/>
+ </xsl:call-template>
+ </xsl:if>
+</xsl:template>
+
+
+<!-- Create a link pointing to an id within the document -->
+<xsl:template name="pg.id.link">
+ <xsl:param name="object" select="."/>
+ <xsl:choose>
+ <xsl:when test="$object/@id or $object/@xml:id">
+ <xsl:text> </xsl:text>
+ <a>
+ <xsl:attribute name="href">
+ <xsl:text>#</xsl:text>
+ <xsl:call-template name="object.id">
+ <xsl:with-param name="object" select="$object"/>
+ </xsl:call-template>
+ </xsl:attribute>
+ <xsl:attribute name="class">
+ <xsl:text>id_link</xsl:text>
+ </xsl:attribute>
+ <xsl:text>#</xsl:text>
+ </a>
+ </xsl:when>
+ <xsl:otherwise>
+ <!-- Only complain about varlistentries if at least one entry in
+ the list has an id -->
+ <xsl:if test="name($object) != 'varlistentry'
+ or $object/parent::variablelist/varlistentry[@id]">
+ <xsl:message terminate="yes">
+ <xsl:text> </xsl:text> <!-- leading newline -->
+ <xsl:text>Ids are required in order to provide the public</xsl:text>
+ <xsl:text> HTML documentation with stable URLs for <</xsl:text>
+ <xsl:value-of select ="name($object)"/>
+ <xsl:text>> element content; id missing at: </xsl:text>
+ <xsl:for-each select="$object/ancestor::*">
+ <xsl:text>/</xsl:text>
+ <xsl:value-of select ="name(.)"/>
+ <xsl:if test="@id|@xml:id">
+ <xsl:text>[@</xsl:text>
+ <xsl:value-of select ="name(@id|@xml:id)"/>
+ <xsl:text> = '</xsl:text>
+ <xsl:value-of select ="@id"/>
+ <xsl:text>']</xsl:text>
+ </xsl:if>
+ </xsl:for-each>
+ <xsl:text> </xsl:text> <!-- trailing newline -->
+ </xsl:message>
+ </xsl:if>
+ </xsl:otherwise>
+ </xsl:choose>
+</xsl:template>
+
</xsl:stylesheet>
diff --git a/doc/src/sgml/stylesheet.css b/doc/src/sgml/stylesheet.css
index cc14efa1ca..15bcc95d41 100644
--- a/doc/src/sgml/stylesheet.css
+++ b/doc/src/sgml/stylesheet.css
@@ -169,3 +169,13 @@ acronym { font-style: inherit; }
width: 75%;
}
}
+
+/* Links to ids of headers and definition terms */
+a.id_link {
+ color: inherit;
+ visibility: hidden;
+}
+
+*:hover > a.id_link {
+ visibility: visible;
+}
