More doc updates.

* backups.texi (Making Backups): Document backup-buffer change.

* commands.texi (Defining Commands): Document the interactive-form
property more carefully.  Document interactive-only.

* compile.texi (Compiler Errors): Copyedits.  Note that the
details for byte-compile-warnings are in its docstring.

* customize.texi (Variable Definitions): Likewise.

* files.texi (Visiting Files): Copyedits.
(Testing Accessibility): Mention ACLs.  Move file-modes here from
File Attributes.
(Truenames): Move file-equal-p here from Kinds of Files.
(File Attributes): Move file-newer-than-file-p here from Testing
Accessibility.
(Extended Attributes): New node.  Add file-extended-attributes.
(Changing Files): Document set-file-extended-attributes.

* minibuf.texi (Minibuffer Contents): Remove obsolete function
minibuffer-completion-contents.

* variables.texi (Defining Variables): Note that defvar acts
always on the dynamic value.

1 files changed, 248 insertions, 251 deletions

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 8f2ca0ccf8d..076c91c0c58 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -7,21 +7,21 @@
 @chapter Files
 
   This chapter describes the Emacs Lisp functions and variables to
-find, create, view, save, and otherwise work with files and file
+find, create, view, save, and otherwise work with files and
 directories.  A few other file-related functions are described in
 @ref{Buffers}, and those related to backups and auto-saving are
 described in @ref{Backups and Auto-Saving}.
 
   Many of the file functions take one or more arguments that are file
-names.  A file name is actually a string.  Most of these functions
-expand file name arguments by calling @code{expand-file-name}, so that
+names.  A file name is a string.  Most of these functions expand file
+name arguments using the function @code{expand-file-name}, so that
 @file{~} is handled correctly, as are relative file names (including
-@samp{../}).  @xref{File Name Expansion}.
+@file{../}).  @xref{File Name Expansion}.
 
   In addition, certain @dfn{magic} file names are handled specially.
 For example, when a remote file name is specified, Emacs accesses the
-file over the network via an appropriate protocol (@pxref{Remote
-Files,, Remote Files, emacs, The GNU Emacs Manual}).  This handling is
+file over the network via an appropriate protocol.  @xref{Remote
+Files,, Remote Files, emacs, The GNU Emacs Manual}.  This handling is
 done at a very low level, so you may assume that all the functions
 described in this chapter accept magic file names as file name
 arguments, except where noted.  @xref{Magic File Names}, for details.
@@ -58,22 +58,21 @@ done, we say that the buffer is @dfn{visiting} that file, and call the
 file ``the visited file'' of the buffer.
 
   A file and a buffer are two different things.  A file is information
-recorded permanently in the computer (unless you delete it).  A buffer,
-on the other hand, is information inside of Emacs that will vanish at
-the end of the editing session (or when you kill the buffer).  Usually,
-a buffer contains information that you have copied from a file; then we
-say the buffer is visiting that file.  The copy in the buffer is what
-you modify with editing commands.  Such changes to the buffer do not
-change the file; therefore, to make the changes permanent, you must
-@dfn{save} the buffer, which means copying the altered buffer contents
-back into the file.
-
-  In spite of the distinction between files and buffers, people often
-refer to a file when they mean a buffer and vice-versa.  Indeed, we say,
-``I am editing a file'', rather than, ``I am editing a buffer that I
-will soon save as a file of the same name''.  Humans do not usually need
-to make the distinction explicit.  When dealing with a computer program,
-however, it is good to keep the distinction in mind.
+recorded permanently in the computer (unless you delete it).  A
+buffer, on the other hand, is information inside of Emacs that will
+vanish at the end of the editing session (or when you kill the
+buffer).  When a buffer is visiting a file, it contains information
+copied from the file.  The copy in the buffer is what you modify with
+editing commands.  Changes to the buffer do not change the file; to
+make the changes permanent, you must @dfn{save} the buffer, which
+means copying the altered buffer contents back into the file.
+
+  Despite the distinction between files and buffers, people often
+refer to a file when they mean a buffer and vice-versa.  Indeed, we
+say, ``I am editing a file'', rather than, ``I am editing a buffer
+that I will soon save as a file of the same name''.  Humans do not
+usually need to make the distinction explicit.  When dealing with a
+computer program, however, it is good to keep the distinction in mind.
 
 @menu
 * Visiting Functions::         The usual interface functions for visiting.
