[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Guile reference manual questions
From: |
Neil Jerram |
Subject: |
Re: Guile reference manual questions |
Date: |
17 Oct 2000 21:59:14 +0100 |
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.
Re: Guile reference manual questions, Richard Stallman, 2000/10/16