[Emacs-diffs] /srv/bzr/emacs/emacs-23 r99685: Document `after-load-functions'.

[Chong Yidong]

------------------------------------------------------------
revno: 99685
committer: Chong Yidong <address@hidden>
branch nick: emacs-23
timestamp: Fri 2010-03-26 13:43:01 -0400
message:
  Document `after-load-functions'.
  
  * loading.texi (Hooks for Loading): Document after-load-functions.
  Copyedits.
modified:
  doc/lispref/ChangeLog
  doc/lispref/loading.texi
  etc/NEWS

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2010-03-24 00:16:45 +0000
+++ b/doc/lispref/ChangeLog     2010-03-26 17:43:01 +0000
@@ -1,3 +1,8 @@
+2010-03-26  Chong Yidong  <address@hidden>
+
+       * loading.texi (Hooks for Loading): Document after-load-functions.
+       Copyedits.
+
 2010-03-24  Arni Magnusson  <address@hidden>  (tiny change)
 
        * frames.texi (Cursor Parameters): Fix typo.  (Bug#5760)

=== modified file 'doc/lispref/loading.texi'
--- a/doc/lispref/loading.texi  2010-01-13 08:35:10 +0000
+++ b/doc/lispref/loading.texi  2010-03-26 17:43:01 +0000
@@ -920,8 +920,17 @@
 @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}:
+
address@hidden 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.
address@hidden 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 @@
 Don't forget to quote @var{form}!
 
 You don't need to give a directory or extension in the file name
address@hidden you just give a bare file name, like this:
address@hidden  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 @@
 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
address@hidden  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} @address@hidden)
 @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
address@hidden 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

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2010-03-26 00:04:48 +0000
+++ b/etc/NEWS  2010-03-26 17:43:01 +0000
@@ -321,7 +321,7 @@
 *** 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 @@
 *** 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