Thread: Linking the previously separated documentation

Hello all!

I've been eyeing providing links between the previously separated
documentation books, e.g., linking this sentence "Please familiarize
yourself with the  pg_dump reference page." in the backup and restore
section <http://www.postgresql.org/docs/current/static/backup.html> to
the applicable reference page. I haven't gone through all of the docs
yet (there are a lot of them!) and right now I'm just looking for
obvious linking possibilities of the "see foo" variety. Is anyone else
working on something like this? Is it worthwhile?

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? (Might not be a bad idea to work up a style
book for the documentation to guide writing, but that's a project in
and of itself.)

If everything seems fine, I'll see if I can't figure out how to submit
a patch.

Michael Glaesemann
grzm myrealbox com

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.

> 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

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

Michael Glaesemann wrote:
> 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.

If you write xref then you already say that this is a cross-reference,
so you don't need the citerefentry element.  (citerefentry is typically
used to automatically link all occurences to the location of the
manpage.  For instance, FreeBSD uses it to link all refentry
"citations" to their online manpage gateway.)

On Feb 9, 2004, at 6:23 PM, Peter Eisentraut wrote:

> Michael Glaesemann wrote:
>> 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.
>
> If you write xref then you already say that this is a cross-reference,
> so you don't need the citerefentry element.  (citerefentry is typically
> used to automatically link all occurences to the location of the
> manpage.  For instance, FreeBSD uses it to link all refentry
> "citations" to their online manpage gateway.)

Thanks, Peter! Good to know.

Michael Glaesemann
grzm myrealbox com