@@ -507,9 +506,9 @@ Name}).
 @section Reading from Files
 @cindex reading from files
 
-  You can copy a file from the disk and insert it into a buffer
-using the @code{insert-file-contents} function.  Don't use the user-level
-command @code{insert-file} in a Lisp program, as that sets the mark.
+  To copy the contents of a file into a buffer, use the function
+@code{insert-file-contents}.  (Don't use the command
+@code{insert-file} in a Lisp program, as that sets the mark.)
 
 @defun insert-file-contents filename &optional visit beg end replace
 This function inserts the contents of file @var{filename} into the
@@ -769,26 +768,24 @@ for its usual definition is in @file{userlock.el}.
 @section Information about Files
 @cindex file, information about
 
-  The functions described in this section all operate on strings that
-designate file names.  With a few exceptions, all the functions have
-names that begin with the word @samp{file}.  These functions all
-return information about actual files or directories, so their
-arguments must all exist as actual files or directories unless
-otherwise noted.
+  This section describes the functions for retrieving various types of
+information about files (or directories or symbolic links), such as
+whether a file is readable or writable, and its size.  These functions
+all take arguments which are file names.  Except where noted, these
+arguments need to specify existing files, or an error is signaled.
 
 @cindex file names, trailing whitespace
 @cindex trailing blanks in file names
-Be careful with file names that end in blanks: some filesystems
-(notably, MS-Windows) will ignore trailing whitespace in file names,
-and return information about the file after stripping those blanks
-from the name, not about the file whose name you passed to the
-functions described in this section.
+  Be careful with file names that end in spaces.  On some filesystems
+(notably, MS-Windows), trailing whitespace characters in file names
+are silently and automatically ignored.
 
 @menu
 * Testing Accessibility::   Is a given file readable?  Writable?
 * Kinds of Files::          Is it a directory?  A symbolic link?
 * Truenames::               Eliminating symbolic links from a file name.
-* File Attributes::         How large is it?  Any other names?  Etc.
+* File Attributes::         File sizes, modification times, etc.
+* Extended Attributes::     Extended file attributes for access control.
 * Locating Files::          How to find a file in standard places.
 @end menu
 
@@ -797,10 +794,16 @@ functions described in this section.
 @cindex accessibility of a file
 @cindex file accessibility
 
-  These functions test for permission to access a file in specific
-ways.  Unless explicitly stated otherwise, they recursively follow
-symbolic links for their file name arguments, at all levels (at the
-level of the file itself and at all levels of parent directories).
+  These functions test for permission to access a file for reading,
+writing, or execution.  Unless explicitly stated otherwise, they
+recursively follow symbolic links for their file name arguments, at
+all levels (at the level of the file itself and at all levels of
+parent directories).
+
+  On some operating systems, more complex sets of access permissions
+can be specified, via mechanisms such as Access Control Lists (ACLs).
+@xref{Extended Attributes}, for how to query and set those
+permissions.
 
 @defun file-exists-p filename
 This function returns @code{t} if a file named @var{filename} appears
@@ -810,9 +813,8 @@ 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 fascist access control policies
-prevent you from finding the attributes of the file, this function
-returns @code{nil}.
+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, symbolic links are treated
@@ -823,24 +825,8 @@ name only if the target file exists.
 @defun file-readable-p filename
 This function returns @code{t} if a file named @var{filename} exists
 and you can read it.  It returns @code{nil} otherwise.
-
-@example
-@group
-(file-readable-p "files.texi")
-     @result{} t
-@end group
-@group
-(file-exists-p "/usr/spool/mqueue")
-     @result{} t
-@end group
-@group
-(file-readable-p "/usr/spool/mqueue")
-     @result{} nil
-@end group
-@end example
 @end defun
 
