Re: Guile Impressions

[Martin Grabmueller]

> From: John Fitzgerald <address@hidden>
> Date: Wed, 9 May 2001 09:57:26 +1200
> 
>       I am frustrated by the missing documentation, and resorting to
> code reading isn't the best way to answer queries as the answer
> often lies in the dynamic behaviour for which you need to read and
> understand large regions of the program.
> 
>       As I see it the two, Guide and Reference need to be separate
> (logically if not physically) because they address different
> concerns.  The Reference is there to precisely answer questions of
> syntax, function, results, return values, etc of specific
> constructs.  It can, as you suggest, explain the concepts as they
> relate to the mechanics of individual components, but I would tend
> to move the descriptions of anything larger into separate section
> and leave the reference section as a (probably alphabetical)
> catalogue of standalone descriptions of the individual components
> (much like a collection of man pages).  It is very much a hard nosed
> technical reference.

Over the last two or so years (since I joined the mailing list),
several times people have suggested to write some Introductory Manual,
User's Guide, Cook Book or however you will call it. [IIRC, my first
post to the list was such a suggestion, too] 

But the problem is: Writing documentation is a hard task, requires
much time and is not as rewarding as implementing some nifty new
feature to show off with.  Especially when it comes to writing
introductory material, it is very hard to write good explanations for
complex concepts.  Finding good (and probably useful) examples is
another problem.

So if we had enough material, introductory material and concept
description on the one hand, and reference material on the other could
be split into two manual, but unfortunately:  We are not there yet.

>       The Guide is orthogonal to this in that it describes how to
> use those constructs in combination to achieve a given effect.  You
> often see the word 'Gentle' in the title of such documents which
> indicates to me that they are an introductory guide only.  But the
> idea is applicable nevertheless, that the Guide should be much more
> of a discussion of how to go about using the individual the API (in
> this case) to best effect along with possible alternatives and
> common practice.

I think that the Guile Tutorial and the current Reference Manual give
a good start for using, embedding and extending Guile.  The real
problem (for me) seems to be the lack of documentation for the harder
bits when embedding/extending Guile.  For example, how long have I
tried figuring out how to call scm_apply() from C code!  Or: How the
hell does the module system work?  Or: Hey, the snarfer is cool! But
how do I get it to work?

>       It would be unreasonable of me to expect hardcore Schemers to
> handicap themselves in their discussions by avoiding Scheme
> terminology.  Such terminology expedites communication, but the
> uninitiated need a "leg up".  The difficulty posed to newcomers
> seems to be much greater in the Scheme world than in others I live
> in because things seem to be almost exclusively defined in Scheme
> terms.  Even in books with teach Scheme programming, there is a
> distinct lack of non-Scheme descriptive text.  Perhaps what is
> needed is a glossary of terms like 'closure', 'fluid' and
> 'continuation' (to name some Scheme language ones) which we newbies
> can refer to to get an plain English description.

Well some of these terms don't come up in other programming language
contexts, simply because they don't exist in other languages.
``Closure'', for example is a concept present in all functional
programming languages.  I know that a lot of people never programmed
functional, but even Perl does have them (implemented with some
strange semantics, IIRC), but calls them `anonymous subroutines' (or
similar).  There is a IMHO nice description in the Reference Manual
about closures.

I never have heard about ``Fluids'' in other languages, but I think
that they are not much more than global variables.  In Guile, they are
thread-local variables.

``Continuations''.  Hum.  I tried to explain them in the Reference
Manual for documenting call/cc, but I simply can't do that.  It took
myself over a year to get used to them, actually, and I don't think I
understood all implications completely.

>       I have to add that one of the reasons I'm raising these issues
> is not just for my own enlightenment, but so that the questions get
> answered and are available to others in the future.  Please consider
> -- and this is a general plea -- including them when maintaining the
> resources (documentation, FAQs, code, etc) of the Guile project.

I am trying to put all issues into my personal to-do file, but it is
easier for me to handle requests like ``Hey the documentation entry
for make-weired-complex-record-type-frobnicator is fucked up!  Fix
it!''  than ``The documentation should be improved''.

So I encourage all Guile users to look at the documentation, see what
is missing, send suggestions, fixes, etc. to address@hidden or
create tutorial material we can either point people to or include in
the documentation.  Our personal bandwidth could surely use some
backup.

Regards,
  'martin