Guile reference manual questions

[Neil Jerram]

I'm trying to finalize the structure of the part of the Guile
reference manual that documents the Scheme language as implemented in
Guile.

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

When I began working on the manual, its structure and contents
indicated the answer "not at all - we just document the Guile
extensions".  So it may be that this question has been discussed and
decided before - in which case I'd just like to check that everyone is
still happy with the decision.  I intuitively felt, though, that this
wasn't really good enough, as a new Guile user will want to find all
the practical information about programming Guile in one place,
regardless of whether the information they need happens to be R5RS or
Guile-specific.  R5RS itself can be extremely terse in its
documentation and is clearly not enough for the new Scheme programmer.

Going with my intuition, I have been planning a structure which mixes
R5RS and Guile extensions together in functional groupings:

  "This reference manual documents all of Guile's Scheme-level
   language and features in functionally-related groups.  Where a
   particular section of the manual includes both R5RS-compliant parts
   and Guile-specific extensions, the text indicates which parts of
   the documentation describe R5RS behaviour and which parts describe
   Guile extensions."

But, after trying it out a bit, this doesn't feel right either,
because

- in practice, Guile extensions tend to be whole new areas - such as
  the options interface - rather than extensions to individual R5RS
  primitives; so there's not really much need to mix R5RS and
  Guile-specific documentation

- 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

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

So now I'm wondering whether the not-documenting-R5RS approach was
right after all.  Perhaps we could provide all the material that
people need by including both R5RS and an existing Scheme programming
tutorial (such as Sitaram's) in the Guile distribution, and then, in
the reference manual, provide

- additional tutorial material for things that are not covered
  sufficiently in the external Scheme programming tutorial

- detailed discursive documentation for Guile extensions

- a unified, terse reference section that contains little more than
  the docstrings for procedures grouped by functional area, covering
  both R5RS and Guile extensions.

Any thoughts that you all have to help pin down the right structure
would be very welcome.

Regards,

        Neil