changeset 62856:19deaa395e85

(Locating Files): Clean up the text.

--- a/lispref/files.texi	Sun May 29 08:25:17 2005 +0000
+++ b/lispref/files.texi	Sun May 29 08:27:37 2005 +0000
@@ -1261,36 +1261,36 @@
 @cindex locate files
 @cindex find files
 
-  Sometimes, you need to find a file that could reside in one of the
-standard directories.  One example is when you need to look for a
-program's executable file, e.g., to find out whether a given program
-is installed on the user's system.  Another example is the search for
+  This section explains how to search for a file in a list of
+directories.  One example is when you need to look for a program's
+executable file, e.g., to find out whether a given program is
+installed on the user's system.  Another example is the search for
 Lisp libraries (@pxref{Library Search}).  Such searches generally need
-to try several alternative file name extensions, in addition to
-looking in every standard directory where the file could be found.
-Emacs provides a function for such a generalized search for a file.
+to try various possible file name extensions, in addition to various
+possible directories.  Emacs provides a function for such a
+generalized search for a file.
 
 @defun locate-file filename path &optional suffixes predicate
-This function searches for the file whose name is @var{filename} in
-a list of directories given by @var{path}.  If it finds the file, it
-returns its full @dfn{absolute file name} (@pxref{Relative File
-Names}); if the file is not found, the function returns @code{nil}.
+This function searches for a file whose name is @var{filename} in a
+list of directories given by @var{path}, trying the suffixes in
+@var{suffixes}.  If it finds such a file, it returns the full
+@dfn{absolute file name} of the file (@pxref{Relative File Names});
+otherwise it returns @code{nil}.
 
 The optional argument @var{suffixes} gives the list of file-name
-suffixes to append to @var{filename} when searching.  If
-@var{suffixes} is @code{nil}, it's equivalent to passing a list with a
-single element that is an empty string @code{""}.
-
-Typical values of @var{path} are @code{exec-path} (@pxref{Subprocess
+suffixes to append to @var{filename} when searching.
+@code{locate-file} tries each possible directory with each of these
+suffixes.  If @var{suffixes} is @code{nil}, or @code{("")}, then there
+are no suffixes, and @var{filename} is used only as-is.  Typical
+values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess
+Creation, exec-suffixes}) and @code{load-suffixes} (@pxref{Library
+Search, load-suffixes}).
+
+Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess
 Creation, exec-path}) when looking for executable programs or
 @code{load-path} (@pxref{Library Search, load-path}) when looking for
-Lisp files.  Use @code{("/")} to disable the path search (e.g., if
-@var{filename} already includes the leading directories), but still
-try the extensions in @var{suffixes}.
-
-Typical values of @var{suffixes} are @code{exec-suffixes}
-(@pxref{Subprocess Creation, exec-suffixes}) and @code{load-suffixes}
-(@pxref{Library Search, load-suffixes}).
+Lisp files.  If @var{filename} is absolute, @var{path} has no effect,
+but the suffixes in @var{suffixes} are still tried.
 
 The optional argument @var{predicate}, if non-@code{nil}, specifies
 the predicate function to use for testing whether a candidate file is
@@ -1316,7 +1316,6 @@
 @code{exec-suffixes}.
 @end defun
 
-
 @node Changing Files
 @section Changing File Names and Attributes
 @cindex renaming files