-@c Emacs 19 feature
 @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
@@ -856,27 +842,18 @@ file exists and you can write it.  It is creatable if it does not exist,
 but the specified directory does exist and you can write in that
 directory.
 
-In the third example below, @file{foo} is not writable because the
-parent directory does not exist, even though the user could create such
-a directory.
+In the example below, @file{foo} is not writable because the parent
+directory does not exist, even though the user could create such a
+directory.
 
 @example
 @group
-(file-writable-p "~/foo")
-     @result{} t
-@end group
-@group
-(file-writable-p "/foo")
-     @result{} nil
-@end group
-@group
 (file-writable-p "~/no-such-dir/foo")
      @result{} nil
 @end group
 @end example
 @end defun
 
-@c Emacs 19 feature
 @defun file-accessible-directory-p dirname
 This function returns @code{t} if you have permission to open existing
 files in the directory whose name as a file is @var{dirname};
@@ -885,16 +862,13 @@ The value of @var{dirname} may be either a directory name (such as
 @file{/foo/}) or the file name of a file which is a directory
 (such as @file{/foo}, without the final slash).
 
-Example: after the following,
+For example, from the following we deduce that any attempt to read a
+file in @file{/foo/} will give an error:
 
 @example
 (file-accessible-directory-p "/foo")
      @result{} nil
 @end example
-
-@noindent
-we can deduce that any attempt to read a file in @file{/foo/} will
-give an error.
 @end defun
 
 @defun access-file filename string
@@ -917,39 +891,59 @@ replace @var{filename} with its target.  However, it does recursively
 follow symbolic links at all levels of parent directories.
 @end defun
 
-@defun file-newer-than-file-p filename1 filename2
-@cindex file age
-@cindex file modification time
-This function returns @code{t} if the file @var{filename1} is
-newer than file @var{filename2}.  If @var{filename1} does not
-exist, it returns @code{nil}.  If @var{filename1} does exist, but
-@var{filename2} does not, it returns @code{t}.
+@defun file-modes filename
+@cindex mode bits
+@cindex file permissions
+@cindex permissions, file
+@cindex file modes
+This function returns the @dfn{mode bits} of @var{filename}---an
+integer summarizing its read, write, and execution permissions.
+Symbolic links in @var{filename} are recursively followed at all
+levels.  If the file does not exist, the return value is @code{nil}.
 
-In the following example, assume that the file @file{aug-19} was written
-on the 19th, @file{aug-20} was written on the 20th, and the file
-@file{no-file} doesn't exist at all.
+@xref{File permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
+Manual}, for a description of mode bits.  For example, if the
+low-order bit is 1, the file is executable by all users; if the
+second-lowest-order bit is 1, the file is writable by all users; etc.
+The highest possible value is 4095 (7777 octal), meaning that everyone
+has read, write, and execute permission, the @acronym{SUID} bit is set
+for both others and group, and the sticky bit is set.
+
+@xref{Changing Files}, for the @code{set-file-modes} function, which
+can be used to set these permissions.
 
 @example
 @group
-(file-newer-than-file-p "aug-19" "aug-20")
-     @result{} nil
+(file-modes "~/junk/diffs")
+     @result{} 492               ; @r{Decimal integer.}
 @end group
 @group
-(file-newer-than-file-p "aug-20" "aug-19")
-     @result{} t
+(format "%o" 492)
+     @result{} "754"             ; @r{Convert to octal.}
 @end group
+
 @group
-(file-newer-than-file-p "aug-19" "no-file")
-     @result{} t
+(set-file-modes "~/junk/diffs" #o666)
+     @result{} nil
 @end group
+
 @group
-(file-newer-than-file-p "no-file" "aug-19")
-     @result{} nil
+$ ls -l diffs
+-rw-rw-rw- 1 lewis lewis 3063 Oct 30 16:00 diffs
 @end group
 @end example
 
-You can use @code{file-attributes} to get a file's last modification
-time as a list of four integers.  @xref{File Attributes}.
+@cindex MS-DOS and file modes
+@cindex file modes and MS-DOS
+@strong{MS-DOS note:} On MS-DOS, there is no such thing as an
+``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,
+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}
+(@pxref{File Attributes}).
 @end defun
 
 @node Kinds of Files
