X-Original-To: pgsql-docs-postgresql.org@postgresql.org Received: from localhost (mx1.hub.org [200.46.208.251]) by postgresql.org (Postfix) with ESMTP id 113499FB2EF for ; Wed, 9 Aug 2006 21:24:39 -0300 (ADT) Received: from postgresql.org ([200.46.204.71]) by localhost (mx1.hub.org [200.46.208.251]) (amavisd-new, port 10024) with ESMTP id 18899-07 for ; Wed, 9 Aug 2006 21:24:29 -0300 (ADT) X-Greylist: from auto-whitelisted by SQLgrey- Received: from mailbox.samurai.com (mailbox.samurai.com [205.207.28.82]) by postgresql.org (Postfix) with ESMTP id 87D049FA0B9 for ; Wed, 9 Aug 2006 21:24:29 -0300 (ADT) Received: from localhost (mailbox.samurai.com [205.207.28.82]) by mailbox.samurai.com (Postfix) with ESMTP id 1012162564; Wed, 9 Aug 2006 20:24:28 -0400 (EDT) X-Virus-Scanned: by amavisd-new at mailbox.samurai.com Received: from mailbox.samurai.com ([205.207.28.82]) by localhost (mailbox.samurai.com [205.207.28.82]) (amavisd-new, port 10024) with LMTP id HUSg8abQy16M; Wed, 9 Aug 2006 20:24:26 -0400 (EDT) Received: from [192.168.1.103] (204.11.229.99.static.etheric.net [204.11.229.99]) (using TLSv1 with cipher RC4-MD5 (128/128 bits)) (No client certificate requested) by mailbox.samurai.com (Postfix) with ESMTP id 6F3D862508; Wed, 9 Aug 2006 20:24:26 -0400 (EDT) Subject: Re: Cross-referencing From: Neil Conway To: Jim Nasby Cc: pgsql-docs@postgresql.org In-Reply-To: <05C72A6D-D5C1-4700-B3F1-D300F611C0A3@pervasive.com> References: <05C72A6D-D5C1-4700-B3F1-D300F611C0A3@pervasive.com> Content-Type: text/plain Date: Wed, 09 Aug 2006 17:24:24 -0700 Message-Id: <1155169465.5129.20.camel@localhost> Mime-Version: 1.0 X-Mailer: Evolution 2.6.1 Content-Transfer-Encoding: 7bit X-Virus-Scanned: Maia Mailguard 1.0.1 X-Spam-Status: No, hits=0.038 tagged_above=0 required=5 tests=AWL, SPF_HELO_PASS, SPF_PASS X-Spam-Level: X-Archive-Number: 200608/20 X-Sequence-Number: 3638 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 , 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