Tools for the HTML manuals

[Robert Graham Merkel]

Christopher Browne writes:
 > On Fri, 28 Jul 2000 13:49:56 EST, the world broke into rejoicing as
 > Robert Graham Merkel <rgmerk@mira.net>  said:
 > > Niklaus Giger writes:
 > >  > Hello,
 > >  > 
 > >  > I am starting the translation of the GnuCash HTML-manuals into german.
 > >  > 
 > >  > Do I just have to copy the doc/html/c/*.html files into a new doc/html/de 
 > >  > directory?
 > >  > 
 > >  > Or do you use any tools (docbook, SGML, XML)?
 > >
 > > No, not at the moment - it's just raw HTML.
 > > 
 > > However, now is a *very* good time to raise this issue - we probably
 > > should move to something that produces a printed manual properly, and
 > > I suspect docbook might be an appropriate choice.
 > > 
 > > Guys, what do you think?
 > 
 > I'm probably the "canonical source" of information on how to do this; not
 > long ago, I got a note from the DocBook mailing list asking permission
 > to use a DSSSL script I wrote to transform HTML into (admittedly not
 > completely complete, but you can't expect that...) DocBook SGML.
 > 
 > The point being that the transformation can be _somewhat_ automated.
 > 
I'll admit to being quite impressed here . . .

 > The other point is that I'd be inclined to do this, as it can improve the
 > degree to which the docs are linked together, as well as improving the
 > "look and feel," as well as providing the ability to take the whole thing
 > and fairly readily make it into cross-referenced printed documentation.
 > (Which will doubtless be much appreciated when it comes time to produce a
 > "boxed set."  My royalty rate is reasonable :-).  
 > 
Very true.

 > Note that I use such techniques to maintain, with _perfect_ accuracy,
 > about 2922 links on my web site, as well as using 72 DocBook
 > files to produce 375 web pages.
 > % grep -i linkend ~/public_html/*.doc | wc -l
 >    2922
 > % ls ~/public_html/*.doc | wc -l
 >      72
 > % ls ~/public_html/*.html | wc -l
 >     375
 > 
 > Such techniques should cope reasonably well with the GnuCash docs :-).
 > [Hmm...  2922/375... averaging 7.79 links per page...  That's _fairly_
 > tightly linked...]
 > 
 > At some point, I should "steal" access to at least the English
 > documentation tree, and turn it into a set of DocBook material.
 > It'll probably take a couple of days, and that won't be _this_ week.
 > --

One question here - if the gnucash source tree stores the
documentation in DocBook format, what tools will we require to turn it
into HTML?  Is it the same set of tools that the other gnome apps use?
I'm wary of introducing another obscure build dependancy here.

Other than that, this sounds like an excellent idea, and if you want
me to do any/all of the work (particularly the grunt work), mail me.
I don't know much about DocBook yet, but I'm going to have to learn
anyway, so now is as good a time as any...

------------------------------------------------------------
Robert Merkel	                           rgmerk@mira.net

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