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

2 files changed, 31 insertions, 0 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 865594de371..7e6e7b41813 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,4 +1,10 @@
 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
 	character sets (Bug#7780).
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index a670f92d26e..ca06f847fb9 100644
--- 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