Be more consistent about "directory name" in manual

This clarifies the documentation, partly in response to the
discussion in Bug#27986.

1 files changed, 47 insertions, 45 deletions

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index d04be63d7ec..edee30e5ad7 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -401,9 +401,7 @@ If @var{confirm} is non-@code{nil}, that means to ask for confirmation
 before overwriting an existing file.  Interactively, confirmation is
 required, unless the user supplies a prefix argument.
 
-@c FIXME: This disagrees with the doc string, which talks about
-@c directory names, not directories.  See Bug#27986.
-If @var{filename} is an existing directory, or a symbolic link to one,
+If @var{filename} is a directory name (@pxref{Directory Names}),
 @code{write-file} uses the name of the visited file, in directory
 @var{filename}.  If the buffer is not visiting a file, it uses the
 buffer name instead.
@@ -832,16 +830,16 @@ permissions.
 @defun file-exists-p filename
 This function returns @code{t} if a file named @var{filename} appears
 to exist.  This does not mean you can necessarily read the file, only
-that you can find out its attributes.  (On Unix and GNU/Linux, this is
-true if the file exists and you have execute permission on the
-containing directories, regardless of the permissions of the file
-itself.)
+that you can find out its attributes.  (On GNU and other POSIX-like
+systems, this is true if the file exists and you have execute
+permission on the containing directories, regardless of the
+permissions of the file itself.)
 
 If the file does not exist, or if access control policies prevent you
 from finding its attributes, this function returns @code{nil}.
 
-Directories are files, so @code{file-exists-p} returns @code{t} when
-given a directory name.  However, because @code{file-exists-p} follows
+Directories are files, so @code{file-exists-p} can return @code{t} when
+given a directory.  However, because @code{file-exists-p} follows
 symbolic links, it returns @code{t} for a symbolic link
 name only if the target file exists.
 @end defun
@@ -852,11 +850,11 @@ and you can read it.  It returns @code{nil} otherwise.
 @end defun
 
 @defun file-executable-p filename
-This function returns @code{t} if a file named @var{filename} exists and
-you can execute it.  It returns @code{nil} otherwise.  On Unix and
-GNU/Linux, if the file is a directory, execute permission means you can
-check the existence and attributes of files inside the directory, and
-open those files if their modes permit.
+This function returns @code{t} if a file named @var{filename} exists
+and you can execute it.  It returns @code{nil} otherwise.  On GNU and
+other POSIX-like systems, if the file is a directory, execute
+permission means you can check the existence and attributes of files
+inside the directory, and open those files if their modes permit.
 @end defun
 
 @defun file-writable-p filename
@@ -960,10 +958,10 @@ $ ls -l diffs
 executable file mode bit.  So @code{file-modes} considers a file
 executable if its name ends in one of the standard executable
 extensions, such as @file{.com}, @file{.bat}, @file{.exe}, and some
