Re: Guile reference manual questions

[Richard Stallman]

    As you know, this Scheme language consists of R5RS + Guile extensions.

    So a very important question is: to what extent should the reference
    manual document R5RS Scheme?  (In either reference or tutorial form.)

The purpose of the manual is to document how to use Guile, as clearly
as possible.  So it should document the R5RS features and the other
features of Guile, in a unified way.  To split the documentation of
Guile into two parts, the R5RS part and the nonstandard part, would
only make the documentation inconvenient to use.  (A user would have
to look in two places.)  The manual should document all the features
of Guile in whatever order makes for the clearest explanation of the
entire set of Guile features.

The emphasis should be on telling people how to use Guile--which of
the features are R5RS is a secondary question.  But some users may
find that information useful.  So it would be useful to also mention
which features are or are not R5RS features.  You could do that with
parenthetical notes, footnotes, appendices, or however you find
natural.  The Make manual, for instance, has appendices saying which
Make features are found in various other versions of Make.  That is
useful for writing portable makefiles, which is something some users
(but not all) want to do.

    - while we should allow for the Scheme newcomer, we also have to
      consider the more experienced programmers who will use the reference
      manual more as a reference; for these people, it's appropriate to
      treat the standard R5RS stuff more lightly than Guile-specific
      extensions, which in turn supports grouping the R5RS stuff together

No, that is an incoherent idea.  Skimping on the explanation of the
R5RS features will not help experienced Scheme users, or anyone.  The
Guile manual should aim to have a clear explanation of *all* the
features.  A terse, hurried explanation is never better than a clear,
thorough explanation--not even for an experienced user.

Because more users need explanations for the non-R5RS features, and
because there is no other source for those, it could be more efficient
to write the documentation for the non-R5RS features *first*.  But
please put this information into an outline which is designed to hold
the entire subject, so that when eventually the whole manual is
completed it will cover the whole subject of Guile clearly.

    - there is freely redistributable Scheme tutorial material already
      available, such as Dorai Sitaram's tutorial at
      http://www.cs.rice.edu/~dorai/t-y-scheme/t-y-scheme.html.

Some day we ought to modify this to teach all of Guile's features, so
that it will provide a unified introduction to using Guile.