Hi there, I maintain the libvorbis, libogg and vorbis-tool package for Fink <http://finkproject.org/ >. Recently I had time to wonder about those again. In particular, since I was informed libsndfile self-tests fails with 1.2.0, but not with a version dubbed 1.2.1rc1 somebody sent me. Also trunk seems to contain security fixes. In https://trac.xiph.org/browser/trunk/vorbis/CHANGES both 1.2.1 and 1.2.2 are mentioned as "unreleased" versions. As far as I can tell. The last release was about 20 months ago. First a disclaimer: I like Ogg Vorbis very much, and I know just much freaking work managing a project like this is, and esp. making releases. I know because i have acted/still act as release monkey project lead for various projects, including the Fink package manager for OS X (which has a libvorbis package I maintain), as well as the ScummVM project (which lets you play old adventure games on new computers), which uses libvorbis (with code I wrote ;-). That said, the following is not meant to attack anybody responsible for releases. Rather, it is meant as a honest inquiry, and a honest offer to help. So, here's my question: When is the next libvorbis release? What is blocking it? Any way I can help? Yes I know: Early last february, there was a thread on this list on this very subject. But apparently it quickly deteriorated in a discussion on how to build the docs, doxygen in general, etc.. It was considered to switch away from Doxygen. Now, that's of course fine, whatever you like. But wouldn't it make most sense to first make new 1.2.x release, and worry about a deep change like that afterwards? Esp. since waiting for people who promise to convert it to any given format simply can take vary long. So, how about finding a temporary workaround for the doc issue, making a release, then finding a long-term solution. (Oh, and maybe some of the nice bug fixes in the track queue could be applied for the release after that then ;-). Here is how I was able to build the current docbook docs: I used fop instead of pdfxmltex and had to replace some PNGs (they were causing fop to error out, very weird). It still gives some strange errors about missing SVG support, but the generated PDF seems to be OK. I submitted my patch to Trac <https://trac.xiph.org/ticket/1523>. Of course you need fop installed for this to work, but I think there are packages for this in most distros. Cheers, Max
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/
Just to stress that point (Michael's email indicates I was not clear
enough):
I have submitted a patch <https://trac.xiph.org/ticket/1523> which
fixes the docbook build issue for me, and should work on most system,
at least on enough to build a PDF & HTML version of the docs and make
a release. This is meant as a short-term solution. If you guys want to
revise your docbook build chain or move to another format, that's all
fine (and I might try to help with it, too). But my impression is that
unblocking the whole release process which currently seems to be
completely wedged should be of higher priority...
If you use fink, it should be sufficient to install these packages to
compile the docbook docs (with my patch from above applied):
fop, docbook-xsl, docbook-dtd.
I am not using Macports, but there it should be:
fop, docbook-xs, docbook-xmll
Debian:
fop, docbook-xsl
Well, tell me your system, and I'll try to find out which packages you
need to install (but obviously "fop" and "docbook-xsl" seem
to be good
candidates ;).
One drawback: You won't get formulas nicely rendered with LaTeX. Of
course, one option would be to switch the whole docs to LaTeX, a more
permanent solution. Quite easy to get both great PDFs and HTML from
this, and very good if you want lots of formulas. Also, pseudo-code
can be typeset very nicely in this.
If using LaTeX is an option for you at all (I am not sure whether any
of you are familiar with it; me, being a mathematician, I use it
daily ;). I could whip up a brief example with a couple pages of the
current specs converted to LaTeX, plus the resulting PDF & HTML
output. And I could convert the whole docs to this format during the
weekend.
Bye,
Max
> > 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!eee? if autoconf is used to build everything else, wtf to use "hand-edited Makefile" for documentation? p.t. -- Petr Tomasek <http://www.etf.cuni.cz/~tomasek> Jabber: butrus at jabbim.cz SIP: butrus at ekiga.net
Max Horn wrote:> * single-page HTML version: <http://dev.quendi.de/vorbis/Vorbis_I_spec/Vorbis_I_spec.htmlHtml looks ok. Obviously a lot could be done with a style sheet.> * PDF generated from this using pdflatex: <http://dev.quendi.de/vorbis/Vorbis_I_spec.pdfPDF looks good.> * LaTeX source files: <http://dev.quendi.de/vorbis/vorbis-docs-tex.tar.bz2 > > Would be really nice if somebody could review it, and also if some > other folks could try whether they can "compile" it. Copy the *.tex > files to the vorbis/doc dir, then run > pdflatex Vorbis_I_spec > to generate the PDF.Worked for me on Ubuntu 8.10. Thats a really great contribution Max. Excellent work. Cheers, Erik -- ----------------------------------------------------------------- Erik de Castro Lopo ----------------------------------------------------------------- "Data is not information, Information is not knowledge, Knowledge is not understanding, Understanding is not wisdom." -- Clifford Stoll