On Feb 9, 2004, at 2:16 PM, Tom Lane wrote:
Michael Glaesemann <[EMAIL PROTECTED]> 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
---------------------------(end of broadcast)--------------------------- TIP 6: Have you searched our list archives?
http://archives.postgresql.org
