Document eager macro expansion

* doc/lispref/loading.texi (How Programs Do Loading): Add eager macro expansion.
* doc/lispref/macros.texi (Expansion): Mention eager macro expansion.

* etc/NEWS: Related edit.

4 files changed, 34 insertions, 6 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index da82ece39c1..43ca9ac4aa5 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2012-11-18  Glenn Morris  <rgm@gnu.org>
+
+        * loading.texi (How Programs Do Loading): Add eager macro expansion.
+        * macros.texi (Expansion): Mention eager macro expansion.
+
 2012-11-17  Glenn Morris  <rgm@gnu.org>
 
         * minibuf.texi (Basic Completion): Mention misc completion-table funcs.
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 3a511d34829..54acd0b4d4c 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -113,6 +113,25 @@ When loading a source file (not compiled), @code{load} performs
 character set translation just as Emacs would do when visiting the file.
 @xref{Coding Systems}.
 
+@c This is referred to from the Macros chapter.
+@c Not sure if it should be the other way round.
+@cindex eager macro expansion
+When loading an uncompiled file, Emacs tries to expand any macros
+that the file contains (@pxref{Macros}).  We refer to this as
+@dfn{eager macro expansion}.  Doing this (rather than deferring
+the expansion until the relevant code runs) can significantly speed
+up the execution of uncompiled code.  Sometimes, this macro expansion
+cannot be done, owing to a cyclic dependency.  In the simplest
+example of this, the file you are loading refers to a macro defined
+in another file, and that file in turn requires the file you are
+loading.  This is generally harmless.  Emacs prints a warning
+(@samp{Eager macro-expansion skipped due to cycle@dots{}})
+giving details of the problem, but it still loads the file, just
+leaving the macro unexpanded for now.  You may wish to restructure
+your code so that this does not happen.  Loading a compiled file does
+not cause macroexpansion, because this should already have happened
+during compilation.  @xref{Compiling Macros}.
+
 Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
 in the echo area during loading unless @var{nomessage} is
 non-@code{nil}.
diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi
index 8be6a3fbcde..b0dee1bf215 100644
--- a/doc/lispref/macros.texi
+++ b/doc/lispref/macros.texi
@@ -86,6 +86,10 @@ macro.
 calls to other macros.  It may even be a call to the same macro, though
 this is unusual.
 
+  Note that Emacs tries to expand macros when loading an uncompiled
+Lisp file.  This is not always possible, but if it is, it speeds up
+subsequent execution.  @xref{How Programs Do Loading}.
+
   You can see the expansion of a given macro call by calling
 @code{macroexpand}.
 
diff --git a/etc/NEWS b/etc/NEWS
index f518605b572..388af4a7d40 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -923,13 +923,13 @@ Previously, they returned NaNs on some platforms but signaled errors
 on others.  The affected functions are acos, asin, tan, exp, expt,
 log, log10, sqrt, and mod.
 
-** Interpreted files are eagerly macro-expanded during load.
++++
+** Emacs tries to macroexpand interpreted (non-compiled) files during load.
 This can significantly speed up execution of non-byte-compiled code,
-but can also bump into harmless and previously unnoticed cyclic
-dependencies.  These should not be fatal: they will simply cause the
-macro-calls to be left for later expansion (as before), but will also
-result in a warning ("Eager macro-expansion skipped due to cycle")
-describing the cycle.
+but can also bump into previously unnoticed cyclic dependencies.
+These are generally harmless: they will simply cause the macro calls
+to be left for later expansion (as before), but will result in a
+warning ("Eager macro-expansion skipped due to cycle") describing the cycle.
 
 ** Miscellaneous new functions:
 +++