From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Edward C. Bailey" To: 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: 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> X-SW-Source: 2000/msg00239.html >>>>> "esr" == Eric S Raymond writes: esr> David C. Mason : >> Then I still don't understand the problems you are having... or at >> least, I still haven't seen a detail of what you would like to see. esr> I'd like to see documentation that spends less time genuflecting esr> before the wonderfulness of semantic markup and stylesheets, and more esr> time telling me how I can install and configure working tools and make esr> HTML and Postscript from actual documents. I wonder if SGML documentation's current focus on the theoretical versus the practical is an evolutionary backwater from the days when people using the technology had to explain why they were "doing things the 'hard' way with SGML" when most people doing documentation were simply using whatever tools they happened to have available. Even if this was the case at one point in time, I think we all agree that most people "get it" when it comes to markup languages (if for no other reason than all the hype XML has brought to our part of the world). So it's time to move on, and leave the Cult of the Sacred Tag mentality behind us now... :-) ... 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. The book is a reference describing a particular markup language. That markup language is processed by a wide variety of software (both open source and non-) on a wide variety of platforms (again, both open source and non-). 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. :-) That's not to say that there *shouldn't* be a book that does just what you describe. I strongly agree with you that this kind of information should be in a book somewhere. I just don't think _DocBook: TDG_ is that book. esr> The unbelievable part is that it's *all* like that. It's not just the esr> individual authors of these particular documents that are high priests esr> of the Cult of Obscurity -- every piece of documentation I've ever esr> seen from the DocBook/SGML community is pretty much off in theoretical esr> cloud-cuckoo land. I can learn more than I ever wanted to know about esr> DSSL and FOSI and fifty other acronyms, but I can't find any clue esr> about what to do when jadetex generates bad Postscript that makes gs esr> choke. esr> What I want to see is a practical guide that is truly a practical esr> guide -- something like what I wrote for SGML-tools, but covering esr> DocBook. I feel compelled to preface my comments by saying that my goal is neither to cut anyone down, nor to build myself up. But I have a bit of background here that leads me to the following observations: 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. o Since ESR has worked with me, he knows I'm not the sharpest knife in the kitchen (and hopefully feels that I'm at least not the dullest, either :-). Yet he's confounded trying to format DocBook documents, while I've been able to convert over 1500 pages of LaTeX-based documentation into DocBook, and to create the tools necessary to support a production environment to produce DocBook-based content here at Red Hat. What's the difference? Time. It was my full-time job to make the move to DocBook, while ESR is probably lucky if he can devote an hour here and there to the task. 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. And as I'm sure ESR can vouch, being treated like a clueless newbie, on the outside looking in, sucks. esr> Don't get an exaggerrated idea of my creds, either. I didn't write esr> SGML-tools, nor was I ever its official maintainer. I did one really esr> serious burst of work on it around 0.99-1.0 -- basically so I could esr> pull Red Hat's nuts out of the fire after Bob Young asked me nicely to esr> fix the godawful mess their old TeX-centric production process had esr> degenerated into. Point of clarification -- ESR helped us replace a contractor (with a largely manual and TeX-centric production process) that seemed to be unable to deliver the goods when promised. That said, the end result still was the extraction of said gonads from the conflagration -- and in a most elegant fashion... :-) Ed -- Ed Bailey Red Hat, Inc. http://www.redhat.com/ From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Edward C. Bailey" To: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Thu, 06 Jul 2000 16:05:00 -0000 Message-ID: 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> X-SW-Source: 2000-q3/msg00037.html Message-ID: <20000706160500.2y1SvFtyqkX4Gb0vBm0cYvnw3-rfgD1wHzLqd36R3T4@z> >>>>> "esr" == Eric S Raymond writes: esr> David C. Mason : >> Then I still don't understand the problems you are having... or at >> least, I still haven't seen a detail of what you would like to see. esr> I'd like to see documentation that spends less time genuflecting esr> before the wonderfulness of semantic markup and stylesheets, and more esr> time telling me how I can install and configure working tools and make esr> HTML and Postscript from actual documents. I wonder if SGML documentation's current focus on the theoretical versus the practical is an evolutionary backwater from the days when people using the technology had to explain why they were "doing things the 'hard' way with SGML" when most people doing documentation were simply using whatever tools they happened to have available. Even if this was the case at one point in time, I think we all agree that most people "get it" when it comes to markup languages (if for no other reason than all the hype XML has brought to our part of the world). So it's time to move on, and leave the Cult of the Sacred Tag mentality behind us now... :-) ... 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. The book is a reference describing a particular markup language. That markup language is processed by a wide variety of software (both open source and non-) on a wide variety of platforms (again, both open source and non-). 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. :-) That's not to say that there *shouldn't* be a book that does just what you describe. I strongly agree with you that this kind of information should be in a book somewhere. I just don't think _DocBook: TDG_ is that book. esr> The unbelievable part is that it's *all* like that. It's not just the esr> individual authors of these particular documents that are high priests esr> of the Cult of Obscurity -- every piece of documentation I've ever esr> seen from the DocBook/SGML community is pretty much off in theoretical esr> cloud-cuckoo land. I can learn more than I ever wanted to know about esr> DSSL and FOSI and fifty other acronyms, but I can't find any clue esr> about what to do when jadetex generates bad Postscript that makes gs esr> choke. esr> What I want to see is a practical guide that is truly a practical esr> guide -- something like what I wrote for SGML-tools, but covering esr> DocBook. I feel compelled to preface my comments by saying that my goal is neither to cut anyone down, nor to build myself up. But I have a bit of background here that leads me to the following observations: 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. o Since ESR has worked with me, he knows I'm not the sharpest knife in the kitchen (and hopefully feels that I'm at least not the dullest, either :-). Yet he's confounded trying to format DocBook documents, while I've been able to convert over 1500 pages of LaTeX-based documentation into DocBook, and to create the tools necessary to support a production environment to produce DocBook-based content here at Red Hat. What's the difference? Time. It was my full-time job to make the move to DocBook, while ESR is probably lucky if he can devote an hour here and there to the task. 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. And as I'm sure ESR can vouch, being treated like a clueless newbie, on the outside looking in, sucks. esr> Don't get an exaggerrated idea of my creds, either. I didn't write esr> SGML-tools, nor was I ever its official maintainer. I did one really esr> serious burst of work on it around 0.99-1.0 -- basically so I could esr> pull Red Hat's nuts out of the fire after Bob Young asked me nicely to esr> fix the godawful mess their old TeX-centric production process had esr> degenerated into. Point of clarification -- ESR helped us replace a contractor (with a largely manual and TeX-centric production process) that seemed to be unable to deliver the goods when promised. That said, the end result still was the extraction of said gonads from the conflagration -- and in a most elegant fashion... :-) Ed -- Ed Bailey Red Hat, Inc. http://www.redhat.com/