[Emacs-diffs] /srv/bzr/emacs/emacs-23 r100405: * loading.texi (Library Search): Document list-load-path-shadows (Bug#7757).

[Chong Yidong]

------------------------------------------------------------
revno: 100405
committer: Chong Yidong <address@hidden>
branch nick: emacs-23
timestamp: Sun 2011-01-23 15:34:12 -0500
message:
  * loading.texi (Library Search): Document list-load-path-shadows (Bug#7757).
modified:
  doc/lispref/ChangeLog
  doc/lispref/loading.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2011-01-23 01:12:25 +0000
+++ b/doc/lispref/ChangeLog     2011-01-23 20:34:12 +0000
@@ -1,4 +1,10 @@
 2011-01-23  Chong Yidong  <address@hidden>
+            Richard Kim  <address@hidden>
+
+       * loading.texi (Library Search): Document list-load-path-shadows
+       (Bug#7757).
+
+2011-01-23  Chong Yidong  <address@hidden>
 
        * searching.texi (Regexp Special): Remove outdated discussion of
        character sets (Bug#7780).

=== modified file 'doc/lispref/loading.texi'
--- a/doc/lispref/loading.texi  2011-01-02 23:50:46 +0000
+++ b/doc/lispref/loading.texi  2011-01-23 20:34:12 +0000
@@ -363,6 +363,31 @@
 tells @code{locate-library} to display the file name in the echo area.
 @end deffn
 
address@hidden shadowed Lisp files
address@hidden 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
+
address@hidden
+  ("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp")
address@hidden smallexample
+
address@hidden
+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 address@hidden, it instead returns
+the shadowed files as a string.
address@hidden deffn
+
 @node Loading Non-ASCII
 @section Loading address@hidden Characters