1 files changed, 14 insertions, 14 deletions
diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi
index e56a85c7478..cf23ecb9d4e 100644
--- a/doc/lispref/macros.texi
+++ b/doc/lispref/macros.texi
@@ -241,7 +241,6 @@ of constants and nonconstant parts.  To make this easier, use the
 @samp{`} syntax (@pxref{Backquote}).  For example:
 
 @example
-@example
 @group
 (defmacro t-becomes-nil (variable)
   `(if (eq ,variable t)
@@ -253,7 +252,6 @@ of constants and nonconstant parts.  To make this easier, use the
      @equiv{} (if (eq foo t) (setq foo nil))
 @end group
 @end example
-@end example
 
 @node Problems with Macros
 @section Common Problems Using Macros
@@ -480,12 +478,16 @@ in expressions ordinarily.
 
   Another problem can happen if the macro definition itself
 evaluates any of the macro argument expressions, such as by calling
-@code{eval} (@pxref{Eval}).  If the argument is supposed to refer to the
-user's variables, you may have trouble if the user happens to use a
-variable with the same name as one of the macro arguments.  Inside the
-macro body, the macro argument binding is the most local binding of this
-variable, so any references inside the form being evaluated do refer to
-it.  Here is an example:
+@code{eval} (@pxref{Eval}).  You have to take into account that macro
+expansion may take place long before the code is executed, when the
+context of the caller (where the macro expansion will be evaluated) is
+not yet accessible.
+
+  Also, if your macro definition does not use @code{lexical-binding}, its
+formal arguments may hide the user's variables of the same name.  Inside
+the macro body, the macro argument binding is the most local binding of
+such variable, so any references inside the form being evaluated do refer
+to it.  Here is an example:
 
 @example
 @group
@@ -508,12 +510,10 @@ it.  Here is an example:
 @code{x}, because @code{a} conflicts with the macro argument variable
 @code{a}.
 
-  Another problem with calling @code{eval} in a macro definition is that
-it probably won't do what you intend in a compiled program.  The
-byte compiler runs macro definitions while compiling the program, when
-the program's own computations (which you might have wished to access
-with @code{eval}) don't occur and its local variable bindings don't
-exist.
+  Also, the expansion of @code{(foo x)} above will return something
+different or signal an error when the code is compiled, since in that case
+@code{(foo x)} is expanded during compilation, whereas the execution of
+@code{(setq x 'b)} will only take place later when the code is executed.
 
   To avoid these problems, @strong{don't evaluate an argument expression
 while computing the macro expansion}.  Instead, substitute the