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)