@@ -987,8 +981,6 @@ If the file @var{filename} is not a symbolic link (or there is no such file),
      @result{} "/pub/bin"
 @end group
 @end example
-
-@c !!! file-symlink-p: should show output of ls -l for comparison
 @end defun
 
 The next two functions recursively follow symbolic links at
@@ -1029,21 +1021,6 @@ a regular file (not a directory, named pipe, terminal, or
 other I/O device).
 @end defun
 
-@defun file-equal-p file1 file2
-This function returns @code{t} if the files @var{file1} and
-@var{file2} name the same file.  If @var{file1} or @var{file2} does
-not exist, the return value is unspecified.
-@end defun
-
-@defun file-in-directory-p file dir
-This function returns @code{t} if @var{file} is a file in directory
-@var{dir}, or in a subdirectory of @var{dir}.  It also returns
-@code{t} if @var{file} and @var{dir} are the same directory.  It
-compares the @code{file-truename} values of the two directories
-(@pxref{Truenames}).  If @var{dir} does not name an existing
-directory, the return value is @code{nil}.
-@end defun
-
 @node Truenames
 @subsection Truenames
 @cindex truename (of file)
@@ -1066,14 +1043,14 @@ This function does not expand environment variables.  Only
 substitute-in-file-name}.
 
 If you may need to follow symbolic links preceding @samp{..}@:
-appearing as a name component, you should make sure to call
-@code{file-truename} without prior direct or indirect calls to
-@code{expand-file-name}, as otherwise the file name component
-immediately preceding @samp{..} will be ``simplified away'' before
-@code{file-truename} is called.  To eliminate the need for a call to
-@code{expand-file-name}, @code{file-truename} handles @samp{~} in the
-same way that @code{expand-file-name} does.  @xref{File Name
-Expansion,, Functions that Expand Filenames}.
+appearing as a name component, call @code{file-truename} without prior
+direct or indirect calls to @code{expand-file-name}.  Otherwise, the
+file name component immediately preceding @samp{..} will be
+``simplified away'' before @code{file-truename} is called.  To
+eliminate the need for a call to @code{expand-file-name},
+@code{file-truename} handles @samp{~} in the same way that
+@code{expand-file-name} does.  @xref{File Name Expansion,, Functions
+that Expand Filenames}.
 @end defun
 
 @defun file-chase-links filename &optional limit
@@ -1102,70 +1079,61 @@ we would have:
      @result{} "/home/foo/hello"
 @end example
 
-  @xref{Buffer File Name}, for related information.
+@defun file-equal-p file1 file2
+This function returns @code{t} if the files @var{file1} and
+@var{file2} name the same file.  This is similar to comparing their
+truenames, except that remote file names are also handled in an
+appropriate manner.  If @var{file1} or @var{file2} does not exist, the
+return value is unspecified.
+@end defun
+
+@defun file-in-directory-p file dir
+This function returns @code{t} if @var{file} is a file in directory
+@var{dir}, or in a subdirectory of @var{dir}.  It also returns
+@code{t} if @var{file} and @var{dir} are the same directory.  It
+compares the truenames of the two directories.  If @var{dir} does not
+name an existing directory, the return value is @code{nil}.
+@end defun
 
 @node File Attributes
-@subsection Other Information about Files
+@subsection File Attributes
+@cindex file attributes
 
   This section describes the functions for getting detailed
-information about a file, other than its contents.  This information
-includes the mode bits that control access permissions, the owner and
-group numbers, the number of names, the inode number, the size, and
-the times of access and modification.
+information about a file, including the owner and group numbers, the
+number of names, the inode number, the size, and the times of access
+and modification.
 
