Tools for the HTML manuals

Christopher Browne cbbrowne@hex.net
Thu, 27 Jul 2000 23:21:25 -0500


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.

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 :-).  

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.
--
aa454@freenet.carleton.ca - <http://www.hex.net/~cbbrowne/linux.html>
Rules of the Evil Overlord #66. "My security keypad will actually be a
fingerprint scanner. Anyone who watches someone press a sequence of
buttons or dusts the pad for fingerprints then subsequently tries to
enter by repeating that sequence will trigger the alarm system."
<http://www.eviloverlord.com/>