Re: [HACKERS] Questionable tag usage

On Tue, Jan 10, 2017 at 12:22 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> 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> ...

I'm not sure if what you describe as existing style is in fact
standard practice. I say that because it's not really my practice. I
tend to use <xref> if there is a way that I can incorporate the link
text into the sentence without contortions or parentheses; if not, I
use <link>. That's not exactly either of the styles you are
mentioning here. It also means that it's quite likely that there are
places where changing what xref produces will make the markup I
committed produce not-so-nice output. I'd be included to write the
above as something like:

...how to frob your wug, as further discussed in <xref linkend="web-frobbing">.

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

I agree, but I think "working well in environments without hyperlinks"
should be something close to a non-goal, perhaps even an anti-goal.
If there's no loss from working well in such a format, fine; if there
is, I'd rather cater to the 99.99% of people whose reading environment
includes links rather than the other 0.01% of people.

> (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.)

+1.

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

Since I've spent a fair amount of brainpower trying to use <xref>
rather than <link> where possible, I'm not innately enthusiastic about
a project whose end is to get rid of <xref>. I won't lose a lot of
sleep over it if we decide to go that direction, though.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company