[Vorbis-dev] Again: Next libvorbis release?

[Michael Crawford]

On Wed, Mar 4, 2009 at 7:36 AM, Max Horn <max at quendi.de> wrote:

> So, here's my question: When is the next libvorbis release? What is
> blocking it?

It is widely reported that the DocBook documentation sources won't
build on various platforms.  That's because DocBook has a really
well-deserved reputation for having tools that are really hard to
figure out.  It turns out that there are ways to use the tools that
aren't so bad - most of the problems could be solved by a well-written
HOWTO and some sample code.

I managed to beat The ZooLib Cookbook into submission, and would like
very much to write that HOWTO and sample code, and offered to fix the
libvorbis doc build in the process, but I am up to my eyeballs in a
bunch of over-committed commitments and right now simply don't have
the headspace to deal with it.

Real Soon Now.  I Promise.  Sort Of.

> Any way I can help?

I think that the use of autoconf and ./configure to build the DocBook
sources is about as appropriate as trying to kill a housefly with a
nuclear weapon.  Sure, you can get rid of a disease-ridden pest that
way, but look at all the carnage that results!

Have a look at the hand-edited Makefile I use to build The ZooLib
Cookbook, as well as the stylesheet customatizations that I use.  It's
in ZooLib's CVS at SourceForce in the zoolib/doc/cookbook directory.
There is also a zoolib/doc/xml directory:

   http://sourceforge.net/cvs/?group_id=5156

The one thing that my build should do but doesn't, is automatically
generate a catalog file, then set the environment variable
XML_CATALOG_FILES to the pathname of the catalog.

This *doesn't* need to be a catalog that lists every XML package on
your system!  *All* it needs to contain is an entry for the DocBook
Relax-NG Schema, and the DocBook XSL stylesheets.  The trick will be
to automatically locate these on every platform one can build on; if
nothing else, you could require the user to name them explicitly in
the "make" command line.

For libvorbis, you would want a standard SGML Catalog File, which has
a different format than an XML Catalog File, and you'd set the
variable SGML_CATALOG_FILES.  Other than the use of an older DocBook
version, libvorbis' doc build should be quite similar to The ZooLib
Cookbook's.

It is *particularly* important to set up and use a catalog file,
because if you don't, the default is to fetch the DTD or the Schema
via HTTP over the Internet!  It's not just that the docs won't build
if there is some kind of network problem - or if you're trying to
build the docs on a completely un-connected computer - but it's a huge
waste of resources to fetch those extremely-verbose documentations any
time you want to see the results of your latest edit.

I think a lot of people just assume that some kind of local caching
takes place automatically.  Yes, there is a local cache, but no, it's
*not* automatic - it's the catalog file that sets up that cache.

Hope That Helps!

Mike
-- 
Michael David Crawford
mdcrawford at gmail dot com

   GoingWare's Bag of Programming Tricks
      http://www.goingware.com/tips/