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

[Gregory Leblanc <GLeblanc at cu-portland dot edu>]

> -----Original Message-----
> From: Norman Walsh [mailto:ndw@nwalsh.com]
> Sent: Friday, July 07, 2000 2:43 PM
> To: docbook-tools-discuss@sourceware.cygnus.com
> Subject: Re: I'm trying to set up docbook-tools...
> 
> / "Eric S. Raymond" <esr@thyrsus.com> was heard to say:
> | 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.
> 
> Moments after sending this message, I regretted making the assertion
> that it wasn't jargon-filled. That's nonsense and I knew better.  (I
> really don't think it's theological, but if you do, I won't argue the
> point any further.)
> 
> There's a definite tension when it comes to vocabulary and it bites
> very deeply in SGML, possibly because I'm familiar with it, although
> my intuition is that it bites deeply in SGML in part because it's
> worse in SGML than in many other jargons. 8879 was written by a lawyer
> after all :-)
> 
> As I expressed earlier, perhaps badly: using the precise 8879
> terminology (which I don't claim to have done, in the interest of
> trying to fight this exact problem, even if you think I failed) is a
> way of describing things in a precise, technically unabiguous way.
> Alas, it comes at the expense of the poor reader who could care less
> about the distinction between a "tag" and a "generic identifier".  The
> trouble is that using loose, informal terms eventually leads to
> confusion in those areas where it really makes a difference.
> 
> Maybe I got the balance wrong. I could have done better.

I have to say that I've been reading this thread with a fair bit of
interest, since there are some huge holes in documentation for actually
doing useful things with DocBook.  As for this jargon thing, I don't think
that there is ANY hope of being able to usefully write a Definitive Guide on
DocBook without a lot of fairly specific jargon.  The terminology allows
things to be described much better than simply using proper English, or even
vernacular for the author and readers.  The problem here, I think, is that
it's bloody hard to figure out which words mean what without working with it
for a good while.  I've finally figured out what DSSSL is, and where all of
the pieces fit together, but it's NOT easy to do, and I don't think I'm an
idiot (which may or may not be relevant).  DocBook: TDG is NOT a gentle
introduction to DocBook, or to writing using DocBook.  It's a reference
guide, and as such, must use terminology suitable for people using a
reference guide.  I don't recall finding a good glossary of SGML terms, or a
good flow-chart (doesn't anybody use them for anything anymore?) of how
publishing a DocBook document work anywhere that I looked.  These two things
together would probably help clarify a lot of things for people getting
started with DocBook publishing.

> | 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?

I have to say that while it may be obvious to you, it is NOT to some other
people.  I happen to find the flow of most chemical equations totally
intuitive, whereas Norm probably finds the flow of taking a DocBook document
and turning it into HTML totally intuitive.  You happen to have a different
point of view, and are able to see things that we may miss.  Isn't that why
open sores works?  Different viewpoints helping each other out, making for a
better end product.
	Grego