Tools for the HTML manuals

Christopher Browne cbbrowne@hex.net
Fri, 28 Jul 2000 01:24:00 -0500


On Fri, 28 Jul 2000 16:07:36 EST, the world broke into rejoicing as
Robert Graham Merkel <rgmerk@mira.net>  said:
> Christopher Browne writes:
>  > 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.

Good question.

There _are_ well-known tools for transforming DocBook to HTML.

My makefile has:

DSL=mysheet.dsl
	jade -ioutput.html -d $(DSL) -t sgml book.doc

And making that all work out normally requires three packages:
   a) Jade/OpenJade
   b) DocBook DTD
   c) Norm Walsh's Modular Style Sheets
which are all available in RPM and .deb form.

Should we have HTML, or SGML in the source tree? is the question.

- If both, then there is the risk that someone may modify the HTML,
and then watch it get overwritten the next time someone upstream runs
"make," and builds fresh HTML.

- If only SGML, then that forces anyone that gets a CVS archive
to add yet another component to those that they install.

Upside is that the tools are reasonably mature now, unlike, say,
gnome-druid.

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

It's basically got (rather) a few more tags than HTML, and allows
you to do inclusions as well as generating multiple output files.

e.g. - I have a main document file, "book.doc," which includes in
the other 71 files, and then they split off, <sect1> by <sect1>, 
each into a separate HTML output file.

All of that is _standard_ SGML behaviour; no "funny custom
oddball Chris stuff."

I'm liable to generate something complex enough to be worth
looking at closely, but won't be doing anything _bizarrely_
complex.
--
aa454@freenet.carleton.ca - <http://www.ntlug.org/~cbbrowne/lsf.html>
"If all you can see is  vast masses of end-users chewing their cud and
running Win95  on Gateways, then what good  is platform independence?"
-- David LeBlanc (dleblanc@mindspring.com)