From: Tom Lane <tgl@sss.pgh.pa.us>
To: Michael Glaesemann <grzm@myrealbox.com>
Cc: pgsql-docs@postgresql.org
Cc: pgsql-hackers@postgresql.org
Subject: Re: [HACKERS] Linking the previously separated documentation
Date: Mon, 09 Feb 2004 00:16:44 -0500
Message-ID: <9500.1076303804@sss.pgh.pa.us> (raw)
In-Reply-To: <381A237E-5AAE-11D8-98AB-000A95C88220@myrealbox.com>
References: <381A237E-5AAE-11D8-98AB-000A95C88220@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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: tgl@sss.pgh.pa.us, grzm@myrealbox.com, pgsql-hackers@postgresql.org
Subject: Re: [HACKERS] Linking the previously separated documentation
In-Reply-To: <9500.1076303804@sss.pgh.pa.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox