[Emacs-diffs] /srv/bzr/emacs/emacs-24 r110906: Document eager macro expansion

[Glenn Morris]

------------------------------------------------------------
revno: 110906
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Sat 2012-11-17 17:38:42 -0800
message:
  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.
modified:
  doc/lispref/ChangeLog
  doc/lispref/loading.texi
  doc/lispref/macros.texi
  etc/NEWS

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-11-17 22:45:24 +0000
+++ b/doc/lispref/ChangeLog     2012-11-18 01:38:42 +0000
@@ -1,3 +1,8 @@
+2012-11-18  Glenn Morris  <address@hidden>
+
+       * loading.texi (How Programs Do Loading): Add eager macro expansion.
+       * macros.texi (Expansion): Mention eager macro expansion.
+
 2012-11-17  Glenn Morris  <address@hidden>
 
        * minibuf.texi (Basic Completion): Mention misc completion-table funcs.

=== modified file 'doc/lispref/loading.texi'
--- a/doc/lispref/loading.texi  2012-10-31 20:59:04 +0000
+++ b/doc/lispref/loading.texi  2012-11-18 01:38:42 +0000
@@ -113,6 +113,25 @@
 character set translation just as Emacs would do when visiting the file.
 @xref{Coding Systems}.
 
address@hidden This is referred to from the Macros chapter.
address@hidden Not sure if it should be the other way round.
address@hidden 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
address@hidden 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 address@hidden)
+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
 address@hidden

=== modified file 'doc/lispref/macros.texi'
--- a/doc/lispref/macros.texi   2012-10-15 04:03:04 +0000
+++ b/doc/lispref/macros.texi   2012-11-18 01:38:42 +0000
@@ -86,6 +86,10 @@
 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}.
 

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-11-17 22:45:24 +0000
+++ b/etc/NEWS  2012-11-18 01:38:42 +0000
@@ -923,13 +923,13 @@
 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:
 +++