Re: New manual plan

[Maciej Stachowiak <mstachow@mit.edu>]

jimb@red-bean.com writes:
> 
> It should assume that the reader understands C and Unix, but not
> Scheme.

I hope only the sections relevant to the C API will assume the reader
understands C.

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

I think this is a bad plan. If you want to write a C extension or app,
the avaiable Scheme functions are not very interesting to
you. Conversely, if you are writing a Guile script, the whole gh_ API
is utterly irrelevant to you, and the scm_ API is only marginally
relevant in those parts that happen to be directly exported to
Scheme. I expect people to want to have a handy reference to _only_
the APIs of interest to a particular project, thus I think separate
Scheme interface and C interface references would be useful.

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

I think some of the gh_ functions, namely the ones for basic setup
(gh_enter), calling back to scheme code (gh_eval_str) and converting
between Scheme and C types logically belong here.

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

Again I think this will be problematic due to the parts of each API
that have no counterpart in the others.

Other than this point, I think this is a good plan.

 - Maciej