Re: I'm trying to set up docbook-tools...

[Eric Lee Green <eric@badtux.org>]

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