From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Fri, 07 Jul 2000 07:49:00 -0000 Message-ID: <87wviym26y.fsf@nwalsh.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> <20000706180129.C26696@thyrsus.com> <20000706195444.D27191@thyrsus.com> X-SW-Source: 2000-q3/msg00047.html Message-ID: <20000707074900.pneEyHOkTe4cX4DsbN1tZMjxVkRiJD-43rbq4Cawzf0@z> / "Eric S. Raymond" was heard to say: With respect to this comment, | 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! And bearing in mind something you said earlier, | You [...] can | start being offended the day I don't respect you enough to criticize | your work. I feel compelled to reply: First, you're mistaken. As the reader of your comments, I'm free to become offended whenever I bloody well choose. 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. 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." I haven't heard a single person disagree with you. And in the two years since you first encountered DocBook, tremendous progress has been made. I'm committed to seeing that, to the extent I can contribute, the progress continues until it's as nearly dead easy as possible. Now would you please stop flogging me for not moving fast enough. I ain't your whipping boy, son. | 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. | 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. For the record, my thought process went something like this. "Today (when I was writing) things are still pretty immature. I could try to document one of the many possible tool sets, but then I'd be leaving out all the others, not to mention the commercial tools from Arbortext, Frame, and Softquad to name but three. And there's no tool set that works equally well on Unix and NT, so I'd have to do at least two. Things will be better soon and the installation instructions for the individual tool sets can do a better job on installation than I can. Heck, I don't even have a Linux box at hand these days. The vast majority of questions that I get aren't about specific tools, people seem to get those installed, they're about how to customize X, Y, or Z in the stylesheets. Since the DSSSL stylesheets form the core of several tool sets, end users would be better served by some explanation of how to use and customize those." | (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. | > 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... Cubed, even. Be seeing you, norm -- Norman Walsh | Whatever you may be sure of, be sure of http://nwalsh.com/ | this: that you are dreadfully like | other people.--James Russell Lowell