public inbox for [email protected]
help / color / mirror / Atom feedFrom: Peter Eisentraut <[email protected]>
To: Josh Berkus <[email protected]>
Cc: [email protected]
Subject: Re: Need help with SGML again
Date: Wed, 15 Oct 2003 09:21:10 +0200 (CEST)
Message-ID: <[email protected]> (raw)
In-Reply-To: <[email protected]>
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 [email protected]
view thread (17+ messages) latest in thread
reply
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: [email protected]
Cc: [email protected], [email protected]
Subject: Re: Need help with SGML again
In-Reply-To: <[email protected]>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox