Some documenting of load-prefer-newer

* doc/lispref/loading.texi (How Programs Do Loading, Load Suffixes):
Mention `load-prefer-newer'.

* src/lread.c (Fload): Mention load-prefer-newer in doc.

2 files changed, 21 insertions, 5 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 96fdb94ca20..dbe148dbcf8 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,6 +1,12 @@
+2013-12-23  Glenn Morris  <rgm@gnu.org>
+
+        * loading.texi (How Programs Do Loading, Load Suffixes):
+        Mention `load-prefer-newer'.
+
 2013-12-22  Xue Fuqiao  <xfq.free@gmail.com>
 
-        * hash.texi (Other Hash): Document `hash-table-keys and `hash-table-values'.
+        * hash.texi (Other Hash): Document `hash-table-keys'
+        and `hash-table-values'.
 
 2013-12-22  Eli Zaretskii  <eliz@gnu.org>
 
@@ -15,11 +21,11 @@
 
         * text.texi (Examining Properties): Document `get-pos-property'.
 
-        * variables.texi (Directory Local Variables): Document
-        `enable-dir-local-variables'.
+        * variables.texi (Directory Local Variables):
+        Document `enable-dir-local-variables'.
 
-        * debugging.texi (Debugger Commands): Document
-        `debugger-toggle-locals'.
+        * debugging.texi (Debugger Commands):
+        Document `debugger-toggle-locals'.
 
 2013-12-21  Chong Yidong  <cyd@gnu.org>
 
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 48866a10687..d1bcfd26a0b 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -93,6 +93,10 @@ If the optional argument @var{must-suffix} is non-@code{nil}, then
 @samp{.el} or @samp{.elc} (possibly extended with a compression
 suffix), unless it contains an explicit directory name.
 
+If the option @code{load-prefer-newer} is non-@code{nil}, then when
+searching suffixes, @code{load} selects whichever version of a file
+(@samp{.elc}, @samp{.el}, etc.) has been modified most recently.
+
 If @var{filename} is a relative file name, such as @file{foo} or
 @file{baz/foo.bar}, @code{load} searches for the file using the variable
 @code{load-path}.  It appends @var{filename} to each of the directories
@@ -246,6 +250,12 @@ value of @code{(get-load-suffixes)} and then those in
 it skips the former group, and if @var{must-suffix} is non-@code{nil},
 it skips the latter group.
 
+@defopt load-prefer-newer
+If this option is non-@code{nil}, then rather than stopping at the
+first suffix that exists, @code{load} tests them all, and uses
+whichever file is the newest.
+@end defopt
+
 @node Library Search
 @section Library Search
 @cindex library search