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

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

Norman Walsh <ndw@nwalsh.com>:
> / Eric Lee Green <eric@badtux.org> was heard to say:
> | 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.
> 
> <sigh/> I'm sorry you found it to be that way. That wasn't the intent.

I don't think anybody doubts that it was your intention to be clear.
Your execution, however, completely failed in that respect.  The
failure seems to me to be an indicator of a wider problem in the
technical culture surrounding SGML, one I've bitched about before.

I looked forward to your book with the hope that it would dispel the
thick fog surrounding DocBook -- only to be disappointed in pretty
much the same way Eric Lee Green was.  What was missing was (a)
motivation, and (b) any mention of the tools ordinary mortals might
use to format actual documents. 

It's symptomatic that the chapter titled "Publishing DocBook Documents"
-- which one might reasonably expect to answer questions like "How do
I generate HTML or Postscript from a DocBook document?" -- consists
mainly of pages and pages of mind-numbing detail about stylesheet
languages, with not a sample command line or complete example of
production code in it anywhere.

Two years ago, I complained vociferously on the DocBook list that the
SGML culture had a pathological case of self-absorption and seemed to
be chronically unable to address the needs or questions of people who
actually want to get some formatting done without first memorizing
fourteen different sacred tomes of document theology. all filled with
an impenetrable jargon that the priests of the cult seem unwilling or
unable to explain.  For bringing this unwelcome news, I was flamed and
shunned.

Sadly, there seems to have been little or no improvement since.  The
SGML- and DocBook-related pages on the Web are marvels of their kind
-- exhaustively detailed and *completely* unhelpful.  (And remember,
this judgment is coming from someone with a very high tolerance for
complexity and lots of expertise in related technical areas!)  As
a result, SGML-related markup now has all the appeal to me of
chewing on barbed wire.  I wouldn't be messing with it at all if
it weren't a political requirement for one of my projects.

Can this be fixed?  I don't know.  The problem isn't any lack of
intelligence or good intentions on the part of the DocBook group.  
There's something fundamentally disconnected and broken in the
attitude department, though -- an inability to see what the SGML
world looks like from the point of view of somebody who just
wants to get some work done.

Again, a symptom, In the document "A Practical Introduction to DocBook",
the Tools section contains the following blatant cop-out:  

"Unfortunately, installing and configuring DocBook Tools is
(currently) outsidethe scope of this document."

Anyone not already eyebrow-deep in the dysfunctional culture surrounding
this software would realize that this lacuna makes the rest of the 
chapter a bad joke.
-- 
		<a href="http://www.tuxedo.org/~esr">Eric S. Raymond</a>

Alcohol still kills more people every year than all `illegal' drugs put
together, and Prohibition only made it worse.  Oppose the War On Some Drugs!