From: Josh Berkus <josh@agliodbs.com>
Organization: PostgreSQL @ Sun
To: Peter Eisentraut <peter_e@gmx.net>
Subject: Re: Authoring Tools WAS: Switching to XML
Date: Mon, 11 Dec 2006 09:54:52 -0800
User-Agent: KMail/1.8.2
Cc: "Joshua D. Drake" <jd@commandprompt.com>, David Fetter <david@fetter.org>,
	Guillaume Lelarge <guillaume@lelarge.info>, pgsql-docs@postgresql.org
References: <4579720E.4000707@dawninglight.net>
	<1165769484.13210.35.camel@localhost.localdomain>
	<200612101825.17409.peter_e@gmx.net>
In-Reply-To: <200612101825.17409.peter_e@gmx.net>
MIME-Version: 1.0
Content-Type: text/plain;
  charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline
Message-Id: <200612110954.52969.josh@agliodbs.com>

Folks,

Tom and Peter correctly point out that discussion of production tools and 
authoring tools are separate, and only come together if there are tools for 
XML which solve both issues, an assertion which is not yet proven.

I am one of the champions of XML simply because I know for a fact that there 
are no real authoring tools* for SGML.  However, I do *not* know that the 
tools for XML produce acceptable output.

So, questions to answer:

1) Are there enhanced tools for Docbook XML, WYSWYG or otherwise, which make 
doc authoring easier and produce correct output for PostgreSQL Docs?
1) a) is there some way we can try various tools and check output?

2) If (1), would switching to XML make doc writing with Emacs/VIM harder?

3) If (1), will having authoring tools available increase the number of doc 
contributors?

Regarding (3), I believe that having authoring tools would increase our pool 
based on two things:
a) Anectodal evidence, including several people (like me) who were prevented 
from doing significant doc clean-up by the amount of labor required to 
restructure large SGML documents.
b) That the vast majority of the OSS world is no longer using SGML, meaning 
that even for hand-editing people who work on other projects will be more 
familiar with XML and thus better able to edit it.

While these two may not be enough to answer "should we migrate", they are 
enough to make it worth trying to find the answer to (1), since if all of the 
Docbook XML authoring tools are crappy the whole discussion is moot.

So, can someone help me come up with a way to validate a Docbook XML version 
of the PostgreSQL docs so that I (and others, hopefully) can start testing 
tools?


* = an authoring tool is one which makes generation of the document 
easier/faster than hand-editing text files.  No such tool exists for SGML -- 
even the Emacs toolkit merely does validation.

-- 
Josh Berkus
PostgreSQL @ Sun
San Francisco