X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/1e103a7cd8a0210ad6d66d6105192e8ab8df19e5..9f6f48455f7d25e5cc2d50485d98ff3af43946a2:/doc/lispref/functions.texi

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 73bdefe19f..9e1d3f9c6a 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -3,7 +3,7 @@
 @c Copyright (C) 1990-1995, 1998-1999, 2001-2012
 @c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
-@node Functions, Macros, Variables, Top
+@node Functions
 @chapter Functions
 
   A Lisp program is composed mainly of Lisp functions.  This chapter
@@ -266,13 +266,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
 
@@ -287,8 +286,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
 
@@ -398,19 +397,19 @@ 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.}
+@example
+(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
+@end example
 
 @node Function Documentation
 @subsection Documentation Strings of Functions
@@ -531,8 +530,7 @@ defines the symbol @var{name} as a function that looks like this:
 @end example
 
 @code{defun} stores this lambda expression in the function cell of
-@var{name}.  It returns the value @var{name}, but usually we ignore this
-value.
+@var{name}.  Its return value is @emph{undefined}.
 
 As described previously, @var{argument-list} is a list of argument
 names and may include the keywords @code{&optional} and @code{&rest}.
@@ -544,9 +542,6 @@ Here are some examples:
 @example
 @group
 (defun foo () 5)
-     @result{} foo
-@end group
-@group
 (foo)
      @result{} 5
 @end group
@@ -554,9 +549,6 @@ Here are some examples:
 @group
 (defun bar (a &optional b &rest c)
     (list a b c))
-     @result{} bar
-@end group
-@group
 (bar 1 2 3 4 5)
      @result{} (1 2 (3 4 5))
 @end group
@@ -577,7 +569,6 @@ Here are some examples:
   (forward-word 1)
   (backward-char 1)
   (capitalize-word 1))
-     @result{} capitalize-backwards
 @end group
 @end example
 
@@ -594,7 +585,7 @@ redefinition from unintentional redefinition.
 @anchor{Definition of defalias}
 This special form defines the symbol @var{name} as a function, with
 definition @var{definition} (which can be any valid Lisp function).
-It returns @var{definition}.
+Its return value is @emph{undefined}.
 
 If @var{docstring} is non-@code{nil}, it becomes the function
 documentation of @var{name}.  Otherwise, any documentation provided by
@@ -821,7 +812,7 @@ char-table; that is, a list, a vector, a bool-vector, or a string.  The
 result is always a list.  The length of the result is the same as the
 length of @var{sequence}.  For example:
 
-@smallexample
+@example
 @group
 (mapcar 'car '((a b) (c d) (e f)))
      @result{} (a c e)
@@ -853,7 +844,7 @@ Return the list of results."
 (mapcar* 'cons '(a b c) '(1 2 3 4))
      @result{} ((a . 1) (b . 2) (c . 3))
 @end group
-@end smallexample
+@end example
 @end defun
 
 @defun mapc function sequence
@@ -874,7 +865,7 @@ argument and return a string.  The argument @var{sequence} can be any
 kind of sequence except a char-table; that is, a list, a vector, a
 bool-vector, or a string.
 
-@smallexample
+@example
 @group
 (mapconcat 'symbol-name
            '(The cat in the hat)
@@ -888,7 +879,7 @@ bool-vector, or a string.
            "")
      @result{} "IBM.9111"
 @end group
-@end smallexample
+@end example
 @end defun
 
 @node Anonymous Functions
@@ -1016,9 +1007,6 @@ function.
 @example
 @group
 (defun bar (n) (+ n 2))
-     @result{} bar
-@end group
-@group
 (symbol-function 'bar)
      @result{} (lambda (n) (+ n 2))
 @end group
@@ -1064,9 +1052,6 @@ subsequent attempt to access this cell will cause a
 @example
 @group
 (defun foo (x) x)
-     @result{} foo
-@end group
-@group
 (foo 1)
      @result{}1
 @end group
@@ -1115,8 +1100,9 @@ named function that you create (e.g.@: with @code{defun}), as well as
 any anonymous function that you create using the @code{lambda} macro
 or the @code{function} special form or the @code{#'} syntax
 (@pxref{Anonymous Functions}), is automatically converted into a
-closure.
+@dfn{closure}.
 
+@cindex closure
   A closure is a function that also carries a record of the lexical
 environment that existed when the function was defined.  When it is
 invoked, any lexical variable references within its definition use the
@@ -1179,28 +1165,30 @@ equivalent to the following:
 In addition, you can mark a certain a particular calling convention
 for a function as obsolete:
 
-@defun set-advertised-calling-convention function signature
+@defun set-advertised-calling-convention function signature when
 This function specifies the argument list @var{signature} as the
 correct way to call @var{function}.  This causes the Emacs byte
 compiler to issue a warning whenever it comes across an Emacs Lisp
 program that calls @var{function} any other way (however, it will
-still allow the code to be byte compiled).
+still allow the code to be byte compiled).  @var{when} should be a
+string indicating when the variable was first made obsolete (usually a
+version number string).
 
 For instance, in old versions of Emacs the @code{sit-for} function
 accepted three arguments, like this
 
-@smallexample
+@example
   (sit-for seconds milliseconds nodisp)
-@end smallexample
+@end example
 
 However, calling @code{sit-for} this way is considered obsolete
 (@pxref{Waiting}).  The old calling convention is deprecated like
 this:
 
-@smallexample
+@example
 (set-advertised-calling-convention
-  'sit-for '(seconds &optional nodisp))
-@end smallexample
+  'sit-for '(seconds &optional nodisp) "22.1")
+@end example
 @end defun
 
 @node Inline Functions
@@ -1260,11 +1248,11 @@ indicates a real problem, but usually the functions in question are
 defined in other files which would be loaded if that code is run.  For
 example, byte-compiling @file{fortran.el} used to warn:
 
-@smallexample
+@example
 In end of data:
-fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known
-    to be defined.
-@end smallexample
+fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not
+    known to be defined.
+@end example
 
 In fact, @code{gud-find-c-expr} is only used in the function that
 Fortran mode uses for the local value of
@@ -1277,9 +1265,9 @@ visible.  You do that with @code{declare-function}.
 All you need to do is add a @code{declare-function} statement before the
 first use of the function in question:
 
-@smallexample
+@example
 (declare-function gud-find-c-expr "gud.el" nil)
-@end smallexample
+@end example
 
 This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the
 @samp{.el} can be omitted).  The compiler takes for granted that that file