Date: Wed, 15 Oct 2003 09:21:10 +0200 (CEST)
From: Peter Eisentraut <peter_e@gmx.net>
To: Josh Berkus <josh@agliodbs.com>
Cc: pgsql-docs@postgresql.org
Subject: Re: Need help with SGML again
In-Reply-To: <200310141401.53987.josh@agliodbs.com>
Message-ID: <Pine.LNX.4.44.0310150914440.20107-100000@peter.localdomain>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII

Josh Berkus writes:

> Per our previous discussion, I'd wanted to set up the "Basics of Config" as a
> index linking to the various common options, and put the specific "how to
> set" text in each GUC var description.   However, SGML does not permit me to
> do this.

You should consider the documentation like a book.  That has two
consequences:

1. Linking to anything that is not a formal object (having a title and a
number) does not render well in print.  ("for more information, see
paragraph 3 on page 15"?)

2. Lists of links are going to annoy readers.  Readers want information
here and now, not information about where the information is.

DocBook allows you to link almost anything to almost anything, but doing
that is not always a good idea.

> Any thoughts on replacing Docbook with something else, someday?

I don't see anything better arising.

-- 
Peter Eisentraut   peter_e@gmx.net