public inbox for [email protected]  

help / color / mirror / Atom feed

From: Josh Berkus <[email protected]>
To: Peter Eisentraut <[email protected]>
Cc: Joshua D. Drake <[email protected]>
Cc: David Fetter <[email protected]>
Cc: Guillaume Lelarge <[email protected]>
Cc: [email protected]
Subject: Re: Authoring Tools WAS: Switching to XML
Date: Mon, 11 Dec 2006 09:54:52 -0800
Message-ID: <[email protected]> (raw)
In-Reply-To: <[email protected]>
References: <[email protected]>
	<[email protected]>
	<[email protected]>

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

view thread (122+ 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], [email protected], [email protected], [email protected]
  Subject: Re: Authoring Tools WAS: Switching to XML
  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