Re: I'm trying to set up docbook-tools...

[Eric Lee Green <eric@badtux.org>]

On Tue, 04 Jul 2000, Eric S. Raymond wrote:
> I'm trying to set up docbook-tools, and finding it a hideously
> frustrating experience.  Why does all the SGML software and
> documentation in the world read as though it was carefully designed 
> to prevent any actual document production from getting done?

That puzzles me too. Even Norm Walsh's so-called "Docbook" book reads as if it
were a briefly written summary written in a foreign language to be as terse as
possible. You would suspect that the authors of documentation tools would
themselves be enamored of documentation. WIth the exception of Donald Knuth, 
that, alas, does not appear to be the case. 

It's bad enough that the authors of every book and document that exists on SGML
have invented their own inscrutable terminology for the process of marking up
documentation... but none of them, zero, zilch, appears to have considered the
notion of a GLOSSARY, and the very thought of explaining complex terms in a
simple, clear manner appears to break every single SGML author out in hives. 
Yes, it's difficult. I've done it before, I know how difficult it is. But it's
as if the creators of SGML DTD's and tools have a death wish... or else they're
trying to protect their cult's purity by keeping out the riff-raff (same
thing). 

Despite all of the above, I have become reasonably proficient in using the
Docbook-Tools set and in Docbook itself.  But the tool kits still do not work
well enough for me to actually use them to produce real documentation. I am
using Docbook for the design documentation for a major project at the office,
but nobody on this list has been able to explain to me why half the entries in
my index have "-999" as the page number, even when the 'jadetex' script does not
complain about unresolved references.  I've even tried updating everything
from the Docbook-tools site thinking maybe Red Hat had a wonked out
docbook-tools installation.  I even tried using Caldera eDesktop 2.4 rather than
Red Hat, thinking maybe Red Hat had something totally foobar in their setup. No
go. I'm on the verge of abandoning the tool kit in frustration. LyX will now
generate decent HTML output, which was my main reason for using DocBook in the
first place (the difficulty of getting good HTML output out of "latex2html" and
its ilk).  My only issue with LyX is the difficulty of maintaining multi-source
documentation in a CVS depository... CVS won't do merges of multi-author edits
of .lyx files, sigh.  But if it's a choice of LyX or using StarOffal, I know
which I'll choose -- at least LyX is a structured markup tool, whereas
StarOffal.. no, don't get me started. 

> The < http://sourceware.cygnus.com/docbook-tools/ > page directs me to
> < ftp://sourceware.cygnus.com:/pub/docbook-tools >.  That server is
> perpetually swamped.  Going to one of the mirrors, I find a
> docbook-3.1-5.noarch.rpm, but it does not contain any of the db2*
> scripts referenced on the DocBook page.  Where are those scripts?

On Red Hat 6.2 Linux, they're in "stylesheets-1.54.13rh-1.xxx.rpm" (put
architecture of choice in place of 'xxx').  Red Hat ships with what is
basically a slight tweak of the docbook-tools kit. 

'docbook-3.1-5.noarch.rpm' is just the DTD (Data Type Definition), it does not
contain the other software you'll need to convert programs written using that
DTD into a useful form. You'll need 'jade' and 'stylesheets' to do that. 
'jade' is the actual grunt engine, while 'stylesheets' is the Scheme and
scripts that the grunt engine uses to know how to do the conversion. 

export SGML_CATALOG_FILES=/usr/lib/sgml/CATALOG 
export SGML_ROOT=/usr/lib/sgml

are also nice to tell Emacs's psgml mode where to find the overall catalog and
SGML dtd and tools. I use 'xemacs', which puts up a nice SGML menu at the top.

-- 
Eric Lee Green      There is No Conspiracy
eric@badtux.org     http://www.badtux.org