*** empty log message ***

2 files changed, 63 insertions, 33 deletions

diff --git a/lispref/macros.texi b/lispref/macros.texi
index 49d2d8e639d..13e85568eaf 100644
--- a/lispref/macros.texi
+++ b/lispref/macros.texi
@@ -224,8 +224,8 @@ two forms yield identical results:
 @end group
 @end example
 
-@findex , @{(with Backquote)}
-The special marker, @code{,}, inside of the argument to backquote,
+@findex , @r{(with Backquote)}
+The special marker @code{,} inside of the argument to backquote
 indicates a value that isn't constant.  Backquote evaluates the
 argument of @code{,} and puts the value in the list structure:
 
@@ -240,7 +240,7 @@ argument of @code{,} and puts the value in the list structure:
 @end group
 @end example
 
-@findex ,@@ @{(with Backquote)}
+@findex ,@@ @r{(with Backquote)}
 @cindex splicing (with backquote)
 You can also @dfn{splice} an evaluated value into the resulting list,
 using the special marker @code{,@@}.  The elements of the spliced list
@@ -278,7 +278,7 @@ Here are some examples:
 @end group
 @end example
 
-Emacs 18 had a bug which made the previous example fail.  The bug
+Emacs 18 had a bug that made the previous example fail.  The bug
 affected @code{,@@} followed only by constant elements.  If you are
 concerned with Emacs 18 compatibility, you can work around the bug like
 this:
@@ -320,9 +320,10 @@ should not be used:
 
 @cindex CL note---@samp{,}, @samp{,@@} as functions
 @quotation
-@b{Common Lisp note:} in Common Lisp, @samp{,} and @samp{,@@} are implemented
-as reader macros, so they do not require parentheses.  Emacs Lisp implements
-them as functions because reader macros are not supported (to save space).
+@b{Common Lisp note:} in Common Lisp, @samp{,} and @samp{,@@} are
+implemented as reader macros, so they do not require parentheses.  In
+Emacs Lisp they use function call syntax because reader macros are not
+supported (for simplicity's sake).
 @end quotation
 
 @node Problems with Macros
@@ -389,11 +390,26 @@ For example, (for i from 1 to 10 do (print i))."
 will write noise words (such as @code{from}, @code{to}, and @code{do})
 in those positions in the macro call.)
 
