public inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedFrom: Bruce Momjian <bruce@momjian.us>
To: Robert Treat <rob@xzilla.net>
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: Fix improper xreflabels created for v18 release notes
Date: Mon, 19 Jan 2026 23:10:38 -0500
Message-ID: <aW8APhZaxG-CprlE@momjian.us> (raw)
In-Reply-To: <CABV9wwNEZDdp5QtrW5ut0H+MOf6U1PvrqBqmgSTgcixqk+Q73A@mail.gmail.com>
References: <CABV9wwNEZDdp5QtrW5ut0H+MOf6U1PvrqBqmgSTgcixqk+Q73A@mail.gmail.com>
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.
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: bruce@momjian.us, rob@xzilla.net, pgsql-docs@lists.postgresql.org
Subject: Re: Fix improper xreflabels created for v18 release notes
In-Reply-To: <aW8APhZaxG-CprlE@momjian.us>
* 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