On 10.01.2023 at 06:28, Brar Piening wrote:
I'll repost a rebased version of the styling patch in a minute.
After checking that there's no need for rebasing I'm reposting the
original patch here, to make cfbot pick it up as the latest one in a
somewhat screwed up thread mixing two patches (sorry for that - won't
happen again).
Althoug the patch is pretty compact you probably need some understanding
of both XSLT and CSS to understand and judge the changes it introduces.
It pretty much does two things:
1. Make html ids discoverable in the browser by adding a link with a
hover effect to items sections and varlistentries that have an id.
Hover one of the psql options and click on the hash mark in [1] to
see the behavior.
2. Emit a warning to the command line and a comment to the HTML output
when the docs build runs into a section without id or a varlistentry
without id where at least one entry in the varlist already has an id.
The original mail for the patch is at [2], the commitfest entry is at
[3] and the initial discussion leading to this patch starts at [4].
Regards,
Brar
[1] https://pgdocs.piening.info/app-psql.html#APP-PSQL-OPTION-PORT
[2]
https://www.postgresql.org/message-id/d6695820-af71-5e84-58b0-ff9f1c189603%40gmx.de
[3] https://commitfest.postgresql.org/41/4042/
[4]
https://www.postgresql.org/message-id/4364ab38-a475-a1fc-b104-ecd6c72010d0%40enterprisedb.com
diff --git a/doc/src/sgml/stylesheet-html-common.xsl
b/doc/src/sgml/stylesheet-html-common.xsl
index 9df2782ce4..111b03d6fc 100644
--- a/doc/src/sgml/stylesheet-html-common.xsl
+++ b/doc/src/sgml/stylesheet-html-common.xsl
@@ -301,4 +301,115 @@ set toc,title
</xsl:choose>
</xsl:template>
+
+<!-- Overridden template to add links to ids in varlists -->
+<xsl:template match="varlistentry">
+ <dt>
+ <xsl:call-template name="id.attribute"/>
+ <xsl:call-template name="anchor"/>
+ <xsl:apply-templates select="term"/>
+ <xsl:call-template name="pg.id.link"/>
+ </dt>
+ <dd>
+ <xsl:apply-templates select="listitem"/>
+ </dd>
+</xsl:template>
+
+<!-- Overridden template to add links to ids in sections -->
+<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"/>
+ <xsl:call-template name="pg.id.link">
+ <xsl:with-param name="object" select="$section"/>
+ </xsl:call-template>
+ </xsl:element>
+</xsl:template>
+
+<!-- Creates 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">
+ <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="no">
+ <xsl:value-of select ="name($object)"/>
+ <xsl:text> element without id. Please add an id to make it
usable</xsl:text>
+ <xsl:text> as stable anchor in the public HTML
documentation.</xsl:text>
+ </xsl:message>
+ <xsl:comment>
+ <xsl:text>Please add an id to the </xsl:text>
+ <xsl:value-of select ="name($object)"/>
+ <xsl:text> element in the sgml source code.</xsl:text>
+ </xsl:comment>
+ </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 6410a47958..e4174e0613 100644
--- a/doc/src/sgml/stylesheet.css
+++ b/doc/src/sgml/stylesheet.css
@@ -163,3 +163,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;
+}
