Mercurial > emacs

--- a/doc/emacs/mini.texi	Mon Sep 22 23:41:27 2008 +0000
+++ b/doc/emacs/mini.texi	Mon Sep 22 23:43:32 2008 +0000
@@ -7,57 +7,42 @@
 @cindex minibuffer

   The @dfn{minibuffer} is where Emacs commands read complicated
-arguments (anything more a single number).  We call it the
-``minibuffer'' because it's a special-purpose buffer with a small
-amount of screen space.  Minibuffer arguments can be file names,
-buffer names, Lisp function names, Emacs command names, Lisp
-expressions, and many other things---whatever the command wants to
-read.  You can use the usual Emacs editing commands in the minibuffer
-to edit the argument text.
+arguments, such as file names, buffer names, Emacs command names, or
+Lisp expressions.  We call it the ``minibuffer'' because it's a
+special-purpose buffer with a small amount of screen space.  You can
+use the usual Emacs editing commands in the minibuffer to edit the
+argument text.

 @cindex prompt
   When the minibuffer is in use, it appears in the echo area, with a
 cursor.  The minibuffer display starts with a @dfn{prompt} in a
-distinct color; it says what kind of input is expected and how it will
-be used.  Often the prompt is derived from the name of the command
-that is reading the argument.  The prompt normally ends with a colon.
+distinct color, usually ending with a colon.  The prompt states what
+kind of input is expected, and how it will be used.
+
+  The simplest way to enter a minibuffer argument is to type the text,
+then @key{RET} to submit the argument and exit the minibuffer.  You
+can cancel the minibuffer, and the command that wants the argument, by
+typing @kbd{C-g}.

 @cindex default argument
-  Sometimes a @dfn{default argument} appears in the prompt, inside
+  Sometimes, a @dfn{default argument} appears in the prompt, inside
 parentheses before the colon.  The default will be used as the
 argument value if you just type @key{RET}.  For example, commands that
-read buffer names show a buffer name as the default.  You can type
-@key{RET} to operate on that default buffer.
-
-  The simplest way to enter a minibuffer argument is to type the text,
-then @key{RET} to exit the minibuffer.  You can cancel the minibuffer,
-and the command that wants the argument, by typing @kbd{C-g}.
+read buffer names usually show a buffer name as the default; you can
+type @key{RET} to operate on that default buffer.

   Since the minibuffer appears in the echo area, it can conflict with
-other uses of the echo area.  Here is how Emacs handles such
-conflicts:
-
-@itemize @bullet
-@item
-An error occurs while the minibuffer is active.
-
-The error message hides the minibuffer for a few seconds, or until you
-type something.  Then the minibuffer comes back.
-
-@item
-A command such as @kbd{C-x =} needs to display a message in the echo
-area.
-
-The message hides the minibuffer for a few seconds, or until you type
-something.  Then the minibuffer comes back.
-
-@item
-Keystrokes don't echo while the minibuffer is in use.
-@end itemize
+other uses of the echo area.  If an error occurs while the minibuffer
+is active, the error message hides the minibuffer for a few seconds,
+or until you type something; then the minibuffer comes back.  If a
+command such as @kbd{C-x =} needs to display a message in the echo
+area, the message hides the minibuffer for a few seconds, or until you
+type something; then the minibuffer comes back.  While the minibuffer
+is in use, keystrokes do not echo.

 @menu
-* File: Minibuffer File.  Entering file names with the minibuffer.
-* Edit: Minibuffer Edit.  How to edit in the minibuffer.
+* Minibuffer File::       Entering file names with the minibuffer.
+* Minibuffer Edit::       How to edit in the minibuffer.
 * Completion::		  An abbreviation facility for minibuffer input.
 * Minibuffer History::    Reusing recent minibuffer arguments.
 * Repetition::		  Re-executing commands that used the minibuffer.
@@ -66,33 +51,31 @@
 @node Minibuffer File
 @section Minibuffers for File Names

