From: Chong Yidong <cyd@stupidchicken.com>
Date: Sun, 23 Jan 2011 20:34:12 +0000 (-0500)
Subject: * loading.texi (Library Search): Document list-load-path-shadows (Bug#7757).
X-Git-Tag: emacs-pretest-23.2.93~34
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=e6cf7a82721b44da3cda83d7267e400ab6a29b98;p=emacs.git

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

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 865594de371..7e6e7b41813 100644
--- 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 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