From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Lee Green To: madhu Cc: "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: <00070422425701.09328@ehome.inhouse> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <00070510365404.00678@needaguru> X-SW-Source: 2000/msg00214.html On Tue, 04 Jul 2000, madhu wrote: > On Tue, 04 Jul 2000, you wrote: > > On Tue, 04 Jul 2000, Eric S. Raymond wrote: > > > I'm trying to set up docbook-tools, and finding it a hideously > > > frustrating experience. Why does all the SGML software and > > > documentation in the world read as though it was carefully designed > > > to prevent any actual document production from getting done? > > > > 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. You would suspect that the authors of documentation tools would > > themselves be enamored of documentation. WIth the exception of Donald Knuth, > > that, alas, does not appear to be the case. > an html.zip file exists on the officail docbook site oasis with enough details > for anybody to start with Are you talking about Paul Prescod's tutorial? That was one of the things that got me going. Right now the manual I'm working on is >200 pages and still growing, so obviously I figured out how to get things going, but I'm still puzzled by the lack of understandable documentation. Donald Knuth's stuff about TeX is not exactly the world's most accessible documentation either, but it is complete, it is clear and unambiguous (except where he deliberately simplifies things for the heathen :-), and it clearly documents all parts of the system. Unfortunately, the SGML purists appear to believe that their job is done once they've created the raw DTD... "just read the DTD!" appears to be the notion. > the problems you are mentioning are mostly to do with SGML tools not with > docbook by itself. Correct. I've already discussed the notion that SGML purists appear to believe that their job is done once they've created the raw DTD and (optionally) style sheet. This attitude is what has prevented SGML from supplanting TeX/LaTeX for structured document creation. As I mentioned earlier, as soon as I'm finished with the current document, I'm falling back to LyX and TeX/LaTeX. > If you use the scripts like db2pdf it doesn,t some time run > jadtex thrice for the numbers to be printed right . I have taken to running jadetex by hand until the 'unresolved reference' messages go away, then running dvi2ps by hand. Some of my page references STILL turn out to be -999. > that situation is not likely to improve what with SGML is dead proclamations > doing the rounds and shift is towards XML . but again tools for XML are not unix > favorable at all . I have come to that conclusion. A pity. Especially since Microsoft seems bound and detirmined to subvert XML into a Microsoft-only standard if in any way possible. Still, TeX and LaTeX still exist. They are thoroughly documented. They run the same way everywhere. They look ghe same everywhere. So while they are not the be-all and end-all of structured document design, they'll have to do, since the SGML crowd has committed collective suicide. A pity, that. -- Eric Lee Green There is No Conspiracy eric@badtux.org http://www.badtux.org