Re: minor doc improvements - Mailing list pgsql-patches

From Neil Conway
Subject Re: minor doc improvements
Date
Msg-id 4046952C.1000404@samurai.com
Whole thread Raw
In response to Re: minor doc improvements  (Peter Eisentraut <peter_e@gmx.net>)
List pgsql-patches
Peter Eisentraut wrote:
> ISTM that the linking changes you propose are stretching the semantics
> of DocBook.  If you want to link, why not just use <link>.  By using
> <xref> plus endterm you're doing the same thing indirectly and you rely
> on the remote endterm having a sensible grammatical structure that fits
> into the local sentence.

I didn't know about the <link> tag, thanks for the suggestion. (I
won't claim to be a DocBook expert.)

Can you suggest when <xref> should be used, and when <link> is the
right tag to use?

(The fact that the endterm of the xref must fit into the grammatical
structure of the local sentence doesn't seem like a major problem to
me. If we change the endterm of *any* xref, couldn't that disturb the
xref's local sentence? i.e. don't the existing uses of <xref> in the
docs suffer from the same problem?)

-Neil

pgsql-patches by date:

Previous
From: Peter Eisentraut
Date:
Subject: Re: minor doc improvements
Next
From: Tom Lane
Date:
Subject: Re: tighten input to float4/float8/oid