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

["Eric S. Raymond" <esr at thyrsus dot com>]

David C. Mason <dcm@redhat.com>:
> Then I still don't understand the problems you are having... or at
> least, I still haven't seen a detail of what you would like to see.

I'd like to see documentation that spends less time genuflecting
before the wonderfulness of semantic markup and stylesheets, and more
time telling me how I can install and configure working tools and make
HTML and Postscript from actual documents.

Let's start with replacing that cop-out in the so-called "Practical
Introduction".  It's inexcusable, absurd, perverse, that a so-called
"Practical Guide" doesn't tell you (a) where to find installable
versions of the tools it's describing, and (b) how to set them up
so you can do the examples in the guide.

Let's continue with the fact that in the entire 635 pages of "DocBook:
The Definitive Guide", I found *not one* example of a command line that
could be used to produce actual, viewable HTML or Postscript from an
actual document.

Is it just me?  Am I crazy to think there's something wrong with a 600-page
tome on document production tools that *never once tells you how to 
format a document?*

The unbelievable part is that it's *all* like that.  It's not just the
individual authors of these particular documents that are high priests
of the Cult of Obscurity -- every piece of documentation I've ever
seen from the DocBook/SGML community is pretty much off in theoretical
cloud-cuckoo land.  I can learn more than I ever wanted to know about
DSSL and FOSI and fifty other acronyms, but I can't find any clue about
what to do when jadetex generates bad Postscript that makes gs choke.

What I want to see is a practical guide that is truly a practical guide --
something like what I wrote for SGML-tools, but covering DocBook.

> I had no idea you did the first SGML-Tools and I apologize, you are a
> single entity in that case. Otherwise, I find that most hackers ignore
> these tools altogether. My apologies.

Don't get an exaggerrated idea of my creds, either.  I didn't write
SGML-tools, nor was I ever its official maintainer.  I did one really
serious burst of work on it around 0.99-1.0 -- basically so I could pull
Red Hat's nuts out of the fire after Bob Young asked me nicely to
fix the godawful mess their old TeX-centric production process had
degenerated into.  And I did write the User's Guide.  But I had
very little to do with the design of the tool.
-- 
		<a href="http://www.tuxedo.org/~esr">Eric S. Raymond</a>

Idealism is the noble toga that political gentlemen drape over their
will to power.
	-- Aldous Huxley