* loading.texi (Library Search): Document list-load-path-shadows (Bug#7757).

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 865594d..7e6e7b4 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2011-01-23  Chong Yidong  <cyd@stupidchicken.com>
+            Richard Kim  <emacs18@gmail.com>
+
+       * loading.texi (Library Search): Document list-load-path-shadows
+       (Bug#7757).
+
 2011-01-23  Chong Yidong  <cyd@stupidchicken.com>
 
        * searching.texi (Regexp Special): Remove outdated discussion of

diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index a670f92..ca06f84 100644 (file)
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -363,6 +363,31 @@ interactively, the argument @var{interactive-call} is @code{t}, and this
 tells @code{locate-library} to display the file name in the echo area.
 @end deffn
 
+@cindex shadowed Lisp files
+@deffn Command list-load-path-shadows &optional stringp
+This command shows a list of @dfn{shadowed} Emacs Lisp files.  A
+shadowed file is one that will not normally be loaded, despite being
+in a directory on @code{load-path}, due to the existence of another
+similarly-named file in a directory earlier on @code{load-path}.
+
+For instance, suppose @code{load-path} is set to
+
+@smallexample
+  ("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp")
+@end smallexample
+
+@noindent
+and that both these directories contain a file named @file{foo.el}.
+Then @code{(require 'foo)} never loads the file in the second
+directory.  Such a situation might indicate a problem in the way Emacs
+was installed.
+
+When called from Lisp, this function prints a message listing the
+shadowed files, instead of displaying them in a buffer.  If the
+optional argument @code{stringp} is non-@code{nil}, it instead returns
+the shadowed files as a string.
+@end deffn
+
 @node Loading Non-ASCII
 @section Loading Non-@acronym{ASCII} Characters