(Hooks for Loading): Make the description of `eval-after-load' more

detailed, and amend the description of after-load-alist, in accordance
with changes from 2006-05.

1 files changed, 29 insertions, 13 deletions

diff --git a/lispref/loading.texi b/lispref/loading.texi
index 004989ad38a..3d294b2cc21 100644
--- a/lispref/loading.texi
+++ b/lispref/loading.texi
@@ -903,14 +903,29 @@ You can ask for code to be executed if and when a particular library is
 loaded, by calling @code{eval-after-load}.
 
 @defun eval-after-load library form
-This function arranges to evaluate @var{form} at the end of loading the
-library @var{library}, if and when @var{library} is loaded.  If
+This function arranges to evaluate @var{form} at the end of loading
+the file @var{library}, each time @var{library} is loaded.  If
 @var{library} is already loaded, it evaluates @var{form} right away.
+Don't forget to quote @var{form}!
 
-If @var{library} is a string, it must exactly match the argument of
-@code{load} used to load the library.  To get the proper results when an
-installed library is found by searching @code{load-path}, you should not
-include any directory names in @var{library}.
+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:
+
+@example
+(eval-after-load "edebug" '(def-edebug-spec c-point t))
+@end example
+
+To restrict which files can trigger the evaluation, include a
+directory or an extension or both in @var{library}.  Only a file whose
+absolute true name (i.e., the name with all symbolic links chased out)
+matches all the given name components will match.  In the following
+example, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory
+@code{..../foo/bar} will trigger the evaluation, but not
+@file{my_inst.el}:
+
+@example
+(eval-after-load "foo/bar/my_inst.elc" @dots{})
+@end example
 
 @var{library} can also be a feature (i.e.@: a symbol), in which case
 @var{form} is evaluated when @code{(provide @var{library})} is called.
@@ -932,19 +947,20 @@ customizations if you don't feel they must meet the design standards for
 programs meant for wider use.
 
 @defvar after-load-alist
-This variable holds an alist of expressions to evaluate if and when
-particular libraries are loaded.  Each element looks like this:
+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:
 
 @example
-(@var{filename} @var{forms}@dots{})
+(@var{regexp-or-feature} @var{forms}@dots{})
 @end example
 
-The function @code{load} checks @code{after-load-alist} in order to
-implement @code{eval-after-load}.
+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 the absolute true name of the file being
+@code{load}ed or the symbol being @code{provide}d.
 @end defvar
 
-@c Emacs 19 feature
-
 @ignore
    arch-tag: df731f89-0900-4389-a436-9105241b6f7a
 @end ignore