Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps
 (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1jZai4-0007Kf-An
	for pgsql-docs@arkaria.postgresql.org; Fri, 15 May 2020 13:49:08 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.92)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1jZai3-0003tZ-8y
	for pgsql-docs@arkaria.postgresql.org; Fri, 15 May 2020 13:49:07 +0000
Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29])
	by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <bruce@momjian.us>)
	id 1jZai3-0003tS-3P
	for pgsql-docs@lists.postgresql.org; Fri, 15 May 2020 13:49:07 +0000
Received: from momjian.us ([72.94.173.45])
	by magus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <bruce@momjian.us>)
	id 1jZahy-0004le-IS
	for pgsql-docs@postgresql.org; Fri, 15 May 2020 13:49:06 +0000
Received: from bruce by momjian.us with local (Exim 4.92)
	(envelope-from <bruce@momjian.us>)
	id 1jZahx-0002pw-0Q; Fri, 15 May 2020 09:49:01 -0400
Date: Fri, 15 May 2020 09:49:00 -0400
From: Bruce Momjian <bruce@momjian.us>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: PostgreSQL-documentation <pgsql-docs@postgresql.org>
Subject: Re: Adding xreflable
Message-ID: <20200515134900.GD3894@momjian.us>
References: <20200515123923.GB3894@momjian.us>
 <18482.1589549850@sss.pgh.pa.us>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <18482.1589549850@sss.pgh.pa.us>
User-Agent: Mutt/1.10.1 (2018-07-13)
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>
Precedence: bulk

On Fri, May 15, 2020 at 09:37:30AM -0400, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > I have noticed that our ref/*.sgml pages don't have such labels.  I
> > would like to add them and use them for our release notes.  Some of our
> > extensions need them too.
> 
> Why?  Our convention generally is to refer to the command, not to the ref
> page as such.

Uh, for the release notes, I am referencing the doc page about the
feature, and without the xref, I have to mention it twice, e.g.:

     This allows efficient btree indexing of low cardinality columns
     by storing duplicate keys only once.  Users upgrading with <link
     linkend="pgupgrade"><application>pg_upgrade</application></link>
     will need to use <link
     linkend="sql-reindex"><command>REINDEX</command></link> to make use
     of this feature.

I am guessing I will have to put the <command> tags around the <xref>.
As you can see, pg_upgrade, is also missing an xreflabel.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +