Re: manual terminology: `procedure', `function' etc.

[Mark Galassi <rosalia@cygnus.com>]

    Tim> Right now the manual uses `procedure' and `function' somewhat
    Tim> arbitrarily, but several categories come to mind: `function'
    Tim> for code that returns a useful value; `procedure' for
    Tim> functions which do not;

Not quite.  In discussing functional programming, function is used to
mean a procedure that does not have side-effects, like sin or cos.
Procedure is a more general term to mean both functiosn and procedures
with side-effects.

I think we should go with just "procedure" for all of them, which is
what R4RS does: even trigonometric functions are listed as
"procedures" in R4RS.

    Tim> `primitive' for Guile functions coded in C; `macro' for code
    Tim> defined with defmacro or define-syntax.

I like the idea of "primitive procedure" for all Guile primitives:
people have a right to know what's primitive.  Regarding "macro", I
believe that R4RS actually uses "syntax" for some standard macros like
"do".  I don't have any good thoughts on this one.

    Tim> Is it useful to employ all of these terms?  My main worry was
    Tim> that it would produce a confusing maze of indices.  However,
    Tim> it appears that any code documented with `@deffn' and friends
    Tim> will appear in the same index regardless of its documentation
    Tim> category, so that's not a cause for concern.

I think that if we keep it down to "procedure", "primitive procedure"
and "syntax" (or "macro") it will be OK.