Re: [HACKERS] Linking the previously separated documentation

Michael Glaesemann <grzm(at)myrealbox(dot)com> writes:
> I've been eyeing providing links between the previously separated
> documentation books, ...
> Is anyone else working on something like this? Is it worthwhile?

There's been talk of this earlier, but I don't recall anyone specifically
saying they'd tackle it. It's definitely worth doing.

> If so, I've got a question as to style. My first idea was not to change
> the text at all, and just replace (in the above example) "pg_dump" with
> <xref linkend="APP-PGDUMP">. Should I be rewriting these sections or is
> what I'm doing agreeable?

There are (or at one time were) references along the line of "see the
pg_dump page in the <link>reference manual</>". These obviously could
do with rephrasing now, if you find any left. As far as style goes,
try to keep in mind that the link only helps for HTML-formatted output,
and we do still try to support printing the documentation on dead trees.
The reference should read well when the link infrastructure isn't there.
I think this means you want to have
... see the <link>pg_dump</> reference page ...
and not just
... see <link>pg_dump</> ...
except where the context is pretty obvious, such as a SEE ALSO section
of another reference page.

regards, tom lane