Re: Cross-referencing

[Neil Conway <neilc(at)samurai(dot)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