Document `load-prefer-newer'.

[bpt/emacs.git] / doc / emacs / building.texi

diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi
index fdb38bf..1df4dcd 100644 (file)
--- a/doc/emacs/building.texi
+++ b/doc/emacs/building.texi
@@ -1348,6 +1348,7 @@ not from an existing Emacs buffer.
 
 @findex load
 @findex load-library
+@vindex load-prefer-newer
 @cindex load path for Emacs Lisp
   If an Emacs Lisp file is installed in the Emacs Lisp @dfn{load path}
 (defined below), you can load it by typing @kbd{M-x load-library},
@@ -1356,15 +1357,17 @@ command prompts for a @dfn{library name} rather than a file name; it
 searches through each directory in the Emacs Lisp load path, trying to
 find a file matching that library name.  If the library name is
 @samp{@var{foo}}, it tries looking for files named
-@file{@var{foo}.elc}, @file{@var{foo}.el}, and lastly just
-@file{@var{foo}}; the first one found is loaded.  This command prefers
-@file{.elc} files over @file{.el} files because compiled files load
-and run faster.  If it finds that @file{@var{lib}.el} is newer than
-@file{@var{lib}.elc}, it issues a warning, in case someone made
+@file{@var{foo}.elc}, @file{@var{foo}.el}, and @file{@var{foo}}.  The
+default behaviour is to load the first file found.  This command
+prefers @file{.elc} files over @file{.el} files because compiled files
+load and run faster.  If it finds that @file{@var{lib}.el} is newer
+than @file{@var{lib}.elc}, it issues a warning, in case someone made
 changes to the @file{.el} file and forgot to recompile it, but loads
 the @file{.elc} file anyway.  (Due to this behavior, you can save
 unfinished edits to Emacs Lisp source files, and not recompile until
-your changes are ready for use.)
+your changes are ready for use.)  However setting
+@code{load-prefer-newer} to a non-@code{nil} value will Emacs load the
+newest version of the file found.
 
   Emacs Lisp programs usually load Emacs Lisp files using the
 @code{load} function.  This is similar to @code{load-library}, but is