Content-Type: text/plain;
  charset="iso-8859-1"
From: Josh Berkus <josh@agliodbs.com>
Organization: Aglio Database Solutions
To: Peter Eisentraut <peter_e@gmx.net>
Subject: Re: Need help with SGML again
Date: Wed, 15 Oct 2003 09:46:01 -0700
User-Agent: KMail/1.4.3
Cc: pgsql-docs@postgresql.org
References: <Pine.LNX.4.44.0310150914440.20107-100000@peter.localdomain>
In-Reply-To: <Pine.LNX.4.44.0310150914440.20107-100000@peter.localdomain>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Message-Id: <200310150946.01052.josh@agliodbs.com>

Peter,

> 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"?)

I see what you mean.   Given that I do 95% of my doc browsing in HTML, this 
seems very redundant to me, though; I think it would be interesting to see 
how many users refer to a paper version of the docs.  We may find it's a tiny 
minority.

I'm also annoyed that I found out that the doc strucutre I wanted to use was 
not permitted only after I typed & marked it, but that's hardly your fault.

The way I see it, lack of linking leaves me with 3 choices:
1) Leave things the way they are, which will force new DBAs to scroll/click 
through runtime.sgml looking for the terms I've defined.

2) Create a seperate page/section giving just the basic settings and move the 
tuning information for the 10 settings I've augmennted to that document, 
making things more convenient for new DBAs but annoying experienced ones who 
need to swtich between the new page and the main GUC listing.

3) Copy the information to *both* places, adding repeated text to 
runtime.sgml, and the possibility of the two versions of each text getting 
out of synch.

I'm leaning toward (2).  Thoughts?

> > Any thoughts on replacing Docbook with something else, someday?
>
> I don't see anything better arising.

Something I could edit WYSWYG comes to mind, or at least standard enough 
DocBook that I could use OpenOffice.org on it.

I'm serious about this.  Documentation writing, like advocacy, is a great task 
for people who want to contribute to the project but don't have the coding 
skills.  Currently, it's very difficult to involve any of those people in 
adding to the docs becuase they have to learn an arcane markup format first, 
for which there are no good tools on Windows.

If we could move the docs to a format supported by a multi-platform WYSWYG 
editor, I'd bet you dinner that we could get at least 4 more regular 
documentation contributors, if not a dozen.

-- 
Josh Berkus
Aglio Database Solutions
San Francisco