Skip site navigation (1) Skip section navigation (2)

Re: Need help with SGML again

From: Peter Eisentraut <peter_e(at)gmx(dot)net>
To: Josh Berkus <josh(at)agliodbs(dot)com>
Cc: pgsql-docs(at)postgresql(dot)org
Subject: Re: Need help with SGML again
Date: 2003-10-15 07:21:10
Message-ID: Pine.LNX.4.44.0310150914440.20107-100000@peter.localdomain (view raw or flat)
Thread:
Lists: pgsql-docs
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(at)gmx(dot)net


In response to

Responses

pgsql-docs by date

Next:From: Rod TaylorDate: 2003-10-15 13:51:45
Subject: Re: Need help with SGML again
Previous:From: Josh BerkusDate: 2003-10-14 21:01:53
Subject: Re: Need help with SGML again

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group