-@defun file-modes filename
-@cindex file permissions
-@cindex permissions, file
-@cindex file attributes
-@cindex file modes
-This function returns the @dfn{mode bits} describing the @dfn{file
-permissions} of @var{filename}, as an integer.  It recursively follows
-symbolic links in @var{filename} at all levels.  If @var{filename}
-does not exist, the return value is @code{nil}.
+@defun file-newer-than-file-p filename1 filename2
+@cindex file age
+@cindex file modification time
+This function returns @code{t} if the file @var{filename1} is
+newer than file @var{filename2}.  If @var{filename1} does not
+exist, it returns @code{nil}.  If @var{filename1} does exist, but
+@var{filename2} does not, it returns @code{t}.
 
-@xref{File permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
-Manual}, for a description of mode bits.  If the low-order bit is 1,
-then the file is executable by all users, if the second-lowest-order
-bit is 1, then the file is writable by all users, etc.  The highest
-value returnable is 4095 (7777 octal), meaning that everyone has read,
-write, and execute permission, that the @acronym{SUID} bit is set for
-both others and group, and that the sticky bit is set.
+In the following example, assume that the file @file{aug-19} was written
+on the 19th, @file{aug-20} was written on the 20th, and the file
+@file{no-file} doesn't exist at all.
 
 @example
 @group
-(file-modes "~/junk/diffs")
-     @result{} 492               ; @r{Decimal integer.}
+(file-newer-than-file-p "aug-19" "aug-20")
+     @result{} nil
 @end group
 @group
-(format "%o" 492)
-     @result{} "754"             ; @r{Convert to octal.}
+(file-newer-than-file-p "aug-20" "aug-19")
+     @result{} t
 @end group
-
 @group
-(set-file-modes "~/junk/diffs" #o666)
-     @result{} nil
+(file-newer-than-file-p "aug-19" "no-file")
+     @result{} t
 @end group
-
 @group
-$ ls -l diffs
--rw-rw-rw- 1 lewis lewis 3063 Oct 30 16:00 diffs
+(file-newer-than-file-p "no-file" "aug-19")
+     @result{} nil
 @end group
 @end example
-
-@xref{Changing Files}, for functions that change file permissions,
-such as @code{set-file-modes}.
-
-@cindex MS-DOS and file modes
-@cindex file modes and MS-DOS
-@strong{MS-DOS note:} On MS-DOS, there is no such thing as an
-``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,
-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},
-below.
 @end defun
 
   If the @var{filename} argument to the next two functions is a
@@ -1173,31 +1141,6 @@ symbolic link, then these function do @emph{not} replace it with its
 target.  However, they both recursively follow symbolic links at all
 levels of parent directories.
 
-@defun file-nlinks filename
-This function returns the number of names (i.e., hard links) that
-file @var{filename} has.  If the file does not exist, this function
-returns @code{nil}.  Note that symbolic links have no effect on this
-function, because they are not considered to be names of the files
-they link to.
-
-@example
-@group
-$ ls -l foo*
--rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo
--rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo1
-@end group
-
-@group
-(file-nlinks "foo")
-     @result{} 2
-@end group
-@group
-(file-nlinks "doesnt-exist")
-     @result{} nil
-@end group
-@end example
-@end defun
-
 @defun file-attributes filename &optional id-format
 @anchor{Definition of file-attributes}
 This function returns a list of attributes of file @var{filename}.  If
@@ -1339,52 +1282,99 @@ is on the file-system device whose number is 1014478468.
 @end table
 @end defun
 
-@cindex SELinux context
-  SELinux is a Linux kernel feature which provides more sophisticated
-file access controls than ordinary ``Unix-style'' file permissions.
-If Emacs has been compiled with SELinux support on a system with
-SELinux enabled, you can use the function @code{file-selinux-context}
-to retrieve a file's SELinux security context.  For the function
-@code{set-file-selinux-context}, see @ref{Changing Files}.
+@defun file-nlinks filename
+This function returns the number of names (i.e., hard links) that
+file @var{filename} has.  If the file does not exist, this function
+returns @code{nil}.  Note that symbolic links have no effect on this
+function, because they are not considered to be names of the files
+they link to.
 
