From mboxrd@z Thu Jan 1 00:00:00 1970 From: Gregory Leblanc To: 'Norman Walsh' , docbook-tools-discuss@sourceware.cygnus.com Subject: RE: I'm trying to set up docbook-tools... Date: Wed, 27 Dec 2000 06:36:00 -0000 Message-id: X-SW-Source: 2000/msg00267.html > -----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" was heard to say: > | Norman Walsh : > | > 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