Vorbis dev - Feb 2009 - How To Beat DocBook Into Submission

To better understand how to work with DocBook, I'd like to suggest
that you check out ZooLib's DocBook documentation from its SourceForge
CVS, and use my work as an example to help you with your work.   I
just went through the whole painful process of getting it all to work.
 Please learn from my example!

See especially the files:

  zoolib/doc/README.txt

  zoolib/doc/cookbook/Makefile

  zoolib/doc/xml/catalogs/catalog-macports.xml

  zoolib/doc/xml/xsl/pdf.xsl

  zoolib/doc/xml/xsl/xhtml.xsl

Just reading my wonderful new README.txt will likely save you all a
whole world of hurt - just think of how I suffered so you won't have
to!

To get ZooLib via anonymous CVS, do the following - Just press return
when it asks for a password:

   cvs -d:pserver:anonymous at zoolib.cvs.sourceforge.net:/cvsroot/zoolib login

   cvs -z3 -d:pserver:anonymous at zoolib.cvs.sourceforge.net:/cvsroot/zoolib
co -P zoolib/doc

If you follow the instructions in the README.txt, you can then do:

  cd zoolib/doc/cookbook

  make

and you'll get the XHTML versions, and both US Letter and A4 PDFs
saved into the zoolib/doc/cookbook/cookbook directory.

Please understand that the reason I'm posting this is to give you a
current, debugged example of publishing DocBook documents - not to get
you working on ZooLib's documentation!

I hope this helps.

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

Hi !

Michael Crawford wrote:
> Please understand that the reason I'm posting this is to give you a
> current, debugged example of publishing DocBook documents - not to get
> you working on ZooLib's documentation!
> 
> I hope this helps.
I hope too and thank you for your help !

But now (this question is not directed to you but to the Vorbis devs in
general),
why, oh why, is it necessary to build the docs from XML to PDF when
the major doc consumption format is HTML ???

Years ago, I wrote my master thesis in HTML, and converted it
to PDF with HTMLDOC so it coud be printed. But nobody cares about
printed material in the 21th century :-/ Who reads docs anyway ?


Now imagine someone who installs the vorbis sources and
it fails because of XML problems. I thought that Vorbis is about
sound and DSP and compression and what else, but not about
linuxities or packaging.

Oh, and in the 21th century, people who develop have
a web access : make sure the doc is up to date (and in HTML)
on the xiph site, and you will reduce your packaging burden.
Furthermore, and as noted before here, a special "printer-friendly"
CSS
is all one needs. CSS was also designed for this purpose !
And SVG and MathML are supported by the browsers today,
unlike 10 or 5 years ago.

I also second the opinion that needing a network connexion for building
a local package is ... bad. Alright we all have Internet connexions
but there is a chicken-and-egg problem and IMHO, a package must
be self-contained, or else dependencies will make the distro explode.

Or imagine that you want to develop a Vorbis port, for example,
on a machine without framebuffer or X display. Vorbis wants Dockbook,
to generate PDF, so the conversion tool will want a PDF reader as
a dependency, for WHATEVER (or no) REASON, so the X package. Juste because
they "could", each package developer included the other in the
dependency constrains. Finally, the Vorbis package will not compile
because the platform has no graphics display. WTF ?


I hope that my remarks will help you concentrate on the
real issues of development, because i'm sure that the docbook issues
are minor and pointless. I may be mistaken, though.

Best regards,
> Mike
yg

-- 
http://ygdes.com / http://yasep.org