bug#24014: 24.5; doc string of `cl-reduce'

[Drew Adams <drew.adams@oracle.com>]

> I wasn't sure about the s[h]ort list; I actually found things more
> confusing that way.

I wonder why?  But OK by me not to shorten.

> Should this go in the ELisp manual, or in the docstring?

Doesn't matter to me.  Maybe the manual is better.

And isn't the CL manual the proper manual, not the Elisp manual?

IMHO, it would help if manual entries for Common-Lisp emulation
stuff had links to the most relevant CLTL2 sections that specify it.

E.g., in this case, our CL manual would point here:
https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node143.html.

It is appropriate for our CL doc to both (1) point to the Common-Lisp
spec for the corresponding thingy and (2) point out any differences
between our emulation and the thing it emulates.

IMHO, not doing this is not doing our job properly, not helping
Emacs-Lisp users use our CL emulation.

> No strong feelings about the double arrow, and fine with me for quoting f.
 
Not quoting f is not an option.  If f is a variable bound to a function
then (f a b c) raises an error.  (This is not Scheme.)

  (setq b #'car)
  (b '(1 2 3))
  Symbol's function definition is void: b

If b is an fboundp symbol then (b '(1 2 3)) => 1.

When you pass a function-valued argument to `cl-reduce' it is the
boundp value of that _variable_ (symbol arg) that is passed, not
the fboundp value of the symbol arg.

The only thing that works a bit like what a Scheme user might
expect in this regard is the use of a lambda at the head of the
list:

((lambda (xs) (car xs)) '(1 2 3)) = 1.