-others.  Files that begin with the Unix-standard @samp{#!} signature,
+others.  Files that begin with the POSIX-standard @samp{#!} signature,
 such as shell and Perl scripts, are also considered executable.
 Directories are also reported as executable, for compatibility with
-Unix.  These conventions are also followed by @code{file-attributes}
+POSIX@.  These conventions are also followed by @code{file-attributes}
 (@pxref{File Attributes}).
 @end defun
 
@@ -1762,8 +1760,8 @@ multiple names, it continues to exist under the other names.  If
 symbolic link and not its target.
 
 A suitable kind of @code{file-error} error is signaled if the file
-does not exist, or is not deletable.  (On Unix and GNU/Linux, a file
-is deletable if its directory is writable.)
+does not exist, or is not deletable.  (On GNU and other POSIX-like
+systems, a file is deletable if its directory is writable.)
 
 If the optional argument @var{trash} is non-@code{nil} and the
 variable @code{delete-by-moving-to-trash} is non-@code{nil}, this
@@ -1811,8 +1809,9 @@ This function sets the default permissions for new files created by
 Emacs and its subprocesses.  Every file created with Emacs initially
 has these permissions, or a subset of them (@code{write-region} will
 not grant execute permissions even if the default file permissions
-allow execution).  On Unix and GNU/Linux, the default permissions are
-given by the bitwise complement of the @samp{umask} value.
+allow execution).  On GNU and other POSIX-like systems, the default
+permissions are given by the bitwise complement of the @samp{umask}
+value.
 
 The argument @var{mode} should be an integer which specifies the
 permissions, similar to @code{set-file-modes} above.  Only the lowest
@@ -1951,9 +1950,9 @@ directory.
 @cindex converting file names from/to MS-Windows syntax
   On MS-DOS and MS-Windows, these functions (like the function that
 actually operate on files) accept MS-DOS or MS-Windows file-name syntax,
-where backslashes separate the components, as well as Unix syntax; but
-they always return Unix syntax.  This enables Lisp programs to specify
-file names in Unix syntax and work properly on all systems without
+where backslashes separate the components, as well as POSIX syntax; but
+they always return POSIX syntax.  This enables Lisp programs to specify
+file names in POSIX syntax and work properly on all systems without
 change.@footnote{In MS-Windows versions of Emacs compiled for the Cygwin
 environment, you can use the functions
 @code{cygwin-convert-file-name-to-windows} and
@@ -1998,16 +1997,16 @@ This function returns the directory part of @var{filename}, as a
 directory name (@pxref{Directory Names}), or @code{nil} if
 @var{filename} does not include a directory part.
 
-On GNU and Unix systems, a string returned by this function always
+On GNU and other POSIX-like systems, a string returned by this function always
 ends in a slash.  On MS-DOS it can also end in a colon.
 
 @example
 @group
-(file-name-directory "lewis/foo")  ; @r{Unix example}
+(file-name-directory "lewis/foo")  ; @r{GNU example}
      @result{} "lewis/"
 @end group
 @group
-(file-name-directory "foo")        ; @r{Unix example}
+(file-name-directory "foo")        ; @r{GNU example}
      @result{} nil
 @end group
 @end example
@@ -2121,8 +2120,9 @@ root directory.  A file name can specify all the directory names
 starting from the root of the tree; then it is called an
 @dfn{absolute} file name.  Or it can specify the position of the file
 in the tree relative to a default directory; then it is called a
-@dfn{relative} file name.  On Unix and GNU/Linux, an absolute file
-name starts with a @samp{/} or a @samp{~}
+@dfn{relative} file name.  On GNU and other POSIX-like systems,
+after any leading @samp{~} has been expanded, an absolute file name
+starts with a @samp{/}
 (@pxref{abbreviate-file-name}), and a relative one does not.  On
 MS-DOS and MS-Windows, an absolute file name starts with a slash or a
 backslash, or with a drive specification @samp{@var{x}:/}, where
@@ -2181,17 +2181,18 @@ form.
 @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 (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
+  A @dfn{directory name} is a string that must name a directory if it
+names any file at all.  A directory is actually a kind of file, and it
+has a file name (called the @dfn{directory file name}, which is
+related to the directory name but is typically not identical.  (This
+is not quite the same as the usual POSIX terminology.)  These two
+names for the same entity are related by a syntactic transformation.
+On GNU and other POSIX-like systems, this is simple: to obtain a
+directory name, append a @samp{/} to a directory file name that does
+not already end in @samp{/}.  On MS-DOS the relationship is more
 complicated.
 
-  The difference between directory name and directory file name is
+  The difference between a directory name and a directory file name is
 subtle but crucial.  When an Emacs variable or function argument is
 described as being a directory name, a directory file name is not
 acceptable.  When @code{file-name-directory} returns a string, that is
@@ -2219,15 +2220,16 @@ string (if it does not already end in one).
 @defun directory-name-p filename
 This function returns non-@code{nil} if @var{filename} ends with a
 directory separator character.  This is the forward slash @samp{/} on
-Unix and GNU systems; MS-Windows and MS-DOS recognize both the forward
-slash and the backslash @samp{\} as directory separators.
+GNU and other POSIX-like systems; MS-Windows and MS-DOS recognize both
+the forward slash and the backslash @samp{\} as directory separators.
 @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 (a
 directory file name).  On most systems, this means removing the final
-slash (or backslash) from the string.
+directory separators from the string, unless the string consists
+entirely of directory separators.
 
 @example
 @group
@@ -2307,7 +2309,7 @@ because it recognizes abbreviations even as part of the name.
 
   @dfn{Expanding} a file name means converting a relative file name to
 an absolute one.  Since this is done relative to a default directory,
-you must specify the default directory name as well as the file name
+you must specify the default directory as well as the file name
 to be expanded.  It also involves expanding abbreviations like
 @file{~/}
 @ifnottex
@@ -2448,7 +2450,7 @@ results.
 
 @c Wordy to avoid overfull hbox.  --rjc 15mar92
 Here we assume that the environment variable @env{HOME}, which holds
-the user's home directory name, has value @samp{/xcssun/users/rms}.
+the user's home directory, has value @samp{/xcssun/users/rms}.
 
 @example
 @group
@@ -2813,8 +2815,8 @@ located in @file{~/.abbrev_defs}.  Here is the definition of
 This function returns a file name based on @var{filename}, which fits
 the conventions of the current operating system.
 
-On GNU and Unix systems, this simply returns @var{filename}.  On other
-operating systems, it may enforce system-specific file name
+On GNU and other POSIX-like systems, this simply returns @var{filename}.
+On other operating systems, it may enforce system-specific file name
 conventions; for example, on MS-DOS this function performs a variety
 of changes to enforce MS-DOS file name limitations, including
 converting any leading @samp{.} to @samp{_} and truncating to three
@@ -2918,7 +2920,7 @@ directory @var{file}, formatted with @code{ls} according to
 @var{switches} may be a string of options, or a list of strings
 representing individual options.
 
-The argument @var{file} may be either a directory name or a file
+The argument @var{file} may be either a directory or a file
 specification including wildcard characters.  If @var{wildcard} is
 non-@code{nil}, that means treat @var{file} as a file specification with
 wildcards.