Re: New manual plan

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

> Should SMOB stuff have a section of its own? It kinda fits in
> with the extension language and kinda with the shared libraries,
> maybe it is part of the dynamic typing system...
> I would expect that no new user is going to walk in thinking,
> ``I wanna write an SMOB'' but pretty soon they are going to realise
> that SMOBs are an essential part of interfacing with guile.

It'll be in the section about extending Guile with C code, along with
how to define your own primitives.

> Don't forget to cover the switching on and off of interrupts and
> the implications of using guile's (sigaction) -- especially when mixed
> with C code sigactions used by an application (is this actually safe?)

Right, that should be in the same section.  "How to make your C code
co-exist with the Guile interpreter."

> Explain error-bailouts, how to correctly cause an error-bailout from
> your C code and your scheme code, how to catch them from your application
> and redirect the messages, how these affect where you can use malloc and
> how the ultimate implication is that you can allocate memory by using an
> SMOB or for a brief time while interrupts are switched off (otherwise a
> possible error-bailout or interrupt can cause a memory leak).

Right.  All this goes in the section on error handling.

> > 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.
> 
> How much of R5RS can legally be included within guile documentation?
> Can R5RS be distributed alongside and the guile documentation make
> reference to suitable sections?

Print out R5RS and see for yourself.  They encourage people to
incorporate their text into their manuals.