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 1jZbE6-0008Qn-62
	for pgsql-docs@arkaria.postgresql.org; Fri, 15 May 2020 14:22:14 +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 1jZbE5-0001Di-4z
	for pgsql-docs@arkaria.postgresql.org; Fri, 15 May 2020 14:22:13 +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 1jZbE4-0001Db-VX
	for pgsql-docs@lists.postgresql.org; Fri, 15 May 2020 14:22:12 +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 1jZbDz-0005Bx-4B
	for pgsql-docs@postgresql.org; Fri, 15 May 2020 14:22:11 +0000
Received: from bruce by momjian.us with local (Exim 4.92)
	(envelope-from <bruce@momjian.us>)
	id 1jZbDw-0005Xa-Oo; Fri, 15 May 2020 10:22:04 -0400
Date: Fri, 15 May 2020 10:22:04 -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: <20200515142204.GE3894@momjian.us>
References: <20200515123923.GB3894@momjian.us>
 <18482.1589549850@sss.pgh.pa.us>
 <20200515134900.GD3894@momjian.us>
 <19807.1589551746@sss.pgh.pa.us>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <19807.1589551746@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 10:09:06AM -0400, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > On Fri, May 15, 2020 at 09:37:30AM -0400, Tom Lane wrote:
> >> 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.:
> 
> Oh, you're talking about the application man pages not the SQL command
> ones.  I'd still be inclined to solve it with something paralleling
> the way we handle SQL command references.

Well, I would like both the SQL command references and the application
man pages to have xreflabel text.

> Quickly comparing the pgupgrade page to a couple of SQL commands,
> it's not real obvious what is missing.  Maybe there's something
> in the stylesheet support, not the ref pages as such?

I would like to change this:

	<refentry id="pgupgrade">

to

	<refentry id="pgupgrade" xreflabel="pg_upgrade">

so I can do this in the release notes:

	<xref linkend="pgupgrade"/>

and not:

	<link linkend="pgupgrade"><application>pg_upgrade</link>

All the other extensions already do this:

	<sect1 id="sepgsql" xreflabel="sepgsql">

-- 
  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 +