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

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

Norman Walsh <ndw@nwalsh.com>:
> Second, I'm tired of your whining about the theology and jargon. I'm
> sorry if TDG didn't answer your questions, I'll try to do better next
> time (although I still think it's an authors prerogative to decide
> what is and what is not in scope), but I don't think it's either
> theological or jargon-filled.

In this respect (if not in others), you and the other core DocBook
people who share this belief are still out to lunch.  And that's sad,
because it seriously hinders the deployment of your good work.
 
> It seems to me that the bulk of your ranting boils down to:
> 
> "The tools one needs to format a DocBook document and get HTML or
> print output are insufficiently documented and too hard to install and
> use."

Nope, see above.  The fact that SGML initiates can't see how
impenetrable their sacred texts are is a larger problem than the lack
of documentation for specific tools -- because it means that said
documentation is unlikely to get written or reviewed by exactly those
who ought to be best qualified to do it.

Instead, hapless schlubs like me end up jerry-rigging together 
things like the SGML-Tools user's guide...and feeling very ill-served 
by an SGML community that seems unwilling to climb down from their
heights of abstraction.

> Now would you please stop flogging me for not moving fast enough.  I
> ain't your whipping boy, son.

"Floggings will continue until morale improves." :-) No, in fact, I'm
not flogging you for moving too slowly.  I'm flogging you for an
apparent inability to understand "motion" at all.  I'll stop when you
either clue in or my arm gets tired.

If we're both committed to excellence of results, it *is* my job to do
that, and your job to cope with it.  Welcome to the sharp end of peer
review, daddy-o.

> | Really.  What would it have cost to supply *one* explicit example of 
> | a document-production flow on Unix and Windows?  A few pages could have
> | made a huge difference -- in helpful symbolism, even if it couldn't
> | cover all the substance.
> 
> Now that's an interesting question. You might be right.

And this is a perfect example of not understanding motion.  You are,
by all accounts, an intelligent and well-intentioned person with a
considerable capacity for both creativity and hard work.  You are also
a pretty good writer -- there is nothing wrong with DTG's prose at the
microlevel.

So why didn't *you* figure one out this out two years ago?  Why does 
it take an outsider, jumping up and down and screaming, to point out
the obvious?

If and when you achieve enlightenment on this koan, I think the root
problem of the SGML culture will also be clear to you.

(I deeply regret that I wasn't on DTG's pre-pub review list...)
 
> | (All right, everybody.  Calm down -- I'm not claiming that was his actual
> | state of mind, simply that that is the message the book sends.)
> 
> And the message you send is...oh, nevermind.

Uh huh.  "The meaning of a communication is not what is sent, but what
is received."  If you really understood that and had acted on it, DTG 
would have been a better book.

This is not academic criticism, nor is it consigning DTG to the trash heap.
I've written two pretty successful books (one technical, one mass-market)
and substantial portions of three others.  I do a lot of technical review
work.  DTG's strengths and its weaknesses are both characteristic of books
written by experts with both an unsurpassed grasp of their technical domain
and a near-complete inability to view that domain from outside.
-- 
		<a href="http://www.tuxedo.org/~esr">Eric S. Raymond</a>

"They that can give up essential liberty to obtain a little temporary 
safety deserve neither liberty nor safety."
	-- Benjamin Franklin, Historical Review of Pennsylvania, 1759.