Re: New manual plan

[Klaus Schilling <Klaus.Schilling@home.ivm.de>]

Jay Glascoe writes:
 > On Sun, 1 Nov 1998, Jim Blandy wrote:
 > 
 > > 
 > > Here's an outline of what I want from the Guile manual.
 > <snip>
 > > It should assume that the reader understands C and Unix, but not
 > > Scheme.  Thus, it will include tutorials that cover Scheme itself.
 > 
 > The manual can and should assume some level of programming experience (in
 > something: Perl, Pascal, FORTRAN, shell,...).

Shouldn't that vary from chapter to chapter?
 > 
 > > 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

The last 2 points should of course definitely require familarity with C 
programming, ANSI and maybe POSIX standard features.

For interactive usage I would not want to assume profound C knowledge, nor
for scripting. People who come from other r*rs scheme interpreters, and never
did any  low-levelish like programming, should not be disadvantaged.
 > 
 > I think you must throw in some comparisons to other scripting/extension
 > languages (maybe give a "top 5" list of Guile/Scheme's features, then say
 > how many of these 5 are/aren't met by Perl/Tcl/...)  Programmers thrive on
 > this kind of thing (lnguage-war fodder, strife,...   ;)
 > 

That should be done in the 'guile for scripting' part. People who are familiar
with the C API of python, perl, ruby, pike and the like, but barely with 
Scheme, will be capable to dig their way through guile's C API much easier 
than scripters-only of non-schemish VHHL will have with scheme scripting in 
general, guile in particular. 

 > > - Guile language tutorial
 > >   Like the above, but tries to show things off more fully.  For people
 > >   who want to actually use Guile for something.

Who does not?

 > >   - interactive use
 > >   - scripting
 > >   - shared libraries
 > >   - extensible applications
 > 
 > I think a basic Scheme tutorial should be embedded in there somewhere.  It
 > should show how to define variables (bind values to symbols), how to
 > define a procedure (perhaps "defun" style notation would be best), how to
 > write your basic loop, how for-each and map are used, etc.
 > 
This reminds me that I learnt Scheme, due to lack of textbooks available in
Germany, directly from the r4rs standard by trial and error, plus by trying
to use stuff from a CL textbook and check what works and what doesn't in 
Scheme. That was an ugly mess, I can tell you ...

     Klaus Schilling