Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtp (Exim 4.84_2)
	(envelope-from
 <pgsql-hackers-owner+M314461=pgsql-hackers-arkari@postgresql.org>)
	id 1cR084-0004kR-7I
	for pgsql-hackers@arkaria.postgresql.org; Tue, 10 Jan 2017 17:22:36 +0000
Received: from localhost ([127.0.0.1] helo=postgresql.org)
	by malur.postgresql.org with smtp (Exim 4.84_2)
	(envelope-from
 <pgsql-hackers-owner+M314461=pgsql-hackers-arkari@postgresql.org>)
	id 1cR083-0007p2-Os
	for pgsql-hackers@arkaria.postgresql.org; Tue, 10 Jan 2017 17:22:35 +0000
Received: from makus.postgresql.org ([2001:4800:1501:1::229])
	by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA384:256)
	(Exim 4.84_2)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1cR082-0007ni-BC; Tue, 10 Jan 2017 17:22:34 +0000
Received: from sss.pgh.pa.us ([66.207.139.130])
	by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA384:256)
	(Exim 4.84_2)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1cR07z-00075x-HQ; Tue, 10 Jan 2017 17:22:33 +0000
Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1])
	by sss.pgh.pa.us (8.14.4/8.14.4) with ESMTP id v0AHMHVv004326;
	Tue, 10 Jan 2017 12:22:17 -0500
From: Tom Lane <tgl@sss.pgh.pa.us>
To: Robert Haas <robertmhaas@gmail.com>
cc: Peter Eisentraut <peter_e@gmx.net>, Magnus Hagander <magnus@hagander.net>,
        Tatsuo Ishii <ishii@sraoss.co.jp>,
        pgsql-docs <pgsql-docs@postgresql.org>,
        PostgreSQL-development <pgsql-hackers@postgresql.org>
Subject: Re: [DOCS] Questionable tag usage
In-reply-to: 
 <CA+Tgmobsw0QhiJzBCoTu1bHwE3krvF2HipdkckNAzJpvdwL3sQ@mail.gmail.com>
References: <20170105.092557.1822243556008160851.t-ishii@sraoss.co.jp>
 <25963.1483591811@sss.pgh.pa.us>
 <CABUevEx145SttH_vpS3_889P7y84BTpDzNCZb4j=UeauT-MQPg@mail.gmail.com>
 <21061.1483715901@sss.pgh.pa.us>
 <CA+TgmoZM9EPfsNtBcSjY2RD4Ys3t0uTXtzFDDuME7_-XWH1UpA@mail.gmail.com>
 <22261.1484063888@sss.pgh.pa.us>
 <CA+Tgmobsw0QhiJzBCoTu1bHwE3krvF2HipdkckNAzJpvdwL3sQ@mail.gmail.com>
Comments: In-reply-to Robert Haas <robertmhaas@gmail.com>
	message dated "Tue, 10 Jan 2017 11:26:36 -0500"
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <4324.1484068937.1@sss.pgh.pa.us>
Date: Tue, 10 Jan 2017 12:22:17 -0500
Message-ID: <4325.1484068937@sss.pgh.pa.us>
X-Pg-Spam-Score: -5.1 (-----)
List-Archive: <http://archives.postgresql.org/pgsql-hackers>
List-Help: <mailto:majordomo@postgresql.org?body=help>
List-ID: <pgsql-hackers.postgresql.org>
List-Owner: <mailto:pgsql-hackers-owner@postgresql.org>
List-Post: <mailto:pgsql-hackers@postgresql.org>
List-Subscribe: <mailto:majordomo@postgresql.org?body=sub%20pgsql-hackers>
List-Unsubscribe: <mailto:majordomo@postgresql.org?body=unsub%20pgsql-hackers>
X-Mailing-List: pgsql-hackers
Precedence: bulk
Sender: pgsql-hackers-owner@postgresql.org

Robert Haas <robertmhaas@gmail.com> writes:
> Personally, I think that if the doc toolchain changeover changed the
> way xrefs render - and it seems that it did - that's a bug that ought
> to be fixed,

I quite agree.  We'll have enough to do with the toolchain changeover;
we don't need random changes in what common markup produces.

However, that complaint was already lodged in another thread.  What I
think *this* thread is about is whether we ought to switch from the
up-to-now-project-standard style

    ... how to frob your wug (see <xref linkend="wug-frobbing">) ...

to

    ... how to <link linkend="wug-frobbing">frob your wug</link> ...

The second way is better adapted to modern doc-reading environments, IMO,
because it doesn't distract you with a parenthetical remark.  But it loses
in output formats that don't have hyperlinks, or at least so I'd expect.
(Possibly an output format like that would insert footnotes, but I've
always found that a footnote marker every few words is really distracting
too.)

If we did start doing things this way, we wouldn't care so much what
<xref> produces because we wouldn't be using it anymore anyway.
Not that that's a good reason to accept the inconsistency.

			regards, tom lane


-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers