Re: [DOCS] Questionable tag usage

Robert Haas <robertmhaas(at)gmail(dot)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