Document `after-load-functions'.

* loading.texi (Hooks for Loading): Document after-load-functions.
Copyedits.

3 files changed, 34 insertions, 21 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 29c3980a2b5..fd5fe0e5262 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2010-03-26  Chong Yidong  <cyd@stupidchicken.com>
+
+        * loading.texi (Hooks for Loading): Document after-load-functions.
+        Copyedits.
+
 2010-03-24  Arni Magnusson  <arnima@hafro.is>  (tiny change)
 
         * frames.texi (Cursor Parameters): Fix typo.  (Bug#5760)
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 38bc9c4d0e8..ec10c51b236 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -920,8 +920,17 @@ library, to remove functions defined in the library.
 @cindex loading hooks
 @cindex hooks for loading
 
-You can ask for code to be executed if and when a particular library is
-loaded, by calling @code{eval-after-load}.
+You can ask for code to be executed each time Emacs loads a library,
+by using the variable @code{after-load-functions}:
+
+@defvar after-load-functions
+This abnormal hook is run after loading a file.  Each function in the
+hook is called with a single argument, the absolute filename of the
+file that was just loaded.
+@end defvar
+
+If you want code to be executed when a @emph{particular} library is
+loaded, use the function @code{eval-after-load}:
 
 @defun eval-after-load library form
 This function arranges to evaluate @var{form} at the end of loading
@@ -930,7 +939,7 @@ the file @var{library}, each time @var{library} is loaded.  If
 Don't forget to quote @var{form}!
 
 You don't need to give a directory or extension in the file name
-@var{library}---normally you just give a bare file name, like this:
+@var{library}.  Normally, you just give a bare file name, like this:
 
 @example
 (eval-after-load "edebug" '(def-edebug-spec c-point t))
@@ -955,31 +964,30 @@ An error in @var{form} does not undo the load, but does prevent
 execution of the rest of @var{form}.
 @end defun
 
-In general, well-designed Lisp programs should not use this feature.
-The clean and modular ways to interact with a Lisp library are (1)
-examine and set the library's variables (those which are meant for
-outside use), and (2) call the library's functions.  If you wish to
-do (1), you can do it immediately---there is no need to wait for when
-the library is loaded.  To do (2), you must load the library (preferably
-with @code{require}).
+Normally, well-designed Lisp programs should not use
+@code{eval-after-load}.  If you need to examine and set the variables
+defined in another library (those meant for outside use), you can do
+it immediately---there is no need to wait until the library is loaded.
+If you need to call functions defined by that library, you should load
+the library, preferably with @code{require} (@pxref{Named Features}).
 
 But it is OK to use @code{eval-after-load} in your personal
-customizations if you don't feel they must meet the design standards for
-programs meant for wider use.
+customizations if you don't feel that they must meet the design
+standards for programs meant for wider use.
 
 @defvar after-load-alist
-This variable, an alist built by @code{eval-after-load}, holds the
-expressions to evaluate when particular libraries are loaded.  Each
-element looks like this:
+This variable stores an alist built by @code{eval-after-load},
+containing the expressions to evaluate when certain libraries are
+loaded.  Each element looks like this:
 
 @example
 (@var{regexp-or-feature} @var{forms}@dots{})
 @end example
 
 The key @var{regexp-or-feature} is either a regular expression or a
-symbol, and the value is a list of forms.  The forms are evaluated when
-the key matches the absolute true name of the file being
-@code{load}ed or the symbol being @code{provide}d.
+symbol, and the value is a list of forms.  The forms are evaluated
+when the key matches the absolute true name or feature name of the
+library being loaded.
 @end defvar
 
 @ignore
diff --git a/etc/NEWS b/etc/NEWS
index 0ab134b2e7c..9a02a221c5a 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -321,7 +321,7 @@ advantage of this feature.
 *** The log command in vc-annotate can display a single log entry
 instead of redisplaying the full log.  The RCS, CVS and SCCS VC
 backends do not support this.
-
+---
 *** When a file is not found, VC will not try to check it out of RCS anymore.
 
 *** Diff and log operations can be used from Dired buffers.
@@ -530,9 +530,9 @@ file name handlers such as Tramp to optimizations.
 *** make-network-process can now also create `seqpacket' Unix sockets.
 
 ** Loading changes
-
+---
 *** eval-next-after-load is obsolete.
-
++++
 *** New hook `after-load-functions' run after loading an Elisp file.
 
 ** Byte compilation changes