From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: Norman Walsh Cc: Eric Lee Green , "Eric S. Raymond" , 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: <20000706131959.A25726@thyrsus.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> X-SW-Source: 2000/msg00224.html Norman Walsh : > / Eric Lee Green was heard to say: > | That puzzles me too. Even Norm Walsh's so-called "Docbook" book > | reads as if it were a briefly written summary written in a foreign > | language to be as terse as possible. > > I'm sorry you found it to be that way. That wasn't the intent. I don't think anybody doubts that it was your intention to be clear. Your execution, however, completely failed in that respect. The failure seems to me to be an indicator of a wider problem in the technical culture surrounding SGML, one I've bitched about before. I looked forward to your book with the hope that it would dispel the thick fog surrounding DocBook -- only to be disappointed in pretty much the same way Eric Lee Green was. What was missing was (a) motivation, and (b) any mention of the tools ordinary mortals might use to format actual documents. It's symptomatic that the chapter titled "Publishing DocBook Documents" -- which one might reasonably expect to answer questions like "How do I generate HTML or Postscript from a DocBook document?" -- consists mainly of pages and pages of mind-numbing detail about stylesheet languages, with not a sample command line or complete example of production code in it anywhere. Two years ago, I complained vociferously on the DocBook list that the SGML culture had a pathological case of self-absorption and seemed to be chronically unable to address the needs or questions of people who actually want to get some formatting done without first memorizing fourteen different sacred tomes of document theology. all filled with an impenetrable jargon that the priests of the cult seem unwilling or unable to explain. For bringing this unwelcome news, I was flamed and shunned. Sadly, there seems to have been little or no improvement since. The SGML- and DocBook-related pages on the Web are marvels of their kind -- exhaustively detailed and *completely* unhelpful. (And remember, this judgment is coming from someone with a very high tolerance for complexity and lots of expertise in related technical areas!) As a result, SGML-related markup now has all the appeal to me of chewing on barbed wire. I wouldn't be messing with it at all if it weren't a political requirement for one of my projects. Can this be fixed? I don't know. The problem isn't any lack of intelligence or good intentions on the part of the DocBook group. There's something fundamentally disconnected and broken in the attitude department, though -- an inability to see what the SGML world looks like from the point of view of somebody who just wants to get some work done. Again, a symptom, In the document "A Practical Introduction to DocBook", the Tools section contains the following blatant cop-out: "Unfortunately, installing and configuring DocBook Tools is (currently) outsidethe scope of this document." Anyone not already eyebrow-deep in the dysfunctional culture surrounding this software would realize that this lacuna makes the rest of the chapter a bad joke. -- Eric S. Raymond Alcohol still kills more people every year than all `illegal' drugs put together, and Prohibition only made it worse. Oppose the War On Some Drugs!