Re: Authoring Tools WAS: Switching to XML - Mailing list pgsql-docs

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

Anything that you produce from a WYSWYG editor is going to have to be
massaged to work with PostgreSQL.Org docs.

> 1) a) is there some way we can try various tools and check output?

OpenOffice.Org, WordPerfect, Kword, Abiword. The first two (last I
checked) were the only mature software supporting Docbook output.

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

Absolutely not.

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

It might. However, getting authors will always be difficult. Having
clear direction from the website on how to contribute documentation.
This should include how to contribute if you don't know Docbook. Right
now, you have to dig all the way to Appendix G (who reads apepedixes?).

Something like this would also be helpful:

http://www.tldp.org/LDP/LDP-Author-Guide/html/index.html


> 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.

Well to be honest, there isn't really anyway around that that I know of.
OpenOffice.Org will allow you to do what you want, but someone is going
to have to clean up after you.

Now, that is not neccessarily a road block. It is certainly plausible
that someone could write a section (although I think plain text would be
better here) or rewrite a section and submit it for factoring. Factoring
would involve any Docbook that needed to be done.

Usually the Docbook that is required is trivial.


> 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.

Well that is certainly true.

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

From the source tree:

make postgres.xml

Then validate as you see fit. Just FYI, it does validate.


>
>
> * = 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.
>

What is it specifically you are looking for then? Because that is what
Docbook is, XML (or sgml) the only thing you need to do is validate.

http://www.commandprompt.com/community/emacs_sgml/

If you use OpenOffice you will have to set up a style to correct mirror
the PostgreSQL Docbook usage.

Is that perhaps useful? An OpenOffice style that people could download
that is documented and can be used for creating reasonably useful
Docbook for the community?


Sincerely,

Joshua D. Drake




--

      === The PostgreSQL Company: Command Prompt, Inc. ===
Sales/Support: +1.503.667.4564 || 24x7/Emergency: +1.800.492.2240
Providing the most comprehensive  PostgreSQL solutions since 1997
             http://www.commandprompt.com/

Donate to the PostgreSQL Project: http://www.postgresql.org/about/donate