Re: New manual plan

[Russell McManus <mcmanus@IDT.NET>]

The most important thing for guile right now is that a comprehensive
and definitive manual exists with a logical structure and proper
indexing.  Anything that slows this down is a Bad Thing (tm).

The manual Jim is working on should be comprehensive, so I think it
makes sense for the C and Scheme documentation to be together.  What
would be nice, is if the index allowed the user to find stuff based on
the fact that she needs the 'C' version only, or vice versa.  That
would be almost as good as separate documentation from an organization
/ usability standpoint, and still make things easy for the writer.

Separate documents is a bad idea; we need a comprehensive work.
Special purpose sections/documents (newbie introduction, examples of
script usage, etc.) are less important then the reference manual, and
will come later.  Those who think these are important should start
writing them now, as separate documents.

I submit that it's not productive to talk about the markup format for
the referce manual right now.  Changing to another format creates
overhead that will slow the production of the manual.  

It makes sense for people to experiment with other formats on the
auxillary documents they write, though.

-russ