Re: Guile reference manual questions

[Neil Jerram]

Richard, Dirk,

Thanks both for your input on this.  I was having difficulty
visualizing an overall structure for the Scheme part of the reference
manual, and your responses to the problem in different terms have been
helpful in resolving this difficulty.

(Part of my problem was failing to distinguish clearly between
reference and tutorial material.  If I focus on reference-style rather
than tutorial-style material - as seems reasonable for a "reference"
manual, the availability of existing Scheme tutorial material is
less relevant, and it feels easier to treat both R5RS and Guile
extensions in a more uniform way.)

So I now plan to follow my intuition and document all of Guile's core
language and features together - mixing R5RS and Guile extensions - in
whatever order of presentation turns out to make most sense.

I think the module-centered view is also useful, but more for add-ons
than for what we consider to be core Guile.  For core Guile,
functional grouping is what is most likely to be useful to the
newcomer.  As one moves away from the core, the distinction between
functional and module-based grouping disappears anyway, since modules
tend to address a particular functional area.

Best regards,

        Neil

>>>>> "Dirk" == Dirk Herrmann <address@hidden> writes:

    Dirk> Hmmm.  You could also use a module centered approach: Guile
    Dirk> has a pure r5rs module, where there are actually no guile
    Dirk> extensions available (or at least that's the way it _should_
    Dirk> be :-).  Whether a certain function behaves as in R5RS or
    Dirk> not depends on the set of modules.  Since modules should
    Dirk> also reflect functionally related groups, this seems to be a
    Dirk> sensible approach (at least in the long term, when guile is
    Dirk> more cleanly separated into modules).  It seems also to be
    Dirk> more helpful with functions that are neither 'guile
    Dirk> extensions' nor R5RS, like the SRFI extensions.

>>>>> "RMS" == Richard Stallman <address@hidden> writes:

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

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