[Zope3-dev] Zope 3 Developers Cookbook [progress update]

[Jean Jordaan]

Hi Stephan

> I hate XML for manual typing, since it is far too verbose. 

With a bit of support from my editor (vim) I don't find
DocBook docs too verbose to type (except for tables!!),
but that's a matter of preference. That said, there are
editors that help: http://www.conglomerate.org/shots.php
looks cool, but I haven't tried it yet.

> Also, is there a Word converter for Docbook?

On my system I find these converters (there are many more
out there .. ):

docbook2dvi           docbook2pdf           docbook2texi-spec.pl
docbook2html          docbook2ps            docbook2texixml
docbook2man           docbook2rtf           docbook2txt
docbook2man-spec.pl   docbook2tex
docbook2manxml        docbook2texi

docbook2rtf should be OK as a Word converter.

> What are the advantages of docbook? 

Lots of tools! see the above list of converters. And a
good, well-documented specification, which means that all
people who process a DocBook doc have a good degree of
certainty about what the author intended.

But I won't try and convert you in this mail .. here are
a couple of links: Eric Raymond found it worthwhile to write
a man->docbook converter:
   http://www.catb.org/~esr/doclifter/
and wrote a HOWTO on the topic:
   http://en.tldp.org/HOWTO/DocBook-Demystification-HOWTO/

This is how he starts:

"""
2. Why care about DocBook at all?

There are two possibilities that make DocBook really interesting. One is 
multi-mode rendering and the other is searchable documentation databases.

Multi-mode rendering is the easier, nearer-term possibility; it's the ability to 
write a document in a single master format that can be rendered in many 
different display modes (in particular, as both HTML for on-line viewing and as 
Postscript for high-quality printed output). This capability is pretty well 
implemented now.

Searchable documentation databases is shorthand for the possibility that DocBook 
might help get us to a world in which all the documentation on your open-source 
operating system is one rich, searchable, cross-indexed and hyperlinked database 
(rather than being scattered across several different formats in multiple 
locations as it is now).
"""

That page continues (addressing some of your issues):

"""
DocBook has the vices that go with its virtues. Some people find it unpleasantly 
heavyweight, and too verbose to be really comfortable as a composition format. 
That's OK; as long as the markup tools they like (things like Perl POD or GNU 
Texinfo) can generate DocBook out their back ends, we can all still get we want. 
It doesn't matter whether or not everybody writes in DocBook — as long as it 
becomes the common document interchange format that everyone uses, we'll still 
get unified searchable documentation databases.
"""

I don't think there is a standard LaTeX->DocBook route, but
there is a basic reStructuredText->DocBook .. that might be worth
considering ..

-- 
Jean Jordaan
http://www.upfrontsystems.co.za