-  When you use the minibuffer to enter a file name, it starts out with
-some initial text---the @dfn{default directory}, ending in a slash.
-The file you specify will be in this directory unless you alter or
-replace it.
-
-@c Separate paragraph to clean up ugly page break--rms
-@need 1500
-  For example, if the minibuffer starts out with these contents:
+  Commands such as @kbd{C-x C-f} (@code{find-file}) use the minibuffer
+to read a file name argument (@pxref{Basic Files}).  When the
+minibuffer is used to read a file name, it typically starts out with
+some initial text---the @dfn{default directory}, which ends in a
+slash.  For example, it may start out like this:

 @example
 Find File: /u2/emacs/src/
 @end example

 @noindent
-(where @samp{Find File:@: } is the prompt), and you type
-@kbd{buffer.c} as input, that specifies the file
-@file{/u2/emacs/src/buffer.c}.  You can specify the parent directory
-by adding @file{..}; thus, if you type @kbd{../lisp/simple.el}, you
-will get @file{/u2/emacs/lisp/simple.el}.  Alternatively, you can use
-@kbd{M-@key{DEL}} to kill the directory names you don't want
-(@pxref{Words}).
+Here, @samp{Find File:@: } is the prompt and @samp{/u2/emacs/src/} is
+the default directory.  If you now type @kbd{buffer.c} as input, that
+specifies the file @file{/u2/emacs/src/buffer.c}.

-  You can kill the entire default with @kbd{C-a C-k}, but there's no
-need to do that.  It's easier to ignore the default, and enter an
-absolute file name starting with a slash or a tilde after the default
-directory.  For example, to specify @file{/etc/termcap}, just type
-that name:
+  You can specify the parent directory by adding @file{..}: for
+example, @file{/u2/emacs/src/../lisp/simple.el} is equivalent to
+@file{/u2/emacs/lisp/simple.el}.  Alternatively, you can use
+@kbd{M-@key{DEL}} to kill directory names backwards (@pxref{Words}).
+
+  To specify a file in a completely different directory, you can kill
+the entire default with @kbd{C-a C-k} (@pxref{Minibuffer Edit}).
+Alternatively, you can ignore the default, and enter an absolute file
+name starting with a slash or a tilde after the default directory.
+For example, you can specify @file{/etc/termcap} as follows:

 @example
 Find File: /u2/emacs/src//etc/termcap
@@ -103,59 +86,74 @@
 @cindex double slash in file name
 @cindex slashes repeated in file name
 @findex file-name-shadow-mode
-GNU Emacs interprets a double slash (which is not normally useful in
-file names) as, ``ignore everything before the second slash in the
-pair.''  In the example above. @samp{/u2/emacs/src/} is ignored, so
-you get @file{/etc/termcap}.  The ignored part of the file name is
-dimmed if the terminal allows it; to disable this dimming, turn off
-File Name Shadow mode (a minor mode) with the command
-@kbd{M-x file-name-shadow-mode}.
+Emacs interprets a double slash as ``ignore everything before the
+second slash in the pair.''  In the example above,
+@samp{/u2/emacs/src/} is ignored, so the argument you supplied is
+@file{/etc/termcap}.  Similarly, Emacs interprets a tilde (@samp{~})
+as your home directory, ignoring everything before the tilde.

-  If the variable @code{insert-default-directory} is @code{nil}, the
-default directory is never inserted in the minibuffer---so the
-minibuffer starts out empty.  Nonetheless, relative file name
-arguments are still interpreted based on the same default directory.
+  The ignored part of the file name is dimmed if the terminal allows
+it.  To disable this dimming, turn off File Name Shadow mode, a minor
+mode, with the command @kbd{M-x file-name-shadow-mode}.
+
+  To prevent Emacs from inserting the default directory when reading
+file names, change the variable @code{insert-default-directory} to
+@code{nil}.  In that case, the minibuffer starts out empty.
+Nonetheless, relative file name arguments are still interpreted based
+on the same default directory.

 @node Minibuffer Edit
 @section Editing in the Minibuffer

-  The minibuffer is an Emacs buffer (albeit a peculiar one), and the
+  The minibuffer is an Emacs buffer, albeit a peculiar one, and the
 usual Emacs commands are available for editing the argument text.
