(Variable Aliases): Clarify text.

1 files changed, 23 insertions, 17 deletions

diff --git a/lispref/variables.texi b/lispref/variables.texi
index 49a8f0d7a26..b39c4abb719 100644
--- a/lispref/variables.texi
+++ b/lispref/variables.texi
@@ -1714,31 +1714,37 @@ of the variable at the end of the chain of aliases.
 This function returns @var{base-var}.
 @end defun
 
-Variables aliases are often used prior to replacing an old name for a variable
-with a new name. To allow some time for existing code to adapt to this change,
-@code{make-obsolete-variable} declares that the old name is obsolete and
-therefore that it may be removed at some stage in the future.
+Variable aliases are convenient for replacing an old name for a
+variable with a new name.  @code{make-obsolete-variable} declares that
+the old name is obsolete and therefore that it may be removed at some
+stage in the future.
 
 @defmac make-obsolete-variable variable new &optional when
-This macro makes the byte-compiler warn that symbol @var{variable} is
-obsolete and that symbol @var{new} should be used instead.  If
-@var{new} is a string, this is the message and there is no replacement
-variable.  If it is provided, @var{when} should be a string indicating
-when the variable was first made obsolete, for example a date or a
-release number.
+This macro makes the byte-compiler warn that the variable
+@var{variable} is obsolete.  If @var{new} is a symbol, it is the
+variable's new name; the warning messages say to use @var{new}
+instead of @var{variable}.
+If @var{new} is a string, this is the message and there is no
+replacement variable.
+
+If provided, @var{when} should be a string indicating when the
+variable was first made obsolete---for example, a date or a release
+number.
 @end defmac
 
 You can make two variables synonyms and declare one obsolete at the
 same time using the macro @code{define-obsolete-variable-alias}.
 
 @defmac define-obsolete-variable-alias variable new &optional when docstring
-This macro defines the symbol @var{variable} as a variable alias for
-symbol @var{new} and warns that @var{variable} is obsolete.  If it is
-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.
+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