public inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedFrom: Robert Treat <rob@xzilla.net>
To: pgsql-docs@lists.postgresql.org
Cc: Bruce Momjian <bruce@momjian.us>
Subject: Fix improper xreflabels created for v18 release notes
Date: Thu, 1 Jan 2026 11:55:27 -0500
Message-ID: <CABV9wwNEZDdp5QtrW5ut0H+MOf6U1PvrqBqmgSTgcixqk+Q73A@mail.gmail.com> (raw)
Looking at https://www.postgresql.org/docs/current/xplang.html during
a near by discussion, I was bothered that plpython was not formatting
the same way as the other PL's listed on that page, so I went
spelunking to see what had happened.
It turns out that some xref labels were added during this commit
(https://github.com/postgres/postgres/commit/d8aa21b74ff4e3d767c3344484c3cb22b9f0ec0d)
in order to make the links more readable in the v18 release notes.
However, based on the discussion here:
https://www.postgresql.org/message-id/20200611223836.GA2507%40momjian.us,
the correct way to style links from the release notes is through the
<link> tag, not by adding xrefs, which can have unintended
side-effects in other places (like in the initial doc link above).
This is a little tricky to fix as it needs to happen across 2
different branches, but I believe the right way to fix this involves 2
parts. First, apply patch 01, which converts the xrefs in the v18
release notes to link tags, against REL_18_STABLE, since those release
notes don't exist on master.
Second, either revert the original commit linked above, or apply the
patch 02 which just undoes those changes. Note, I created the patch
against master, but I think it should be applied there and back
patched to 18 stable.
Also note I did a quick scan to see if either the liboq or plpython
xreflabel situation existed elsewhere but I only turned up one usage,
at https://www.postgresql.org/docs/current/triggers.html, which is
also corrected with these changes.
Robert Treat
https://xzilla.net
Attachments:
[application/octet-stream] v1-0001-Replace-improper-use-of-xrefs-with-links.patch (1.2K, 2-v1-0001-Replace-improper-use-of-xrefs-with-links.patch)
download | inline diff:
From a4c1f5cca426f49a0ce140a94dfa9374ee6a1b58 Mon Sep 17 00:00:00 2001
From: Robert Treat <rob@xzilla.net>
Date: Thu, 1 Jan 2026 11:38:11 -0500
Subject: [PATCH v1] Replace improper use of xrefs with links.
Content-Type: text/plain; charset="utf-8"
---
doc/src/sgml/release-18.sgml | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/release-18.sgml b/doc/src/sgml/release-18.sgml
index f35082861e0..7481fae575c 100644
--- a/doc/src/sgml/release-18.sgml
+++ b/doc/src/sgml/release-18.sgml
@@ -3873,7 +3873,7 @@ Author: Tom Lane <tgl@sss.pgh.pa.us>
</sect3>
<sect3 id="release-18-libpq">
- <title><xref linkend="libpq"/></title>
+ <title><link linkend="libpq">Libpq</link></title>
<itemizedlist>
@@ -4860,8 +4860,8 @@ Author: Peter Eisentraut <peter@eisentraut.org>
<listitem>
<para>
- Add support for Python "Limited <acronym>API</acronym>" in <xref
- linkend="plpython"/> (Peter Eisentraut)
+ Add support for Python "Limited <acronym>API</acronym>" in <link
+ linkend="plpython">PL/Python</link> (Peter Eisentraut)
<ulink url="&commit_baseurl;72a3d0462">§</ulink>
<ulink url="&commit_baseurl;0793ab810">§</ulink>
</para>
--
2.24.3 (Apple Git-128)
[application/octet-stream] v1-0002-Remove-libpq-plpython-xreflabel-from-chapter-tags.patch (1.3K, 3-v1-0002-Remove-libpq-plpython-xreflabel-from-chapter-tags.patch)
download | inline diff:
From 2da8b67f63a4c488e5de6a718204e54c174d6222 Mon Sep 17 00:00:00 2001
From: Robert Treat <rob@xzilla.net>
Date: Thu, 1 Jan 2026 11:43:27 -0500
Subject: [PATCH v1] Remove libpq/plpython xreflabel from chapter tags
Content-Type: text/plain; charset="utf-8"
This essentially reverts the changes made in d8aa21b, which were added for
the version 18 release notes, which have been updated in-line in
a seperate commit.
---
doc/src/sgml/libpq.sgml | 2 +-
doc/src/sgml/plpython.sgml | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 7d05938feda..c2cc1326081 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,6 +1,6 @@
<!-- doc/src/sgml/libpq.sgml -->
-<chapter id="libpq" xreflabel="libpq">
+<chapter id="libpq">
<title><application>libpq</application> — C Library</title>
<indexterm zone="libpq">
diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml
index c447452b7c5..c860a47a2e1 100644
--- a/doc/src/sgml/plpython.sgml
+++ b/doc/src/sgml/plpython.sgml
@@ -1,6 +1,6 @@
<!-- doc/src/sgml/plpython.sgml -->
-<chapter id="plpython" xreflabel="PL/Python">
+<chapter id="plpython">
<title>PL/Python — Python Procedural Language</title>
<indexterm zone="plpython"><primary>PL/Python</primary></indexterm>
--
2.24.3 (Apple Git-128)
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: rob@xzilla.net, pgsql-docs@lists.postgresql.org, bruce@momjian.us
Subject: Re: Fix improper xreflabels created for v18 release notes
In-Reply-To: <CABV9wwNEZDdp5QtrW5ut0H+MOf6U1PvrqBqmgSTgcixqk+Q73A@mail.gmail.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox