[Vorbis-dev] Next libvorbis release?

[Michael Crawford]

It happens that since just last night I've been working on
foolproofing the production of The ZooLib Cookbook from its DocBook
XML source.

The last time I monkeyed with DocBook at all was way back in 2001, on
Slackware, where I had to build all the tools from source.  It was all
very painful, and I never got it to work very well, so I dreaded ever
having to deal with it again, and in fact stopped working on the book
entirely.

But I'm preparing a release of ZooLib, and it's going to need proper
documentation, so I am not only getting back to work on the Cookbook,
but figuring out how to build both PDF and HTML on all of ZooLib's
supported platforms.  Being a cross-platform application framework,
there are a lot of platforms.

The tools have come a long ways since 2001, so using them doesn't have
to be so hard, at least on Mac OS X - but I found the process of
arriving at the easy solution to be very painful, with an entire night
spent groping around on mailing list archives and message boards with
Google.

There are some very common problems, that no one ever seems to know
the answers to, but that turn out to be very easy to solve if you do
know the answers.

So I decided early this morning that a DocBook HOWTO would be a quite
popular addition to Ogg Frog's website.  For platforms that either
lack the tools entirely, or don't have current versions of them, I
plan to also provide ready-to-install tool binaries.

It's going to take me at least a week or two to get all this done, but
I'll post placeholder pages for them right now:

   Getting Started with DocBook
   http://www.oggfrog.com/howto/docbook-introduction/

   DocBook Publishing Tools
   http://www.oggfrog.com/free-software/docbook-tools/

Most of DocBook's tools seem to be World Champions at producing
completely inappropriate and utterly uninformative error messages.  In
every single case, it turned out that the solution to each error I
encountered was very simple - but figuring out each simple solution
was very painful.

I hope to spare others their pain.

Mike
-- 
Michael David Crawford
mdcrawford at gmail dot com

   I'm looking for a job in Silicon Valley:
     http://www.goingware.com/resume/cover-letter.html