-@defun file-selinux-context filename
-This function returns the SELinux security context of the file
-@var{filename}.  This return value is a list of the form
-@code{(@var{user} @var{role} @var{type} @var{range})}, whose elements
-are the context's user, role, type, and range respectively, as Lisp
-strings.  See the SELinux documentation for details about what these
-actually mean.
+@example
+@group
+$ ls -l foo*
+-rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo
+-rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo1
+@end group
 
-If the file does not exist or is inaccessible, or if the system does
-not support SELinux, or if Emacs was not compiled with SELinux
-support, then the return value is @code{(nil nil nil nil)}.
+@group
+(file-nlinks "foo")
+     @result{} 2
+@end group
+@group
+(file-nlinks "doesnt-exist")
+     @result{} nil
+@end group
+@end example
 @end defun
 
+@node Extended Attributes
+@subsection Extended File Attributes
+@cindex extended file attributes
+
+On some operating systems, each file can be associated with arbitrary
+@dfn{extended file attributes}.  At present, Emacs supports querying
+and setting two specific sets of extended file attributes: Access
+Control Lists (ACLs) and SELinux contexts.  These extended file
+attributes are used, on some systems, to impose more sophisticated
+file access controls than the basic ``Unix-style'' permissions
+discussed in the previous sections.
+
 @cindex access control list
 @cindex ACL entries
-  If Emacs has been compiled with @dfn{ACL} (access control list)
-support, you can use the function @code{file-acl} to retrieve a file's
-ACL entries.  The interface implementation is platform-specific; on
-GNU/Linux and BSD, Emacs uses the POSIX ACL interface, while on
-MS-Windows Emacs emulates the POSIX ACL interface with native file
-security APIs.
+@cindex SELinux context
+  A detailed explanation of ACLs and SELinux is beyond the scope of
+this manual.  For our purposes, each file can be associated with an
+@dfn{ACL}, which specifies its properties under an ACL-based file
+control system, and/or an @dfn{SELinux context}, which specifies its
+properties under the SELinux system.
 
 @defun file-acl filename
-This function returns the ACL entries of the file @var{filename}.  The
-return value is a platform-dependent object containing some
-representation of the ACL entries.  Don't use it for anything except
-passing it to the @code{set-file-acl} function (@pxref{Changing Files,
-set-file-acl}).
+This function returns the ACL for the file @var{filename}.  The exact
+Lisp representation of the ACL is unspecified (and may change in
+future Emacs versions), but it is the same as what @code{set-file-acl}
+takes for its @var{acl} argument (@pxref{Changing Files}).
 
-If the file does not exist or is inaccessible, or if Emacs was unable to
-determine the ACL entries, then the return value is @code{nil}.  The
-latter can happen for local files if Emacs was not compiled with ACL
-support, or for remote files if the file handler returns nil for the
-file's ACL entries.
+The underlying ACL implementation is platform-specific; on GNU/Linux
+and BSD, Emacs uses the POSIX ACL interface, while on MS-Windows Emacs
+emulates the POSIX ACL interface with native file security APIs.
+
+If Emacs was not compiled with ACL support, or the file does not exist
+or is inaccessible, or Emacs was unable to determine the ACL entries
+for any other reason, then the return value is @code{nil}.
+@end defun
+
+@defun file-selinux-context filename
+This function returns the SELinux context of the file @var{filename},
+as a list of the form @code{(@var{user} @var{role} @var{type}
+@var{range})}.  The list elements are the context's user, role, type,
+and range respectively, as Lisp strings; see the SELinux documentation
+for details about what these actually mean.  The return value has the
+same form as what @code{set-file-selinux-context} takes for its
+@var{context} argument (@pxref{Changing Files}).
+
+If Emacs was not compiled with SELinux support, or the file does not
+exist or is inaccessible, or if the system does not support SELinux,
+then the return value is @code{(nil nil nil nil)}.
+@end defun
+
+@defun file-extended-attributes filename
+This function returns an alist of the Emacs-recognized extended
+attributes of file @var{filename}.  Currently, it serves as a
+convenient way to retrieve both the ACL and SELinux context; you can
+then call the function @code{set-file-extended-attributes}, with the
+returned alist as its second argument, to apply the same file access
+attributes to another file (@pxref{Changing Files}).
+
+One of the elements is @code{(acl . @var{acl})}, where @var{acl} has
+the same form returned by @code{file-acl}.
+
+Another element is @code{(selinux-context . @var{context})}, where
+@var{context} is the SELinux context, in the same form returned by
+@code{file-selinux-context}.
 @end defun
 
 @node Locating Files
