Re: swarm docs: minor problem. PS?

[glen e. p. ropella]

>     FWIW, it's not hard to (gasp!) hand-edit html into latex.  Mostly involves
> taking things out and slapping a wrapper at beginning and end.  (Yes, I've 
> done it.)  Generally, the time-consuming part is overcoming one's aversion
> to doing it.

I know.  Especially since I have some tools like html2latex
and emacs, I can probably get by pretty well.  The real problem
lies in the organization of the manual.  I (personally) don't 
think the web-pages, as presently organized, will make a very
good manual.  They provide all the necessary pieces, I guess.
But, somehow, if I want to learn how something in Swarm works,
I never think to look at the swarmdocs.  I usually go straight
to the code.

This could be just me (I don't read instructions for putting
anything together or installing software or fixing my car,
either!); but, I *do* use language reference manuals, 
dictionaries, howtos, and faq's.  I guess, if had my way, 
we'd make the Swarm manual in the unix man page format....
greppable, to-the-point, ascii, ... heaven!

Anyway, it's the big picture that's keeping me from doing it
(how does one organize a good user's manual?) ... and, I guess,
the lack of time might have something to do with it.  Do you 
(or anybody else) have any strong opinions on user manual 
organization?  For instance, are the O'Reilly styles good?
Do you go for the "XYZ Unleashed" style?  Or the "XYZ for
Dummies" style?  Should it read like prose or like a tutorial?

glen