On 23.03.2023 at 10:35, Alvaro Herrera wrote:
As with the <simplelist> patch, we'll need to patch the CSS used in the
website for the docs too, as that's the most important place where docs
are visited.
Ok, I've created and tested a patch for this too.
Since the need for ids is starting to grow again (ecb696527c added an id
to a varlistentry in doc/src/sgml/ref/create_subscription.sgml) I've
also amended the add-needed-ids patch once again so that the build does
not fail after applying the make_html_ids_discoverable patch.
I've also attached the (unchanged) make_html_ids_discoverable patch for
convenience so this email now contains two patches for postgresql
(ending with .postgresql.patch) and one patch for pgweb (ending with
.pgweb.patch).
TBH I'm a bit afraid that people will immediately start complaining
about the failing docs builds after this got applied since it forces
them to add ids to all varlistenries in a variablelist if they add one,
which can be perceived as quite a burden (also committers and reviewers
will have to get used to always watch out for failing docs builds
because of this).
Since breaking the build on missing ids was an intentional decision we
can theoretically soften this by only issuing a warning or removing the
check for missing id's altogether but this would probably defeat the
purpose since it would lead to an increasing number of entries that lack
an id after a while.
Regards,
Brar
diff --git a/doc/src/sgml/logical-replication.sgml
b/doc/src/sgml/logical-replication.sgml
index 3836d13ad3..1432c67c2a 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -252,7 +252,7 @@
additional columns not provided by the published table. Any such columns
will be filled with the default value as specified in the definition of the
target table. However, logical replication in binary format is more
- restrictive. See the <link
linkend="sql-createsubscription-binary"><literal>binary</literal>
+ restrictive. See the <link
linkend="sql-createsubscription-with-binary"><literal>binary</literal>
option</link> of <command>CREATE SUBSCRIPTION</command> for details.
</para>
diff --git a/doc/src/sgml/pgwalinspect.sgml b/doc/src/sgml/pgwalinspect.sgml
index 9a0241a8d6..62d9f9eb22 100644
--- a/doc/src/sgml/pgwalinspect.sgml
+++ b/doc/src/sgml/pgwalinspect.sgml
@@ -157,7 +157,7 @@ combined_size_percentage | 2.8634072910530795
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="pgwalinspect-funcs-pg-get-wal-block-info">
<term>
<function>pg_get_wal_block_info(start_lsn pg_lsn, end_lsn pg_lsn) returns
setof record</function>
</term>
diff --git a/doc/src/sgml/ref/alter_subscription.sgml
b/doc/src/sgml/ref/alter_subscription.sgml
index e92346edef..f0ab6a918e 100644
--- a/doc/src/sgml/ref/alter_subscription.sgml
+++ b/doc/src/sgml/ref/alter_subscription.sgml
@@ -178,7 +178,7 @@ ALTER SUBSCRIPTION <replaceable
class="parameter">name</replaceable> RENAME TO <
<literal>origin</literal> parameter.
</para>
<para>
- See the <link
linkend="sql-createsubscription-binary"><literal>binary</literal>
+ See the <link
linkend="sql-createsubscription-with-binary"><literal>binary</literal>
option</link> of <command>CREATE SUBSCRIPTION</command> for details
about copying pre-existing data in binary format.
</para>
diff --git a/doc/src/sgml/ref/create_subscription.sgml
b/doc/src/sgml/ref/create_subscription.sgml
index 9d4b9d4e33..605b11bc67 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -61,7 +61,7 @@ CREATE SUBSCRIPTION <replaceable
class="parameter">subscription_name</replaceabl
<title>Parameters</title>
<variablelist>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-subscription-name">
<term><replaceable class="parameter">subscription_name</replaceable></term>
<listitem>
<para>
@@ -70,7 +70,7 @@ CREATE SUBSCRIPTION <replaceable
class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-connection">
<term><literal>CONNECTION '<replaceable
class="parameter">conninfo</replaceable>'</literal></term>
<listitem>
<para>
@@ -81,7 +81,7 @@ CREATE SUBSCRIPTION <replaceable
class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-publication">
<term><literal>PUBLICATION <replaceable
class="parameter">publication_name</replaceable> [, ...]</literal></term>
<listitem>
<para>
@@ -90,7 +90,7 @@ CREATE SUBSCRIPTION <replaceable
class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with">
<term><literal>WITH ( <replaceable
class="parameter">subscription_parameter</replaceable> [= <replaceable
class="parameter">value</replaceable>] [, ... ] )</literal></term>
<listitem>
<para>
@@ -102,7 +102,7 @@ CREATE SUBSCRIPTION <replaceable
class="parameter">subscription_name</replaceabl
<variablelist>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with-connect">
<term><literal>connect</literal> (<type>boolean</type>)</term>
<listitem>
<para>
@@ -129,7 +129,7 @@ CREATE SUBSCRIPTION <replaceable
class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with-create-slot">
<term><literal>create_slot</literal> (<type>boolean</type>)</term>
<listitem>
<para>
@@ -145,7 +145,7 @@ CREATE SUBSCRIPTION <replaceable
class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with-enabled">
<term><literal>enabled</literal> (<type>boolean</type>)</term>
<listitem>
<para>
@@ -156,7 +156,7 @@ CREATE SUBSCRIPTION <replaceable
class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with-slot-name">
<term><literal>slot_name</literal> (<type>string</type>)</term>
<listitem>
<para>
@@ -185,7 +185,7 @@ CREATE SUBSCRIPTION <replaceable
class="parameter">subscription_name</replaceabl
<variablelist>
- <varlistentry id="sql-createsubscription-binary" xreflabel="binary">
+ <varlistentry id="sql-createsubscription-with-binary"
xreflabel="binary">
<term><literal>binary</literal> (<type>boolean</type>)</term>
<listitem>
<para>
@@ -222,7 +222,7 @@ CREATE SUBSCRIPTION <replaceable
class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with-copy-data">
<term><literal>copy_data</literal> (<type>boolean</type>)</term>
<listitem>
<para>
@@ -243,7 +243,7 @@ CREATE SUBSCRIPTION <replaceable
class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with-streaming">
<term><literal>streaming</literal> (<type>enum</type>)</term>
<listitem>
<para>
@@ -271,7 +271,7 @@ CREATE SUBSCRIPTION <replaceable
class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with-synchronous-commit">
<term><literal>synchronous_commit</literal> (<type>enum</type>)</term>
<listitem>
<para>
@@ -303,7 +303,7 @@ CREATE SUBSCRIPTION <replaceable
class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with-two-phase">
<term><literal>two_phase</literal> (<type>boolean</type>)</term>
<listitem>
<para>
@@ -334,7 +334,7 @@ CREATE SUBSCRIPTION <replaceable
class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with-disable-on-error">
<term><literal>disable_on_error</literal> (<type>boolean</type>)</term>
<listitem>
<para>
@@ -346,7 +346,7 @@ CREATE SUBSCRIPTION <replaceable
class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sql-createsubscription-with-origin">
<term><literal>origin</literal> (<type>string</type>)</term>
<listitem>
<para>
diff --git a/doc/src/sgml/stylesheet-html-common.xsl
b/doc/src/sgml/stylesheet-html-common.xsl
index 9df2782ce4..65c58ba750 100644
--- a/doc/src/sgml/stylesheet-html-common.xsl
+++ b/doc/src/sgml/stylesheet-html-common.xsl
@@ -301,4 +301,126 @@ set toc,title
</xsl:choose>
</xsl:template>
+
+<!-- Override the standard section heading generation to add an id link -->
+<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>
+
+
+<!-- Override the standard varlistentry/term generation to add an id link
+ after the last term -->
+<xsl:template match="varlistentry/term">
+ <xsl:apply-imports/>
+ <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>
+
+
+<!-- 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">
+ <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;
+}
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
*/
