public inbox for pgsql-docs@postgresql.orghelp / color / mirror / Atom feed
Fix improper xreflabels created for v18 release notes 2+ messages / 2 participants [nested] [flat]
* Fix improper xreflabels created for v18 release notes @ 2026-01-01 16:55 Robert Treat <rob@xzilla.net> 2026-01-20 04:10 ` Re: Fix improper xreflabels created for v18 release notes Bruce Momjian <bruce@momjian.us> 0 siblings, 1 reply; 2+ messages in thread From: Robert Treat @ 2026-01-01 16:55 UTC (permalink / raw) To: pgsql-docs@lists.postgresql.org; +Cc: Bruce Momjian <bruce@momjian.us> 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) ^ permalink raw reply [nested|flat] 2+ messages in thread
* Re: Fix improper xreflabels created for v18 release notes 2026-01-01 16:55 Fix improper xreflabels created for v18 release notes Robert Treat <rob@xzilla.net> @ 2026-01-20 04:10 ` Bruce Momjian <bruce@momjian.us> 0 siblings, 0 replies; 2+ messages in thread From: Bruce Momjian @ 2026-01-20 04:10 UTC (permalink / raw) To: Robert Treat <rob@xzilla.net>; +Cc: pgsql-docs@lists.postgresql.org On Thu, Jan 1, 2026 at 11:55:27AM -0500, Robert Treat wrote: > 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. Huh, I didn't notice that, but now that I think if it, it makes sense. I forgot that adding xreflabel can change references to it --- doc/src/sgml/README.link clearly states this: <xref> use to get chapter/section number from the title of the --> target link, or xreflabel if defined at the target, or refentrytitle if target is a refentry; has no close tag http://www.oasis-open.org/docbook/documentation/reference/html/xref.html > 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). Yep. > 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. Applied. > 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. I applied your patch two to both branches. > 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. Yeah, I see some xreflabels for "sect1" links but none for "chapter", except those two I just removed. Not sure what our future plans are in this area, and I know there was a recent thread about this, but we should remain consistent. Thanks for the research, and I apologize for the mistake. -- Bruce Momjian <bruce@momjian.us> https://momjian.us EDB https://enterprisedb.com Do not let urgent matters crowd out time for investment in the future. ^ permalink raw reply [nested|flat] 2+ messages in thread
end of thread, other threads:[~2026-01-20 04:10 UTC | newest] Thread overview: 2+ messages (download: mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2026-01-01 16:55 Fix improper xreflabels created for v18 release notes Robert Treat <rob@xzilla.net> 2026-01-20 04:10 ` Bruce Momjian <bruce@momjian.us>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox