From: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
To: Magnus Hagander <magnus@hagander.net>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: Tatsuo Ishii <ishii@sraoss.co.jp>
Cc: pgsql-docs <pgsql-docs@postgresql.org>
Cc: PostgreSQL-development <pgsql-hackers@postgresql.org>
Subject: Re: [HACKERS] Questionable tag usage
Date: Wed, 11 Jan 2017 12:02:46 -0500
Message-ID: <3022c5b6-b5cd-de3f-7255-26d1633394c6@2ndquadrant.com> (raw)
In-Reply-To: <CABUevEx145SttH_vpS3_889P7y84BTpDzNCZb4j=UeauT-MQPg@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>
List-Unsubscribe: <mailto:majordomo@postgresql.org?body=unsub%20pgsql-docs>
On 1/6/17 8:56 AM, Magnus Hagander wrote:
> You could argue that nobody reads the PG docs on dead trees anymore
> and we should embrace the hyperlink style with enthusiasm. I wouldn't
> be against that personally, but there are a lot of places to change if
> we decide that parenthetical "(see Section M.N)" hotlinks are pass
> ,Ai (B.
> I don't think there are a lto of people who use dead tree editions
> anymore, but they certainly do exist. A lot of people use the PDFs
> though, particularly for offline reading or loading them in ebook
> readers. So it still has to be workable there.
And there are man pages as the canonical example of why environments
without full hyperlinking are still useful.
Also, I'm not fond of the style of writing where random words are
hyperlinks, because then there is no context of what the link is for.
Is it more information, is it the canonical definition, is a glossary
entry, a link to Wikipedia, is it essential that I read the linked-to
material to be able to understand the current material, etc. And for
mostly technical reasons, the links sometimes point into the middle of a
section, so it's hard to find what the link was supposed to help you
with, even more so if the target section was rewritten since the link
was placed. The xref style of linking makes the relationship between
both ends of the link more explicit and keeps up with changes in either
side of the link better.
--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
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: peter.eisentraut@2ndquadrant.com, magnus@hagander.net, tgl@sss.pgh.pa.us, ishii@sraoss.co.jp, pgsql-hackers@postgresql.org
Subject: Re: [HACKERS] Questionable tag usage
In-Reply-To: <3022c5b6-b5cd-de3f-7255-26d1633394c6@2ndquadrant.com>
* 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