10 files changed, 373 insertions, 312 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 124ee8fe1dd..454e716a5bf 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,30 @@
+2014-01-05  Chong Yidong  <cyd@gnu.org>
+
+        * backups.texi (Making Backups): Document backup-buffer change.
+
+        * 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.
+
+        * 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.
+
+        * minibuf.texi (Minibuffer Contents): Remove obsolete function
+        minibuffer-completion-contents.
+
+        * variables.texi (Defining Variables): Note that defvar acts
+        always on the dynamic value.
+
+        * customize.texi (Variable Definitions): Likewise.
+
 2014-01-05  Paul Eggert  <eggert@cs.ucla.edu>
 
         Document vconcat and the empty vector (Bug#16246).
diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi
index ac3a81931c1..83ffb2f95e4 100644
--- a/doc/lispref/backups.texi
+++ b/doc/lispref/backups.texi
@@ -57,13 +57,15 @@ buffer, if appropriate.  It is called by @code{save-buffer} before
 saving the buffer the first time.
 
 If a backup was made by renaming, the return value is a cons cell of
-the form (@var{modes} @var{context} @var{backupname}), where
+the form (@var{modes} @var{extra-alist} @var{backupname}), where
 @var{modes} are the mode bits of the original file, as returned by
-@code{file-modes} (@pxref{File Attributes,, Other Information about
-Files}), @var{context} is a list describing the original file's
-SELinux context (@pxref{File Attributes}), and @var{backupname} is the
-name of the backup.  In all other cases, that is, if a backup was made
-by copying or if no backup was made, this function returns @code{nil}.
+@code{file-modes} (@pxref{Testing Accessibility}), @var{extra-alist}
+is an alist describing the original file's extended attributes, as
+returned by @code{file-extended-attributes} (@pxref{Extended
+Attributes}), and @var{backupname} is the name of the backup.
+
+In all other cases (i.e., if a backup was made by copying or if no
+backup was made), this function returns @code{nil}.
 @end defun
 
 @defvar buffer-backed-up
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index a118e9132a3..f9476e5e34c 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -108,13 +108,26 @@ command does.
 
   The special form @code{interactive} turns a Lisp function into a
 command.  The @code{interactive} form must be located at top-level in
-the function body (usually as the first form in the body), or in the
-@code{interactive-form} property of the function symbol.  When the
-@code{interactive} form is located in the function body, it does
-nothing when actually executed.  Its presence serves as a flag, which
-tells the Emacs command loop that the function can be called
-interactively.  The argument of the @code{interactive} form controls
-the reading of arguments for an interactive call.
+the function body, usually as the first form in the body; this applies
+to both lambda expressions (@pxref{Lambda Expressions}) and
+@code{defun} forms (@pxref{Defining Functions}).  This form does
+nothing during the actual execution of the function; its presence
+serves as a flag, telling the Emacs command loop that the function can
+be called interactively.  The argument of the @code{interactive} form
+specifies how the arguments for an interactive call should be read.
+
+@cindex @code{interactive-form} property
+  Alternatively, an @code{interactive} form may be specified in a
+function symbol's @code{interactive-form} property.  A non-@code{nil}
+value for this property takes precedence over any @code{interactive}
+form in the function body itself.  This feature is seldom used.
+
+@cindex @code{interactive-only} property
+  Sometimes, a named command is only intended to be called
+interactively, never directly from Lisp.  In that case, give it a
+non-@code{nil} @code{interactive-only} property.  In that case, the
+byte compiler will print a warning message if the command is called
+from Lisp.
 
 @menu
 * Using Interactive::     General rules for @code{interactive}.
diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 85c9ac5f73c..fe492df1d94 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -430,29 +430,35 @@ to what @code{eval-when-compile} does.
 @section Compiler Errors
 @cindex compiler errors
 
-  Byte compilation outputs all errors and warnings into the buffer
-@file{*Compile-Log*}.  The messages include file names and line
-numbers that identify the location of the problem.  The usual Emacs
-commands for operating on compiler diagnostics work properly on these
+  Error and warning messages from byte compilation are printed in a
+buffer named @file{*Compile-Log*}.  These messages include file names
+and line numbers identifying the location of the problem.  The usual
+Emacs commands for operating on compiler output can be used on these
 messages.
 
   When an error is due to invalid syntax in the program, the byte
 compiler might get confused about the errors' exact location.  One way
-to investigate is to switch to the buffer @w{@file{ *Compiler Input*}}.
-(This buffer name starts with a space, so it does not show up in
-@kbd{M-x list-buffers}.)  This buffer contains the program being
+to investigate is to switch to the buffer @w{@file{ *Compiler
+Input*}}.  (This buffer name starts with a space, so it does not show
+up in the Buffer Menu.)  This buffer contains the program being
 compiled, and point shows how far the byte compiler was able to read;
 the cause of the error might be nearby.  @xref{Syntax Errors}, for
 some tips for locating syntax errors.
 
-  When the byte compiler warns about functions that were used but not
-defined, it always reports the line number for the end of the file,
-not the locations where the missing functions were called.  To find
-the latter, you must search for the function names.
+  A common type of warning issued by the byte compiler is for
+functions and variables that were used but not defined.  Such warnings
+report the line number for the end of the file, not the locations
+where the missing functions or variables were used; to find these, you
+must search the file manually.
 
-  You can suppress the compiler warning for calling an undefined
-function @var{func} by conditionalizing the function call on an
-@code{fboundp} test, like this:
+  If you are sure that a warning message about a missing function or
+variable is unjustified, there are several ways to suppress it:
+
+@itemize @bullet
+@item
+You can suppress the warning for a specific call to a function
+@var{func} by conditionalizing it on an @code{fboundp} test, like
+this:
 
 @example
 (if (fboundp '@var{func}) ...(@var{func} ...)...)
@@ -463,14 +469,10 @@ The call to @var{func} must be in the @var{then-form} of the
 @code{if}, and @var{func} must appear quoted in the call to
 @code{fboundp}.  (This feature operates for @code{cond} as well.)
 
-  You can tell the compiler that a function is defined using
-@code{declare-function} (@pxref{Declaring Functions}).  Likewise, you
-can tell the compiler that a variable is defined using @code{defvar}
-with no initial value.
-
-  You can suppress the compiler warning for a specific use of an
-undefined variable @var{variable} by conditionalizing its use on a
-@code{boundp} test, like this:
+@item
+Likewise, you can suppress the warning for a specific use of a
+variable @var{variable} by conditionalizing it on a @code{boundp}
+test:
 
 @example
 (if (boundp '@var{variable}) ...@var{variable}...)
@@ -481,7 +483,17 @@ The reference to @var{variable} must be in the @var{then-form} of the
 @code{if}, and @var{variable} must appear quoted in the call to
 @code{boundp}.
 
-  You can suppress any and all compiler warnings within a certain
+@item
+You can tell the compiler that a function is defined using
+@code{declare-function}. @xref{Declaring Functions}.
+
+@item
+Likewise, you can tell the compiler that a variable is defined using
+@code{defvar} with no initial value.  (Note that this marks the
+variable as special.)  @xref{Defining Variables}.
+@end itemize
+
+  You can also suppress any and all compiler warnings within a certain
 expression using the construct @code{with-no-warnings}:
 
 @c This is implemented with a defun, but conceptually it is
@@ -497,8 +509,9 @@ possible piece of code, to avoid missing possible warnings other than
 one you intend to suppress.
 @end defspec
 
-  More precise control of warnings is possible by setting the variable
-@code{byte-compile-warnings}.
+  Byte compiler warnings can be controlled more precisely by setting
+the variable @code{byte-compile-warnings}.  See its documentation
+string for details.
 
 @node Byte-Code Objects
 @section Byte-Code Function Objects
diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index 1e54a7fa444..4b0a0a9ba2c 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -287,13 +287,17 @@ customizable variable).  You should not quote @var{option}.
 
 The argument @var{standard} is an expression that specifies the
 standard value for @var{option}.  Evaluating the @code{defcustom} form
-evaluates @var{standard}, but does not necessarily install the
-standard value.  If @var{option} already has a default value,
-@code{defcustom} does not change it.  If the user has saved a
-customization for @var{option}, @code{defcustom} installs the user's
-customized value as @var{option}'s default value.  If neither of those
-cases applies, @code{defcustom} installs the result of evaluating
-@var{standard} as the default value.
+evaluates @var{standard}, but does not necessarily bind the option to
+that value.  If @var{option} already has a default value, it is left
+unchanged.  If the user has already saved a customization for
+@var{option}, the user's customized value is installed as the default
+value.  Otherwise, the result of evaluating @var{standard} is
+installed as the default value.
+
+Like @code{defvar}, this macro marks @code{option} as a special
+variable, meaning that it should always be dynamically bound.  If
+@var{option} is already lexically bound, that lexical binding remains
+in effect until the binding construct exits.  @xref{Variable Scoping}.
 
 The expression @var{standard} can be evaluated at various other times,
 too---whenever the customization facility needs to know @var{option}'s
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 94c06a130b1..9681c3c42a3 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -951,7 +951,8 @@ Information about Files
 * 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.
 
 File Names
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
 
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 0e58816ecf3..e32922eef68 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -2224,12 +2224,6 @@ This is like @code{minibuffer-contents}, except that it does not copy text
 properties, just the characters themselves.  @xref{Text Properties}.
 @end defun
 
-@defun minibuffer-completion-contents
-This is like @code{minibuffer-contents}, except that it returns only
-the contents before point.  That is the part that completion commands
-operate on.  @xref{Minibuffer Completion}.
-@end defun
-
 @defun delete-minibuffer-contents
 This function erases the editable contents of the minibuffer (that is,
 everything except the prompt), if a minibuffer is current.  Otherwise,
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index a80a6c0b1e3..dbeebcc6ee6 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -416,18 +416,23 @@ explicitly in the @code{defvar} form.  The variable is marked as
 @dfn{special}, meaning that it should always be dynamically bound
 (@pxref{Variable Scoping}).
 
-If @var{symbol} is void and @var{value} is specified, @code{defvar}
-evaluates @var{value} and sets @var{symbol} to the result.  But if
-@var{symbol} already has a value (i.e., it is not void), @var{value}
-is not even evaluated, and @var{symbol}'s value remains unchanged.  If
-@var{value} is omitted, the value of @var{symbol} is not changed in
-any case.
+If @var{value} is specified, and @var{symbol} is void (i.e., it has no
+dynamically bound value; @pxref{Void Variables}), then @var{value} is
+evaluated and @var{symbol} is set to the result.  But if @var{symbol}
+is not void, @var{value} is not evaluated, and @var{symbol}'s value is
+left unchanged.  If @var{value} is omitted, the value of @var{symbol}
+is not changed in any case.
 
 If @var{symbol} has a buffer-local binding in the current buffer,
-@code{defvar} operates on the default value, which is buffer-independent,
-not the current (buffer-local) binding.  It sets the default value if
+@code{defvar} acts on the default value, which is buffer-independent,
+rather than the buffer-local binding.  It sets the default value if
 the default value is void.  @xref{Buffer-Local Variables}.
 
+If @var{symbol} is already lexically bound (e.g., if the @code{defvar}
+form occurs in a @code{let} form with lexical binding enabled), then
+@code{defvar} sets the dynamic value.  The lexical binding remains in
+effect until its binding construct exits.  @xref{Variable Scoping}.
+
 When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in
 Emacs Lisp mode (@code{eval-defun}), a special feature of
 @code{eval-defun} arranges to set the variable unconditionally, without
diff --git a/etc/NEWS b/etc/NEWS
index 801f5b8ed20..6f2b80f0bf7 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -904,6 +904,7 @@ low-level libraries gfilenotify.c, inotify.c or w32notify.c.
 ** `(input-pending-p)' no longer runs other timers which are ready to
 run.  The new optional CHECK-TIMERS param allows for the prior behavior.
 
++++
 ** `defvar' and `defcustom' in a let-binding affect the "external" default.
 
 ---
@@ -958,6 +959,7 @@ special-forms any more.
 when lexical binding is enabled.  Previously, VAR was bound to nil,
 which often led to spurious unused-variable warnings.
 
++++
 ** The return value of `backup-buffer' has changed.
 The second argument is no longer an SELinux context, instead it is an
 alist of extended attributes as returned by the new function
@@ -1083,6 +1085,7 @@ displaying the buffer in a window.
 *** `string-remove-prefix'
 *** `string-remove-suffix'
 
++++
 ** Obsoleted functions:
 *** `log10'
 *** `dont-compile'
@@ -1100,8 +1103,10 @@ The few hooks that used with-wrapper-hook are replaced as follows:
 *** `completion-in-region-function' obsoletes `completion-in-region-functions'.
 *** `filter-buffer-substring-function' obsoletes `filter-buffer-substring-functions'.
 
++++
 ** `byte-compile-interactive-only-functions' is now obsolete.
-It has been replaced by the symbol property 'interactive-only.
+To specify that a command should only be called interactively, give it
+a non-nil `interactive-only' property.
 
 +++
 ** `split-string' now takes an optional argument TRIM.