[Emacs-diffs] Changes to emacs/lispref/functions.texi

[Luc Teirlinck]

Index: emacs/lispref/functions.texi
diff -c emacs/lispref/functions.texi:1.30 emacs/lispref/functions.texi:1.31
*** emacs/lispref/functions.texi:1.30   Mon Feb 14 10:11:48 2005
--- emacs/lispref/functions.texi        Thu May  5 23:12:19 2005
***************
*** 21,26 ****
--- 21,27 ----
  * 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
***************
*** 601,607 ****
  
  By contrast, in programs that manipulate function definitions for other
  purposes, it is better to use @code{fset}, which does not keep such
! records.
  @end defun
  
    You cannot create a new primitive function with @code{defun} or
--- 602,608 ----
  
  By contrast, in programs that manipulate function definitions for other
  purposes, it is better to use @code{fset}, which does not keep such
! records.  @xref{Function Cells}.
  @end defun
  
    You cannot create a new primitive function with @code{defun} or
***************
*** 1150,1155 ****
--- 1151,1194 ----
  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 function new &optional when
+ This function makes the byte compiler warn that the function
+ @var{function} is obsolete.  If @var{new} is a symbol, the warning
+ message says to use @var{new} instead of @var{function}.  @var{new}
+ does not need to be an alias for @var{function}; it can be a different
+ function with similar functionality.  If @var{new} 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 function new &optional when docstring
+ This macro marks the function @var{function} obsolete and also defines
+ it as an alias for the function @var{new}.  A typical call has the form:
+ 
+ @example
+ (define-obsolete-function-alias 'old-fun 'new-fun "22.1" "Doc.")
+ @end example
+ 
+ @noindent
+ which is equivalent to the following two lines of code:
+ 
+ @example
+ (defalias 'old-fun 'new-fun "Doc.")
+ (make-obsolete 'old-fun 'new-fun "22.1")
+ @end example
+ @end defmac
+ 
  @node Inline Functions
  @section Inline Functions
  @cindex inline functions
***************
*** 1186,1192 ****
  following the definition, just like macros.
  
  @node Function Safety
! @section Determining whether a function is safe to call
  @cindex function safety
  @cindex safety of functions
  
--- 1225,1231 ----
  following the definition, just like macros.
  
  @node Function Safety
! @section Determining whether a Function is Safe to Call
  @cindex function safety
  @cindex safety of functions