This is the mail archive of the guile@cygnus.com mailing list for the guile project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: New manual plan


> 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

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.

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?)

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

I know a lot of this hasn't been resolved yet but it is the sort of
thing that people are going to keep on asking...

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

I like the idea of grouping scheme and C functions together and
organising the groups by functionality.

	- Tel

PS:

I'm currently trying to get some of the other numerical people around
me away from using MATLAB, C and FORTRAN and toward using scheme but
I'm making a lot more friends by teaching people to use Microsoft's
crappy network workgroups or how to find their mail on the local server
than by offering them scheme interpreters <sigh>. There are quite a
few text books on scheme but maybe some really beginner's language
tutorial stuff should be up on the web, some sort of interactive tutorial
or a list of 101 simple programming problems coded in scheme
(and coded in the easiest to read manner, not the ultimate speed manner).