minor doc improvements

Neil Conway wrote:

I've applied the attached patch to HEAD. It does the following:

Add a few more cross-references where appropriate, add more text
about the FROM clause and an example to the UPDATE reference page,
and make a few other SGML tweaks.

Suggestions for further improvement (for example, to the UPDATE ref
page) are welcome.

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.

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

Peter Eisentraut <peter_e@gmx.net> writes:

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 believe Neil was just copying the existing examples in our docs.
What's this <link> and how would you use it, exactly?

regards, tom lane