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.

4 files changed, 29 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
diff --git a/src/ChangeLog b/src/ChangeLog
index 6e0a01bcbae..8a521a585b6 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,7 @@
+2013-12-23  Glenn Morris  <rgm@gnu.org>
+
+        * lread.c (Fload): Mention load-prefer-newer in doc.
+
 2013-12-22  Martin Rudalics  <rudalics@gmx.at>
 
         Handle Bug#16207 by being more restrictive when running hooks.
diff --git a/src/lread.c b/src/lread.c
index 1db3a47ef0a..a6181b0cb85 100644
--- a/src/lread.c
+++ b/src/lread.c
@@ -1029,6 +1029,10 @@ in `load-file-rep-suffixes'.  If MUST-SUFFIX is non-nil, only the
 return value of `get-load-suffixes' is used, i.e. the file name is
 required to have a non-empty suffix.
 
+When searching suffixes, this function normally stops at the first
+one that exists.  If the option `load-prefer-newer' is non-nil,
+however, it tries all suffixes, and uses whichever file is the newest.
+
 Loading a file records its definitions, and its `provide' and
 `require' calls, in an element of `load-history' whose
 car is the file name loaded.  See `load-history'.