Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps  (TLS1.3) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.96)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1vi34m-00DaP2-1U
	for pgsql-docs@arkaria.postgresql.org;
	Tue, 20 Jan 2026 04:10:44 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.96)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1vi34j-00Flwg-2D
	for pgsql-docs@arkaria.postgresql.org;
	Tue, 20 Jan 2026 04:10:42 +0000
Received: from makus.postgresql.org ([2001:4800:3e1:1::229])
	by malur.postgresql.org with esmtps  (TLS1.3) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.96)
	(envelope-from <bruce@momjian.us>)
	id 1vi34j-00FlwY-1F
	for pgsql-docs@lists.postgresql.org;
	Tue, 20 Jan 2026 04:10:41 +0000
Received: from momjian.us ([72.94.173.45])
	by makus.postgresql.org with esmtps  (TLS1.3) tls
 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	(Exim 4.96)
	(envelope-from <bruce@momjian.us>)
	id 1vi34h-001Lsr-0H
	for pgsql-docs@lists.postgresql.org;
	Tue, 20 Jan 2026 04:10:40 +0000
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=momjian.us;
	s=2026010100; h=In-Reply-To:Content-Type:MIME-Version:References:Message-ID:
	Subject:Cc:To:From:Date:Sender:Reply-To:Content-Transfer-Encoding:Content-ID:
	Content-Description; bh=G8CGMH49s1RiKVS+gM871zo2S6LkeHT+UTCEElN+NEc=; b=LSzXk
	47FQ2NC7k/82cnTQQZibOWkbaC4BZddvJMcQHprXD2Zdkqumfluk+LJQWteSsJBkBQ5BWW3u8Z6fz
	tATn/l+1gMxnpV7Wm9sabqS7swRy7sJazkAOZfeKpFs0XR2gkTvngKsPLu8A7jGibzb/LAd3auru/
	Cb+22MNO6TeHIbq4mRyzNKtb9WhmbD777F7nT+sl1DPefeBT2p7clDtkQ7YWPAesJa0rTgzjh5EaQ
	iDuh42hxqLuWKmBp6mOOHYrgqHKj8xGljnMBLdgEJxZN6cloI0wMyOnT7C5Yxkfjy5h7dZ8UfX7Mt
	8CbImv6IfdAywhNyPKLa9yeGccbSA==;
Received: from bruce by momjian.us with local (Exim 4.98.2)
	(envelope-from <bruce@momjian.us>)
	id 1vi34g-00000007OoN-2D2I;
	Mon, 19 Jan 2026 23:10:38 -0500
Date: Mon, 19 Jan 2026 23:10:38 -0500
From: 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
Message-ID: <aW8APhZaxG-CprlE@momjian.us>
References: 
 <CABV9wwNEZDdp5QtrW5ut0H+MOf6U1PvrqBqmgSTgcixqk+Q73A@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: 
 <CABV9wwNEZDdp5QtrW5ut0H+MOf6U1PvrqBqmgSTgcixqk+Q73A@mail.gmail.com>
List-Id: <pgsql-docs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-docs@lists.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-docs>
Archived-At: 
 <https://www.postgresql.org/message-id/aW8APhZaxG-CprlE%40momjian.us>
Precedence: bulk

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.