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

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

Edward C. Bailey <ed@redhat.com>:
>                               So it's time to move on, and leave the
> Cult of the Sacred Tag mentality behind us now... :-)

Indeed.  And an important point: I wouldn't be so exercised about the
Cult of the Sacred Tag if, on some level, I didn't grok that the SGML
people have some reason behind the religion.  If it was all just just
bullshit, I could ignore it and go away.  As it is, the fact that the
power of these techniques is surrounded by a near-impenetrable thicket
of theology and jargon is deeply frustrating to me -- and the apparent
inability of SGML people to see that this is an issue is maddening!

> esr> Is it just me?  Am I crazy to think there's something wrong with a
> esr> 600-page tome on document production tools that *never once tells you
> esr> how to format a document?*
> 
> To be honest, and at least in the case of _DocBook: The Definitive Guide_,
> I think it's just you. [...]  To have this particular reference guide get
> into how the markup language is processed by one particular application on
> a subset of the possible platforms would be something similar to HP
> including a chapter called "Using Your New Printer to Print Romance Novels"
> in every LaserJet owner's manual. :-)

No, I'd say it's more like supplying schematics and chip masks for the 
printer's electronics and neglecting to document the front-panel controls.

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.

As it is, one is left with the impression that Mr. Walsh was so caught
up in the arcana of Scheme and CSS and DTD composition that he couldn't be 
bothered to descend to the level of actually showing the reader how to
actually use any of it.

(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.)

>     o If you were to change a few of the terms in ESR's comments, you'd
>       have almost exactly the same kinds of feedback we at Red Hat get from
>       users regarding the state of Linux documentation today.  So those of
>       us that do documentation for one or more open source software
>       projects should keep in mind that we ain't done yet -- not by a long
>       shot.  This complaint is true for DocBook documentation, and it's
>       true for many (most? all?) open source software projects.

Yup.  That's why I maintain, at last count, eight (8) different technical
FAQ documents.  
 
>                                                The important point
>       here is that we need to get away from the mentality that
>       introductory/tutorial texts are for clueless newbies, that hard-core
>       reference material is the only truly important documentation.  The
>       introductory stuff makes the technology accessible to people that
>       would otherwise not have access.

Amen.  Squared...
-- 
		<a href="http://www.tuxedo.org/~esr">Eric S. Raymond</a>

"Rightful liberty is unobstructed action, according to our will, within limits
drawn around us by the equal rights of others."
	-- Thomas Jefferson