+(The prompt, however, is @dfn{read-only}, and cannot be changed.)

   Since @key{RET} in the minibuffer is defined to exit the minibuffer,
 you can't use it to insert a newline in the minibuffer.  To do that,
 type @kbd{C-o} or @kbd{C-q C-j}.  (The newline character is really the
 @acronym{ASCII} character control-J.)

-  The minibuffer has its own window, which normally has space in the
-frame at all times, but it only acts like an Emacs window when the
-minibuffer is active.  When active, this window is much like any other
-Emacs window; for instance, you can switch to another window (with
-@kbd{C-x o}), edit text there, then return to the minibuffer window to
-finish the argument.  You can even kill text in another window, return
-to the minibuffer window, and then yank the text into the argument.
-@xref{Windows}.
+  Inside a minibuffer, the keys @kbd{@key{TAB}}, @kbd{@key{SPC}}, and
+@kbd{@key{?}} are often bound to commands that perform
+@dfn{completion}.  @xref{Completion}.  You can use @kbd{C-q}
+(@code{quoted-insert}) to insert a @key{TAB}, @key{SPC}, or @key{?}
+character.  For example, @kbd{C-q @key{TAB}} inserts a @key{TAB}
+character.  @xref{Inserting Text}.
+
+  For convenience, @kbd{C-a} (@code{move-beginning-of-line}) in a
+minibuffer moves point to the beginning of the argument text, not the
+beginning of the prompt.  For example, this allows you to erase the
+entire argument with @kbd{C-a C-k}.

 @cindex height of minibuffer
 @cindex size of minibuffer
 @cindex growing minibuffer
 @cindex resizing minibuffer
-  There are some restrictions on the minibuffer window, however: you
-cannot kill it, or split it, or switch buffers in it---the minibuffer
-and its window are permanently attached.
+  When the minibuffer is active, the echo area is treated much like an
+ordinary Emacs window.  For instance, you can switch to another window
+(with @kbd{C-x o}), edit text there, then return to the minibuffer
+window to finish the argument.  You can even kill text in another
+window, return to the minibuffer window, and yank the text into the
+argument.  There are some restrictions on the minibuffer window,
+however: for instance, you cannot split it.  @xref{Windows}.

 @vindex resize-mini-windows
-  The minibuffer window expands vertically as necessary to hold the
-text that you put in the minibuffer.  If @code{resize-mini-windows} is
-@code{t}, the window always resizes as needed by its contents.  If its
-value is the symbol @code{grow-only} (the default), the window grows
-automatically as needed, but shrinks (back to the normal size) only
-when the minibuffer becomes inactive.  If its value is @code{nil}, you
-have to adjust the height yourself.
+  Normally, the minibuffer window occupies a single screen line.
+However, if you add two or more lines' worth of text into the
+minibuffer, it expands automatically to accomodate the text.  The
+variable @code{resize-mini-windows} controls the resizing of the
+minibuffer.  The default value is @code{grow-only}, which means the
+behavior we have just described.  If the value is @code{t}, the
+minibuffer window will also shrink automatically if you remove some
+lines of text from the minibuffer, down to a minimum of one screen
+line.  If the value is @code{nil}, the minibuffer window never changes
+size automatically, but you can use the usual window-resizing commands
+on it (@pxref{Windows}).

 @vindex max-mini-window-height
   The variable @code{max-mini-window-height} controls the maximum
-height for resizing the minibuffer window: a floating-point number
+height for resizing the minibuffer window.  A floating-point number
 specifies a fraction of the frame's height; an integer specifies the
 maximum number of lines; @code{nil} means do not resize the minibuffer
 window automatically.  The default value is 0.25.
@@ -168,47 +166,40 @@

 @vindex enable-recursive-minibuffers
   Emacs normally disallows most commands that use the minibuffer while
-the minibuffer is active.  (Entering the minibuffer from the
-minibuffer can be confusing.)  To allow such commands in the
-minibuffer, set the variable @code{enable-recursive-minibuffers} to
-@code{t}.
+the minibuffer is active.  To allow such commands in the minibuffer,
+set the variable @code{enable-recursive-minibuffers} to @code{t}.

 @node Completion
 @section Completion
 @c This node is referenced in the tutorial.  When renaming or deleting
 @c it, the tutorial needs to be adjusted.
 @cindex completion
