bug#17623: 24.4.50; incorrect example for `apply-partially' in (elisp) `Calling Functions'

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

> should we try to find a different example?  Maybe something like
> (defalias 'string-empty-p (apply-partially #'string= "")) ?

Yes, we should.  But forget about giving an example that (re)defines
a function that is a built-in or is otherwise predefined.

And again, it is better to have an example that illustrates and
takes advantage of the fact that the function returned accepts any
number of args.

`string=' accepts only two args.  The signature of `string-empty-p'
shows that it accepts any number of arguments, and it says nothing
about their type, but `string-empty-p' raises an error if it is
passed anything other than 2 strings.  Nothing wrong with that, but
it is not so clear as an illustration of `apply-partially'.

And it is better to have an example where the function passed does
not have _only_ an &rest parameter (in which case it could be applied
to just the first argument anyway).  This example uses a function (+)
that accepts any number of args, but its only parameter is an &rest
parameter, so it is not a great way to show `apply-partially':

(defalias '3+ (apply-partially '+ 3)
  "Return 3 plus the sum of the arguments.")

(3+ 2 5 1)
    => 11

That is better than an example that uses a function that accepts
only a fixed number of arguments, but it is not as informative as
examples like these, which accept a first arg that is a string
and other args of any type.

(defun present-list (frmt &rest things)
  "Use format string FRMT to present a list of THINGS."
  (format frmt things))

(defalias 'list-en (apply-partially #'present-list "The list: `%S'")
  "Return a string that presents a list of arguments.")

(defalias 'list-fr (apply-partially #'present-list "La liste : `%S'")
  "Renvoyer une chaine qui presente use liste d'arguments.")

(list-en 1 2 3)
    => "The list: `(1 2 3)'"

(list-fr '(x 42) '(y alpha))
    => "La liste : `((x 42) (y alpha))'"

However, instead of (or in addition to) showing such an example,
we could show the simple equivalence of these two (for all FUN,
ARG1, and ARGS):

(apply (apply-partially FUN ARG1) ARGS) = (apply FUN ARG1 ARGS)

That alone tells users what `apply-partially' is all about.