From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Lee Green To: Mark Galassi , 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: <00070613480700.15291@ehome.inhouse> References: <200007041511.LAA15779@snark.thyrsus.com> <14692.50781.521325.126382@cmpu.net> <768zvf9mdh.fsf@odie.lanl.gov> X-SW-Source: 2000/msg00231.html On Thu, 06 Jul 2000, Mark Galassi wrote: > Kendall> As for actually setting up and installing the various > Kendall> permutations of the free tool chain, I just don't see why > Kendall> it's *so* hard for someone with a bit of technical > Kendall> ability or experience. > It isn't. The person who started this thread said there was no > tutorial which includes setting up the tools, but there actually was. > Although things are out of date, this whole thread is mostly > unnecessary. Futile, perhaps. Unnecessary, no. I am constantly fighting The Cult Of Obscurity both on the job and off it, because so many good technical people just don't see what's wrong with their documentation and programming. "It makes sense to me, other people must just be stupid" is the attitude of the typical adherent of the Cult of Obscurity. I sometimes have to fuss at my own co-workers about "Look, I don't care about details x, y, and z, I, the hypothetical the end user, just want to get job 'n' done", and I'm certainly not going to be reticient about doing the same elsewhere, even if I'm not being paid to do it elsewhere :-). People do not care about elegance. They do not care about how terse and formal the language is surrounding a topic. They just want to get a job done with as few keystrokes or mouse clicks as possible, and learning as few details as possible to do it. This is one place where Lamport's LaTeX book shines (despite how aweful it is otherwise), the first thing he does is say, "Here is how you write a letter in LaTeX." What genius! Regarding Norm Walsh's book: the biggest problem was a lack of examples of how to use DocBook to create entire documents. There's reasonably good examples of the use of many of the individual elements, but nothing like where Lamport says, "Here is how you create a document. Here is how you create a letter. Here is how to create a document that has a table in it." Lamport's LaTeX book sucks... but it sucks in a way that lets most people write simple documents after reading it. Note that I'm not calling the SGML crowd stupid. I'm not saying that their documentation "sucks" for people who are already initiated into the Cult Of SGML. What I'm saying is that a) there's a paucity of documentation about how to Get The Job Done, the only one I know about is the FreeBSD one, and b) there has been a lack of attention to Getting The Job Done on the part of the SGML community as a whole, they have been absorbed in the technical excellence of SGML, the theoretical possibilities of parsing SGML, the stylistic elegance of DSSL and stylesheet languages, whilst ignoring the whole point of the exercise. I realize this is not an attitude that is restricted to the SGML crowd. This sort of attitude is rampant in the computer biz, those of us who have a good understanding of end user wants and needs are always the minority, and those of us with both technical skills and writing skills are even rarer. But, as the other Eric mentioned, this sort of attitude is also what kept SGML from sweeping the world over the last five years, and is what basically has killed SGML (with the exception of the HTML DTD and XML subset, the former of which isn't really SGML anymore). 'Nuff said. I'm sure I'll find many more flames in my mailbox from adherents of the Highly Theoretical Cult of SGML Gurus. But (shrug), when it comes to document production, I'm an end user. I design tape backup and related software for a living, not documentation tools. All I want to do is to get a job done. I don't CARE about how elegant DSSL is, or how flexible the Docbook DTD is... it's a tool, for cryin' out loud, not a religion. And if it doesn't Do The Job, I'll dump it and use some other tool. Which, apparently, has been the conclusion of most others who would use SGML, too, with the exception of a few of the Open Source projects which use it because that's what the LinuxDoc project uses. -- Eric Lee Green There is No Conspiracy eric@badtux.org http://www.badtux.org From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Lee Green To: Mark Galassi , docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Thu, 06 Jul 2000 13:38:00 -0000 Message-ID: <00070613480700.15291@ehome.inhouse> References: <200007041511.LAA15779@snark.thyrsus.com> <14692.50781.521325.126382@cmpu.net> <768zvf9mdh.fsf@odie.lanl.gov> X-SW-Source: 2000-q3/msg00029.html Message-ID: <20000706133800.lOhiTb3rtnscQlezT979G7arOHEmCv0VMOknv_Nn57Q@z> On Thu, 06 Jul 2000, Mark Galassi wrote: > Kendall> As for actually setting up and installing the various > Kendall> permutations of the free tool chain, I just don't see why > Kendall> it's *so* hard for someone with a bit of technical > Kendall> ability or experience. > It isn't. The person who started this thread said there was no > tutorial which includes setting up the tools, but there actually was. > Although things are out of date, this whole thread is mostly > unnecessary. Futile, perhaps. Unnecessary, no. I am constantly fighting The Cult Of Obscurity both on the job and off it, because so many good technical people just don't see what's wrong with their documentation and programming. "It makes sense to me, other people must just be stupid" is the attitude of the typical adherent of the Cult of Obscurity. I sometimes have to fuss at my own co-workers about "Look, I don't care about details x, y, and z, I, the hypothetical the end user, just want to get job 'n' done", and I'm certainly not going to be reticient about doing the same elsewhere, even if I'm not being paid to do it elsewhere :-). People do not care about elegance. They do not care about how terse and formal the language is surrounding a topic. They just want to get a job done with as few keystrokes or mouse clicks as possible, and learning as few details as possible to do it. This is one place where Lamport's LaTeX book shines (despite how aweful it is otherwise), the first thing he does is say, "Here is how you write a letter in LaTeX." What genius! Regarding Norm Walsh's book: the biggest problem was a lack of examples of how to use DocBook to create entire documents. There's reasonably good examples of the use of many of the individual elements, but nothing like where Lamport says, "Here is how you create a document. Here is how you create a letter. Here is how to create a document that has a table in it." Lamport's LaTeX book sucks... but it sucks in a way that lets most people write simple documents after reading it. Note that I'm not calling the SGML crowd stupid. I'm not saying that their documentation "sucks" for people who are already initiated into the Cult Of SGML. What I'm saying is that a) there's a paucity of documentation about how to Get The Job Done, the only one I know about is the FreeBSD one, and b) there has been a lack of attention to Getting The Job Done on the part of the SGML community as a whole, they have been absorbed in the technical excellence of SGML, the theoretical possibilities of parsing SGML, the stylistic elegance of DSSL and stylesheet languages, whilst ignoring the whole point of the exercise. I realize this is not an attitude that is restricted to the SGML crowd. This sort of attitude is rampant in the computer biz, those of us who have a good understanding of end user wants and needs are always the minority, and those of us with both technical skills and writing skills are even rarer. But, as the other Eric mentioned, this sort of attitude is also what kept SGML from sweeping the world over the last five years, and is what basically has killed SGML (with the exception of the HTML DTD and XML subset, the former of which isn't really SGML anymore). 'Nuff said. I'm sure I'll find many more flames in my mailbox from adherents of the Highly Theoretical Cult of SGML Gurus. But (shrug), when it comes to document production, I'm an end user. I design tape backup and related software for a living, not documentation tools. All I want to do is to get a job done. I don't CARE about how elegant DSSL is, or how flexible the Docbook DTD is... it's a tool, for cryin' out loud, not a religion. And if it doesn't Do The Job, I'll dump it and use some other tool. Which, apparently, has been the conclusion of most others who would use SGML, too, with the exception of a few of the Open Source projects which use it because that's what the LinuxDoc project uses. -- Eric Lee Green There is No Conspiracy eric@badtux.org http://www.badtux.org