[ZooLib-dev] Quick tips on DocBook

[Michael D. C. <cra...@go...>]

Greetings from wintry Maine!

I was going to write a much longer mail but frequent power outages due to
tonight's blizzard have been impeding progress.

When reliable power is restored, I think I'll at last be able to make a serious
go of writing some ZooLib manuals in DocBook.  I like to write, but I've had no
luck with DocBook so far.  Real Soon Now, I promise.

But check out:

http://www.linuxdoc.org/LDP/LDP-Author-Guide/

The Linux Documentation Project has settled on DocBook as its standard format as
we have, but helpfully they've also figured out the tools and have provided a
pretty clear HOWTO on how to write HOWTO's.  

I think if one doesn't have the cash for Frame+SGML then Emacs with psgml is the
best bet:

http://www.lysator.liu.se/~lenst/about_psgml/

I installed psgml in my emacs and it seems to work with the little test given in
the LDP HOWTO.

Note that Emacs will run on many platforms and psgml is written in emacs lisp,
so you could use it in Windows, for example.

The LDP also says how to use Jade or OpenJade to translate one's DocBook to
HTML.  I found OpenJade's webpage pretty perplexing.  You need to get a lot of
stuff set up just right before anything works.

One might be able to get OpenJade to work on Windows with CygWin, a GNU/Unix
emulation for Win32.

Andy's been able to get a program called "db2html" working but this is
apparently not universally provided with Linux distributions.

Finally see:

http://freshmeat.net/projects/treenotes/

and

http://alphaworks.ibm.com/tech/xeena

which are two Java XML editors.  Treenotes is available as open source under the
BSD license.  Being Java, you can run them on almost any platform, but I found
that Xeena wasn't really robust enough to edit something with a DTD as complex
as DocBook's.  Partially it was slow and partially the UI was confusing when I
had dozens of elements I could choose from in a given context.

Finally, I'd like to recommend that if you're going to write ZooLib
documentation, you should choose the XML DocBook DTD rather than the SGML DTD. 
Both forms are still available and supported, but if you use XML DocBook we can
run our manuals through all manner of XML tools.  There's a lot more work being
done these days for XML than there is for the more general SGML.  The actual
differences in practice between the two DTD's are quite minor.

-- 
Michael D. Crawford
GoingWare Inc. - Expert Software Development and Consulting
http://www.goingware.com/
cra...@go...

   Tilting at Windmills for a Better Tomorrow.