changeset 6555:771fa0ddb356

Initial revision

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/lispref/files.texi	Mon Mar 28 18:36:14 1994 +0000
@@ -0,0 +1,1893 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/files
+@node Files, Backups and Auto-Saving, Documentation, Top
+@comment  node-name,  next,  previous,  up
+@chapter Files
+
+  In Emacs, you can find, create, view, save, and otherwise work with
+files and file directories.  This chapter describes most of the
+file-related functions of Emacs Lisp, but a few others are described in
+@ref{Buffers}, and those related to backups and auto-saving are
+described in @ref{Backups and Auto-Saving}.
+
+@menu
+* Visiting Files::           Reading files into Emacs buffers for editing.
+* Saving Buffers::           Writing changed buffers back into files.
+* Reading from Files::       Reading files into buffers without visiting.
+* Writing to Files::         Writing new files from parts of buffers.
+* File Locks::               Locking and unlocking files, to prevent
+                               simultaneous editing by two people.
+* Information about Files::  Testing existence, accessibility, size of files.
+* Changing File Attributes:: Renaming files, changing protection, etc.
+* File Names::               Decomposing and expanding file names.
+* Contents of Directories::  Getting a list of the files in a directory.
+* Create/Delete Dirs::	     Creating and Deleting Directories.
+* Magic File Names::	     Defining "magic" special handling
+			       for certain file names.
+@end menu
+
+@node Visiting Files
+@section Visiting Files
+@cindex finding files
+@cindex visiting files
+
+  Visiting a file means reading a file into a buffer.  Once this is
+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 which 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.
+* Subroutines of Visiting::    Lower-level subroutines that they use.
+@end menu
+
+@node Visiting Functions
+@subsection Functions for Visiting Files
+
+  This section describes the functions normally used to visit files.
+For historical reasons, these functions have names starting with
+@samp{find-} rather than @samp{visit-}.  @xref{Buffer File Name}, for
+functions and variables that access the visited file name of a buffer or
+that find an existing buffer by its visited file name.
+
+@deffn Command find-file filename
+This command selects a buffer visiting the file @var{filename},
+using an existing buffer if there is one, and otherwise creating a 
+new buffer and reading the file into it.  It also returns that buffer.
+
+The body of the @code{find-file} function is very simple and looks
+like this:
+
+@example
+(switch-to-buffer (find-file-noselect filename))
+@end example
+
+@noindent
+(See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
+
+When @code{find-file} is called interactively, it prompts for
+@var{filename} in the minibuffer.
+@end deffn
+
+@defun find-file-noselect filename
+This function is the guts of all the file-visiting functions.  It finds
+or creates a buffer visiting the file @var{filename}, and returns it.
+It uses an existing buffer if there is one, and otherwise creates a new
+buffer and reads the file into it.  You may make the buffer current or
+display it in a window if you wish, but this function does not do so.
+
+When @code{find-file-noselect} uses an existing buffer, it first
+verifies that the file has not changed since it was last visited or
+saved in that buffer.  If the file has changed, then this function asks
+the user whether to reread the changed file.  If the user says
+@samp{yes}, any changes previously made in the buffer are lost.
+
+If @code{find-file-noselect} needs to create a buffer, and there is no
+file named @var{filename}, it displays the message @samp{New file} in
+the echo area, and leaves the buffer empty.
+
+The @code{find-file-noselect} function calls @code{after-find-file}
+after reading the file (@pxref{Subroutines of Visiting}).  That function
+sets the buffer major mode, parses local variables, warns the user if
+there exists an auto-save file more recent than the file just visited,
+and finishes by running the functions in @code{find-file-hooks}.
+
+The @code{find-file-noselect} function returns the buffer that is
+visiting the file @var{filename}.
+
+@example
+@group
+(find-file-noselect "/etc/fstab")
+     @result{} #<buffer fstab>
+@end group
+@end example
+@end defun
+
+@deffn Command find-alternate-file filename
+This command selects a buffer visiting the file @var{filename}, then
+kills the buffer that was previously displayed in the selected window.
+It is useful if you have visited the wrong file by mistake, so that you
+can get rid of the buffer that you did not want to create, at the same
+time as you visit the file you intended.
+
+When this command is called interactively, it prompts for @var{filename}.
+@end deffn
+
+@deffn Command find-file-other-window filename
+This command selects a buffer visiting the file @var{filename}, but
+does so in a window other than the selected window.  It may use another
+existing window or split a window; see @ref{Displaying Buffers}.
+
+When this command is called interactively, it prompts for
+@var{filename}.
+@end deffn
+
+@deffn Command find-file-read-only filename
+This command selects a buffer visiting the file @var{filename}, like
+@code{find-file}, but it marks the buffer as read-only.  @xref{Read Only
+Buffers}, for related functions and variables.
+
+When this command is called interactively, it prompts for
+@var{filename}.
+@end deffn
+
+@deffn Command view-file filename
+This command views @var{filename} in View mode, returning to the
+previous buffer when done.  View mode is a mode that allows you to skim
+rapidly through the file but does not let you modify it.  Entering View
+mode runs the normal hook @code{view-mode-hook}.  @xref{Hooks}.
+
+When @code{view-file} is called interactively, it prompts for
+@var{filename}.
+@end deffn
+
+@defvar find-file-hooks
+The value of this variable is a list of functions to be called after a
+file is visited.  The file's local-variables specification (if any) will
+have been processed before the hooks are run.  The buffer visiting the
+file is current when the hook functions are run.
+
+This variable works just like a normal hook, but we think that renaming
+it would not be advisable.
+@end defvar
+
+@defvar find-file-not-found-hooks
+The value of this variable is a list of functions to be called when
+@code{find-file} or @code{find-file-noselect} is passed a nonexistent
+file name.  @code{find-file-noselect} calls these functions as soon as
+it detects a nonexistent file.  It calls them in the order of the list,
+until one of them returns non-@code{nil}.  @code{buffer-file-name} is
+already set up.
+
+This is not a normal hook because the values of the functions are
+used and they may not all be called.
+@end defvar
+
+@node Subroutines of Visiting
+@comment  node-name,  next,  previous,  up
+@subsection Subroutines of Visiting
+
+  The @code{find-file-noselect} function uses the
+@code{create-file-buffer} and @code{after-find-file} functions as
+subroutines.  Sometimes it is useful to call them directly.
+
+@defun create-file-buffer filename
+This function creates a suitably named buffer for visiting
+@var{filename}, and returns it.  It uses @var{filename} (sans directory)
+as the name if that name is free; otherwise, it appends a string such as
+@samp{<2>} to get an unused name.  See also @ref{Creating Buffers}.
+
+@strong{Please note:} @code{create-file-buffer} does @emph{not}
+associate the new buffer with a file and does not select the buffer.
+
+@example
+@group
+(create-file-buffer "foo")
+     @result{} #<buffer foo>
+@end group
+@group
+(create-file-buffer "foo")
+     @result{} #<buffer foo<2>>
+@end group
+@group
+(create-file-buffer "foo")
+     @result{} #<buffer foo<3>>
+@end group
+@end example
+
+This function is used by @code{find-file-noselect}.
+It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
+@end defun
+
+@defun after-find-file &optional error warn
+This function sets the buffer major mode, and parses local variables
+(@pxref{Auto Major Mode}).  It is called by @code{find-file-noselect}
+and by the default revert function (@pxref{Reverting}).
+
+@cindex new file message
+@cindex file open error
+If reading the file got an error because the file does not exist, but
+its directory does exist, the caller should pass a non-@code{nil} value
+for @var{error}.  In that case, @code{after-find-file} issues a warning:
+@samp{(New File)}.  For more serious errors, the caller should usually not
+call @code{after-find-file}.
+
+If @var{warn} is non-@code{nil}, then this function issues a warning
+if an auto-save file exists and is more recent than the visited file.
+
+The last thing @code{after-find-file} does is call all the functions
+in @code{find-file-hooks}.
+@end defun
+
+@node Saving Buffers
+@section Saving Buffers
+
+  When you edit a file in Emacs, you are actually working on a buffer
+that is visiting that file---that is, the contents of the file are
+copied into the buffer and the copy is what you edit.  Changes to the
+buffer do not change the file until you @dfn{save} the buffer, which
+means copying the contents of the buffer into the file.
+
+@deffn Command save-buffer &optional backup-option
+This function saves the contents of the current buffer in its visited
+file if the buffer has been modified since it was last visited or saved.
+Otherwise it does nothing.
+
+@code{save-buffer} is responsible for making backup files.  Normally,
+@var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
+file only if this is the first save or if the buffer was previously
+modified.  Other values for @var{backup-option} request the making of
+backup files in other circumstances:
+
+@itemize @bullet
+@item
+With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the
+@code{save-buffer} function marks this version of the file to be
+backed up when the buffer is next saved.
+
+@item
+With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
+@code{save-buffer} function unconditionally backs up the previous
+version of the file before saving it.
+@end itemize
+@end deffn
+
+@deffn Command save-some-buffers &optional save-silently-p exiting
+This command saves some modified file-visiting buffers.  Normally it
+asks the user about each buffer.  But if @var{save-silently-p} is
+non-@code{nil}, it saves all the file-visiting buffers without querying
+the user.
+
+The optional @var{exiting} argument, if non-@code{nil}, requests this
+function to offer also to save certain other buffers that are not
+visiting files.  These are buffers that have a non-@code{nil} local
+value of @code{buffer-offer-save}.  (A user who says yes to saving one
+of these is asked to specify a file name to use.)  The
+@code{save-buffers-kill-emacs} function passes a non-@code{nil} value
+for this argument.
+@end deffn
+
+@defvar buffer-offer-save
+When this variable is non-@code{nil} in a buffer, Emacs offers to save
+the buffer on exit even if the buffer is not visiting a file.  The
+variable is automatically local in all buffers.  Normally, Mail mode
+(used for editing outgoing mail) sets this to @code{t}.
+@end defvar
+
+@deffn Command write-file filename
+This function writes the current buffer into file @var{filename}, makes
+the buffer visit that file, and marks it not modified.  Then it renames
+the buffer based on @var{filename}, appending a string like @samp{<2>}
+if necessary to make a unique buffer name.  It does most of this work by
+calling @code{set-visited-file-name} and @code{save-buffer}.
+@end deffn
+
+@defvar write-file-hooks
+The value of this variable is a list of functions to be called before
+writing out a buffer to its visited file.  If one of them returns
+non-@code{nil}, the file is considered already written and the rest of
+the functions are not called, nor is the usual code for writing the file
+executed.
+
+If a function in @code{write-file-hooks} returns non-@code{nil}, it
+is responsible for making a backup file (if that is appropriate).
+To do so, execute the following code:
+
+@example
+(or buffer-backed-up (backup-buffer))
+@end example
+
+You might wish to save the file modes value returned by
+@code{backup-buffer} and use that to set the mode bits of the file that
+you write.  This is what @code{save-buffer} normally does.
+
+Even though this is not a normal hook, you can use @code{add-hook} and
+@code{remove-hook} to manipulate the list.  @xref{Hooks}.
+@end defvar
+
+@c Emacs 19 feature
+@defvar local-write-file-hooks
+This works just like @code{write-file-hooks}, but it is intended
+to be made local to particular buffers.  It's not a good idea to make
+@code{write-file-hooks} local to a buffer---use this variable instead.
+
+The variable is marked as a permanent local, so that changing the major
+mode does not alter a buffer-local value.  This is convenient for
+packages that read ``file'' contents in special ways, and set up hooks
+to save the data in a corresponding way.
+@end defvar
+
+@c Emacs 19 feature
+@defvar write-contents-hooks
+This works just like @code{write-file-hooks}, but it is intended for
+hooks that pertain to the contents of the file, as opposed to hooks that
+pertain to where the file came from.  Typically major mode commands make
+buffer-local bindings for this variable.
+@end defvar
+
+@c Emacs 19 feature
+@defvar after-save-hook
+This normal hook runs after a buffer has been saved in its visited file.
+@end defvar
+
+@defvar file-precious-flag
+If this variable is non-@code{nil}, then @code{save-buffer} protects
+against I/O errors while saving by writing the new file to a temporary
+name instead of the name it is supposed to have, and then renaming it to
+the intended name after it is clear there are no errors.  This procedure
+prevents problems such as a lack of disk space from resulting in an
+invalid file.
+
+(This feature worked differently in older Emacs versions.)
+
+Some modes set this non-@code{nil} locally in particular buffers.
+@end defvar
+
+@defopt require-final-newline
+This variable determines whether files may be written out that do
+@emph{not} end with a newline.  If the value of the variable is
+@code{t}, then @code{save-buffer} silently adds a newline at the end of
+the file whenever the buffer being saved does not already end in one.
+If the value of the variable is non-@code{nil}, but not @code{t}, then
+@code{save-buffer} asks the user whether to add a newline each time the
+case arises.
+
+If the value of the variable is @code{nil}, then @code{save-buffer}
+doesn't add newlines at all.  @code{nil} is the default value, but a few
+major modes set it to @code{t} in particular buffers.
+@end defopt
+
+@node Reading from Files
+@comment  node-name,  next,  previous,  up
+@section 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.
+
+@defun insert-file-contents filename &optional visit beg end replace
+This function inserts the contents of file @var{filename} into the
+current buffer after point. It returns a list of the absolute file name
+and the length of the data inserted.  An error is signaled if
+@var{filename} is not the name of a file that can be read.
+
+To set up saved text properties, @code{insert-file-contents} calls the
+functions in the list @code{after-insert-file-functions}.  For more
+information, see @ref{Saving Properties}.
+
+If @var{visit} is non-@code{nil}, this function additionally marks the
+buffer as unmodified and sets up various fields in the buffer so that it
+is visiting the file @var{filename}: these include the buffer's visited
+file name and its last save file modtime.  This feature is used by
+@code{find-file-noselect} and you probably should not use it yourself.
+
+If @var{beg} and @var{end} are non-@code{nil}, they should be integers
+specifying the portion of the file to insert.  In this case, @var{visit}
+must be @code{nil}.  For example,
+
+@example
+(insert-file-contents filename nil 0 500)
+@end example
+
+@noindent
+inserts the first 500 characters of a file.
+
+If the argument @var{replace} is non-@code{nil}, it means to replace the
+contents of the buffer (actually, just the accessible portion) with the
+contents of the file.  This is better than simply deleting the buffer
+contents and inserting the whole file, because (1) it preserves some
+marker positions and (2) it puts less data in the undo list.
+@end defun
+
+If you want to pass a file name to another process so that another
+program can read the file, use the function @code{file-local-copy}; see
+@ref{Magic File Names}.
+
+@node Writing to Files
+@comment  node-name,  next,  previous,  up
+@section Writing to Files
+
+  You can write the contents of a buffer, or part of a buffer, directly
+to a file on disk using the @code{append-to-file} and
+@code{write-region} functions.  Don't use these functions to write to
+files that are being visited; that could cause confusion in the
+mechanisms for visiting.
+
+@deffn Command append-to-file start end filename
+This function appends the contents of the region delimited by
+@var{start} and @var{end} in the current buffer to the end of file
+@var{filename}.  If that file does not exist, it is created.  This
+function returns @code{nil}.
+
+An error is signaled if @var{filename} specifies a nonwritable file,
+or a nonexistent file in a directory where files cannot be created.
+@end deffn
+
+@deffn Command write-region start end filename &optional append visit
+This function writes the region delimited by @var{start} and @var{end}
+in the current buffer into the file specified by @var{filename}.
+
+@c Emacs 19 feature
+If @var{start} is a string, then @code{write-region} writes or appends
+that string, rather than text from the buffer.
+
+If @var{append} is non-@code{nil}, then the specified text is appended
+to the existing file contents (if any).
+
+If @var{visit} is @code{t}, then Emacs establishes an association
+between the buffer and the file: the buffer is then visiting that file.
+It also sets the last file modification time for the current buffer to
+@var{filename}'s modtime, and marks the buffer as not modified.  This
+feature is used by @code{save-buffer}, but you probably should not use
+it yourself.
+
+@c Emacs 19 feature
+If @var{visit} is a string, it specifies the file name to visit.  This
+way, you can write the data to one file (@var{filename}) while recording
+the buffer as visiting another file (@var{visit}).  The argument
+@var{visit} is used in the echo area message and also for file locking;
+@var{visit} is stored in @code{buffer-file-name}.  This feature is used
+to implement @code{file-precious-flag}; don't use it yourself unless you
+really know what you're doing.
+
+To output information about text properties, @code{write-region} calls
+the functions in the list @code{write-region-annotation-functions}.  For
+more information, see @ref{Saving Properties}.
+
+Normally, @code{write-region} displays a message @samp{Wrote file
+@var{filename}} in the echo area.  If @var{visit} is neither @code{t}
+nor @code{nil} nor a string, then this message is inhibited.  This
+feature is useful for programs that use files for internal purposes,
+files which the user does not need to know about.
+@end deffn
+
+@node File Locks
+@section File Locks
+@cindex file locks
+
+  When two users edit the same file at the same time, they are likely to
+interfere with each other.  Emacs tries to prevent this situation from
+arising by recording a @dfn{file lock} when a file is being modified.
+Emacs can then detect the first attempt to modify a buffer visiting a
+file that is locked by another Emacs job, and ask the user what to do.
+
+  File locks do not work properly when multiple machines can share
+file systems, such as with NFS.  Perhaps a better file locking system
+will be implemented in the future.  When file locks do not work, it is
+possible for two users to make changes simultaneously, but Emacs can
+still warn the user who saves second.  Also, the detection of
+modification of a buffer visiting a file changed on disk catches some
+cases of simultaneous editing; see @ref{Modification Time}.
+
+@defun file-locked-p filename
+  This function returns @code{nil} if the file @var{filename} is not
+locked by this Emacs process.  It returns @code{t} if it is locked by
+this Emacs, and it returns the name of the user who has locked it if it
+is locked by someone else.
+
+@example
+@group
+(file-locked-p "foo")
+     @result{} nil
+@end group
+@end example
+@end defun
+
+@defun lock-buffer &optional filename
+  This function locks the file @var{filename}, if the current buffer is
+modified.  The argument @var{filename} defaults to the current buffer's
+visited file.  Nothing is done if the current buffer is not visiting a
+file, or is not modified.
+@end defun
+
+@defun unlock-buffer
+This function unlocks the file being visited in the current buffer,
+if the buffer is modified.  If the buffer is not modified, then
+the file should not be locked, so this function does nothing.  It also
+does nothing if the current buffer is not visiting a file.
+@end defun
+
+@defun ask-user-about-lock file other-user
+This function is called when the user tries to modify @var{file}, but it
+is locked by another user name @var{other-user}.  The value it returns
+determines what happens next:
+
+@itemize @bullet
+@item
+A value of @code{t} says to grab the lock on the file.  Then
+this user may edit the file and @var{other-user} loses the lock.
+
+@item
+A value of @code{nil} says to ignore the lock and let this
+user edit the file anyway.
+
+@item
+@kindex file-locked
+This function may instead signal a @code{file-locked} error, in which
+case the change that the user was about to make does not take place.
+
+The error message for this error looks like this:
+
+@example
+@error{} File is locked: @var{file} @var{other-user}
+@end example
+
+@noindent
+where @code{file} is the name of the file and @var{other-user} is the
+name of the user who has locked the file.
+@end itemize
+
+  The default definition of this function asks the user to choose what
+to do.  If you wish, you can replace the @code{ask-user-about-lock}
+function with your own version that decides in another way.  The code
+for its usual definition is in @file{userlock.el}.
+@end defun
+
+@node Information about Files
+@section Information about Files
+
+  The functions described in this section are similar in as much as
+they all operate on strings which are interpreted as file names.  All
+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.
+
+  Most of the file-oriented functions take a single argument,
+@var{filename}, which must be a string.  The file name is expanded using
+@code{expand-file-name}, so @file{~} is handled correctly, as are
+relative file names (including @samp{../}).  These functions don't
+recognize environment variable substitutions such as @samp{$HOME}.
+@xref{File Name Expansion}.
+
+@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.
+@end menu
+
+@node Testing Accessibility
+@comment  node-name,  next,  previous,  up
+@subsection Testing Accessibility
+@cindex accessibility of a file
+@cindex file accessibility
+
+  These functions test for permission to access a file in specific ways.
+
+@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, this is true if the
+file exists and you have execute permission on the containing
+directories, regardless of the protection 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}.
+@end defun
+
+@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.  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
+This function returns @code{t} if the file @var{filename} can be written or
+created by you.  It is writable if the file exists and you can write it.
+It is creatable if the file does not exist, but the specified directory
+does exist and you can write in that directory.  @code{file-writable-p}
+returns @code{nil} otherwise.
+
+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.
+
+@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 directory @var{dirname}; otherwise (and if there is no such
+directory), it returns @code{nil}.  The value of @var{dirname} may be
+either a directory name or the file name of a directory.
+
+Example: after the following,
+
+@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 file-newer-than-file-p filename1 filename2
+@cindex file age
+@cindex file modification time
+This functions 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{filename2} does not exist,
+it returns @code{t}.
+
+In the following example, assume that the file @file{aug-19} was
+written on the 19th, and @file{aug-20} was written on the 20th.  The
+file @file{no-file} doesn't exist at all.
+
+@example
+@group
+(file-newer-than-file-p "aug-19" "aug-20")
+     @result{} nil
+@end group
+@group
+(file-newer-than-file-p "aug-20" "aug-19")
+     @result{} t
+@end group
+@group
+(file-newer-than-file-p "aug-19" "no-file")
+     @result{} t
+@end group
+@group
+(file-newer-than-file-p "no-file" "aug-19")
+     @result{} nil
+@end group
+@end example
+
+You can use @code{file-attributes} to get a file's last modification
+time as a list of two numbers.  @xref{File Attributes}.
+@end defun
+
+@node Kinds of Files
+@comment  node-name,  next,  previous,  up
+@subsection Distinguishing Kinds of Files
+
+  This section describes how to distinguish directories and symbolic
+links from ordinary files.
+
+@defun file-symlink-p filename
+@cindex file symbolic links
+If the file @var{filename} is a symbolic link, the @code{file-symlink-p}
+function returns the file name to which it is linked.  This may be the
+name of a text file, a directory, or even another symbolic link, or of
+no file at all.
+
+If the file @var{filename} is not a symbolic link (or there is no such file),
+@code{file-symlink-p} returns @code{nil}.  
+
+@example
+@group
+(file-symlink-p "foo")
+     @result{} nil
+@end group
+@group
+(file-symlink-p "sym-link")
+     @result{} "foo"
+@end group
+@group
+(file-symlink-p "sym-link2")
+     @result{} "sym-link"
+@end group
+@group
+(file-symlink-p "/bin")
+     @result{} "/pub/bin"
+@end group
+@end example
+
+@c !!! file-symlink-p: should show output of ls -l for comparison
+@end defun
+
+@defun file-directory-p filename
+This function returns @code{t} if @var{filename} is the name of an
+existing directory, @code{nil} otherwise.
+
+@example
+@group
+(file-directory-p "~rms")
+     @result{} t
+@end group
+@group
+(file-directory-p "~rms/lewis/files.texi")
+     @result{} nil
+@end group
+@group
+(file-directory-p "~rms/lewis/no-such-file")
+     @result{} nil
+@end group
+@group
+(file-directory-p "$HOME")
+     @result{} nil
+@end group
+@group
+(file-directory-p
+ (substitute-in-file-name "$HOME"))
+     @result{} t
+@end group
+@end example
+@end defun
+
+@node Truenames
+@subsection Truenames
+@cindex truename (of file)
+
+@c Emacs 19 features
+  The @dfn{truename} of a file is the name that you get by following
+symbolic links until none remain, then expanding to get rid of @samp{.}
+and @samp{..} as components.  Strictly speaking, a file need not have a
+unique truename; the number of distinct truenames a file has is equal to
+the number of hard links to the file.  However, truenames are useful
+because they eliminate symbolic links as a cause of name variation.
+
+@defun file-truename filename
+The function @code{file-truename} returns the true name of the file
+@var{filename}.  This is the name that you get by following symbolic
+links until none remain.  The argument must be an absolute file name.
+@end defun
+
+  @xref{Buffer File Name}, for related information.
+
+@node File Attributes
+@comment  node-name,  next,  previous,  up
+@subsection Other Information about Files
+
+  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 permission, 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 permission
+@cindex file attributes
+This function returns the mode bits of @var{filename}, as an integer.
+The mode bits are also called the file permissions, and they specify
+access control in the usual Unix fashion.  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 @sc{suid} bit
+is set for both others and group, and that the sticky bit is set.
+
+@example
+@group
+(file-modes "~/junk/diffs")
+     @result{} 492               ; @r{Decimal integer.}
+@end group
+@group
+(format "%o" 492)
+     @result{} "754"             ; @r{Convert to octal.}
+@end group
+
+@group
+(set-file-modes "~/junk/diffs" 438)
+     @result{} nil
+@end group
+
+@group
+(format "%o" 438)
+     @result{} "666"             ; @r{Convert to octal.}
+@end group
+
+@group
+% ls -l diffs
+  -rw-rw-rw-  1 lewis 0 3063 Oct 30 16:00 diffs
+@end group
+@end example
+@end defun
+
+@defun file-nlinks filename
+This functions returns the number of names (i.e., hard links) that
+file @var{filename} has.  If the file does not exist, then 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       4 Aug 19 01:27 foo
+-rw-rw-rw-  2 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
+This function returns a list of attributes of file @var{filename}.  If
+the specified file cannot be opened, it returns @code{nil}.
+
+The elements of the list, in order, are:
+
+@enumerate 0
+@item
+@code{t} for a directory, a string for a symbolic link (the name
+linked to), or @code{nil} for a text file.
+
+@c Wordy so as to prevent an overfull hbox.  --rjc 15mar92
+@item
+The number of names the file has.  Alternate names, also known as hard
+links, can be created by using the @code{add-name-to-file} function
+(@pxref{Changing File Attributes}).
+
+@item
+The file's @sc{uid}.
+
+@item
+The file's @sc{gid}.
+
+@item
+The time of last access, as a list of two integers.
+The first integer has the high-order 16 bits of time,
+the second has the low 16 bits.  (This is similar to the
+value of @code{current-time}; see @ref{Time of Day}.)
+
+@item
+The time of last modification as a list of two integers (as above).
+
+@item
+The time of last status change as a list of two integers (as above).
+
+@item
+The size of the file in bytes.
+
+@item
+The file's modes, as a string of ten letters or dashes
+as in @samp{ls -l}.
+
+@item
+@code{t} if the file's @sc{gid} would change if file were
+deleted and recreated; @code{nil} otherwise.
+
+@item
+The file's inode number.
+
+@item
+The file system number of the file system that the file is in.  This
+element together with the file's inode number, give enough information
+to distinguish any two files on the system---no two files can have the
+same values for both of these numbers.
+@end enumerate
+
+For example, here are the file attributes for @file{files.texi}:
+
+@example
+@group
+(file-attributes "files.texi")
+     @result{}  (nil 
+          1 
+          2235 
+          75 
+          (8489 20284) 
+          (8489 20284) 
+          (8489 20285)
+          14906 
+          "-rw-rw-rw-" 
+          nil 
+          129500
+          -32252)
+@end group
+@end example
+
+@noindent
+and here is how the result is interpreted:
+
+@table @code
+@item nil
+is neither a directory nor a symbolic link.
+
+@item 1
+has only one name (the name @file{files.texi} in the current default
+directory).
+
+@item 2235
+is owned by the user with @sc{uid} 2235.
+
+@item 75
+is in the group with @sc{gid} 75.
+
+@item (8489 20284)
+was last accessed on Aug 19 00:09.  Unfortunately, you cannot convert
+this number into a time string in Emacs.
+
+@item (8489 20284)
+was last modified on Aug 19 00:09.
+
+@item (8489 20285)
+last had its inode changed on Aug 19 00:09.
+
+@item 14906
+is 14906 characters long.
+
+@item "-rw-rw-rw-"
+has a mode of read and write access for the owner, group, and world.
+
+@item nil
+would retain the same @sc{gid} if it were recreated.
+
+@item 129500
+has an inode number of 129500.
+@item -32252
+is on file system number -32252.
+@end table
+@end defun
+
+@node Changing File Attributes
+@section Changing File Names and Attributes
+@cindex renaming files
+@cindex copying files
+@cindex deleting files
+@cindex linking files
+@cindex setting modes of files
+
+  The functions in this section rename, copy, delete, link, and set the
+modes of files.
+
+  In the functions that have an argument @var{newname}, if a file by the
+name of @var{newname} already exists, the actions taken depend on the
+value of the argument @var{ok-if-already-exists}:
+
+@itemize @bullet
+@item
+Signal a @code{file-already-exists} error if
+@var{ok-if-already-exists} is @code{nil}.
+
+@item
+Request confirmation if @var{ok-if-already-exists} is a number.
+
+@item
+Replace the old file without confirmation if @var{ok-if-already-exists}
+is any other value.
+@end itemize
+
+@defun add-name-to-file oldname newname &optional ok-if-already-exists
+@cindex file with multiple names
+@cindex file hard link
+This function gives the file named @var{oldname} the additional name
+@var{newname}.  This means that @var{newname} becomes a new ``hard
+link'' to @var{oldname}.
+
+In the first part of the following example, we list two files,
+@file{foo} and @file{foo3}.
+
+@example
+@group
+% ls -l fo*
+-rw-rw-rw-  1 rms       29 Aug 18 20:32 foo
+-rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
+@end group
+@end example
+
+Then we evaluate the form @code{(add-name-to-file "~/lewis/foo"
+"~/lewis/foo2")}.  Again we list the files.  This shows two names,
+@file{foo} and @file{foo2}.
+
+@example
+@group
+(add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
+     @result{} nil
+@end group
+
+@group
+% ls -l fo*
+-rw-rw-rw-  2 rms       29 Aug 18 20:32 foo
+-rw-rw-rw-  2 rms       29 Aug 18 20:32 foo2
+-rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
+@end group
+@end example
+
+@c !!! Check whether this set of examples is consistent.  --rjc 15mar92
+  Finally, we evaluate the following:
+
+@example
+(add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)
+@end example
+
+@noindent
+and list the files again.  Now there are three names
+for one file: @file{foo}, @file{foo2}, and @file{foo3}.  The old
+contents of @file{foo3} are lost.
+
+@example
+@group
+(add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
+     @result{} nil
+@end group
+
+@group
+% ls -l fo*
+-rw-rw-rw-  3 rms       29 Aug 18 20:32 foo
+-rw-rw-rw-  3 rms       29 Aug 18 20:32 foo2
+-rw-rw-rw-  3 rms       29 Aug 18 20:32 foo3
+@end group
+@end example
+
+  This function is meaningless on VMS, where multiple names for one file
+are not allowed.
+
+  See also @code{file-nlinks} in @ref{File Attributes}.
+@end defun
+
+@deffn Command rename-file filename newname &optional ok-if-already-exists
+This command renames the file @var{filename} as @var{newname}.
+
+If @var{filename} has additional names aside from @var{filename}, it
+continues to have those names.  In fact, adding the name @var{newname}
+with @code{add-name-to-file} and then deleting @var{filename} has the
+same effect as renaming, aside from momentary intermediate states.
+
+In an interactive call, this function prompts for @var{filename} and
+@var{newname} in the minibuffer; also, it requests confirmation if
+@var{newname} already exists.
+@end deffn
+
+@deffn Command copy-file oldname newname &optional ok-if-exists time
+This command copies the file @var{oldname} to @var{newname}.  An
+error is signaled if @var{oldname} does not exist.
+
+If @var{time} is non-@code{nil}, then this functions gives the new
+file the same last-modified time that the old one has.  (This works on
+only some operating systems.)
+
+In an interactive call, this function prompts for @var{filename} and
+@var{newname} in the minibuffer; also, it requests confirmation if
+@var{newname} already exists.
+@end deffn
+
+@deffn Command delete-file filename
+@pindex rm
+This command deletes the file @var{filename}, like the shell command
+@samp{rm @var{filename}}.  If the file has multiple names, it continues
+to exist under the other names.
+
+A suitable kind of @code{file-error} error is signaled if the file
+does not exist, or is not deletable.  (On Unix, a file is deletable if
+its directory is writable.)
+
+See also @code{delete-directory} in @ref{Create/Delete Dirs}.
+@end deffn
+
+@deffn Command make-symbolic-link filename newname  &optional ok-if-exists
+@pindex ln
+@kindex file-already-exists
+This command makes a symbolic link to @var{filename}, named
+@var{newname}.  This is like the shell command @samp{ln -s
+@var{filename} @var{newname}}.
+
+In an interactive call, @var{filename} and @var{newname} are read in the
+minibuffer; it requests confirmation if the file @var{newname} already
+exists.
+@end deffn
+
+@defun define-logical-name varname string
+This function defines the logical name @var{name} to have the value
+@var{string}.  It is available only on VMS.
+@end defun
+
+@defun set-file-modes filename mode
+This function sets mode bits of @var{filename} to @var{mode} (which must
+be an integer).  Only the 12 low bits of @var{mode} are used.
+@end defun
+
+@c Emacs 19 feature
+@defun set-default-file-modes mode
+This function sets the default file protection for new files created by
+Emacs and its subprocesses.  Every file created with Emacs initially has
+this protection.  On Unix, the default protection is the bitwise
+complement of the ``umask'' value.
+
+The argument @var{mode} must be an integer.  Only the 9 low bits of
+@var{mode} are used.
+
+Saving a modified version of an existing file does not count as creating
+the file; it does not change the file's mode, and does not use the
+default file protection.
+@end defun
+
+@defun default-file-modes
+This function returns the current default protection value.
+@end defun
+
+@node File Names
+@section File Names
+@cindex file names
+
+  Files are generally referred to by their names, in Emacs as elsewhere.
+File names in Emacs are represented as strings.  The functions that
+operate on a file all expect a file name argument.
+
+  In addition to operating on files themselves, Emacs Lisp programs
+often need to operate on the names; i.e., to take them apart and to use
+part of a name to construct related file names.  This section describes
+how to manipulate file names.
+
+  The functions in this section do not actually access files, so they
+can operate on file names that do not refer to an existing file or
+directory.
+
+  On VMS, all these functions understand both VMS file name syntax and
+Unix syntax.  This is so that all the standard Lisp libraries can
+specify file names in Unix syntax and work properly on VMS without
+change.
+
+@menu
+* File Name Components::  The directory part of a file name, and the rest.
+* Directory Names::       A directory's name as a directory
+                            is different from its name as a file.
+* Relative File Names::   Some file names are relative to a current directory.
+* File Name Expansion::   Converting relative file names to absolute ones.
+* Unique File Names::     Generating names for temporary files.
+* File Name Completion::  Finding the completions for a given file name.
+@end menu
+
+@node File Name Components
+@subsection File Name Components
+@cindex directory part (of file name)
+@cindex nondirectory part (of file name)
+@cindex version number (in file name)
+
+  The operating system groups files into directories.  To specify a
+file, you must specify the directory, and the file's name in that
+directory.  Therefore, a file name in Emacs is considered to have two
+main parts: the @dfn{directory name} part, and the @dfn{nondirectory}
+part (or @dfn{file name within the directory}).  Either part may be
+empty.  Concatenating these two parts reproduces the original file name.
+
+  On Unix, the directory part is everything up to and including the last
+slash; the nondirectory part is the rest.  The rules in VMS syntax are
+complicated.
+
+  For some purposes, the nondirectory part is further subdivided into
+the name proper and the @dfn{version number}.  On Unix, only backup
+files have version numbers in their names; on VMS, every file has a
+version number, but most of the time the file name actually used in
+Emacs omits the version number.  Version numbers are found mostly in
+directory lists.
+
+@defun file-name-directory filename
+  This function returns the directory part of @var{filename} (or
+@code{nil} if @var{filename} does not include a directory part).  On
+Unix, the function returns a string ending in a slash.  On VMS, it
+returns a string ending in one of the three characters @samp{:},
+@samp{]}, or @samp{>}.
+
+@example
+@group
+(file-name-directory "lewis/foo")  ; @r{Unix example}
+     @result{} "lewis/"
+@end group
+@group
+(file-name-directory "foo")        ; @r{Unix example}
+     @result{} nil
+@end group
+@group
+(file-name-directory "[X]FOO.TMP") ; @r{VMS example}
+     @result{} "[X]"
+@end group
+@end example
+@end defun
+
+@defun file-name-nondirectory filename
+  This function returns the nondirectory part of @var{filename}.
+
+@example
+@group
+(file-name-nondirectory "lewis/foo")
+     @result{} "foo"
+@end group
+@group
+(file-name-nondirectory "foo")
+     @result{} "foo"
+@end group
+@group
+;; @r{The following example is accurate only on VMS.}
+(file-name-nondirectory "[X]FOO.TMP")
+     @result{} "FOO.TMP"
+@end group
+@end example
+@end defun
+
+@defun file-name-sans-versions filename
+  This function returns @var{filename} without any file version numbers,
+backup version numbers, or trailing tildes.
+
+@example
+@group
+(file-name-sans-versions "~rms/foo.~1~")
+     @result{} "~rms/foo"
+@end group
+@group
+(file-name-sans-versions "~rms/foo~")
+     @result{} "~rms/foo"
+@end group
+@group
+(file-name-sans-versions "~rms/foo")
+     @result{} "~rms/foo"
+@end group
+@group
+;; @r{The following example applies to VMS only.}
+(file-name-sans-versions "foo;23")
+     @result{} "foo"
+@end group
+@end example
+@end defun
+
+@node Directory Names
+@comment  node-name,  next,  previous,  up
+@subsection Directory Names
+@cindex directory name
+@cindex file name of directory
+
+  A @dfn{directory name} is the name of a directory.  A directory is a
+kind of file, and 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 Unix, this is simple: a
+directory name ends in a slash, whereas the directory's name as a file
+lacks that slash.  On VMS, the relationship is more complicated.
+
+  The difference between a directory name and its name as a file 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
+acceptable.
+
+  These 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{~}, 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.  In
+Unix, this means appending a slash to the string.  On VMS, the function
+converts a string of the form @file{[X]Y.DIR.1} to the form
+@file{[X.Y]}.
+
+@example
+@group
+(file-name-as-directory "~rms/lewis")
+     @result{} "~rms/lewis/"
+@end group
+@end example
+@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
+Unix, this means removing a final slash from the string.  On VMS, the
+function converts a string of the form @file{[X.Y]} to
+@file{[X]Y.DIR.1}.
+
+@example
+@group
+(directory-file-name "~lewis/")
+     @result{} "~lewis"
+@end group
+@end example
+@end defun
+
+@cindex directory name abbreviation
+  Directory name abbreviations are useful for directories that are
+normally accessed through symbolic links.  Sometimes the users recognize
+primarily the link's name as ``the name'' of the directory, and find it
+annoying to see the directory's ``real'' name.  If you define the link
+name as an abbreviation for the ``real'' name, Emacs shows users the
+abbreviation instead.
+
+@defvar directory-abbrev-alist
+The variable @code{directory-abbrev-alist} contains an alist of
+abbreviations to use for file directories.  Each element has the form
+@code{(@var{from} . @var{to})}, and says to replace @var{from} with
+@var{to} when it appears in a directory name.  The @var{from} string is
+actually a regular expression; it should always start with @samp{^}.
+The function @code{abbreviate-file-name} performs these substitutions.
+
+You can set this variable in @file{site-init.el} to describe the
+abbreviations appropriate for your site.
+
+Here's an example, from a system on which file system @file{/home/fsf}
+and so on are normally accessed through symbolic links named @file{/fsf}
+and so on.
+
+@example
+(("^/home/fsf" . "/fsf")
+ ("^/home/gp" . "/gp")
+ ("^/home/gd" . "/gd"))
+@end example
+@end defvar
+
+  To convert a directory name to its abbreviation, use this
+function:
+
+@defun abbreviate-file-name dirname
+This function applies abbreviations from @code{directory-abbrev-alist}
+to its argument, and substitutes @samp{~} for the user's home
+directory.
+@end defun
+
+@node Relative File Names
+@subsection Absolute and Relative File Names
+@cindex absolute file name
+@cindex relative file name
+
+  All the directories in the file system form a tree starting at the
+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, an absolute file name starts with a slash or a
+tilde (@samp{~}), and a relative one does not.  The rules on VMS are
+complicated.
+
+@defun file-name-absolute-p filename
+This function returns @code{t} if file @var{filename} is an absolute
+file name, @code{nil} otherwise.  On VMS, this function understands both
+Unix syntax and VMS syntax.
+
+@example
+@group
+(file-name-absolute-p "~rms/foo")
+     @result{} t
+@end group
+@group
+(file-name-absolute-p "rms/foo")
+     @result{} nil
+@end group
+@group
+(file-name-absolute-p "/user/rms/foo")
+     @result{} t
+@end group
+@end example
+@end defun
+
+@node File Name Expansion
+@subsection Functions that Expand Filenames
+@cindex expansion of file names
+
+  @dfn{Expansion} of 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 to
+be expanded.  Expansion also simplifies file names by eliminating
+redundancies such as @file{./} and @file{@var{name}/../}.
+
+@defun expand-file-name filename &optional directory
+This function converts @var{filename} to an absolute file name.  If
+@var{directory} is supplied, it is the directory to start with if
+@var{filename} is relative.  (The value of @var{directory} should itself
+be an absolute directory name; it may start with @samp{~}.)
+Otherwise, the current buffer's value of @code{default-directory} is
+used.  For example:
+
+@example
+@group
+(expand-file-name "foo")
+     @result{} "/xcssun/users/rms/lewis/foo"
+@end group
+@group
+(expand-file-name "../foo")
+     @result{} "/xcssun/users/rms/foo"
+@end group
+@group
+(expand-file-name "foo" "/usr/spool/")
+     @result{} "/usr/spool/foo"
+@end group
+@group
+(expand-file-name "$HOME/foo")
+     @result{} "/xcssun/users/rms/lewis/$HOME/foo"
+@end group
+@end example
+
+Filenames containing @samp{.} or @samp{..} are simplified to their
+canonical form:
+
+@example
+@group
+(expand-file-name "bar/../foo")
+     @result{} "/xcssun/users/rms/lewis/foo"
+@end group
+@end example
+
+@samp{~/} is expanded into the user's home directory.  A @samp{/} or
+@samp{~} following a @samp{/} is taken to be the start of an absolute
+file name that overrides what precedes it, so everything before that
+@samp{/} or @samp{~} is deleted.  For example:
+
+@example
+@group
+(expand-file-name 
+ "/a1/gnu//usr/local/lib/emacs/etc/MACHINES")
+     @result{} "/usr/local/lib/emacs/etc/MACHINES"
+@end group
+@group
+(expand-file-name "/a1/gnu/~/foo")
+     @result{} "/xcssun/users/rms/foo"
+@end group
+@end example
+
+@noindent
+In both cases, @file{/a1/gnu/} is discarded because an absolute file
+name follows it.
+
+Note that @code{expand-file-name} does @emph{not} expand environment
+variables; only @code{substitute-in-file-name} does that.
+@end defun
+
+@c Emacs 19 feature
+@defun file-relative-name filename directory
+This function does the inverse of expansion---it tries to return a
+relative name which is equivalent to @var{filename} when interpreted
+relative to @var{directory}.  (If such a relative name would be longer
+than the absolute name, it returns the absolute name instead.)
+
+@example
+(file-relative-name "/foo/bar" "/foo/")
+     @result{} "bar")
+(file-relative-name "/foo/bar" "/hack/")
+     @result{} "/foo/bar")
+@end example
+@end defun
+
+@defvar default-directory
+The value of this buffer-local variable is the default directory for the
+current buffer.  It should be an absolute directory name; it may start
+with @samp{~}.  This variable is local in every buffer.
+
+@code{expand-file-name} uses the default directory when its second
+argument is @code{nil}.
+
+On Unix systems, the value is always a string ending with a slash.
+
+@example
+@group
+default-directory
+     @result{} "/user/lewis/manual/"
+@end group
+@end example
+@end defvar
+
+@defun substitute-in-file-name filename
+This function replaces environment variables references in
+@var{filename} with the environment variable values.  Following standard
+Unix shell syntax, @samp{$} is the prefix to substitute an environment
+variable value.
+
+The environment variable name is the series of alphanumeric characters
+(including underscores) that follow the @samp{$}.  If the character following
+the @samp{$} is a @samp{@{}, then the variable name is everything up to the
+matching @samp{@}}.
+
+@c Wordy to avoid overfull hbox.  --rjc 15mar92
+Here we assume that the environment variable @code{HOME}, which holds
+the user's home directory name, has value @samp{/xcssun/users/rms}.
+
+@example
+@group
+(substitute-in-file-name "$HOME/foo")
+     @result{} "/xcssun/users/rms/foo"
+@end group
+@end example
+
+If a @samp{~} or a @samp{/} appears following a @samp{/}, after
+substitution, everything before the following @samp{/} is discarded:
+
+@example
+@group
+(substitute-in-file-name "bar/~/foo")
+     @result{} "~/foo"
+@end group
+@group
+(substitute-in-file-name "/usr/local/$HOME/foo")
+     @result{} "/xcssun/users/rms/foo"
+@end group
+@end example
+
+On VMS, @samp{$} substitution is not done, so this function does nothing
+on VMS except discard superfluous initial components as shown above.
+@end defun
+
+@node Unique File Names
+@subsection Generating Unique File Names
+
+  Some programs need to write temporary files.  Here is the usual way to
+construct a name for such a file:
+
+@example
+(make-temp-name (concat "/tmp/" @var{name-of-application}))
+@end example
+
+@noindent
+Here we use the directory @file{/tmp/} because that is the standard
+place on Unix for temporary files.  The job of @code{make-temp-name} is
+to prevent two different users or two different jobs from trying to use
+the same name.
+
+@defun make-temp-name string
+This function generates string that can be used as a unique name.  The
+name starts with the prefix @var{string}, and ends with a number that
+is different in each Emacs job.
+
+@example
+@group
+(make-temp-name "/tmp/foo")
+     @result{} "/tmp/foo021304"
+@end group
+@end example
+
+To prevent conflicts among different libraries running in the same
+Emacs, each Lisp program that uses @code{make-temp-name} should have its
+own @var{string}.  The number added to the end of the name distinguishes
+between the same application running in different Emacs jobs.
+@end defun
+
+@node File Name Completion
+@subsection File Name Completion
+@cindex file name completion subroutines
+@cindex completion, file name
+
+  This section describes low-level subroutines for completing a file
+name.  For other completion functions, see @ref{Completion}.
+
+@defun file-name-all-completions partial-filename directory
+This function returns a list of all possible completions for a file
+whose name starts with @var{partial-filename} in directory
+@var{directory}.  The order of the completions is the order of the files
+in the directory, which is unpredictable and conveys no useful
+information.
+
+The argument @var{partial-filename} must be a file name containing no
+directory part and no slash.  The current buffer's default directory is
+prepended to @var{directory}, if @var{directory} is not absolute.
+
+In the following example, suppose that the current default directory,
+@file{~rms/lewis}, has five files whose names begin with @samp{f}:
+@file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
+@file{file.c.~2~}.@refill
+
+@example
+@group
+(file-name-all-completions "f" "")
+     @result{} ("foo" "file~" "file.c.~2~" 
+                "file.c.~1~" "file.c")
+@end group
+
+@group
+(file-name-all-completions "fo" "")  
+     @result{} ("foo")
+@end group
+@end example
+@end defun
+
+@defun file-name-completion filename directory
+This function completes the file name @var{filename} in directory
+@var{directory}.  It returns the longest prefix common to all file names
+in directory @var{directory} that start with @var{filename}.
+
+If only one match exists and @var{filename} matches it exactly, the
+function returns @code{t}.  The function returns @code{nil} if directory
+@var{directory} contains no name starting with @var{filename}.
+
+In the following example, suppose that the current default directory
+has five files whose names begin with @samp{f}: @file{foo},
+@file{file~}, @file{file.c}, @file{file.c.~1~}, and
+@file{file.c.~2~}.@refill
+
+@example
+@group
+(file-name-completion "fi" "")
+     @result{} "file"
+@end group
+
+@group
+(file-name-completion "file.c.~1" "")
+     @result{} "file.c.~1~"
+@end group
+
+@group
+(file-name-completion "file.c.~1~" "")
+     @result{} t
+@end group
+
+@group
+(file-name-completion "file.c.~3" "")
+     @result{} nil
+@end group
+@end example
+@end defun
+
+@defopt completion-ignored-extensions
+@code{file-name-completion} usually ignores file names that end in any
+string in this list.  It does not ignore them when all the possible
+completions end in one of these suffixes or when a buffer showing all
+possible completions is displayed.@refill
+
+A typical value might look like this:
+
+@example
+@group
+completion-ignored-extensions
+     @result{} (".o" ".elc" "~" ".dvi")
+@end group
+@end example
+@end defopt
+
+@node Contents of Directories
+@section Contents of Directories
+@cindex directory-oriented functions
+@cindex file names in directory
+
+  A directory is a kind of file that contains other files entered under
+various names.  Directories are a feature of the file system.
+
+  Emacs can list the names of the files in a directory as a Lisp list,
+or display the names in a buffer using the @code{ls} shell command.  In
+the latter case, it can optionally display information about each file,
+depending on the options passed to the @code{ls} command.
+
+@defun directory-files directory &optional full-name match-regexp nosort
+This function returns a list of the names of the files in the directory
+@var{directory}.  By default, the list is in alphabetical order.
+
+If @var{full-name} is non-@code{nil}, the function returns the files'
+absolute file names.  Otherwise, it returns the names relative to
+the specified directory.
+
+If @var{match-regexp} is non-@code{nil}, this function returns only
+those file names that contain a match for that regular expression---the
+other file names are excluded from the list.
+
+@c Emacs 19 feature
+If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort
+the list, so you get the file names in no particular order.  Use this if
+you want the utmost possible speed and don't care what order the files
+are processed in.  If the order of processing is visible to the user,
+then the user will probably be happier if you do sort the names.
+
+@example
+@group
+(directory-files "~lewis")
+     @result{} ("#foo#" "#foo.el#" "." ".."
+         "dired-mods.el" "files.texi" 
+         "files.texi.~1~")
+@end group
+@end example
+
+An error is signaled if @var{directory} is not the name of a directory
+that can be read.
+@end defun
+
+@defun file-name-all-versions file dirname
+This function returns a list of all versions of the file named
+@var{file} in directory @var{dirname}.
+@end defun
+
+@defun insert-directory file switches &optional wildcard full-directory-p
+This function inserts a directory listing for directory @var{dir},
+formatted with @code{ls} according to @var{switches}.  It leaves point
+after the inserted text.
+
+The argument @var{dir} may be either a directory name 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.
+
+If @var{full-directory-p} is non-@code{nil}, that means @var{file} is a
+directory and switches do not contain @samp{d}, so that a full listing
+is expected.
+
+This function works by running a directory listing program whose name is
+in the variable @code{insert-directory-program}.  If @var{wildcard} is
+non-@code{nil}, it also runs the shell specified by
+@code{shell-file-name}, to expand the wildcards.
+@end defun
+
+@defvar insert-directory-program
+This variable's value is the program to run to generate a directory listing
+for the function @code{insert-directory}.
+@end defvar
+
+@node Create/Delete Dirs
+@section Creating and Deleting Directories
+@c Emacs 19 features
+
+@defun make-directory dirname
+This function creates a directory named @var{dirname}.
+@end defun
+
+@defun delete-directory dirname
+This function deletes the directory named @var{dirname}.  The function
+@code{delete-file} does not work for files that are directories; you
+must use @code{delete-directory} in that case.
+@end defun
+
+@node Magic File Names
+@section Making Certain File Names ``Magic''
+@cindex magic file names
+
+@c Emacs 19 feature
+You can implement special handling for certain file names.  This is
+called making those names @dfn{magic}.  You must supply a regular
+expression to define the class of names (all those which match the
+regular expression), plus a handler that implements all the primitive
+Emacs file operations for file names that do match.
+
+The value of @code{file-name-handler-alist} is a list of handlers,
+together with regular expressions that determine when to apply each
+handler.  Each element has this form:
+
+@example
+(@var{regexp} . @var{handler})
+@end example
+
+@noindent
+All the Emacs primitives for file access and file name transformation
+check the given file name against @code{file-name-handler-alist}.  If
+the file name matches @var{regexp}, the primitives handle that file by
+calling @var{handler}.
+
+The first argument given to @var{handler} is the name of the primitive;
+the remaining arguments are the arguments that were passed to that
+operation.  (The first of these arguments is typically the file name
+itself.)  For example, if you do this:
+
+@example
+(file-exists-p @var{filename})
+@end example
+
+@noindent
+and @var{filename} has handler @var{handler}, then @var{handler} is
+called like this:
+
+@example
+(funcall @var{handler} 'file-exists-p @var{filename})
+@end example
+
+Here are the operations that you can handle for a magic file name:
+
+@noindent
+@code{add-name-to-file}, @code{copy-file}, @code{delete-directory},
+@code{delete-file},@*
+@code{directory-file-name},
+@code{diff-latest-backup-file}, @code{directory-files},
+@code{dired-compress-file}, @code{dired-uncache},
+@code{expand-file-name},@*
+@code{file-accessible-directory-p},
+@code{file-attributes}, @code{file-directory-p},
+@code{file-executable-p}, @code{file-exists-p}, @code{file-local-copy},
+@code{file-modes}, @code{file-name-all-completions},
+@code{file-name-as-directory}, @code{file-name-completion},
+@code{file-name-directory}, @code{file-name-nondirectory},
+@code{file-name-sans-versions}, @code{file-newer-than-file-p},
+@code{file-readable-p}, @code{file-symlink-p}, @code{file-truename},
+@code{file-writable-p}, @code{insert-directory},
+@code{insert-file-contents}, @code{load}, @code{make-directory},
+@code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes},
+@code{set-visited-file-modtime}, @code{unhandled-file-name-directory},
+@code{verify-visited-file-modtime}, @code{write-region}.
+
+The handler function must handle all of the above operations, and
+possibly others to be added in the future.  Therefore, it should always
+reinvoke the ordinary Lisp primitive when it receives an operation it
+does not recognize.  Here's one way to do this:
+
+@example
+(defun my-file-handler (operation &rest args)
+  ;; @r{First check for the specific operations}
+  ;; @r{that we have special handling for.}
+  (cond ((eq operation 'insert-file-contents) @dots{})
+        ((eq operation 'write-region) @dots{})
+        @dots{}
+        ;; @r{Handle any operation we don't know about.}
+        (t (let (file-name-handler-alist)
+             (apply operation args)))))
+@end example
+
+@defun find-file-name-handler file
+This function returns the handler function for file name @var{file}, or
+@code{nil} if there is none.
+@end defun
+
+@defun file-local-copy filename
+This function copies file @var{filename} to the local site, if it isn't
+there already.  If @var{filename} specifies a ``magic'' file name which
+programs outside Emacs cannot directly read or write, this copies the
+contents to an ordinary file and returns that file's name.
+
+If @var{filename} is an ordinary file name, not magic, then this function
+does nothing and returns @code{nil}.
+@end defun
+
+@defun unhandled-file-name-directory filename
+This function returns the name of a directory that is not magic.
+It uses the directory part of @var{filename} if that is not magic.
+Otherwise, it asks the handler what to do.
+
+This is useful for running a subprocess; every subprocess must have a
+non-magic directory to serve as its current directory, and this function
+is a good way to come up with one.
+@end defun

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/lispref/minibuf.texi	Mon Mar 28 18:36:14 1994 +0000
@@ -0,0 +1,1404 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/minibuf
+@node Minibuffers, Command Loop, Streams, Top
+@chapter Minibuffers
+@cindex arguments, reading
+@cindex complex arguments
+@cindex minibuffer
+
+  A @dfn{minibuffer} is a special buffer that Emacs commands use to read
+arguments more complicated than the single numeric prefix argument.
+These arguments include file names, buffer names, and command names (as
+in @kbd{M-x}).  The minibuffer is displayed on the bottom line of the
+screen, in the same place as the echo area, but only while it is in
+use for reading an argument.
+
+@menu
+* Intro to Minibuffers::      Basic information about minibuffers.
+* Text from Minibuffer::      How to read a straight text string.
+* Object from Minibuffer::    How to read a Lisp object or expression.
+* Minibuffer History::	      Recording previous minibuffer inputs
+				so the user can reuse them.
+* Completion::                How to invoke and customize completion.
+* Yes-or-No Queries::         Asking a question with a simple answer.
+* Multiple Queries::	      Asking a series of similar questions.
+* Minibuffer Misc::           Various customization hooks and variables.
+@end menu
+
+@node Intro to Minibuffers
+@section Introduction to Minibuffers
+
+  In most ways, a minibuffer is a normal Emacs buffer.  Most operations
+@emph{within} a buffer, such as editing commands, work normally in a
+minibuffer.  However, many operations for managing buffers do not apply
+to minibuffers.  The name of a minibuffer always has the form @w{@samp{
+*Minibuf-@var{number}}}, and it cannot be changed.  Minibuffers are
+displayed only in special windows used only for minibuffers; these
+windows always appear at the bottom of a frame.  (Sometime frames have
+no minibuffer window, and sometimes a special kind of frame contains
+nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
+
+  The minibuffers window is normally a single line.  You can resize it
+temporarily with the window sizing commands; it reverts to its normal
+size when the minibuffer is exited.  You can resize it permanently by
+using the window sizing commands in the frame's other window, when the
+minibuffer is not active.  If the frame contains just a minibuffer, you
+can change the minibuffer's size by changing the frame's size.
+
+  If a command uses a minibuffer while there is an active minibuffer,
+this is called a @dfn{recursive minibuffer}.  The first minibuffer is
+named @w{@samp{ *Minibuf-0*}}.  Recursive minibuffers are named by
+incrementing the number at the end of the name.  (The names begin with a
+space so that they won't show up in normal buffer lists.)  Of several
+recursive minibuffers, the innermost (or most recently entered) is the
+active minibuffer.  We usually call this ``the'' minibuffer.  You can
+permit or forbid recursive minibuffers by setting the variable
+@code{enable-recursive-minibuffers} or by putting properties of that
+name on command symbols (@pxref{Minibuffer Misc}).
+
+  Like other buffers, a minibuffer may use any of several local keymaps
+(@pxref{Keymaps}); these contain various exit commands and in some cases
+completion commands.  @xref{Completion}.
+
+@itemize @bullet
+@item
+@code{minibuffer-local-map} is for ordinary input (no completion).
+
+@item
+@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
+just like @key{RET}.  This is used mainly for Mocklisp compatibility.
+
+@item
+@code{minibuffer-local-completion-map} is for permissive completion.
+
+@item
+@code{minibuffer-local-must-match-map} is for strict completion and
+for cautious completion.
+@end itemize
+
+@node Text from Minibuffer
+@section Reading Text Strings with the Minibuffer
+
+  Most often, the minibuffer is used to read text which is returned as a
+string.  It can also be used to read a Lisp object in textual form.  The
+most basic primitive for minibuffer input is
+@code{read-from-minibuffer}; it can do either one.
+
+@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist
+This function is the most general way to get input through the
+minibuffer.  By default, it accepts arbitrary text and returns it as a
+string; however, if @var{read} is non-@code{nil}, then it uses
+@code{read} to convert the text into a Lisp object (@pxref{Input
+Functions}).
+
+The first thing this function does is to activate a minibuffer and 
+display it with @var{prompt-string} as the prompt.  This value must be a
+string.
+
+Then, if @var{initial-contents} is a string, @code{read-from-minibuffer}
+inserts it into the minibuffer, leaving point at the end.  The
+minibuffer appears with this text as its contents.
+
+@c Emacs 19 feature
+The value of @var{initial-contents} may also be a cons cell of the form
+@code{(@var{string} . @var{position})}.  This means to insert
+@var{string} in the minibuffer but put point @var{position} characters
+from the beginning, rather than at the end.
+
+If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
+use in the minibuffer.  If @var{keymap} is omitted or @code{nil}, the
+value of @code{minibuffer-local-map} is used as the keymap.  Specifying
+a keymap is the most important way to customize the minibuffer for
+various applications such as completion.
+
+The argument @var{hist} specifies which history list variable to use
+for saving the input and for history commands used in the minibuffer.
+It defaults to @code{minibuffer-history}.  @xref{Minibuffer History}.
+
+When the user types a command to exit the minibuffer,
+@code{read-from-minibuffer} uses the text in the minibuffer to produce
+its return value.  Normally it simply makes a string containing that
+text.  However, if @var{read} is non-@code{nil},
+@code{read-from-minibuffer} reads the text and returns the resulting
+Lisp object, unevaluated.  (@xref{Input Functions}, for information
+about reading.)
+@end defun
+
+@defun read-string prompt &optional initial
+This function reads a string from the minibuffer and returns it.  The
+arguments @var{prompt} and @var{initial} are used as in
+@code{read-from-minibuffer}.  The keymap used is
+@code{minibuffer-local-map}.
+
+This is a simplified interface to the
+@code{read-from-minibuffer} function:
+
+@smallexample
+@group
+(read-string @var{prompt} @var{initial})
+@equiv{}
+(read-from-minibuffer @var{prompt} @var{initial} nil nil)
+@end group
+@end smallexample
+@end defun
+
+@defvar minibuffer-local-map
+This is the default local keymap for reading from the minibuffer.  By
+default, it makes the following bindings:
+
+@table @asis
+@item @key{LFD}
+@code{exit-minibuffer}
+
+@item @key{RET}
+@code{exit-minibuffer}
+
+@item @kbd{C-g}
+@code{abort-recursive-edit}
+
+@item @kbd{M-n}
+@code{next-history-element}
+
+@item @kbd{M-p}
+@code{previous-history-element}
+
+@item @kbd{M-r}
+@code{next-matching-history-element}
+
+@item @kbd{M-s}
+@code{previous-matching-history-element}
+@end table
+@end defvar
+
+@c In version 18, initial is required
+@c Emacs 19 feature
+@defun read-no-blanks-input prompt &optional initial
+This function reads a string from the minibuffer, but does not allow
+whitespace characters as part of the input: instead, those characters
+terminate the input.  The arguments @var{prompt} and @var{initial} are
+used as in @code{read-from-minibuffer}.
+
+This is a simplified interface to the @code{read-from-minibuffer}
+function, and passes the value of the @code{minibuffer-local-ns-map}
+keymap as the @var{keymap} argument for that function.  Since the keymap
+@code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is}
+possible to put a space into the string, by quoting it.
+
+@smallexample
+@group
+(read-no-blanks-input @var{prompt} @var{initial})
+@equiv{}
+(read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map)
+@end group
+@end smallexample
+@end defun
+
+@defvar minibuffer-local-ns-map
+This built-in variable is the keymap used as the minibuffer local keymap
+in the function @code{read-no-blanks-input}.  By default, it makes the
+following bindings:
+
+@table @asis
+@item @key{LFD}
+@code{exit-minibuffer}
+
+@item @key{SPC}
+@cindex @key{SPC} in minibuffer
+@code{exit-minibuffer}
+
+@item @key{TAB}
+@cindex @key{TAB} in minibuffer
+@code{exit-minibuffer}
+
+@item @key{RET}
+@code{exit-minibuffer}
+
+@item @kbd{C-g}
+@code{abort-recursive-edit}
+
+@item @kbd{?}
+@cindex @kbd{?} in minibuffer
+@code{self-insert-and-exit}
+
+@item @kbd{M-n} and @kbd{M-p}
+@code{next-history-element} and @code{previous-history-element}
+
+@item @kbd{M-r}
+@code{next-matching-history-element}
+
+@item @kbd{M-s}
+@code{previous-matching-history-element}
+@end table
+@end defvar
+
+@node Object from Minibuffer
+@section Reading Lisp Objects with the Minibuffer
+
+  This section describes functions for reading Lisp objects with the
+minibuffer.
+
+@defun read-minibuffer prompt &optional initial
+  This function reads a Lisp object in the minibuffer and returns it,
+without evaluating it.  The arguments @var{prompt} and @var{initial} are
+used as in @code{read-from-minibuffer}; in particular, @var{initial}
+must be a string or @code{nil}.
+
+  This is a simplified interface to the
+@code{read-from-minibuffer} function:
+
+@smallexample
+@group
+(read-minibuffer @var{prompt} @var{initial})
+@equiv{}
+(read-from-minibuffer @var{prompt} @var{initial} nil t)
+@end group
+@end smallexample
+
+Here is an example in which we supply the string @code{"(testing)"} as
+initial input:
+
+@smallexample
+@group
+(read-minibuffer
+ "Enter an expression: " (format "%s" '(testing)))
+
+;; @r{Here is how the minibuffer is displayed:}
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+Enter an expression: (testing)@point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end smallexample
+
+@noindent
+The user can type @key{RET} immediately to use the initial input as a
+default, or can edit the input.
+@end defun
+
+@defun eval-minibuffer prompt &optional initial
+  This function reads a Lisp expression in the minibuffer, evaluates it,
+then returns the result.  The arguments @var{prompt} and @var{initial}
+are used as in @code{read-from-minibuffer}.
+
+  This function simply evaluates the result of a call to
+@code{read-minibuffer}:
+
+@smallexample
+@group
+(eval-minibuffer @var{prompt} @var{initial})
+@equiv{}
+(eval (read-minibuffer @var{prompt} @var{initial}))
+@end group
+@end smallexample
+@end defun
+
+@defun edit-and-eval-command prompt form
+  This function reads a Lisp expression in the minibuffer, and then
+evaluates it.  The difference between this command and
+@code{eval-minibuffer} is that here the initial @var{form} is not
+optional and it is treated as a Lisp object to be converted to printed
+representation rather than as a string of text.  It is printed with
+@code{prin1}, so if it is a string, double-quote characters (@samp{"})
+appear in the initial text.  @xref{Output Functions}.
+
+  The first thing @code{edit-and-eval-command} does is to activate the
+minibuffer with @var{prompt} as the prompt.  Then it inserts the printed
+representation of @var{form} in the minibuffer, and lets the user edit.
+When the user exits the minibuffer, the edited text is read with
+@code{read} and then evaluated.  The resulting value becomes the value
+of @code{edit-and-eval-command}.
+
+  In the following example, we offer the user an expression with initial
+text which is a valid form already:
+
+@smallexample
+@group
+(edit-and-eval-command "Please edit: " '(forward-word 1))
+
+;; @r{After evaluating the preceding expression,} 
+;;   @r{the following appears in the minibuffer:}
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+Please edit: (forward-word 1)@point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end smallexample
+
+@noindent
+Typing @key{RET} right away would exit the minibuffer and evaluate the
+expression, thus moving point forward one word.
+@code{edit-and-eval-command} returns @code{nil} in this example.
+@end defun
+
+@node Minibuffer History
+@section Minibuffer History
+@cindex minibuffer history
+@cindex history list
+
+A @dfn{minibuffer history list} records previous minibuffer inputs so
+the user can reuse them conveniently.  A history list is a symbol, a
+variable whose value is a list of strings (previous inputs), most recent
+first.
+
+There are many separate history lists, used for different kinds of
+inputs.  It's the Lisp programmer's job to specify the right history
+list for each use of the minibuffer.
+
+The basic minibuffer input functions @code{read-from-minibuffer} and
+@code{completing-read} both accept an optional argument named @var{hist}
+which is how you specify the history list.  Here are the possible
+values:
+
+@table @asis
+@item @var{variable}
+Use @var{variable} (a symbol) as the history list.
+
+@item (@var{variable} . @var{startpos})
+Use @var{variable} (a symbol) as the history list, and assume that the
+initial history position is @var{startpos} (an integer, counting from
+zero which specifies the most recent element of the history).
+
+If you specify @var{startpos}, then you should also specify that element
+of the history as the initial minibuffer contents, for consistency.
+@end table
+
+If you don't specify @var{hist}, then the default history list
+@code{minibuffer-history} is used.  For other standard history lists,
+see below.  You can also create your own history list variable; just
+initialize it to @code{nil} before the first use.
+
+Both @code{read-from-minibuffer} and @code{completing-read} add new
+elements to the history list automatically, and provide commands to
+allow the user to reuse items on the list.  The only thing your program
+needs to do to use a history list is to initialize it and to pass its
+name to the input functions when you wish.  But it is safe to modify the
+list by hand when the minibuffer input functions are not using it.
+
+@defvar minibuffer-history
+The default history list for minibuffer history input.
+@end defvar
+
+@defvar query-replace-history
+A history list for arguments to @code{query-replace} (and similar
+arguments to other commands).
+@end defvar
+
+@defvar file-name-history
+A history list for file name arguments.
+@end defvar
+
+@defvar regexp-history
+A history list for regular expression arguments.
+@end defvar
+
+@defvar extended-command-history
+A history list for arguments that are names of extended commands.
+@end defvar
+
+@defvar shell-command-history
+A history list for arguments that are shell commands.
+@end defvar
+
+@defvar read-expression-history
+A history list for arguments that are Lisp expressions to evaluate.
+@end defvar
+
+@node Completion
+@section Completion
+@cindex completion
+
+  @dfn{Completion} is a feature that fills in the rest of a name
+starting from an abbreviation for it.  Completion works by comparing the
+user's input against a list of valid names and determining how much of
+the name is determined uniquely by what the user has typed.  For
+example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then
+type the first few letters of the name of the buffer to which you wish
+to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs
+extends the name as far as it can.
+
+  Standard Emacs commands offer completion for names of symbols, files,
+buffers, and processes; with the functions in this section, you can
+implement completion for other kinds of names.
+
+  The @code{try-completion} function is the basic primitive for
+completion: it returns the longest determined completion of a given
+initial string, with a given set of strings to match against.
+
+  The function @code{completing-read} provides a higher-level interface
+for completion.  A call to @code{completing-read} specifies how to
+determine the list of valid names.  The function then activates the
+minibuffer with a local keymap that binds a few keys to commands useful
+for completion.  Other functions provide convenient simple interfaces
+for reading certain kinds of names with completion.
+
+@menu
+* Basic Completion::       Low-level functions for completing strings.
+                             (These are too low level to use the minibuffer.)
+* Minibuffer Completion::  Invoking the minibuffer with completion.
+* Completion Commands::    Minibuffer commands that do completion.
+* High-Level Completion::  Convenient special cases of completion
+                             (reading buffer name, file name, etc.)
+* Reading File Names::     Using completion to read file names.
+* Programmed Completion::  Finding the completions for a given file name.
+@end menu
+
+@node Basic Completion
+@subsection Basic Completion Functions
+
+@defun try-completion string collection &optional predicate
+This function returns the longest common substring of all possible
+completions of @var{string} in @var{collection}.  The value of
+@var{collection} must be an alist, an obarray, or a function which
+implements a virtual set of strings (see below).
+
+Completion compares @var{string} against each of the permissible
+completions specified by @var{collection}; if the beginning of the
+permissible completion equals @var{string}, it matches.  If no permissible
+completions match, @code{try-completion} returns @code{nil}.  If only
+one permissible completion matches, and the match is exact, then
+@code{try-completion} returns @code{t}.  Otherwise, the value is the
+longest initial sequence common to all the permissible completions that
+match.
+
+If @var{collection} is an alist (@pxref{Association Lists}), the
+@sc{car}s of the alist elements form the set of permissible completions.
+
+@cindex obarray in completion
+If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
+of all symbols in the obarray form the set of permissible completions.  The
+global variable @code{obarray} holds an obarray containing the names of
+all interned Lisp symbols.
+
+Note that the only valid way to make a new obarray is to create it
+empty and then add symbols to it one by one using @code{intern}.
+Also, you cannot intern a given symbol in more than one obarray.
+
+If the argument @var{predicate} is non-@code{nil}, then it must be a
+function of one argument.  It is used to test each possible match, and
+the match is accepted only if @var{predicate} returns non-@code{nil}.
+The argument given to @var{predicate} is either a cons cell from the alist
+(the @sc{car} of which is a string) or else it is a symbol (@emph{not} a
+symbol name) from the obarray.
+
+You can also use a function symbol as @var{collection}.  Then the
+function is solely responsible for performing completion;
+@code{try-completion} returns whatever this function returns.  The
+function is called with three arguments: @var{string}, @var{predicate}
+and @code{nil}.  (The reason for the third argument is so that the same
+function can be used in @code{all-completions} and do the appropriate
+thing in either case.)  @xref{Programmed Completion}.
+
+In the first of the following examples, the string @samp{foo} is
+matched by three of the alist @sc{car}s.  All of the matches begin with
+the characters @samp{fooba}, so that is the result.  In the second
+example, there is only one possible match, and it is exact, so the value
+is @code{t}.
+
+@smallexample
+@group
+(try-completion 
+ "foo"
+ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
+     @result{} "fooba"
+@end group
+
+@group
+(try-completion "foo" '(("barfoo" 2) ("foo" 3)))
+     @result{} t
+@end group
+@end smallexample
+
+In the following example, numerous symbols begin with the characters
+@samp{forw}, and all of them begin with the word @samp{forward}.  In
+most of the symbols, this is followed with a @samp{-}, but not in all,
+so no more than @samp{forward} can be completed.
+
+@smallexample
+@group
+(try-completion "forw" obarray)
+     @result{} "forward"
+@end group
+@end smallexample
+
+Finally, in the following example, only two of the three possible
+matches pass the predicate @code{test} (the string @samp{foobaz} is
+too short).  Both of those begin with the string @samp{foobar}.
+
+@smallexample
+@group
+(defun test (s) 
+  (> (length (car s)) 6))
+     @result{} test
+@end group
+@group
+(try-completion 
+ "foo"
+ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) 
+     'test)
+     @result{} "foobar"
+@end group
+@end smallexample
+@end defun
+
+@defun all-completions string collection &optional predicate 
+This function returns a list of all possible completions of
+@var{string}.  The parameters to this function are the same as to
+@code{try-completion}.
+
+If @var{collection} is a function, it is called with three arguments:
+@var{string}, @var{predicate} and @code{t}; then @code{all-completions}
+returns whatever the function returns.  @xref{Programmed Completion}.
+
+Here is an example, using the function @code{test} shown in the
+example for @code{try-completion}:
+
+@smallexample
+@group
+(defun test (s) 
+  (> (length (car s)) 6))
+     @result{} test
+@end group
+
+@group
+(all-completions  
+ "foo"
+ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
+ (function test))
+     @result{} ("foobar1" "foobar2")
+@end group
+@end smallexample
+@end defun
+
+@defvar completion-ignore-case
+If the value of this variable is 
+non-@code{nil}, Emacs does not consider case significant in completion.
+@end defvar
+
+  The two functions @code{try-completion} and @code{all-completions}
+have nothing in themselves to do with minibuffers.  We describe them in
+this chapter so as to keep them near the higher-level completion
+features that do use the minibuffer.
+
+@node Minibuffer Completion
+@subsection Completion and the Minibuffer
+
+  This section describes the basic interface for reading from the
+minibuffer with completion.
+
+@defun completing-read prompt collection &optional predicate require-match initial hist
+This function reads a string in the minibuffer, assisting the user by
+providing completion.  It activates the minibuffer with prompt
+@var{prompt}, which must be a string.  If @var{initial} is
+non-@code{nil}, @code{completing-read} inserts it into the minibuffer as
+part of the input.  Then it allows the user to edit the input, providing
+several commands to attempt completion.
+
+The actual completion is done by passing @var{collection} and
+@var{predicate} to the function @code{try-completion}.  This happens in
+certain commands bound in the local keymaps used for completion.
+
+If @var{require-match} is @code{t}, the usual minibuffer exit commands
+won't exit unless the input completes to an element of @var{collection}.
+If @var{require-match} is neither @code{nil} nor @code{t}, then the exit
+commands won't exit unless the input typed is itself an element of
+@var{collection}.
+
+The function @code{completing-read} works by calling
+@code{read-minibuffer}.  It uses @code{minibuffer-local-completion-map}
+as the keymap if @var{require-match} is @code{nil}, and uses
+@code{minibuffer-local-must-match-map} if @var{require-match} is
+non-@code{nil}.
+
+The argument @var{hist} specifies which history list variable to use for
+saving the input and for minibuffer history commands.  It defaults to
+@code{minibuffer-history}.  @xref{Minibuffer History}.
+
+Completion ignores case when comparing the input against the possible
+matches, if the built-in variable @code{completion-ignore-case} is
+non-@code{nil}.  @xref{Basic Completion}.
+
+Here's an example of using @code{completing-read}:
+
+@smallexample
+@group
+(completing-read
+ "Complete a foo: "
+ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
+ nil t "fo")
+@end group
+
+@group
+;; @r{After evaluating the preceding expression,} 
+;;   @r{the following appears in the minibuffer:}
+
+---------- Buffer: Minibuffer ----------
+Complete a foo: fo@point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end smallexample
+
+@noindent
+If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}},
+@code{completing-read} returns @code{barfoo}.
+
+The @code{completing-read} function binds three variables to pass
+information to the commands which actually do completion.  Here they
+are:
+
+@table @code
+@item minibuffer-completion-table
+This variable is bound to the @var{collection} argument.  It is passed
+to the @code{try-completion} function.
+
+@item minibuffer-completion-predicate
+This variable is bound to the @var{predicate} argument.  It is passed to
+the @code{try-completion} function.
+
+@item minibuffer-completion-confirm
+This variable is bound to the @var{require-match} argument.  It is used
+in the @code{minibuffer-complete-and-exit} function.
+@end table
+@end defun
+
+@node Completion Commands
+@subsection Minibuffer Commands That Do Completion
+
+  This section describes the keymaps, commands and user options used in
+the minibuffer to do completion.
+
+@defvar minibuffer-local-completion-map
+  @code{completing-read} uses this value as the local keymap when an
+exact match of one of the completions is not required.  By default, this
+keymap makes the following bindings:
+
+@table @asis
+@item @kbd{?}
+@code{minibuffer-completion-help}
+
+@item @key{SPC}
+@code{minibuffer-complete-word}
+
+@item @key{TAB}
+@code{minibuffer-complete}
+@end table
+
+@noindent
+with other characters bound as in @code{minibuffer-local-map}.
+@end defvar
+
+@defvar minibuffer-local-must-match-map
+@code{completing-read} uses this value as the local keymap when an
+exact match of one of the completions is required.  Therefore, no keys
+are bound to @code{exit-minibuffer}, the command which exits the
+minibuffer unconditionally.  By default, this keymap makes the following
+bindings:
+
+@table @asis
+@item @kbd{?}
+@code{minibuffer-completion-help}
+
+@item @key{SPC}
+@code{minibuffer-complete-word}
+
+@item @key{TAB}
+@code{minibuffer-complete}
+
+@item @key{LFD}
+@code{minibuffer-complete-and-exit}
+
+@item @key{RET}
+@code{minibuffer-complete-and-exit}
+@end table
+
+@noindent
+with other characters bound as in @code{minibuffer-local-map}.
+@end defvar
+
+@defvar minibuffer-completion-table
+The value of this variable is the alist or obarray used for completion
+in the minibuffer.  This is the global variable that contains what
+@code{completing-read} passes to @code{try-completion}.  It is used by
+minibuffer completion commands such as @code{minibuffer-complete-word}.
+@end defvar
+
+@defvar minibuffer-completion-predicate
+This variable's value is the predicate that @code{completing-read}
+passes to @code{try-completion}.  The variable is also used by the other
+minibuffer completion functions.
+@end defvar
+
+@deffn Command minibuffer-complete-word
+This function completes the minibuffer contents by at most a single
+word.  Even if the minibuffer contents have only one completion,
+@code{minibuffer-complete-word} does not add any characters beyond the
+first character that is not a word constituent.  @xref{Syntax Tables}.
+@end deffn
+
+@deffn Command minibuffer-complete
+This function completes the minibuffer contents as far as possible.
+@end deffn
+
+@deffn Command minibuffer-complete-and-exit
+This function completes the minibuffer contents, and exits if
+confirmation is not required, i.e., if
+@code{minibuffer-completion-confirm} is non-@code{nil}.  If confirmation
+@emph{is} required, it is given by repeating this command immediately.
+@end deffn
+
+@defvar minibuffer-completion-confirm
+When the value of this variable is non-@code{nil}, Emacs asks for
+confirmation of a completion before exiting the minibuffer.  The
+function @code{minibuffer-complete-and-exit} checks the value of this
+variable before it exits.
+@end defvar
+
+@deffn Command minibuffer-completion-help
+This function creates a list of the possible completions of the
+current minibuffer contents.  It works by calling @code{all-completions}
+using the value of the variable @code{minibuffer-completion-table} as
+the @var{collection} argument, and the value of
+@code{minibuffer-completion-predicate} as the @var{predicate} argument.
+The list of completions is displayed as text in a buffer named
+@samp{*Completions*}.
+@end deffn
+
+@defun display-completion-list completions
+This function displays @var{completions} to the stream in
+@code{standard-output}, usually a buffer.  (@xref{Streams}, for more
+information about streams.)  The argument @var{completions} is normally
+a list of completions just returned by @code{all-completions}, but it
+does not have to be.  Each element may be a symbol or a string, either
+of which is simply printed, or a list of two strings, which is printed
+as if the strings were concatenated.
+
+This function is called by @code{minibuffer-completion-help}.  The
+most common way to use it is together with
+@code{with-output-to-temp-buffer}, like this:
+
+@example
+(with-output-to-temp-buffer "*Completions*"
+  (display-completion-list
+    (all-completions (buffer-string) my-alist)))
+@end example
+@end defun
+
+@defopt completion-auto-help
+If this variable is non-@code{nil}, the completion commands
+automatically display a list of possible completions whenever nothing
+can be completed because the next character is not uniquely determined.
+@end defopt
+
+@node High-Level Completion
+@subsection High-Level Completion  Functions
+
+  This section describes the higher-level convenient functions for
+reading certain sorts of names with completion.
+
+@defun read-buffer prompt &optional default existing
+This function reads the name of a buffer and returns it as a string.
+The argument @var{default} is the default name to use, the value to
+return if the user exits with an empty minibuffer.  If non-@code{nil},
+it should be a string or a buffer.  It is mentioned in the prompt, but
+is not inserted in the minibuffer as initial input.
+
+If @var{existing} is non-@code{nil}, then the name specified must be
+that of an  existing buffer.  The usual commands to exit the
+minibuffer do not exit if the text is not valid, and @key{RET} does
+completion to attempt to find a valid name.  (However, @var{default} is
+not checked for this; it is returned, whatever it is, if the user exits
+with the minibuffer empty.)
+
+In the following example, the user enters @samp{minibuffer.t}, and
+then types @key{RET}.  The argument @var{existing} is @code{t}, and the
+only buffer name starting with the given input is
+@samp{minibuffer.texi}, so that name is the value.
+
+@example
+(read-buffer "Buffer name? " "foo" t)
+@group
+;; @r{After evaluating the preceding expression,} 
+;;   @r{the following prompt appears,}
+;;   @r{with an empty minibuffer:}
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+Buffer name? (default foo) @point{}
+---------- Buffer: Minibuffer ----------
+@end group
+
+@group
+;; @r{The user types @kbd{minibuffer.t @key{RET}}.}
+     @result{} "minibuffer.texi"
+@end group
+@end example
+@end defun
+
+@defun read-command prompt
+This function reads the name of a command and returns it as a Lisp
+symbol.  The argument @var{prompt} is used as in
+@code{read-from-minibuffer}.  Recall that a command is anything for
+which @code{commandp} returns @code{t}, and a command name is a symbol
+for which @code{commandp} returns @code{t}.  @xref{Interactive Call}.
+
+@example
+(read-command "Command name? ")
+
+@group
+;; @r{After evaluating the preceding expression,} 
+;;   @r{the following prompt appears with an empty minibuffer:}
+@end group
+
+@group
+---------- Buffer: Minibuffer ---------- 
+Command name?  
+---------- Buffer: Minibuffer ----------
+@end group
+@end example
+
+@noindent
+If the user types @kbd{forward-c @key{RET}}, then this function returns
+@code{forward-char}.
+
+The @code{read-command} function is a simplified interface to the
+function @code{completing-read}.  It uses the variable @code{obarray} so
+as to complete in the set of extant Lisp symbols, and it uses the
+@code{commandp} predicate so as to accept only command names:
+
+@cindex @code{commandp} example
+@example
+@group
+(read-command @var{prompt})
+@equiv{}
+(intern (completing-read @var{prompt} obarray 
+                         'commandp t nil))
+@end group
+@end example
+@end defun
+
+@defun read-variable prompt
+This function reads the name of a user variable and returns it as a
+symbol.
+
+@example
+@group
+(read-variable "Variable name? ")
+
+;; @r{After evaluating the preceding expression,} 
+;;   @r{the following prompt appears,} 
+;;   @r{with an empty minibuffer:}
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+Variable name? @point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end example
+
+@noindent
+If the user then types @kbd{fill-p @key{RET}}, @code{read-variable}
+returns @code{fill-prefix}.
+
+This function is similar to @code{read-command}, but uses the
+predicate @code{user-variable-p} instead of @code{commandp}:
+
+@cindex @code{user-variable-p} example
+@example
+@group
+(read-variable @var{prompt})
+@equiv{}
+(intern
+ (completing-read @var{prompt} obarray
+                  'user-variable-p t nil))
+@end group
+@end example
+@end defun
+
+@node Reading File Names
+@subsection Reading File Names
+
+  Here is another high-level completion function, designed for reading a
+file name.  It provides special features including automatic insertion
+of the default directory.
+
+@defun read-file-name prompt &optional directory default existing initial
+This function reads a file name in the minibuffer, prompting with
+@var{prompt} and providing completion.  If @var{default} is
+non-@code{nil}, then the function returns @var{default} if the user just
+types @key{RET}.
+
+If @var{existing} is non-@code{nil}, then the name must refer to an
+existing file; then @key{RET} performs completion to make the name valid
+if possible, and then refuses to exit if it is not valid.  If the value
+of @var{existing} is neither @code{nil} nor @code{t}, then @key{RET}
+also requires confirmation after completion.
+
+The argument @var{directory} specifies the directory to use for
+completion of relative file names.  Usually it is inserted in the
+minibuffer as initial input as well.  It defaults to the current
+buffer's value of @code{default-directory}.
+
+@c Emacs 19 feature
+If you specify @var{initial}, that is an initial file name to insert in
+the buffer along with @var{directory}.  In this case, point goes after
+@var{directory}, before @var{initial}.  The default for @var{initial} is
+@code{nil}---don't insert any file name.  To see what @var{initial}
+does, try the command @kbd{C-x C-v}.
+
+Here is an example: 
+
+@example
+@group
+(read-file-name "The file is ")
+
+;; @r{After evaluating the preceding expression,} 
+;;   @r{the following appears in the minibuffer:}
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+The file is /gp/gnu/elisp/@point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end example
+
+@noindent
+Typing @kbd{manual @key{TAB}} results in the following:
+
+@example
+@group
+---------- Buffer: Minibuffer ----------
+The file is /gp/gnu/elisp/manual.texi@point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end example
+
+@c Wordy to avoid overfull hbox in smallbook mode.
+@noindent
+If the user types @key{RET}, @code{read-file-name} returns the file name
+as the string @code{"/gp/gnu/elisp/manual.texi"}.
+@end defun
+
+@defopt insert-default-directory
+This variable is used by @code{read-file-name}.  Its value controls
+whether @code{read-file-name} starts by placing the name of the default
+directory in the minibuffer, plus the initial file name if any.  If the
+value of this variable is @code{nil}, then @code{read-file-name} does
+not place any initial input in the minibuffer.  In that case, the
+default directory is still used for completion of relative file names,
+but is not displayed.
+
+For example:
+
+@example
+@group
+;; @r{Here the minibuffer starts out with the default directory.}
+(let ((insert-default-directory t))
+  (read-file-name "The file is "))
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+The file is ~lewis/manual/@point{}
+---------- Buffer: Minibuffer ----------
+@end group
+
+@group
+;; @r{Here the minibuffer is empty and only the prompt}
+;;   @r{appears on its line.}
+(let ((insert-default-directory nil))
+  (read-file-name "The file is "))
+@end group
+
+@group
+---------- Buffer: Minibuffer ----------
+The file is @point{}
+---------- Buffer: Minibuffer ----------
+@end group
+@end example
+@end defopt
+
+@node Programmed Completion
+@subsection Programmed Completion
+@cindex programmed completion
+
+  Sometimes it is not possible to create an alist or an obarray
+containing all the intended possible completions.  In such a case, you
+can supply your own function to compute the completion of a given string.
+This is called @dfn{programmed completion}.
+
+  To use this feature, pass a symbol with a function definition as the
+@var{collection} argument to @code{completing-read}.  This function
+arranges to pass your completion function along to @code{try-completion}
+and @code{all-completions}, which will then let your function do all the
+work.
+
+  The completion function should accept three arguments:
+
+@itemize @bullet
+@item
+The string to be completed.
+
+@item
+The predicate function to filter possible matches, or @code{nil} if
+none.  Your function should call the predicate for each possible match,
+and ignore the possible match if the predicate returns @code{nil}.
+
+@item
+A flag specifying the type of operation.
+@end itemize
+
+  There are three flag values for three operations:
+
+@itemize @bullet
+@item
+@code{nil} specifies @code{try-completion}.  The completion function
+should return the completion of the specified string, or @code{t} if the
+string is an exact match already, or @code{nil} if the string matches no
+possibility.
+
+@item
+@code{t} specifies @code{all-completions}.  The completion function
+should return a list of all possible completions of the specified
+string.
+
+@item
+@code{lambda} specifies a test for an exact match.  The completion
+function should return @code{t} if the specified string is an exact
+match for some possibility; @code{nil} otherwise.
+@end itemize
+
+  It would be consistent and clean for completion functions to allow
+lambda expressions (lists which are functions) as well as function
+symbols as @var{collection}, but this is impossible.  Lists as
+completion tables are already assigned another meaning---as alists.  It
+would be unreliable to fail to handle an alist normally because it is
+also a possible function.  So you must arrange for any function you wish
+to use for completion to be encapsulated in a symbol.
+
+  Emacs uses programmed completion when completing file names.
+@xref{File Name Completion}.
+
+@node Yes-or-No Queries
+@section Yes-or-No Queries
+@cindex asking the user questions
+@cindex querying the user
+@cindex yes-or-no questions
+
+  This section describes functions used to ask the user a yes-or-no
+question.  The function @code{y-or-n-p} can be answered with a single
+character; it is useful for questions where an inadvertent wrong answer
+will not have serious consequences.  @code{yes-or-no-p} is suitable for
+more momentous questions, since it requires three or four characters to
+answer.
+
+  Strictly speaking, @code{yes-or-no-p} uses the minibuffer and
+@code{y-or-n-p} does not; but it seems best to describe them together.
+
+@defun y-or-n-p prompt
+  This function asks the user a question, expecting input in the echo
+area.  It returns @code{t} if the user types @kbd{y}, @code{nil} if the
+user types @kbd{n}.  This function also accepts @key{SPC} to mean yes
+and @key{DEL} to mean no.  It accepts @kbd{C-]} to mean ``quit'', like
+@kbd{C-g}, because the question might look like a minibuffer and for
+that reason the user might try to use @kbd{C-]} to get out.  The answer
+is a single character, with no @key{RET} needed to terminate it.  Upper
+and lower case are equivalent.
+
+  ``Asking the question'' means printing @var{prompt} in the echo area,
+followed by the string @w{@samp{(y or n) }}.  If the input is not one of
+the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}},
+@kbd{@key{DEL}}, or something that quits), the function responds
+@samp{Please answer y or n.}, and repeats the request.
+
+  This function does not actually use the minibuffer, since it does not
+allow editing of the answer.  It actually uses the echo area (@pxref{The
+Echo Area}), which uses the same screen space as the minibuffer.  The
+cursor moves to the echo area while the question is being asked.
+
+  The answers and their meanings, even @samp{y} and @samp{n}, are not
+hardwired.  The keymap @code{query-replace-map} specifies them.
+@xref{Search and Replace}.
+
+  If @code{y-or-n-p} is called in a command that was invoked using the
+mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
+Loop Info}) is either @code{nil} or a mouse event---then it uses a
+dialog box or pop-up menu to ask the question.  In this case, it does
+not use keyboard input or the echo area.
+
+  In the following example, the user first types @kbd{q}, which is
+invalid.  At the next prompt the user types @kbd{y}.
+
+@smallexample
+@group
+(y-or-n-p "Do you need a lift? ")
+
+;; @r{After evaluating the preceding expression,} 
+;;   @r{the following prompt appears in the echo area:}
+@end group
+
+@group
+---------- Echo area ----------
+Do you need a lift? (y or n) 
+---------- Echo area ----------
+@end group
+
+;; @r{If the user then types @kbd{q}, the following appears:}
+
+@group
+---------- Echo area ----------
+Please answer y or n.  Do you need a lift? (y or n) 
+---------- Echo area ----------
+@end group
+
+;; @r{When the user types a valid answer,}
+;;   @r{it is displayed after the question:}
+
+@group
+---------- Echo area ----------
+Do you need a lift? (y or n) y
+---------- Echo area ----------
+@end group
+@end smallexample
+
+@noindent
+We show successive lines of echo area messages, but only one actually
+appears on the screen at a time.
+@end defun
+
+@defun yes-or-no-p prompt
+  This function asks the user a question, expecting input in minibuffer.
+It returns @code{t} if the user enters @samp{yes}, @code{nil} if the
+user types @samp{no}.  The user must type @key{RET} to finalize the
+response.  Upper and lower case are equivalent.
+
+  @code{yes-or-no-p} starts by displaying @var{prompt} in the echo area,
+followed by @w{@samp{(yes or no) }}.  The user must type one of the
+expected responses; otherwise, the function responds @samp{Please answer
+yes or no.}, waits about two seconds and repeats the request.
+
+  @code{yes-or-no-p} requires more work from the user than
+@code{y-or-n-p} and is appropriate for more crucial decisions.
+
+  If @code{yes-or-no-p} is called in a command that was invoked using
+the mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
+Loop Info}) is either @code{nil} or a mouse event---then it uses a
+dialog box or pop-up menu to ask the question.  In this case, it does
+not use keyboard input or the echo area.
+
+Here is an example:
+
+@smallexample
+@group
+(yes-or-no-p "Do you really want to remove everything? ")
+
+;; @r{After evaluating the preceding expression,} 
+;;   @r{the following prompt appears,} 
+;;   @r{with an empty minibuffer:}
+@end group
+
+@group
+---------- Buffer: minibuffer ----------
+Do you really want to remove everything? (yes or no) 
+---------- Buffer: minibuffer ----------
+@end group
+@end smallexample
+
+@noindent
+If the user first types @kbd{y @key{RET}}, which is invalid because this
+function demands the entire word @samp{yes}, it responds by displaying
+these prompts, with a brief pause between them:
+
+@smallexample
+@group
+---------- Buffer: minibuffer ----------
+Please answer yes or no.
+Do you really want to remove everything? (yes or no)
+---------- Buffer: minibuffer ----------
+@end group
+@end smallexample
+@end defun
+
+@node Multiple Queries
+@section Asking Multiple Y-or-N Questions
+
+@defun map-y-or-n-p prompter actor list &optional help action-alist
+This function, new in Emacs 19, asks the user a series of questions,
+reading a single-character answer in the echo area for each one.
+
+The value of @var{list} specifies the objects to ask questions about.
+It should be either a list of objects or a generator function.  If it is
+a function, it should expect no arguments, and should return either the
+next object to ask about, or @code{nil} meaning stop asking questions.
+
+The argument @var{prompter} specifies how to ask each question.  If
+@var{prompter} is a string, the question text is computed like this:
+
+@example
+(format @var{prompter} @var{object})
+@end example
+
+@noindent
+where @var{object} is the next object to ask about (as obtained from
+@var{list}).
+
+If not a string, @var{prompter} should be a function of one argument
+(the next object to ask about) and should return the question text.
+
+The argument @var{actor} says how to act on the answers that the user
+gives.  It should be a function of one argument, and it is called with
+each object that the user says yes for.  Its argument is always an
+object obtained from @var{list}.
+
+If the argument @var{help} is given, it should be a list of this form:
+
+@example
+(@var{singular} @var{plural} @var{action})
+@end example
+
+@noindent
+where @var{singular} is a string containing a singular noun that
+describes the objects conceptually being acted on, @var{plural} is the
+corresponding plural noun, and @var{action} is a transitive verb
+describing what @var{actor} does.
+
+If you don't specify @var{help}, the default is @code{("object"
+"objects" "act on")}.
+
+Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or
+@key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip
+that object; @kbd{!} to act on all following objects; @key{ESC} or
+@kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on
+the current object and then exit; or @kbd{C-h} to get help.  These are
+the same answers that @code{query-replace} accepts.  The keymap
+@code{query-replace-map} defines their meaning for @code{map-y-or-n-p}
+as well as for @code{query-replace}; see @ref{Search and Replace}.
+
+You can use @var{action-alist} to specify additional possible answers
+and what they mean.  It is an alist of elements of the form
+@code{(@var{char} @var{function} @var{help})}, each of which defines one
+additional answer.  In this element, @var{char} is a character (the
+answer); @var{function} is a function of one argument (an object from
+@var{list}); @var{help} is a string.
+
+When the user responds with @var{char}, @code{map-y-or-n-p} calls
+@var{function}.  If it returns non-@code{nil}, the object is considered
+``acted upon'', and @code{map-y-or-n-p} advances to the next object in
+@var{list}.  If it returns @code{nil}, the prompt is repeated for the
+same object.
+
+The return value of @code{map-y-or-n-p} is the number of objects acted on.
+@end defun
+
+@node Minibuffer Misc
+@comment  node-name,  next,  previous,  up
+@section Minibuffer Miscellany
+
+  This section describes some basic functions and variables related to
+minibuffers.
+
+@deffn Command exit-minibuffer
+This command exits the active minibuffer.  It is normally bound to
+keys in minibuffer local keymaps.
+@end deffn
+
+@deffn Command self-insert-and-exit
+This command exits the active minibuffer after inserting the last
+character typed on the keyboard (found in @code{last-command-char};
+@pxref{Command Loop Info}).
+@end deffn
+
+@deffn Command previous-history-element n
+This command replaces the minibuffer contents with the value of the
+@var{n}th previous (older) history element.
+@end deffn
+
+@deffn Command next-history-element n
+This command replaces the minibuffer contents with the value of the
+@var{n}th more recent history element.
+@end deffn
+
+@deffn Command previous-matching-history-element pattern
+This command replaces the minibuffer contents with the value of the
+previous (older) history element that matches @var{pattern}.
+@end deffn
+
+@deffn Command next-matching-history-element pattern
+This command replaces the minibuffer contents with the value of the
+next (newer) history element that matches @var{pattern}.
+@end deffn
+
+@defvar minibuffer-setup-hook
+This is a normal hook that is run whenever the minibuffer is entered.
+@end defvar
+
+@defvar minibuffer-help-form
+The current value of this variable is used to rebind @code{help-form}
+locally inside the minibuffer (@pxref{Help Functions}).
+@end defvar
+
+@defun minibuffer-window &optional frame
+This function returns the window that is used for the minibuffer.  In
+Emacs 18, there is one and only one minibuffer window; this window
+always exists and cannot be deleted.  In Emacs 19, each frame can have
+its own minibuffer, and this function returns the minibuffer window used
+for frame @var{frame} (which defaults to the currently selected frame).
+@end defun
+
+@c Emacs 19 feature
+@defun window-minibuffer-p window
+This function returns non-@code{nil} if @var{window} is a minibuffer window.
+@end defun
+
+It is not correct to determine whether a given window is a minibuffer by
+comparing it with the result of @code{(minibuffer-window)}, because
+there can be more than one minibuffer window if there is more than one
+frame.
+
+@defun minibuffer-window-active-p window
+This function returns non-@code{nil} if @var{window}, assumed to be
+a minibuffer window, is currently active.
+@end defun
+
+@defvar minibuffer-scroll-window
+If the value of this variable is non-@code{nil}, it should be a window
+object.  When the function @code{scroll-other-window} is called in the
+minibuffer, it scrolls this window.
+@end defvar
+
+Finally, some functions and variables deal with recursive minibuffers
+(@pxref{Recursive Editing}):
+
+@defun minibuffer-depth
+This function returns the current depth of activations of the
+minibuffer, a nonnegative integer.  If no minibuffers are active, it
+returns zero.
+@end defun
+
+@defopt enable-recursive-minibuffers
+If this variable is non-@code{nil}, you can invoke commands (such as
+@code{find-file}) which use minibuffers even while in the minibuffer
+window.  Such invocation produces a recursive editing level for a new
+minibuffer.  The outer-level minibuffer is invisible while you are
+editing the inner one.
+
+This variable only affects invoking the minibuffer while the
+minibuffer window is selected.   If you switch windows while in the 
+minibuffer, you can always invoke minibuffer commands while some other
+window is selected.
+@end defopt
+
+@c Emacs 19 feature
+If a command name has a property @code{enable-recursive-minibuffers}
+which is non-@code{nil}, then the command can use the minibuffer to read
+arguments even if it is invoked from the minibuffer.  The minibuffer
+command @code{next-matching-history-element} (normally bound to
+@kbd{M-s} in the minibuffer) uses this feature.