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

[Garrett Smith]

Very interesting thread...and great info Jean.

Has anyone used the more recent versions of OpenOffice to generate 
DocBook files? I know older versions had some support but it was weak.

Stephan, it sounds like you strongly prefer a plain text editing 
option...would making a tool like OpenOffice (assuming it would work) be 
too steep a requirement?

  -- Garrett


Jean Jordaan wrote:

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