X-Original-To: pgsql-docs-postgresql.org@localhost.postgresql.org
Received: from localhost (unknown [200.46.204.2])
	by svr1.postgresql.org (Postfix) with ESMTP
	id 06D91D1C995; Mon,  9 Feb 2004 05:16:54 +0000 (GMT)
Received: from svr1.postgresql.org ([200.46.204.71])
	by localhost (neptune.hub.org [200.46.204.2]) (amavisd-new, port 10024)
	with ESMTP id 65404-09; Mon,  9 Feb 2004 01:16:46 -0400 (AST)
Received: from sss.pgh.pa.us (unknown [192.204.191.242])
	by svr1.postgresql.org (Postfix) with ESMTP
	id 5FDE1D1B45B; Mon,  9 Feb 2004 01:16:40 -0400 (AST)
Received: from sss2.sss.pgh.pa.us (tgl@localhost [127.0.0.1])
	by sss.pgh.pa.us (8.12.11/8.12.11) with ESMTP id i195GjmZ009501;
	Mon, 9 Feb 2004 00:16:45 -0500 (EST)
To: Michael Glaesemann <grzm@myrealbox.com>
Cc: pgsql-docs@postgresql.org, pgsql-hackers@postgresql.org
Subject: Re: [HACKERS] Linking the previously separated documentation 
In-reply-to: <381A237E-5AAE-11D8-98AB-000A95C88220@myrealbox.com> 
References: <381A237E-5AAE-11D8-98AB-000A95C88220@myrealbox.com>
Comments: In-reply-to Michael Glaesemann <grzm@myrealbox.com>
	message dated "Mon, 09 Feb 2004 12:15:31 +0900"
Date: Mon, 09 Feb 2004 00:16:44 -0500
Message-ID: <9500.1076303804@sss.pgh.pa.us>
From: Tom Lane <tgl@sss.pgh.pa.us>
X-Virus-Scanned: by amavisd-new at postgresql.org
X-Archive-Number: 200402/2
X-Sequence-Number: 2257

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