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.

3 files changed, 28 insertions, 0 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}.