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


Mon, 9 Feb 2004 12:15:31 +0900
Michael Glaesemann <grzm@myrealbox.com>
Linking the previously separated documentation
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

Mon, 09 Feb 2004 00:16:44 -0500
Tom Lane <tgl@sss.pgh.pa.us>
Re: [HACKERS] 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


Mon, 9 Feb 2004 14:57:13 +0900
Michael Glaesemann <grzm@myrealbox.com>
Re: [HACKERS] Linking the previously separated documentation 
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.)



Mon, 9 Feb 2004 10:23:58 +0100
Peter Eisentraut <peter_e@gmx.net>
Re: [HACKERS] Linking the previously separated documentation

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


Mon, 9 Feb 2004 19:50:30 +0900
Michael Glaesemann <grzm@myrealbox.com>
Re: [HACKERS] Linking the previously separated documentation