Clarify that load-path contents should be directory file names

* doc/lispref/files.texi (Directory Names): Define and use "directory
file name". Recommend `expand-file-name'.

* src/lread.c (load-path): Fix doc string; elements are directory file
names.

2 files changed, 34 insertions, 22 deletions

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index ca8abe54ace..65a97a46699 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2038,32 +2038,35 @@ forward slash (@samp{/}) character.
 @node Directory Names
 @subsection Directory Names
 @cindex directory name
+@cindex directory file name
 @cindex file name of directory
 
   A @dfn{directory name} is the name of a directory.  A directory is
-actually a kind of file, so it has a file name, which is related to
-the directory name but not identical to it.  (This is not quite the
-same as the usual Unix terminology.)  These two different names for
-the same entity are related by a syntactic transformation.  On GNU and
-Unix systems, this is simple: a directory name ends in a slash,
-whereas the directory's name as a file lacks that slash.  On MS-DOS
-the relationship is more complicated.
-
-  The difference between a directory name and its name as a file is
+actually a kind of file, so it has a file name (called the
+@dfn{directory file name}, which is related to the directory name but
+not identical to it.  (This is not quite the same as the usual Unix
+terminology.)  These two different names for the same entity are
+related by a syntactic transformation.  On GNU and Unix systems, this
+is simple: a directory name ends in a slash, whereas the directory
+file name lacks that slash.  On MS-DOS the relationship is more
+complicated.
+
+  The difference between directory name and directory file name is
 subtle but crucial.  When an Emacs variable or function argument is
-described as being a directory name, a file name of a directory is not
+described as being a directory name, a directory file name is not
 acceptable.  When @code{file-name-directory} returns a string, that is
 always a directory name.
 
-  The following two functions convert between directory names and file
-names.  They do nothing special with environment variable substitutions
-such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}.
+  The following two functions convert between directory names and
+directory file names.  They do nothing special with environment
+variable substitutions such as @samp{$HOME}, and the constructs
+@samp{~}, @samp{.} and @samp{..}.
 
 @defun file-name-as-directory filename
 This function returns a string representing @var{filename} in a form
-that the operating system will interpret as the name of a directory.  On
-most systems, this means appending a slash to the string (if it does not
-already end in one).
+that the operating system will interpret as the name of a directory (a
+directory name).  On most systems, this means appending a slash to the
+string (if it does not already end in one).
 
 @example
 @group
@@ -2074,10 +2077,10 @@ already end in one).
 @end defun
 
 @defun directory-file-name dirname
-This function returns a string representing @var{dirname} in a form that
-the operating system will interpret as the name of a file.  On most
-systems, this means removing the final slash (or backslash) from the
-string.
+This function returns a string representing @var{dirname} in a form
+that the operating system will interpret as the name of a file (a
+directory file name).  On most systems, this means removing the final
+slash (or backslash) from the string.
 
 @example
 @group
@@ -2119,6 +2122,13 @@ Don't try concatenating a slash by hand, as in
 because this is not portable.  Always use
 @code{file-name-as-directory}.
 
+  To avoid the issues mentioned above, or if the @var{dirname} value
+might be nil (for example, from an element of @code{load-path}), use:
+
+@example
+(expand-file-name @var{relfile} @var{dirname})
+@end example
+
   To convert a directory name to its abbreviation, use this
 function:
 
diff --git a/src/lread.c b/src/lread.c
index a98fa6199f1..1119f3fdfd4 100644
--- a/src/lread.c
+++ b/src/lread.c
@@ -4479,8 +4479,10 @@ were read in.  */);
 
   DEFVAR_LISP ("load-path", Vload_path,
                doc: /* List of directories to search for files to load.
-Each element is a string (directory name) or nil (meaning `default-directory').
-Initialized during startup as described in Info node `(elisp)Library Search'.  */);
+Each element is a string (directory file name) or nil (meaning
+`default-directory').  Initialized during startup as described in Info
+node `(elisp)Library Search'.  Use `directory-file-name' when adding items
+to this path.  */);
 
   DEFVAR_LISP ("load-suffixes", Vload_suffixes,
                doc: /* List of suffixes for (compiled or source) Emacs Lisp files.