diff options
author | Peter Eisentraut | 2023-04-13 08:15:20 +0000 |
---|---|---|
committer | Peter Eisentraut | 2023-04-13 08:16:33 +0000 |
commit | e2922702a3027945f139f9b0c7b4686423304e21 (patch) | |
tree | 1b1a96497a7c92b780df1c02ce97be4ecb595789 | |
parent | a34901dd03edb473ddbd81ee5c7332575f6d8881 (diff) |
doc: Make HTML ids discoverable
In the HTML output, this decorates section headers and variable list
terms with a marker ("#") that is a link to the same section/term.
That way, links inside a page can be discovered for easier sharing.
The marker only appears when hovering.
This now requires that all elements that are candidates for such a
link have an id attribute. Otherwise, an error will be generated.
All previously missing ids have been added prior to this patch.
Author: Brar Piening <[email protected]>
Reviewed-by: Karl O. Pinc <[email protected]>
Discussion: https://www.postgresql.org/message-id/flat/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
-rw-r--r-- | doc/src/sgml/stylesheet-html-common.xsl | 127 | ||||
-rw-r--r-- | doc/src/sgml/stylesheet.css | 11 |
2 files changed, 138 insertions, 0 deletions
diff --git a/doc/src/sgml/stylesheet-html-common.xsl b/doc/src/sgml/stylesheet-html-common.xsl index bb6429ef7c..a368e0e199 100644 --- a/doc/src/sgml/stylesheet-html-common.xsl +++ b/doc/src/sgml/stylesheet-html-common.xsl @@ -309,4 +309,131 @@ set toc,title </xsl:choose> </xsl:template> + +<!-- Add an id link to each section heading. --> + +<!-- from html/sections.xsl --> +<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"/> + <!-- pgsql-docs: begin --> + <xsl:call-template name="pg.id.link"> + <xsl:with-param name="object" select="$section"/> + </xsl:call-template> + <!-- pgsql-docs: end --> + </xsl:element> +</xsl:template> + + +<!-- Add an id link after the last term of a varlistentry. --> + +<!-- overrides html/lists.xsl --> +<xsl:template match="varlistentry/term"> + <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>ERROR: id attribute missing on <</xsl:text> + <xsl:value-of select ="name($object)"/> + <xsl:text>> element under </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: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..86a8edb926 100644 --- a/doc/src/sgml/stylesheet.css +++ b/doc/src/sgml/stylesheet.css @@ -169,3 +169,14 @@ 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; +} |