From: Neil Conway <neilc@samurai.com>
To: Jim Nasby <jnasby@pervasive.com>
Cc: pgsql-docs@postgresql.org
Subject: Re: Cross-referencing
Date: Wed, 09 Aug 2006 17:24:24 -0700
Message-ID: <1155169465.5129.20.camel@localhost> (raw)
In-Reply-To: <05C72A6D-D5C1-4700-B3F1-D300F611C0A3@pervasive.com>
References: <05C72A6D-D5C1-4700-B3F1-D300F611C0A3@pervasive.com>
On Wed, 2006-08-09 at 15:29 -0500, Jim Nasby wrote:
> It's always bugged me that the docs don't do a better job of cross-
> referencing things. IE: if a webpage mentions pg_start_backup(), that
> mention should be a link to the documentation for that function.
>
> Is there a historical reason for this?
When the documentation was split into separate DocBook books, you
couldn't link easily link between books. That has since changed. Several
people have been incrementally improving the cross-references, but there
is room for further improvement.
> Any reason not to change it?
If a phrase is mentioned multiple times within a short span of text, I
think we need only make a link out of the first mention. It would also
be nice to ensure the typesetting is consistent: for example, if we're
marking up "pg_start_backup" with <function>, it would be nice to ensure
that linked versions of same are typeset in a similar manner.
If you'd like to improve the cross-referencing, please go ahead and
submit patches.
-Neil
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: neilc@samurai.com, jnasby@pervasive.com
Subject: Re: Cross-referencing
In-Reply-To: <1155169465.5129.20.camel@localhost>
* 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