[ZDP] Is DocBook still being considered?

Robert OConnor bob@rocnet.com
Thu, 1 Apr 1999 10:13:01 -0500


Hi Philip,
*I am posting this message to the zope list
for wider distribution.

I am struggling with the issues you raise regarding
one base format for all outputs.  I look forward
to the experiences of you and others.

-Bob OConnor bob@rocnet.com

-----Original Message-----
From: Philip Aylesworth <zopelist@regalint.com>
To: zdp@zope.org 
Date: Thursday, April 01, 1999 9:47 AM


I am wondering if DocBook is still being considered for the ZDP. Since
it was first discussed here I have done some research and have decided
to try it for some of our own documentation. The learning curve looks
steep but the benefits seem many. The important ones that I see are:

* One source for Web, paper, PDF, and future formats.

* Does not become obsolete like Word processor formats. (How many of us
have documents that we can't or are too much trouble to read because
they were written on an Apple II or a Commodore 64 in some program that
you will never find now.) I guess HTML and structured text have this
advantage, too.

* Searching can be very powerful because the markup includes meaning
rather that  formatting instructions. So it would be possible to look
for the definition of "external method" rather than all mentions of it.

* DocBook is being rewritten in XML (a subset of SGML) so its future
looks bright!

Some good sources of information that I have found are:

http://nwalsh.com/docbook/ - he is writing a book for O'Reilley to be
published in the spring and also provided as open source

http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html
- gives an introduction to what docbook is and how to use it. Pretty
good, even though there are pieces that haven't been written yet.
Explains what SGML, XML, DTD, docbook, Stylesheets, etc are and their
relationships.

http://www.oasis-open.org/docbook/ - the docbook home page

I think the sooner a good standard is chosen the better. Get the
learning out of the way and start producing useful, long-lasting docs.
If some people don't want to use docbook maybe some of use would be
willing to format other people's text with docbook tags.

Phil A