New manual plan

[Jim Blandy <jimb@red-bean.com>]

Here's an outline of what I want from the Guile manual.  Of course,
I'm responsible for getting it written; I'm just posting it for
information and comments.


For starters, the Guile manual should be a complete manual for a
programmer wanting to use Guile.  That is, it should be both a
reference work, and something that helps people new to Guile quickly
find their way around.

It should assume that the reader understands C and Unix, but not
Scheme.  Thus, it will include tutorials that cover Scheme itself.
This tutorial needs to reflect Guile's orientation towards system
programming and scripting; we shouldn't be shy to show off Guile's
system support.

The manual will not be generated from docstrings.  I've seen several
such manuals, and they are all very poor.  Until I see a very nice
counterexample (the SCWM manual, hopefully!), I don't want to use this
tactic in Guile.  We'll maintain docstrings and the manual separately.
I've done this before, for Emacs, and it's not too oppressive.

I'd like to use the GNU C library manual as a model for what a chapter
should contain.  The libc manual does a great job of combining general
explanatory material ("Why would want to use these functions?"
"What's the overall design here?") with reference material ("How,
exactly, do I use these functions?").

The manual will be organized by the function performed.  Scheme
functions, scm_ functions, and gh_ functions will not be segregated
into their own sections; they will be listed side by side, and
distinguished by giving an appropriate category to @deffn.


Here's the overall layout.  We're going to prioritize these, and do
the detailed stuff first, and fill in the tutorial material afterwards.

- Road Map, Overview, whatever you want to call it.
- The Four Faces of Guile
  For people asking, "What is Guile for?"  Short sketches of the
  following, 1-2 pages each:
  - using Guile interactively
  - using Guile for scripting
  - writing shared libraries that provide Guile modules
  - writing applications that use Guile as their extension language
- Guile language tutorial
  Like the above, but tries to show things off more fully.  For people
  who want to actually use Guile for something.
  - interactive use
  - scripting
  - shared libraries
  - extensible applications

The following are reference sections.  The need to be careful about
what other parts of Guile they assume the user already knows.  In
particular, they should not depend on the tutorial sections above.

- interpreter definition
  Exhaustive docs of everything you can do with the interpreter.
- scripting definition - ditto
- C-level definition 
  Note that this does not include specs for all the scm_ and gh_
  functions.  Those go in the chapters for their functions.
  - Guile's dynamic typing system
  - How GC works, and how to play nice with conservative GC
  - the relationship between the C and Scheme views of primitive
    Scheme functions
  - snarfing

Then, chapters on each group of functions Guile provides: lists,
vectors, I/O, etc.  Follow the plan of R5RS, and extend it to handle
Guile's new offerings.  Document gh_ and scm_ functions side-by-side
with the corresponding Scheme-level functionality.