Add something for variable aliases.

diff --git a/lispref/variables.texi b/lispref/variables.texi
index 8ab6739bdb7a5b40215274a1b60a3cb3cb3710bd..4b08c8955e60643238ae53628d96b29fc4706762 100644 (file)
--- a/lispref/variables.texi
+++ b/lispref/variables.texi
@@ -41,6 +41,7 @@ variable.
 * Buffer-Local Variables::  Variable values in effect only in one buffer.
 * Frame-Local Variables::   Variable values in effect only in one frame.
 * Future Local Variables::  New kinds of local values we might add some day.
+* Variable Aliases::      Variables that are aliases for other variables.
 * File Local Variables::  Handling local variable lists in files.
 @end menu
 
@@ -1653,6 +1654,45 @@ bindings offer a way to handle these situations more robustly.
   If sufficient application is found for either of these two kinds of
 local bindings, we will provide it in a subsequent Emacs version.
 
+@node Variable Aliases
+@section Variable Aliases
+
+  When maintaining Lisp programs, it is sometimes useful to make two
+variables synonyms for each other, so that both variables invariably
+refer to the same value.  When a program variable slightly changes
+meaning, or when a variable name was chosen badly to begin with, it is
+desirable to rename that variable.  For compatibility with older
+versions of the program it is also desirable to not break code that
+uses the original variable name.  This can be done with
+@code{defvaralias}.
+
+@defun defvaralias old-name new-name
+This function defines the symbol @var{old-name} as a variable alias
+for symbol @var{new-name}.  Subsequently, retrieving the value of
+@var{old-name} returns the value of @var{new-name}, and changing the
+value of @var{old-name} changes the value of @var{new-name}.
+@end defun
+
+@defun indirect-variable name
+This function returns the variable at the end of the variable chain
+of @var{name}.  If @var{name} is not a symbol or if @var{name}
+is not a variable alias, @var{name} is returned unchanged.
+@end defun
+
+@example
+(defvaralias 'foo 'bar)
+(setq bar 2)
+bar
+     @result{} 2
+foo
+     @result{} 2
+(setq foo 0)
+bar
+     @result{} 0
+foo
+     @result{} 0
+@end example
+
 @node File Local Variables
 @section File Local Variables