Merge from emacs-23

[bpt/emacs.git] / doc / lispref / functions.texi

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 9e68343..198cc1a 100644 (file)
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -1,7 +1,8 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c   2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010  Free Software Foundation, Inc.
+@c   2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
+@c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/functions
 @node Functions, Macros, Variables, Top
@@ -22,7 +23,7 @@ define them.
 * Function Cells::        Accessing or setting the function definition
                             of a symbol.
 * Obsolete Functions::    Declaring functions obsolete.
-* Inline Functions::     Defining functions that the compiler will open code.
+* Inline Functions::      Defining functions that the compiler will open code.
 * Declaring Functions::   Telling the compiler that a function is defined.
 * Function Safety::       Determining whether a function is safe to call.
 * Related Topics::        Cross-references to specific Lisp primitives
@@ -817,7 +818,7 @@ length of @var{sequence}.  For example:
      @result{} (a c e)
 (mapcar '1+ [1 2 3])
      @result{} (2 3 4)
-(mapcar 'char-to-string "abc")
+(mapcar 'string "abc")
      @result{} ("a" "b" "c")
 @end group
 
@@ -1197,7 +1198,7 @@ was first made obsolete---for example, a date or a release number.
 @end defun
 
 You can define a function as an alias and declare it obsolete at the
-same time using the macro @code{define-obsolete-function-alias}.
+same time using the macro @code{define-obsolete-function-alias}:
 
 @defmac define-obsolete-function-alias obsolete-name current-name &optional when docstring
 This macro marks the function @var{obsolete-name} obsolete and also
@@ -1210,6 +1211,33 @@ equivalent to the following:
 @end example
 @end defmac
 
+In addition, you can mark a certain a particular calling convention
+for a function as obsolete:
+
+@defun set-advertised-calling-convention function signature
+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).
+
+For instance, in old versions of Emacs the @code{sit-for} function
+accepted three arguments, like this
+
+@smallexample
+  (sit-for seconds milliseconds nodisp)
+@end smallexample
+
+However, calling @code{sit-for} this way is considered obsolete
+(@pxref{Waiting}).  The old calling convention is deprecated like
+this:
+
+@smallexample
+(set-advertised-calling-convention
+  'sit-for '(seconds &optional nodisp))
+@end smallexample
+@end defun
+
 @node Inline Functions
 @section Inline Functions
 @cindex inline functions