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

[Jim Blandy <jimb@red-bean.com>]

The 'procedure' vs. 'primitive' distinction is a clumsy way to tell
the Guile programmer which functions were also available as C
functions in libguile.

There are a lot of Scheme procedures in Guile that are also available
to C code if it links against libguile.  Given the full description of
a Scheme function (optional args, rest args, etc.), there's a
straightforward way to determine the name of the corresponding C
function, the arguments it takes, etc.

For example, if you see

- Primitive: list-ref LIST K
    Return the K'th element of LIST...

then you know there is a C function that's declared as:

	SCM scm_list_ref (SCM list, SCM k);

Rather than documenting all these functions twice --- once for the
Scheme interface and once for the C interface --- the manual should
document them once.  

However, as I say, this is clumsy.  It might be better to write the
entries like this:

- Scheme Procedure: list-ref LIST K
- C Function: SCM scm_list_ref (SCM LIST, SCM K)
    Return the K'th element of List...

The Texinfo source corresponding to this would be:

@deftypefn {Scheme Procedure} {} list-ref @var{LIST} 
@deftypefnx {C Procedure} SCM scm_space_p (SCM @var{obj})
Return a true value iff @var{obj} is a space object.
@end deftypefn

This doesn't quite typeset as well as I'd like.  Texinfo doesn't allow
you to start with a @deffn and continue with a @deftypefnx, although I
don't see any reason why not.  We can probably fix makeinfo and
texinfo.tex to allow this.