Documentation of obsolete declarations and aliases.

[Luc Teirlinck]

I propose the following doc changes.  The main two points are the following.

Firstly, since the Elisp manual describes the details of how to
declare variables obsolete, should it not also document how to declare
functions obsolete?  The patch to lispref/functions.texi does that
with a new node "Obsolete Functions".

Secondly, all `define-obsolete-variable-alias' and
`define-obsolete-function-alias' are is shorthand for two lines of
code.  But their documentation fails to make that clear and makes them
look like a real alternate way to declare variables or functions
obsolete.  The documentation also fails to point out that the main
arguments to these macros need to be quoted (which is somewhat
surprising for macros.)  I believe that it is better to give a usage
example with expansion, as the patches below do, and refer to the
docstrings of the two functions they combine for details on those two
individual functions.

As a minor detail, the section title "Determining whether a function is
safe to call" does not appear to follow the usual capitalization
conventions.  The patch to functions.texi corrects that.

As usual, I can install if desired.

===File ~/lispref-functions.texi-diff=======================
*** functions.texi      14 Feb 2005 15:39:00 -0600      1.30
--- functions.texi      03 May 2005 19:48:58 -0500      
***************
*** 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
  
============================================================

===File ~/lispref-variables.texi-diff=======================
*** variables.texi      01 May 2005 21:31:19 -0500      1.58
--- variables.texi      03 May 2005 19:31:47 -0500      
***************
*** 1736,1749 ****
  
  @defmac define-obsolete-variable-alias variable new &optional when docstring
  This macro marks the variable @var{variable} as obsolete and also
! makes it an alias for the variable @var{new}.
  
! If provided, @var{when} should be a string indicating when
! @var{variable} was first made obsolete.  The optional argument
! @var{docstring} specifies the documentation string for @var{variable}.
! If @var{docstring} is omitted or nil, @var{variable} uses the
! documentation string of @var{new} unless it already has one of its
! own.
  @end defmac
  
  @defun indirect-variable variable
--- 1736,1754 ----
  
  @defmac define-obsolete-variable-alias variable new &optional when docstring
  This macro marks the variable @var{variable} as obsolete and also
! makes it an alias for the variable @var{new}.  A typical call has the form:
  
! @example
! (define-obsolete-variable-alias 'old-var 'new-var "22.1" "Doc.")
! @end example
! 
! @noindent
! which is equivalent to the following two lines of code:
! 
! @example
! (defvaralias 'oldvar 'newvar "Doc.")
! (make-obsolete-variable 'old-var 'new-var "22.1")
! @end example
  @end defmac
  
  @defun indirect-variable variable
============================================================

===File ~/byte-run-diff=====================================
*** byte-run.el 26 Apr 2005 09:35:07 -0500      1.10
--- byte-run.el 03 May 2005 19:58:44 -0500      
***************
*** 116,127 ****
  
  (defmacro define-obsolete-function-alias (function new
                                                   &optional when docstring)
!   "Set FUNCTION's function definition to NEW and warn that FUNCTION is 
obsolete.
! If provided, WHEN should be a string indicating when FUNCTION was
! first made obsolete, for example a date or a release number.  The
! optional argument DOCSTRING specifies the documentation string
! for FUNCTION; if DOCSTRING is omitted or nil, FUNCTION uses the
! documentation string of NEW unluess it already has one."
    `(progn
       (defalias ,function ,new ,docstring)
       (make-obsolete ,function ,new ,when)))
--- 116,131 ----
  
  (defmacro define-obsolete-function-alias (function new
                                                   &optional when docstring)
!   "Set FUNCTION's function definition to NEW and mark it obsolete.
! 
! \(define-obsolete-function-alias 'old-fun 'new-fun \"22.1\" \"old-fun's 
doc.\")
! 
! is equivalent to the following two lines of code:
! 
! \(defalias 'old-fun 'new-fun \"old-fun's doc.\")
! \(make-obsolete 'old-fun 'new-fun \"22.1\")
! 
! See the docstrings of `defalias' and `make-obsolete' for more details."
    `(progn
       (defalias ,function ,new ,docstring)
       (make-obsolete ,function ,new ,when)))
***************
*** 143,154 ****
  
  (defmacro define-obsolete-variable-alias (variable new
                                                 &optional when docstring)
!   "Make VARIABLE a variable alias for NEW and warn that VARIABLE is obsolete.
! If provided, WHEN should be a string indicating when VARIABLE was
! first made obsolete, for example a date or a release number.  The
! optional argument DOCSTRING specifies the documentation string
! for VARIABLE; if DOCSTRING is omitted or nil, VARIABLE uses the
! documentation string of NEW unless it already has one."
    `(progn
       (defvaralias ,variable ,new ,docstring)
        (make-obsolete-variable ,variable ,new ,when)))
--- 147,163 ----
  
  (defmacro define-obsolete-variable-alias (variable new
                                                 &optional when docstring)
!   "Make VARIABLE a variable alias for NEW and mark it obsolete.
! 
! \(define-obsolete-variable-alias 'old-var 'new-var \"22.1\" \"old-var's 
doc.\")
! 
! is equivalent to the following two lines of code:
! 
! \(defvaralias 'old-var 'new-var \"old-var's doc.\")
! \(make-obsolete-variable 'old-var 'new-var \"22.1\")
! 
! See the docstrings of `defvaralias' and `make-obsolete-variable' or
! Info node `(elisp)Variable Aliases' for more details."
    `(progn
       (defvaralias ,variable ,new ,docstring)
        (make-obsolete-variable ,variable ,new ,when)))
============================================================

===File ~/eval.c-diff=======================================
*** eval.c      28 Apr 2005 07:59:32 -0500      1.236
--- eval.c      03 May 2005 20:44:24 -0500      
***************
*** 725,731 ****
         doc: /* Make SYMBOL a variable alias for symbol ALIASED.
  Setting the value of SYMBOL will subsequently set the value of ALIASED,
  and getting the value of SYMBOL will return the value ALIASED has.
! Third arg DOCSTRING, if non-nil, is documentation for SYMBOL.
  The return value is ALIASED.  */)
       (symbol, aliased, docstring)
       Lisp_Object symbol, aliased, docstring;
--- 725,733 ----
         doc: /* Make SYMBOL a variable alias for symbol ALIASED.
  Setting the value of SYMBOL will subsequently set the value of ALIASED,
  and getting the value of SYMBOL will return the value ALIASED has.
! Third arg DOCSTRING, if non-nil, is documentation for SYMBOL.  If it is
! omitted or nil, SYMBOL gets the documentation string of ALIASED, or of the
! variable at the end of the chain of aliases, if ALIASED is itself an alias.
  The return value is ALIASED.  */)
       (symbol, aliased, docstring)
       Lisp_Object symbol, aliased, docstring;
============================================================