Re: Doc Tasks (was RE: docstrings in Guile!)

["Greg J. Badros" <gjb at cs dot washington dot edu>]

Greg Harvey <Greg.Harvey@thezone.net> writes:

<snip>

> First and foremost is that the freely available tools for dealing with
> the stuff aren't all that great. Yes, they'll get better, etc... but
> we should be making this decision for now, when we actually plan to
> use this stuff; everything might be super-duper 5 years down the road,
> but by then there'll be a new flavour of the month that everyone will
> be pushing for.
> 
> Second is that you currently can't reliably generate a decent online
> manual (html doesn't count, unless you consider it a reasonable
> requirement to have to run a web server and search engine on your home
> machine to look up a term in the documentation; I don't). I've been
> playing around with the docbook2texi thing; I've been underwhelmed. If
> we have to rely on someone, somewhere maybe doing something in order
> to get useful online documentation, then we're in big trouble.

But if we can convert to TeXInfo from DocBook (and rumour has it that
the tools are there, though I've not had time to try them yet), then
these problems go away and we're able to just use the strictly richer
SGML markup.

> As it stands, our success story is the extracted documentation of
> scwm. If I said I thought it was great, I'd be lying (it's better than
> nothing, granted ;). Apparently, it also takes absurd amounts of time
> and memory to generate html from the sgml (so far it's topped at 92
> megabytes, and it's been running for > 35 minutes; if you need to do
> this on a small machine, you're in very big trouble). 

It's probably faster to convert to TeXInfo then use its tools for now.
The point is, with SGML DocBook we can leverage *both* sets of tools and 
use a richer markup format.

> Yes, I know that `someday, someone can make a whole new layout for
> your documentation without touching the documentation
> itself'. Somehow, the thought that someday, someone might want
> cross-refs highlighted in mauve doesn't fill me with the overwhelming
> urge to learn a whole new (and to my eyes ugly) markup language.
> 
> Plus, the sgml support for emacs isn't nearly as good as the texinfo
> support ;)

That's changing, of course.  This is a question of the present vs. the
future, and DocBook is betting on the future, w/o giving up anything in
the present (given DocBook->TexInfo translators).

Greg