-This macro suffers from the defect that @var{final} is evaluated on
-every iteration.  If @var{final} is a constant, this is not a problem.
-If it is a more complex form, say @code{(long-complex-calculation x)},
-this can slow down the execution significantly.  If @var{final} has side
-effects, executing it more than once is probably incorrect.
+Here's an equivalent definition simplified through use of backquote:
+
+@smallexample
+@group
+(defmacro for (var from init to final do &rest body)
+  "Execute a simple \"for\" loop.
+For example, (for i from 1 to 10 do (print i))."
+  (` (let (((, var) (, init)))
+        (while (<= (, var) (, final))
+          (,@@ body)
+          (inc (, var))))))
+@end group
+@end smallexample
+
+Both forms of this definition (with backquote and without) suffer from
+the defect that @var{final} is evaluated on every iteration.  If
+@var{final} is a constant, this is not a problem.  If it is a more
+complex form, say @code{(long-complex-calculation x)}, this can slow
+down the execution significantly.  If @var{final} has side effects,
+executing it more than once is probably incorrect.
 
 @cindex macro argument evaluation
 A well-designed macro definition takes steps to avoid this problem by
@@ -475,11 +491,12 @@ the binding made by @code{for}.
 
 The way to correct this is to use an uninterned symbol instead of
 @code{max} (@pxref{Creating Symbols}).  The uninterned symbol can be
-bound and referred to just like any other symbol, but since it is created
-by @code{for}, we know that it cannot appear in the user's program.
-Since it is not interned, there is no way the user can put it into the
-program later.  It will never appear anywhere except where put by
-@code{for}.  Here is a definition of @code{for} which works this way:
+bound and referred to just like any other symbol, but since it is
+created by @code{for}, we know that it cannot already appear in the
+user's program.  Since it is not interned, there is no way the user can
+put it into the program later.  It will never appear anywhere except
+where put by @code{for}.  Here is a definition of @code{for} that works
+this way:
 
 @smallexample
 @group
diff --git a/lispref/variables.texi b/lispref/variables.texi
index 2b12607d488..ffee1a39c45 100644
--- a/lispref/variables.texi
+++ b/lispref/variables.texi
@@ -20,7 +20,7 @@ symbol.  The use of a symbol as a variable is independent of its use as
 a function name.  @xref{Symbol Components}.
 
   The Lisp objects that constitute a Lisp program determine the textual
-form of the program--it is simply the read syntax for those Lisp
+form of the program---it is simply the read syntax for those Lisp
 objects.  This is why, for example, a variable in a textual Lisp program
 is written using the read syntax for the symbol that represents the
 variable.
@@ -166,7 +166,7 @@ binding.
 local bindings.
 
 @defspec let (bindings@dots{}) forms@dots{}
-This function binds variables according to @var{bindings} and then
+This special form binds variables according to @var{bindings} and then
 evaluates all of the @var{forms} in textual order.  The @code{let}-form
 returns the value of the last form in @var{forms}.
 
@@ -217,7 +217,7 @@ form.  Compare the following example with the example above for
 @end example
 @end defspec
 
-  Here is a complete list of the other facilities which create local
+  Here is a complete list of the other facilities that create local
 bindings:
 
 @itemize @bullet
@@ -365,9 +365,11 @@ more precisely, if its current binding is not void.  It returns
 
 @node Defining Variables
 @section Defining Global Variables
+@cindex variable definition
 
   You may announce your intention to use a symbol as a global variable
-with a definition, using @code{defconst} or @code{defvar}.
+with a @dfn{variable definition}: a special form, either @code{defconst}
+or @code{defvar}.
 
   In Emacs Lisp, definitions serve three purposes.  First, they inform
 people who read the code that certain symbols are @emph{intended} to be
@@ -381,7 +383,7 @@ variables in a program.
 a matter of intent, serving to inform human readers of whether programs
 will change the variable.  Emacs Lisp does not restrict the ways in
 which a variable can be used based on @code{defconst} or @code{defvar}
-declarations.  However, it also makes a difference for initialization:
+declarations.  However, it does make a difference for initialization:
 @code{defconst} unconditionally initializes the variable, while
 @code{defvar} initializes it only if it is void.
 
@@ -518,7 +520,7 @@ pi
 
 @defun user-variable-p variable
 @cindex user option
-This function returns @code{t} if @var{variable} is a user option--- a
+This function returns @code{t} if @var{variable} is a user option---a
 variable intended to be set by the user for customization---and
 @code{nil} otherwise.  (Variables other than user options exist for the
 internal purposes of Lisp programs, and users need not know about them.)
@@ -647,8 +649,7 @@ This function sets @var{symbol}'s value to @var{value}, then returns
 @var{symbol} is evaluated to obtain the symbol to set.
 
 The most-local existing binding of the variable is the binding that is
-set; shadowed bindings are not affected.  If @var{symbol} is not
-actually a symbol, a @code{wrong-type-argument} error is signaled.
+set; shadowed bindings are not affected.
 
 @example
 @group
@@ -681,18 +682,26 @@ one
 @end group
 @end example
 
+If @var{symbol} is not actually a symbol, a @code{wrong-type-argument}
+error is signaled.
+
+@example
+(set '(x y) 'z)
+@error{} Wrong type argument: symbolp, (x y)
+@end example
+
 Logically speaking, @code{set} is a more fundamental primitive than
 @code{setq}.  Any use of @code{setq} can be trivially rewritten to use
 @code{set}; @code{setq} could even be defined as a macro, given the
 availability of @code{set}.  However, @code{set} itself is rarely used;
-beginners hardly need to know about it.  It is needed for choosing which
-variable to set is made at run time.  For example, the command
+beginners hardly need to know about it.  It is useful only for choosing
+at run time which variable to set.  For example, the command
 @code{set-variable}, which reads a variable name from the user and then
 sets the variable, needs to use @code{set}.
 
 @cindex CL note---@code{set} local
 @quotation
-@b{Common Lisp note:} in Common Lisp, @code{set} always changes the
+@b{Common Lisp note:} In Common Lisp, @code{set} always changes the
 symbol's special value, ignoring any lexical bindings.  In Emacs Lisp,
 all variables and all bindings are (in effect) special, so @code{set}
 always affects the most local existing binding.
@@ -726,7 +735,7 @@ located textually within the function or block that binds the variable.
 @cindex CL note---special variables
 @quotation
 @b{Common Lisp note:} variables declared ``special'' in Common Lisp
-are dynamically scoped like variables in Emacs Lisp.
+are dynamically scoped, like variables in Emacs Lisp.
 @end quotation
 
 @menu
@@ -1012,7 +1021,7 @@ But @code{save-excursion} as shown here avoids the problem:
 buffer-local binding of buffer @samp{b}.
 
   When a file specifies local variable values, these become buffer-local
-value when you visit the file.  @xref{Auto Major Mode}.
+values when you visit the file.  @xref{Auto Major Mode}.
 
 @node Creating Buffer-Local
 @subsection Creating and Deleting Buffer-Local Bindings
@@ -1116,6 +1125,10 @@ buffer.  However, if you set the variable again, that will once again
 create a local binding for it.
 
 @code{kill-local-variable} returns @var{variable}.
+
+This function is a command because it is sometimes useful to kill one
+buffer-local variable interactively, just as it is useful to create
+buffer-local variables interactively.
 @end deffn
 
 @defun kill-all-local-variables
@@ -1156,7 +1169,7 @@ change a variable's default value regardless of whether the current
 buffer has a buffer-local binding.  For example, you could use
 @code{setq-default} to change the default setting of
 @code{paragraph-start} for most buffers; and this would work even when
-you are in a C or Lisp mode buffer which has a buffer-local value for
+you are in a C or Lisp mode buffer that has a buffer-local value for
 this variable.
 
 @c Emacs 19 feature
@@ -1172,8 +1185,8 @@ variable.  If @var{symbol} is not buffer-local, this is equivalent to
 @end defun
 
 @c Emacs 19 feature
-@defun default-boundp variable
-The function @code{default-boundp} tells you whether @var{variable}'s
+@defun default-boundp symbol
+The function @code{default-boundp} tells you whether @var{symbol}'s
 default value is nonvoid.  If @code{(default-boundp 'foo)} returns
 @code{nil}, then @code{(default-value 'foo)} would get an error.