Deprecate the ((lambda ...) ...) form.

* doc/lispref/functions.texi (Simple Lambda, Argument List):
* doc/lispref/eval.texi (Function Indirection): Avoid deprecated form.

3 files changed, 34 insertions, 14 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index d65a8813fda..401b674f98b 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2012-04-26  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * functions.texi (Simple Lambda, Argument List):
+        * eval.texi (Function Indirection): Avoid deprecated form.
+
 2012-04-26  Glenn Morris  <rgm@gnu.org>
 
         * book-spine.texi, elisp.texi, vol1.texi, vol2.texi:
diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index 5bb514451b8..62de337a5e3 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -305,6 +305,22 @@ function, not a symbol.
 Executing the function itself evaluates its body; this does involve
 symbol function indirection when calling @code{erste}.
 
+  This form is rarely used and is now deprecated.  Instead, you should write it
+as:
+
+@smallexample
+@group
+(funcall (lambda (arg) (erste arg))
+         '(1 2 3))
+@end group
+@end smallexample
+or just
+@smallexample
+@group
+(let ((arg '(1 2 3))) (erste arg))
+@end group
+@end smallexample
+
   The built-in function @code{indirect-function} provides an easy way to
 perform symbol function indirection explicitly.
 
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 9ee94557066..24fe9ed5e68 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -267,13 +267,12 @@ function is the value returned by the last element of the body.
 @end example
 
 @noindent
-We can call this function by writing it as the @sc{car} of an
-expression, like this:
+We can call this function by passing it to @code{funcall}, like this:
 
 @example
 @group
-((lambda (a b c) (+ a b c))
- 1 2 3)
+(funcall (lambda (a b c) (+ a b c))
+         1 2 3)
 @end group
 @end example
 
@@ -288,8 +287,8 @@ this example:
 
 @example
 @group
-((lambda (a b c) (+ a b c))
- 1 (* 2 3) (- 5 4))
+(funcall (lambda (a b c) (+ a b c))
+         1 (* 2 3) (- 5 4))
 @end group
 @end example
 
@@ -400,16 +399,16 @@ after a @code{&rest} argument.
   Here are some examples of argument lists and proper calls:
 
 @smallexample
-((lambda (n) (1+ n))                ; @r{One required:}
- 1)                                 ; @r{requires exactly one argument.}
+(funcall (lambda (n) (1+ n))        ; @r{One required:}
+         1)                         ; @r{requires exactly one argument.}
      @result{} 2
-((lambda (n &optional n1)           ; @r{One required and one optional:}
-         (if n1 (+ n n1) (1+ n)))   ; @r{1 or 2 arguments.}
- 1 2)
+(funcall (lambda (n &optional n1)   ; @r{One required and one optional:}
+           (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.}
+         1 2)
      @result{} 3
-((lambda (n &rest ns)               ; @r{One required and one rest:}
-         (+ n (apply '+ ns)))       ; @r{1 or more arguments.}
- 1 2 3 4 5)
+(funcall (lambda (n &rest ns)       ; @r{One required and one rest:}
+           (+ n (apply '+ ns)))     ; @r{1 or more arguments.}
+         1 2 3 4 5)
      @result{} 15
 @end smallexample