Re: Linking the previously separated documentation

On Feb 9, 2004, at 2:16 PM, Tom Lane wrote:

> Michael Glaesemann <grzm@myrealbox.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.

Okay. I'll keep working.

>> 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.

If I'm understanding you correctly, that's what I'm doing. Here's an
example of the change:

Original:
     Please familiarize yourself with the
     <citerefentry><refentrytitle>pg_dump</> reference page.

Revised:
     Please familiarize yourself with the
     <citerefentry><refentrytitle><xref linkend="APP-PGDUMP"></></>
reference page.

Doing it this way makes for quicker changes and few disruptions of any
output flow, I believe. And it gets things linked. Rewriting could be
worried about later.

Michael Glaesemann
grzm myrealbox com