From: Tom Lane <tgl@sss.pgh.pa.us>
To: Robert Haas <robertmhaas@gmail.com>
Cc: Peter Eisentraut <peter_e@gmx.net>
Cc: Magnus Hagander <magnus@hagander.net>
Cc: Tatsuo Ishii <ishii@sraoss.co.jp>
Cc: pgsql-docs <pgsql-docs@postgresql.org>
Cc: PostgreSQL-development <pgsql-hackers@postgresql.org>
Subject: Re: [DOCS] Questionable tag usage
Date: Tue, 10 Jan 2017 12:22:17 -0500
Message-ID: <4325.1484068937@sss.pgh.pa.us> (raw)
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>
List-Unsubscribe: <mailto:majordomo@postgresql.org?body=unsub%20pgsql-hackers>
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
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: tgl@sss.pgh.pa.us, robertmhaas@gmail.com, peter_e@gmx.net, magnus@hagander.net, ishii@sraoss.co.jp, pgsql-hackers@postgresql.org
Subject: Re: [DOCS] Questionable tag usage
In-Reply-To: <4325.1484068937@sss.pgh.pa.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox