update copyright year(s)

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

diff --git a/lispref/functions.texi b/lispref/functions.texi
index 26c2449..9c7381b 100644 (file)
--- a/lispref/functions.texi
+++ b/lispref/functions.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004
-@c   Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
+@c   2004, 2005, 2006 Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/functions
 @node Functions, Macros, Variables, Top
@@ -21,6 +21,7 @@ define them.
 * Anonymous Functions::   Lambda expressions are functions with no names.
 * 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.
 * Function Safety::       Determining whether a function is safe to call.
 * Related Topics::        Cross-references to specific Lisp primitives
@@ -98,7 +99,7 @@ Keyboard macros (strings and vectors) are commands also, even though
 they are not functions.  A symbol is a command if its function
 definition is a command; such symbols can be invoked with @kbd{M-x}.
 The symbol is a function as well if the definition is a function.
-@xref{Command Overview}.
+@xref{Interactive Call}.
 
 @item keystroke command
 @cindex keystroke command
@@ -524,9 +525,9 @@ defines the symbol @var{name} as a function that looks like this:
 @var{name}.  It returns the value @var{name}, but usually we ignore this
 value.
 
-As described previously (@pxref{Lambda Expressions}),
-@var{argument-list} is a list of argument names and may include the
-keywords @code{&optional} and @code{&rest}.  Also, the first two of the
+As described previously, @var{argument-list} is a list of argument
+names and may include the keywords @code{&optional} and @code{&rest}
+(@pxref{Lambda Expressions}).  Also, the first two of the
 @var{body-forms} may be a documentation string and an interactive
 declaration.
 
@@ -601,7 +602,7 @@ which file defined the function, just like @code{defun}
 
 By contrast, in programs that manipulate function definitions for other
 purposes, it is better to use @code{fset}, which does not keep such
-records.
+records.  @xref{Function Cells}.
 @end defun
 
   You cannot create a new primitive function with @code{defun} or
@@ -1150,6 +1151,39 @@ file to redefine a function defined elsewhere.  If you want to modify
 a function defined by another package, it is cleaner to use
 @code{defadvice} (@pxref{Advising Functions}).
 
+@node Obsolete Functions
+@section Declaring Functions Obsolete
+
+You can use @code{make-obsolete} to declare a function obsolete.  This
+indicates that the function may be removed at some stage in the future.
+
+@defun make-obsolete obsolete-name current-name &optional when
+This function makes the byte compiler warn that the function
+@var{obsolete-name} is obsolete.  If @var{current-name} is a symbol, the
+warning message says to use @var{current-name} instead of
+@var{obsolete-name}.  @var{current-name} does not need to be an alias for
+@var{obsolete-name}; it can be a different function with similar
+functionality.  If @var{current-name} is a string, it is the warning
+message.
+
+If provided, @var{when} should be a string indicating when the function
+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}.
+
+@defmac define-obsolete-function-alias obsolete-name current-name &optional when docstring
+This macro marks the function @var{obsolete-name} obsolete and also
+defines it as an alias for the function @var{current-name}.  It is
+equivalent to the following:
+
+@example
+(defalias @var{obsolete-name} @var{current-name} @var{docstring})
+(make-obsolete @var{obsolete-name} @var{current-name} @var{when})
+@end example
+@end defmac
+
 @node Inline Functions
 @section Inline Functions
 @cindex inline functions
@@ -1186,7 +1220,7 @@ Inline functions can be used and open-coded later on in the same file,
 following the definition, just like macros.
 
 @node Function Safety
-@section Determining whether a function is safe to call
+@section Determining whether a Function is Safe to Call
 @cindex function safety
 @cindex safety of functions