-@subsection How to Locate Files in Standard Places
+@subsection Locating Files in Standard Places
 @cindex locate file in path
 @cindex find file in path
 
@@ -1571,10 +1561,11 @@ file.  This works only on some operating systems, and only if you have
 the correct permissions to do so.
 
 If the optional argument @var{preserve-permissions} is non-@code{nil},
-this function copies the file's permissions, such as its file modes,
-its SELinux context, and ACL entries (@pxref{File Attributes}).
-Otherwise, if the destination is created its file permission bits are
-those of the source, masked by the default file permissions.
+this function copies the file modes (or ``permissions''), as well as
+its Access Control List and SELinux context (if any).
+@xref{Information about Files}.  Otherwise, if the destination is
+created its file permission bits are those of the source, masked by
+the default file permissions.
 @end deffn
 
 @deffn Command make-symbolic-link filename newname  &optional ok-if-exists
@@ -1616,7 +1607,7 @@ See also @code{delete-directory} in @ref{Create/Delete Dirs}.
 @cindex permissions, file
 @cindex file modes, setting
 @deffn Command set-file-modes filename mode
-This function sets the @dfn{file mode} (or @dfn{file permissions}) of
+This function sets the @dfn{file mode} (or @dfn{permissions}) of
 @var{filename} to @var{mode}.  It recursively follows symbolic links
 at all levels for @var{filename}.
 
@@ -1705,25 +1696,31 @@ time and must be in the format returned by @code{current-time}
 (@pxref{Time of Day}).
 @end defun
 
+@defun set-file-extended-attributes filename attribute-alist
+This function sets the Emacs-recognized extended file attributes for
+@code{filename}.  The second argument @var{attribute-alist} should be
+an alist of the same form returned by @code{file-extended-attributes}.
+@xref{Extended Attributes}.
+@end defun
+
 @defun set-file-selinux-context filename context
-This function sets the SELinux security context of the file
-@var{filename} to @var{context}.  @xref{File Attributes}, for a brief
-description of SELinux contexts.  The @var{context} argument should be
-a list @code{(@var{user} @var{role} @var{type} @var{range})}, like the
-return value of @code{file-selinux-context}.  The function returns
-@code{t} if it succeeds to set the SELinux security context of
-@var{filename}, @code{nil} otherwise.  The function does nothing and
-returns @code{nil} if SELinux is disabled, or if Emacs was compiled
-without SELinux support.
-@end defun
-
-@defun set-file-acl filename acl-string
-This function sets the ACL entries of the file @var{filename} to
-@var{acl-string}.  @xref{File Attributes}, for a brief description of
-ACLs.  The @var{acl-string} argument should be a string containing the
-textual representation of the desired ACL entries as returned by
-@code{file-acl} (@pxref{File Attributes, file-acl}).  The function
-returns @code{t} if it succeeds to set the ACL entries of
+This function sets the SELinux security context for @var{filename} to
+@var{context}.  The @var{context} argument should be a list
+@code{(@var{user} @var{role} @var{type} @var{range})}, where each
+element is a string.  @xref{Extended Attributes}.
+
+The function returns @code{t} if it succeeds in setting the SELinux
+context of @var{filename}.  It returns @code{nil} if the context was
+not set (e.g., if SELinux is disabled, or if Emacs was compiled
+without SELinux support).
+@end defun
+
+@defun set-file-acl filename acl
+This function sets the Access Control List for @var{filename} to
+@var{acl}.  The @var{acl} argument should have the same form returned
+by the function @code{file-acl}.  @xref{Extended Attributes}.
+
+The function returns @code{t} if it successfully sets the ACL of
 @var{filename}, @code{nil} otherwise.
 @end defun