On Tue, Jan 10, 2017 at 12:22 PM, Tom Lane <t...@sss.pgh.pa.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 -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
