Subject: Re: [HACKERS] Questionable tag usage
To: Magnus Hagander <magnus@hagander.net>, Tom Lane <tgl@sss.pgh.pa.us>
References: <20170105.092557.1822243556008160851.t-ishii@sraoss.co.jp>
 <25963.1483591811@sss.pgh.pa.us>
 <CABUevEx145SttH_vpS3_889P7y84BTpDzNCZb4j=UeauT-MQPg@mail.gmail.com>
Cc: Tatsuo Ishii <ishii@sraoss.co.jp>, pgsql-docs
 <pgsql-docs@postgresql.org>,
 PostgreSQL-development <pgsql-hackers@postgresql.org>
From: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
Organization: 2ndQuadrant
Message-ID: <3022c5b6-b5cd-de3f-7255-26d1633394c6@2ndquadrant.com>
Date: Wed, 11 Jan 2017 12:02:46 -0500
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:45.0)
 Gecko/20100101 Thunderbird/45.6.0
MIME-Version: 1.0
In-Reply-To: 
 <CABUevEx145SttH_vpS3_889P7y84BTpDzNCZb4j=UeauT-MQPg@mail.gmail.com>
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
Precedence: bulk
Sender: pgsql-docs-owner@postgresql.org

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