-
-  Some arguments allow @dfn{completion} to enter their value.  This
-means that after you type part of the argument, Emacs can fill in the
-rest, or some of it, based on what you have typed so far.
+
+  Sometimes, you can use a feature called @dfn{completion} to help you
+enter arguments.  This means that after you type part of the argument,
+Emacs can fill in the rest, or some of it, based on what you have
+typed so far.

-  When completion is available, certain keys---@key{TAB}, @key{RET},
-and @key{SPC}---are rebound to complete the text in the minibuffer
-before point into a longer string chosen from a set of @dfn{completion
-alternatives} provided by the command that requested the argument.
-(@key{SPC} does not do completion in reading file names, because it is
-common to use spaces in file names on some systems.)  @kbd{?} displays
-a list of the possible completions at any time.
+  When completion is available, certain keys (usually @key{TAB},
+@key{RET}, and @key{SPC}) are rebound to complete the text in the
+minibuffer into a longer string chosen from a set of @dfn{completion
+alternatives}.  The set of completion alternatives depends on the
+command that requested the argument, and on what you have typed so
+far.  In addition, you can usually type @kbd{?} to display a list of
+possible completions.

   For example, @kbd{M-x} uses the minibuffer to read the name of a
-command, so it provides a list of all Emacs command names for
-completion candidates.  The completion keys match the minibuffer text
-against these candidates, find any additional name characters implied
-by the text already present in the minibuffer, and add those
-characters.  This makes it possible to type @kbd{M-x ins @key{SPC} b
-@key{RET}} instead of @kbd{M-x insert-buffer @key{RET}}, for example.
+command, so completion works by matching the minibuffer text against
+the names of existing Emacs commands.  So, to run the command
+@code{insert-buffer}, you can type @kbd{M-x ins @key{SPC} b @key{RET}}
+instead of the full @kbd{M-x insert-buffer @key{RET}}.

   Case is significant in completion when it is significant in the
-argument you are entering (buffer names, file names, command names,
-for instance).  Thus, @samp{fo} does not complete to @samp{Foo}.
+argument you are entering, such as command names.  Thus,
+@samp{insert-buffer} is not a valid completion for @samp{IN}.
 Completion ignores case distinctions for certain arguments in which
 case does not matter.

-  Completion acts only on the text before point.  If there is text in
-the minibuffer after point---i.e., if you move point backward after
-typing some text into the minibuffer---it remains unchanged.
-
 @menu
 * Example: Completion Example.    Examples of using completion.
 * Commands: Completion Commands.  A list of completion commands.
@@ -220,22 +211,24 @@
 @subsection Completion Example

 @kindex TAB @r{(completion)}
