Skip to content

Commit e292270

Browse files
peterepetere
committed
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 <brar@gmx.de> Reviewed-by: Karl O. Pinc <kop@karlpinc.com> Discussion: https://www.postgresql.org/message-id/flat/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com
1 parent a34901d commit e292270

File tree

2 files changed

+138
-0
lines changed

2 files changed

+138
-0
lines changed

‎doc/src/sgml/stylesheet-html-common.xsl

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -309,4 +309,131 @@ set toc,title
309309
</xsl:choose>
310310
</xsl:template>
311311

312+
313+
<!-- Add an id link to each section heading. -->
314+
315+
<!-- from html/sections.xsl -->
316+
<xsl:template name="section.heading">
317+
<xsl:param name="section" select="."/>
318+
<xsl:param name="level" select="1"/>
319+
<xsl:param name="allow-anchors" select="1"/>
320+
<xsl:param name="title"/>
321+
<xsl:param name="class" select="'title'"/>
322+
323+
<xsl:variable name="id">
324+
<xsl:choose>
325+
<!-- Make sure the subtitle doesn't get the same id as the title -->
326+
<xsl:when test="self::subtitle">
327+
<xsl:call-template name="object.id">
328+
<xsl:with-param name="object" select="."/>
329+
</xsl:call-template>
330+
</xsl:when>
331+
<!-- if title is in an *info wrapper, get the grandparent -->
332+
<xsl:when test="contains(local-name(..), 'info')">
333+
<xsl:call-template name="object.id">
334+
<xsl:with-param name="object" select="../.."/>
335+
</xsl:call-template>
336+
</xsl:when>
337+
<xsl:otherwise>
338+
<xsl:call-template name="object.id">
339+
<xsl:with-param name="object" select=".."/>
340+
</xsl:call-template>
341+
</xsl:otherwise>
342+
</xsl:choose>
343+
</xsl:variable>
344+
345+
<!-- HTML H level is one higher than section level -->
346+
<xsl:variable name="hlevel">
347+
<xsl:choose>
348+
<!-- highest valid HTML H level is H6; so anything nested deeper
349+
than 5 levels down just becomes H6 -->
350+
<xsl:when test="$level &gt; 5">6</xsl:when>
351+
<xsl:otherwise>
352+
<xsl:value-of select="$level + 1"/>
353+
</xsl:otherwise>
354+
</xsl:choose>
355+
</xsl:variable>
356+
<xsl:element name="h{$hlevel}" namespace="http://www.w3.org/1999/xhtml">
357+
<xsl:attribute name="class"><xsl:value-of select="$class"/></xsl:attribute>
358+
<xsl:if test="$css.decoration != '0'">
359+
<xsl:if test="$hlevel&lt;3">
360+
<xsl:attribute name="style">clear: both</xsl:attribute>
361+
</xsl:if>
362+
</xsl:if>
363+
<xsl:if test="$allow-anchors != 0">
364+
<xsl:call-template name="anchor">
365+
<xsl:with-param name="node" select="$section"/>
366+
<xsl:with-param name="conditional" select="0"/>
367+
</xsl:call-template>
368+
</xsl:if>
369+
<xsl:copy-of select="$title"/>
370+
<!-- pgsql-docs: begin -->
371+
<xsl:call-template name="pg.id.link">
372+
<xsl:with-param name="object" select="$section"/>
373+
</xsl:call-template>
374+
<!-- pgsql-docs: end -->
375+
</xsl:element>
376+
</xsl:template>
377+
378+
379+
<!-- Add an id link after the last term of a varlistentry. -->
380+
381+
<!-- overrides html/lists.xsl -->
382+
<xsl:template match="varlistentry/term">
383+
<xsl:apply-imports/>
384+
385+
<!-- Add the link after the last term -->
386+
<xsl:if test="position() = last()">
387+
<xsl:call-template name="pg.id.link">
388+
<xsl:with-param name="object" select="parent::varlistentry"/>
389+
</xsl:call-template>
390+
</xsl:if>
391+
</xsl:template>
392+
393+
394+
<!-- Create a link pointing to an id within the document -->
395+
<xsl:template name="pg.id.link">
396+
<xsl:param name="object" select="."/>
397+
<xsl:choose>
398+
<xsl:when test="$object/@id or $object/@xml:id">
399+
<xsl:text> </xsl:text>
400+
<a>
401+
<xsl:attribute name="href">
402+
<xsl:text>#</xsl:text>
403+
<xsl:call-template name="object.id">
404+
<xsl:with-param name="object" select="$object"/>
405+
</xsl:call-template>
406+
</xsl:attribute>
407+
<xsl:attribute name="class">
408+
<xsl:text>id_link</xsl:text>
409+
</xsl:attribute>
410+
<xsl:text>#</xsl:text>
411+
</a>
412+
</xsl:when>
413+
<xsl:otherwise>
414+
<!-- Only complain about varlistentries if at least one entry in
415+
the list has an id -->
416+
<xsl:if test="name($object) != 'varlistentry'
417+
or $object/parent::variablelist/varlistentry[@id]">
418+
<xsl:message terminate="yes">
419+
<xsl:text>ERROR: id attribute missing on &lt;</xsl:text>
420+
<xsl:value-of select ="name($object)"/>
421+
<xsl:text>&gt; element under </xsl:text>
422+
<xsl:for-each select="$object/ancestor::*">
423+
<xsl:text>/</xsl:text>
424+
<xsl:value-of select ="name(.)"/>
425+
<xsl:if test="@id|@xml:id">
426+
<xsl:text>[@</xsl:text>
427+
<xsl:value-of select ="name(@id|@xml:id)"/>
428+
<xsl:text> = '</xsl:text>
429+
<xsl:value-of select ="@id"/>
430+
<xsl:text>']</xsl:text>
431+
</xsl:if>
432+
</xsl:for-each>
433+
</xsl:message>
434+
</xsl:if>
435+
</xsl:otherwise>
436+
</xsl:choose>
437+
</xsl:template>
438+
312439
</xsl:stylesheet>

‎doc/src/sgml/stylesheet.css

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -169,3 +169,14 @@ acronym { font-style: inherit; }
169169
width: 75%;
170170
}
171171
}
172+
173+
/* links to ids of headers and definition terms */
174+
175+
a.id_link {
176+
color: inherit;
177+
visibility: hidden;
178+
}
179+
180+
*:hover > a.id_link {
181+
visibility: visible;
182+
}

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy