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

[Greg Harvey <Greg dot Harvey at thezone dot net>]

"Greg J. Badros" <gjb@cs.washington.edu> writes:

> "Dale P. Smith" <dpsm@bigbird.en.com> writes:
> 
> > 
> > When scwm went with a sgml style markup, I wanted to say something, but since
> > I am basically incoherent I didn't.  I don't want to make the same mistake.
> > 
> > Please use texinfo.  Besides the above arguments, it just looks nicer.  There
> > is good support for it in emacs.  I believe it has grown over time, features
> > being added as they were needed.
> 
> We can argue over looks and style all day so I won't.
> 
> There's good support for SGML in Emacs, too.  And docbook has grown over
> time, as well.  The primary advantages of DocBook are that it provides
> far richer markup and is supported much more widely by tools and the
> industry.

How rich a markup do you really need, though, for generating the
reference manual? Ignoring the industry bit (the `industry' goes
apeshit for anything `new and innovative'), what really useful tools
are we talking about? Not the required tools to translate the bloody
stuff into something useful, mind, but tools that provide a very
useful service. Because there are drawbacks to using docbook.

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.

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

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 ;)

-- 
Greg