-  A concrete example may help here.  If you type @kbd{M-x au
+  A concrete example may help here.  If you type @kbd{M-x a u
 @key{TAB}}, the @key{TAB} looks for alternatives (in this case,
 command names) that start with @samp{au}.  There are several,
-including @code{auto-fill-mode} and @code{auto-save-mode}, but they
-all begin with @code{auto-}, so the @samp{au} in the minibuffer
-completes to @samp{auto-}.
+including @code{auto-fill-mode} and @code{autoconf-mode}, but they all
+begin with @code{auto}, so the @samp{au} in the minibuffer completes
+to @samp{auto}.

   If you type @key{TAB} again immediately, it cannot determine the
-next character; it could be any of @samp{cfilrs}.  So it does not add
-any characters; instead, @key{TAB} displays a list of all possible
-completions in another window.
+next character; it could be @samp{-}, @samp{a}, or @samp{c}.  So it
+does not add any characters; instead, @key{TAB} displays a list of all
+possible completions in another window.

-  Now type @kbd{f @key{TAB}}.  This @key{TAB} sees @samp{auto-f}.  The
-only command name starting with that is @code{auto-fill-mode}, so
-completion fills in the rest of that.  You have been able to enter
-@samp{auto-fill-mode} by typing just @kbd{au @key{TAB} f @key{TAB}}.
+  Next, type @kbd{- f}.  The minibuffer now contains @samp{auto-f},
+and the only command name that starts with this is
+@code{auto-fill-mode}.  If you now type @key{TAB}, completion fills in
+the rest of the argument @samp{auto-fill-mode} into the minibuffer.
+You have been able to enter @samp{auto-fill-mode} by typing just
+@kbd{a u @key{TAB} - f @key{TAB}}.

 @node Completion Commands
 @subsection Completion Commands
@@ -246,7 +239,8 @@
 @table @kbd
 @item @key{TAB}
 @findex minibuffer-complete
-Complete the text before point in the minibuffer as much as possible
+Complete the text before point in the minibuffer as much as possible;
+if unable to complete, display a list of possible completions
 (@code{minibuffer-complete}).
 @item @key{SPC}
 Complete up to one word from the minibuffer text before point
@@ -255,13 +249,12 @@
 spaces.
 @item @key{RET}
 Submit the text in the minibuffer as the argument, possibly completing
-first as described
+first as described in the next
 @iftex
-in the next subsection (@code{minibuffer-complete-and-exit}).
+subsection (@code{minibuffer-complete-and-exit}).
 @end iftex
 @ifnottex
-in the next node (@code{minibuffer-complete-and-exit}).  @xref{Strict
-Completion}.
+node (@code{minibuffer-complete-and-exit}).  @xref{Strict Completion}.
 @end ifnottex
 @item ?
 Display a list of possible completions of the text before point
@@ -270,13 +263,12 @@

 @kindex SPC
 @findex minibuffer-complete-word
-  @key{SPC} completes like @key{TAB}, but only up to the next hyphen
-or space.  If you have @samp{auto-f} in the minibuffer and type
-@key{SPC}, it finds that the completion is @samp{auto-fill-mode}, but
-it only inserts @samp{ill-}, giving @samp{auto-fill-}.  Another
-@key{SPC} at this point completes all the way to
-@samp{auto-fill-mode}.  The command that implements this behavior is
-called @code{minibuffer-complete-word}.
+  @key{SPC} (@code{minibuffer-complete-word}) completes like
+@key{TAB}, but only up to the next hyphen or space.  If you have
+@samp{auto-f} in the minibuffer and type @key{SPC}, it finds that the
+completion is @samp{auto-fill-mode}, but it only inserts @samp{ill-},
+giving @samp{auto-fill-}.  Another @key{SPC} at this point completes
+all the way to @samp{auto-fill-mode}.

   When you display a list of possible completions, you can choose
 one from it:
@@ -286,34 +278,34 @@
 @item Mouse-1
 @itemx Mouse-2
 Clicking mouse button 1 or 2 on a completion possibility chooses that
-completion (@code{mouse-choose-completion}).  You must click in the
-list of completions, not in the minibuffer.
+completion (@code{mouse-choose-completion}).

 @findex switch-to-completions
-@item @key{PRIOR}
-@itemx M-v
-Typing @key{PRIOR} or @key{PAGE-UP}, or @kbd{M-v}, while in the
-minibuffer, selects the window showing the completion list buffer
-(@code{switch-to-completions}).  This paves the way for using the
-commands below.  (Selecting that window in other ways has the same
-effect.)
+@item M-v
+@itemx @key{PageUp}
+@itemx @key{PRIOR}
+Typing @kbd{M-v}, while in the minibuffer, selects the window showing
+the completion list buffer (@code{switch-to-completions}).  This paves
+the way for using the commands below.  Typing @key{PageUp} or
+@key{PRIOR} does the same, as does selecting that window in other
+ways.

 @findex choose-completion
 @item @key{RET}
-Typing @key{RET} @emph{in the completion list buffer} chooses the
+Typing @key{RET}, while in the completion list buffer, chooses the
 completion that point is in or next to (@code{choose-completion}).  To
 use this command, you must first switch to the completion list window.

 @findex next-completion
-@item @key{RIGHT}
-Typing the right-arrow key @key{RIGHT} @emph{in the completion list
-buffer} moves point to the following completion possibility
+@item @key{Right}
+Typing the right-arrow key @key{Right}, while in the completion list
+buffer, moves point to the following completion possibility
 (@code{next-completion}).

 @findex previous-completion
-@item @key{LEFT}
-Typing the left-arrow key @key{LEFT} @emph{in the completion list
-buffer} moves point to the previous completion possibility
+@item @key{Left}
+Typing the left-arrow key @key{Left}, while in the completion list
+buffer, moves point to the previous completion possibility
 (@code{previous-completion}).
 @end table

@@ -357,29 +349,34 @@
 @node Completion Options
 @subsection Completion Options

+@vindex completion-auto-help
+  If @code{completion-auto-help} is set to @code{nil}, the completion
+commands never display the completion list buffer; you must type
+@kbd{?}  to display the list.  If the value is @code{lazy}, Emacs only
+shows the completion list buffer on the second attempt to complete.
+In other words, if there is nothing to complete, the first @key{TAB}
+echoes @samp{Next char not unique}; the second @key{TAB} does the
+completion list buffer buffer.
+
 @vindex completion-ignored-extensions
 @cindex ignored file names, in completion
   When completing file names, certain file names are usually ignored.
 The variable @code{completion-ignored-extensions} contains a list of
 strings; a file name ending in any of those strings is ignored as a
 completion candidate.  The standard value of this variable has several
-elements including @code{".o"}, @code{".elc"}, @code{".dvi"} and
-@code{"~"}.  The effect is that, for example, @samp{foo} can complete
-to @samp{foo.c} even though @samp{foo.o} exists as well.  However, if
-@emph{all} the possible completions end in ``ignored'' strings, then
-they are not ignored.  Displaying a list of possible completions
-disregards @code{completion-ignored-extensions}; it shows them all.
+elements including @code{".o"}, @code{".elc"}, and @code{"~"}.  For
+example, if a directory contains @samp{foo.c} and @samp{foo.elc},
+@samp{foo} completes to @samp{foo.c}.  However, if @emph{all} possible
+completions end in ``ignored'' strings, they are not ignored: in the
+previous example, @samp{foo.e} completes to @samp{foo.elc}.
+Displaying a list of possible completions disregards
+@code{completion-ignored-extensions}; it shows them all.

   If an element of @code{completion-ignored-extensions} ends in a
-slash (@file{/}), it's a subdirectory name; then that directory and
-its contents are ignored.  Elements of
-@code{completion-ignored-extensions} which do not end in a slash are
-ordinary file names, and do not apply to names of directories.
-
-@vindex completion-auto-help
-  If @code{completion-auto-help} is set to @code{nil}, the completion
-commands never display a list of possibilities; you must type @kbd{?}
-to display the list.
+slash (@file{/}), it's a subdirectory name; that directory and its
+contents are ignored.  Elements of
+@code{completion-ignored-extensions} that do not end in a slash are
+ordinary file names.

 @cindex Partial Completion mode
 @vindex partial-completion-mode
@@ -390,7 +387,7 @@
 @code{print-buffer} if no other command starts with two words whose
 initials are @samp{p} and @samp{b}.

-  To enable this mode, use @kbd{M-x partial-completion-mode}, or
+  To enable this mode, use @kbd{M-x partial-completion-mode} or
 customize the variable @code{partial-completion-mode}.  This mode
 binds special partial completion commands to @key{TAB}, @key{SPC},
 @key{RET}, and @kbd{?} in the minibuffer.  The usual completion
@@ -423,19 +420,18 @@
 @cindex minibuffer history
 @cindex history of minibuffer input

-  Every argument that you enter with the minibuffer is saved on a
+  Every argument that you enter with the minibuffer is saved in a
 @dfn{minibuffer history list} so you can easily use it again later.
-Special commands fetch the text of an earlier argument into the
-minibuffer, replacing the old minibuffer contents.  You can think of
-them as moving through the history of previous arguments.
+You can use the following arguments to quickly fetch an earlier
+argument into the minibuffer:

 @table @kbd
-@item @key{UP}
-@itemx M-p
-Move to the previous item in the minibuffer history, an earlier argument
-(@code{previous-history-element}).
-@item @key{DOWN}
-@itemx M-n
+@item M-p
+@itemx @key{Up}
+Move to the previous item in the minibuffer history, an earlier
+argument (@code{previous-history-element}).
+@item M-n
+@itemx @key{Down}
 Move to the next item in the minibuffer history
 (@code{next-history-element}).
 @item M-r @var{regexp} @key{RET}
@@ -450,24 +446,27 @@
 @kindex M-n @r{(minibuffer history)}
 @findex next-history-element
 @findex previous-history-element
-  To move through the minibuffer history list one item at a time, use
-@kbd{M-p} or up-arrow (@code{previous-history-element}) to fetch the
-next earlier minibuffer input, and use @kbd{M-n} or down-arrow
-(@code{next-history-element}) to fetch the next later input.  These
-commands don't move the cursor, they pull different saved strings into
-the minibuffer.  But you can think of them as ``moving'' through the
-history list.
+  While in the minibuffer, typing @kbd{M-p} or @key{Up}
+(@code{previous-history-element}) moves up through the minibuffer
+history list, one item at a time.  Each @kbd{M-p} fetches an earlier
+item from the history list into the minibuffer, replacing its existing
+contents.  Similarly, typing @kbd{M-n} or @key{Down}
+(@code{next-history-element}) moves back down the history list,
+fetching later entries into the minibuffer.  You can think of these
+commands as ``backwards'' and ``forwards'' through the history list.

-  The input that you fetch from the history entirely replaces the
-contents of the minibuffer.  To use it again unchanged, just type
-@key{RET}.  You can also edit the text before you reuse it; this does
-not change the history element that you ``moved'' to, but your new
-argument does go at the end of the history list in its own right.
+  If you type @kbd{M-n} in the minibuffer when there are no later
+entries in the minibuffer history (e.g., if you haven't previously
+typed @kbd{M-p}), Emacs tries fetching from a list of default
+argument: values that you are likely to enter.  You can think of this
+as moving through the ``future list'' instead of the ``history list''.

-  For many minibuffer arguments there is a ``default'' value, or
-a list of default values.  You can insert the default value into the
-minibuffer as text by using @kbd{M-n} one or more times.  You can
-think of this as moving ``into the future'' in the history.
+  The input that @kbd{M-p} or @kbd{M-n} fetches into the minibuffer
+entirely replaces the existing contents of the minibuffer, so you can
+simply type @key{RET} to use it as an argument.  You can also edit the
+text before you reuse it; this does not change the history element
+that you ``moved'' to, but your new argument does go at the end of the
+history list in its own right.

 @findex previous-matching-history-element
 @findex next-matching-history-element
@@ -478,21 +477,11 @@
 expression.  @kbd{M-r} (@code{previous-matching-history-element})
 searches older elements in the history, while @kbd{M-s}
 (@code{next-matching-history-element}) searches newer elements.  These
-commands are unusual; they use the minibuffer to read the regular
+commands are unusual: they use the minibuffer to read the regular
 expression even though they are invoked from the minibuffer.  As with
 incremental searching, an upper-case letter in the regular expression
 makes the search case-sensitive (@pxref{Search Case}).

-@ignore
-  We may change the precise way these commands read their arguments.
-Perhaps they will search for a match for the string given so far in the
-minibuffer; perhaps they will search for a literal match rather than a
-regular expression match; perhaps they will only accept matches at the
-beginning of a history element; perhaps they will read the string to
-search for incrementally like @kbd{C-s}.  To find out what interface is
-actually available, type @kbd{C-h f previous-matching-history-element}.
-@end ignore
-
   All uses of the minibuffer record your input on a history list, but
 there are separate history lists for different kinds of arguments.
 For example, there is a list for file names, used by all the commands
@@ -510,12 +499,13 @@
   The variable @code{history-length} specifies the maximum length of a
 minibuffer history list; adding a new element deletes the oldest
 element if the list gets too long.  If the value of
-@code{history-length} is @code{t}, though, there is no maximum length.
+@code{history-length} is @code{t}, there is no maximum length.

 @vindex history-delete-duplicates
   The variable @code{history-delete-duplicates} specifies whether to
-delete duplicates in history.  If it is @code{t}, adding a new element
-deletes from the list all other elements that are equal to it.
+delete duplicates in history.  If it is non-@code{nil}, adding a new
+element deletes from the list all other elements that are equal to it.
+The default is @code{nil}.

 @node Repetition
 @section Repeating Minibuffer Commands