doco scm_apply

[Kevin Ryde]

This is a proposed revision for the "apply" documentation, mainly to
add the C level calling functions.

        * scheme-evaluation.texi (Fly Evaluation): In apply, reword for
        clarity, drop the "append" example, add scm_apply, scm_apply_0,
        scm_apply_1, scm_apply_2, scm_apply_3.
        Add scm_call_0, scm_call_1, scm_call_2, scm_call_3.
        In apply:nconc2last, move down after "apply", reword for clarity, note
        correspondence to apply params.

I don't see a great need for the current apply example "(append (list
ARG1 ...) ARGS)", I think just describing the arguments is enough.

scm_apply is shown in the smobs example and so I guess should be
documented.  What about the rest?

I guess scm_call_X would be replacements for gh_callX, and scm_apply_0
for gh_apply likewise, so these at least could be documented.


 - Scheme Procedure: apply proc arg1 ... argN arglst
 - C Function: scm_apply (proc, arg, rest)
 - C Function: scm_apply_0 (proc, arglst)
 - C Function: scm_apply_1 (proc, arg1, arglst)
 - C Function: scm_apply_2 (proc, arg1, arg2, arglst)
 - C Function: scm_apply_3 (proc, arg1, arg2, arg3, arglst)
     Call PROC with arguments ARG1 ... ARGN plus the elements of the
     ARGLST list.

     `scm_apply' takes parameters corresponding to a Scheme level
     `(lambda (proc arg . rest) ...)'.  So ARG and all but the last
     element of the REST list make up ARG1...ARGN and the last element
     of REST is the ARGLST list.  Or if REST is `SCM_EOL' then there is
     no ARG1...ARGN and ARG is the ARGLST.

 - C Function: scm_call_0 (proc)
 - C Function: scm_call_1 (proc, arg1)
 - C Function: scm_call_2 (proc, arg1, arg2)
 - C Function: scm_call_3 (proc, arg1, arg2, arg3)
     Call PROC with the given arguments.

 - Scheme Procedure: apply:nconc2last lst
 - C Function: scm_nconc2last (lst)
     LST should be a list (ARG1 ... ARGN ARGLST), with ARGLST being a
     list.  This function returns a list comprising ARG1 to ARGN plus
     the elements of ARGLST.  LST is modified to form the return.
     ARGLST is not modified, though the return does share structure
     with it.

     This operation collects up the arguments from a list which is
     `apply' style parameters.