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

[madhu <b_maddy_016 at yahoo dot com>]

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  . it is also linked from normans website from where
you can download the latest stylesheets for the docbook,
oasis wesite is 
 http://www.oasis-open.org/docbook/
and normans website is 
http://nwalsh.com/~ndw/
  > 
> It's bad enough that the authors of every book and document that exists on SGML
> have invented their own inscrutable terminology for the process of marking up
> documentation... but none of them, zero, zilch, appears to have considered the
> notion of a GLOSSARY, and the very thought of explaining complex terms in a
> simple, clear manner appears to break every single SGML author out in hives. 
> Yes, it's difficult. I've done it before, I know how difficult it is. But it's
> as if the creators of SGML DTD's and tools have a death wish... or else they're
> trying to protect their cult's purity by keeping out the riff-raff (same
> thing). 
> 
> Despite all of the above, I have become reasonably proficient in using the
> Docbook-Tools set and in Docbook itself.  But the tool kits still do not work
> well enough for me to actually use them to produce real documentation. I am
> using Docbook for the design documentation for a major project at the office,
> but nobody on this list has been able to explain to me why half the entries in
> my index have "-999" as the page number, even when the 'jadetex' script does not
> complain about unresolved references.  I've even tried updating everything
> from the Docbook-tools site thinking maybe Red Hat had a wonked out
> docbook-tools installation.  I even tried using Caldera eDesktop 2.4 rather than
> Red Hat, thinking maybe Red Hat had something totally foobar in their setup. No
> go. I'm on the verge of abandoning the tool kit in frustration. LyX will now
> generate decent HTML output, which was my main reason for using DocBook in the
> first place (the difficulty of getting good HTML output out of "latex2html" and
> its ilk).  My only issue with LyX is the difficulty of maintaining multi-source
> documentation in a CVS depository... CVS won't do merges of multi-author edits
> of .lyx files, sigh.  But if it's a choice of LyX or using StarOffal, I know
> which I'll choose -- at least LyX is a structured markup tool, whereas
> StarOffal.. no, don't get me started. 
the problems you are mentioning are mostly to do with SGML tools not with
docbook by itself. if you use the scripts like db2pdf it doesn,t some time run
jadtex thrice for the numbers to be printed right .the db2* scripts are a sort
of primer a starting point so to say but without them you can produce docbook
documents , please refer to the readme's of jade, jadetex etc.and be warned
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 .

additionally i would suggest you subcribe to 

docbook-apps@lists.oasis-open.org, 
and
docbook@lists.oasis-open.org
 lists whree you might get more help than this list since this is of late a very
low traffic list.
and as Mark's excellent tutorial, please don't forget this
 http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html

regards
-- 
maddy
-------------------------------------------------------------------------       
         Fishing baskets are employed to catch fish;
         but when the fish are got, the men forget the baskets;
         Words are employed to convey ideas;
         but when the ideas are grasped, the men forget the words; 
				
					        --"Chuang Tzu"

-------------------------------------------------------------------------