Reorganize confirm-nonexistent-file-or-buffer documentation in Emacs manual.

* doc/emacs/buffers.texi (Buffers): Tweak mention of mail buffer name.
(Select Buffer): Move confirmation discussion to Minibuffer Exit.

* doc/emacs/files.texi (File Names, Visiting): Move detailed discussion of
minibuffer confirmation to Minibuffer Exit.

* doc/emacs/mini.texi (Minibuffer Exit): Rename from Strict Completion.
Move confirm-nonexistent-file-or-buffer discussion here.

6 files changed, 137 insertions, 119 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 94b7bbe2432..06523d40d94 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,14 @@
+2011-10-22  Chong Yidong  <cyd@gnu.org>
+
+        * mini.texi (Minibuffer Exit): Rename from Strict Completion.
+        Move confirm-nonexistent-file-or-buffer discussion here.
+
+        * files.texi (File Names, Visiting): Move detailed discussion of
+        minibuffer confirmation to Minibuffer Exit.
+
+        * buffers.texi (Buffers): Tweak mention of mail buffer name.
+        (Select Buffer): Move confirmation discussion to Minibuffer Exit.
+
 2011-10-21  Chong Yidong  <cyd@gnu.org>
 
         * files.texi (File Names, Visiting, Interlocking): Copyedits.
diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi
index 1108b501ee9..5eba954773c 100644
--- a/doc/emacs/buffers.texi
+++ b/doc/emacs/buffers.texi
@@ -7,11 +7,11 @@
 
 @cindex buffers
   The text you are editing in Emacs resides in an object called a
-@dfn{buffer}.  Each time you visit a file, a buffer is created to hold the
-file's text.  Each time you invoke Dired, a buffer is created to hold the
-directory listing.  If you send a message with @kbd{C-x m}, a buffer named
-@samp{*mail*} is used to hold the text of the message.  When you ask for a
-command's documentation, that appears in a buffer called @samp{*Help*}.
+@dfn{buffer}.  Each time you visit a file, a buffer is used to hold
+the file's text.  Each time you invoke Dired, a buffer is used to hold
+the directory listing.  If you send a message with @kbd{C-x m}, a
+buffer is used to hold the text of the message.  When you ask for a
+command's documentation, that appears in a buffer named @samp{*Help*}.
 
   Each buffer has a unique name, which can be of any length.  When a
 buffer is displayed in a window, its name is shown in the mode line
@@ -19,35 +19,34 @@ buffer is displayed in a window, its name is shown in the mode line
 matters in buffer names.  Most buffers are made by visiting files, and
 their names are derived from the files' names; however, you can also
 create an empty buffer with any name you want.  A newly started Emacs
-has a buffer named @samp{*scratch*}, which is not associated with any
-file and can be used for evaluating Lisp expressions in Emacs
-(@pxref{Lisp Interaction}).
+has several buffers, including one named @samp{*scratch*}, which can
+be used for evaluating Lisp expressions and is not associated with any
+file (@pxref{Lisp Interaction}).
 
 @cindex selected buffer
 @cindex current buffer
-  At any time, one and only one buffer is @dfn{current}.  This is also
-called the @dfn{selected buffer}.  We often say that a command
-operates on ``the buffer''; this really means that the command
-operates on the current buffer (most commands do).  When there is only
-one Emacs window, the buffer displayed in that window is current.
-When there are multiple windows present, the buffer displayed in the
-@dfn{selected window} is current.  @xref{Windows}.
-
-  Each buffer records individually what file it is visiting (if any),
-whether it is modified, and what major mode and minor modes are in
-effect (@pxref{Major Modes}).  Any Emacs variable can be made
-@dfn{local to} a particular buffer, meaning its value in that buffer
-can be different from the value in other buffers.  @xref{Locals}.
+  At any time, one and only one buffer is @dfn{selected}; we call it
+the @dfn{current buffer}.  We sometimes say that a command operates on
+``the buffer''; this really means that it operates on the current
+buffer.  When there is only one Emacs window, the buffer displayed in
+that window is current.  When there are multiple windows, the buffer
+displayed in the @dfn{selected window} is current.  @xref{Windows}.
+
+  Aside from its textual contents, each buffer records several pieces
+of information, such as what file it is visiting (if any), whether it
+is modified, and what major mode and minor modes are in effect
+(@pxref{Modes}).  These are stored in @dfn{buffer-local
+variables}---variables that can have a different value in each buffer.
+@xref{Locals}.
 
 @cindex buffer size, maximum
   A buffer's size cannot be larger than some maximum, which is defined
-by the largest buffer position representable by the @dfn{Emacs
-integer} data type.  This is because Emacs tracks buffer positions
-using that data type.  For typical 64-bit machines, the maximum buffer size
-enforced by the data types is @math{2^61 - 2} bytes, or about 2 EiB.
-For typical 32-bit machines, the maximum is @math{2^29 - 2} bytes, or
-about 512 MiB.  Buffer sizes are also limited by the size of Emacs's
-virtual memory.
+by the largest buffer position representable by @dfn{Emacs integers}.
+This is because Emacs tracks buffer positions using that data type.
+For typical 64-bit machines, this maximum buffer size is @math{2^61 -
+2} bytes, or about 2 EiB.  For typical 32-bit machines, the maximum is
+usually @math{2^29 - 2} bytes, or about 512 MiB.  Buffer sizes are
+also limited by the amount of memory present in the system.
 
 @menu
 * Select Buffer::       Creating a new buffer or reselecting an old one.
@@ -76,9 +75,9 @@ Similar, but select @var{buffer} in another window
 Similar, but select @var{buffer} in a separate frame
 (@code{switch-to-buffer-other-frame}).
 @item C-x @key{LEFT}
-Select the previous buffer in the list of existing buffers.
+Select the previous buffer in the buffer list (@code{previous-buffer}).
 @item C-x @key{RIGHT}
-Select the next buffer in the list of existing buffers.
+Select the next buffer in the buffer list (@code{next-buffer}).
 @item C-u M-g M-g
 @itemx C-u M-g g
 Read a number @var{n} and move to line @var{n} in the most recently
@@ -87,28 +86,21 @@ selected buffer other than the current buffer.
 
 @kindex C-x b
 @findex switch-to-buffer
-  To select the buffer named @var{bufname}, type @kbd{C-x b
-@var{bufname} @key{RET}}.  This runs the command
-@code{switch-to-buffer} with argument @var{bufname}.  While entering
-the buffer name, you can use the usual minibuffer completion and
-history commands (@pxref{Minibuffer}).  An empty input specifies the
-buffer that was current most recently among those not now displayed in
-any window.
-
-@cindex minibuffer confirmation
-@cindex confirming in the minibuffer
-  If you specify a buffer that does not exist, @kbd{C-x b} creates a
-new, empty buffer that is not visiting any file, and selects it for
-editing.  First, however, Emacs might prompt you for confirmation, in
-case you entered the wrong buffer name.  Emacs asks for confirmation
-only if the last key you typed, before submitting the minibuffer input
-with @key{RET}, was @key{TAB} (@code{minibuffer-complete}).  This
-catches a common mistake, in which one types @key{RET} before
-realizing that @key{TAB} did not complete far enough to yield the
-desired buffer name (@pxref{Completion}).  Emacs asks for confirmation
-by putting the message @samp{[Confirm]} in the minibuffer; type
-@key{RET} again to confirm and visit the buffer.  @xref{Visiting}, for
-information about modifying this behavior.
+  The @kbd{C-x b} (@code{switch-to-buffer}) command reads a buffer
+name using the minibuffer.  Then it makes that buffer current, and
+displays it in the currently-selected window.  An empty input
+specifies the buffer that was current most recently among those not
+now displayed in any window.  If you specify a buffer that does not
+exist, @kbd{C-x b} creates a new, empty buffer that is not visiting
+any file, and selects it for editing.
+
+  While entering the buffer name, you can use the usual completion and
+history commands (@pxref{Minibuffer}).  Note that @kbd{C-x b}, and
+related commands, use ``permissive completion with confirmation'' for
+minibuffer completion: if you type @key{RET} immediately after
+completing up to a nonexistent buffer name, Emacs prints
+@samp{[Confirm]} and you must type a second @key{RET} to submit that
+buffer name.  @xref{Completion Exit}, for details.
 
   One reason to create a new buffer is to use it for making temporary
 notes.  If you try to save it, Emacs asks for the file name to use.
diff --git a/doc/emacs/calendar.texi b/doc/emacs/calendar.texi
index 71a2dba7d08..4a09d6e3d9c 100644
--- a/doc/emacs/calendar.texi
+++ b/doc/emacs/calendar.texi
@@ -893,11 +893,12 @@ Move to a date specified in the Ethiopic calendar
 (@code{calendar-ethiopic-goto-date}).
 @end table
 
-  These commands ask you for a date on the other calendar, move point to
-the Gregorian calendar date equivalent to that date, and display the
-other calendar's date in the echo area.  Emacs uses strict completion
-(@pxref{Strict Completion}) whenever it asks you to type a month name, so you
-don't have to worry about the spelling of Hebrew, Islamic, or French names.
+  These commands ask you for a date on the other calendar, move point
+to the Gregorian calendar date equivalent to that date, and display
+the other calendar's date in the echo area.  Emacs uses strict
+completion (@pxref{Completion Exit}) whenever it asks you to type a
+month name, so you don't have to worry about the spelling of Hebrew,
+Islamic, or French names.
 
 @c FIXME move?
 @findex calendar-hebrew-list-yahrzeits
@@ -993,7 +994,7 @@ occurrence of that combination.  Use @kbd{g m n c} to move point to the
 next occurrence of a combination.  These commands signal an error if the
 haab/tzolkin date combination you have typed is impossible.
 
-  Emacs uses strict completion (@pxref{Strict Completion}) whenever it
+  Emacs uses strict completion (@pxref{Completion Exit}) whenever it
 asks you to type a Mayan name, so you don't have to worry about
 spelling.
 
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 58136ce6730..cad0e4db3c0 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -281,7 +281,7 @@ Completion
 
 * Completion Example::  Examples of using completion.
 * Completion Commands:: A list of completion commands.
-* Strict Completion::   Different types of completion.
+* Completion Exit::     Completion and minibuffer text submission.
 * Completion Styles::   How completion matches are chosen.
 * Completion Options::  Options for completion.
 
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index fdd977cf5ff..2317f876b08 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -49,11 +49,18 @@ on file directories.
 
 @cindex default file name
   Many Emacs commands that operate on a file require you to specify
-the file name, using the minibuffer (@pxref{Minibuffer File}).  You
-can use @dfn{completion} to specify long file names
-(@pxref{Completion}); note that file name completion ignores file
-names whose extensions appear in the variable
+the file name, using the minibuffer (@pxref{Minibuffer File}).
+
+  While in the minibuffer, you can use the usual completion and
+history commands (@pxref{Minibuffer}).  Note that file name completion
+ignores file names whose extensions appear in the variable
 @code{completion-ignored-extensions} (@pxref{Completion Options}).
+Note also that most commands use ``permissive completion with
+confirmation'' for reading file names: you are allowed to submit a
+nonexistent file name, but if you type @key{RET} immediately after
+completing up to a nonexistent file name, Emacs prints
+@samp{[Confirm]} and you must type a second @key{RET} to confirm.
+@xref{Completion Exit}, for details.
 
 @cindex default directory
 @vindex default-directory
@@ -152,9 +159,9 @@ that you visit.
 @kindex C-x C-f
 @findex find-file
   To visit a file, type @kbd{C-x C-f} (@code{find-file}) and use the
-minibuffer to enter the name of the desired file (@pxref{File Names}).
-While in the minibuffer, you can abort the command by typing
-@kbd{C-g}.
+minibuffer to enter the name of the desired file.  While in the
+minibuffer, you can abort the command by typing @kbd{C-g}.  @xref{File
+Names}, for details about entering file names into minibuffers.
 
   If the specified file exists but the system does not allow you to
 read it, an error message is displayed in the echo area.  Otherwise,
@@ -213,25 +220,6 @@ File Names}, for information on how to visit a file whose name
 actually contains wildcard characters.  You can disable the wildcard
 feature by customizing @code{find-file-wildcards}.
 
-@cindex minibuffer confirmation
-@cindex confirming in the minibuffer
-@vindex confirm-nonexistent-file-or-buffer
-  When @key{TAB} completion results in a nonexistent file name and you
-type @key{RET} immediately to visit it, Emacs asks for confirmation;
-this is because it's possible that you expected completion to go
-further and give you an existing file's name.  The string
-@samp{[Confirm]} appears for a short time after the file name to
-indicate the need to confirm in this way.  Type @key{RET} to confirm
-and visit the nonexistent file.  The variable
-@code{confirm-nonexistent-file-or-buffer} controls whether Emacs asks
-for confirmation before visiting a new file.  The default value,
-@code{after-completion}, gives the behavior we have just described.
-If the value is @code{nil}, Emacs never asks for confirmation; for any
-other non-@code{nil} value, Emacs always asks for confirmation.  This
-variable also affects the @code{switch-to-buffer} command
-(@pxref{Select Buffer}).  @xref{Completion}, for more information
-about completion.
-
 @kindex C-x C-v
 @findex find-alternate-file
   If you visit the wrong file unintentionally by typing its name
@@ -382,10 +370,10 @@ Wrote /u/rms/gnu/gnu.tasks
 @end example
 
 @noindent
-If the selected buffer is not modified (no changes have been made in it
-since the buffer was created or last saved), saving is not really done,
-because it would have no effect.  Instead, @kbd{C-x C-s} displays a message
-like this in the echo area:
+If the current buffer is not modified (no changes have been made in it
+since the buffer was created or last saved), saving is not really
+done, because it would have no effect.  Instead, @kbd{C-x C-s}
+displays a message like this in the echo area:
 
 @example
 (No changes need to be saved)
diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index e84b4c9f080..bbe42551345 100644
--- a/doc/emacs/mini.texi
+++ b/doc/emacs/mini.texi
@@ -219,11 +219,11 @@ is sometimes available in ordinary buffers too.  @xref{Symbol
 Completion}.
 
 @menu
-* Example: Completion Example.    Examples of using completion.
-* Commands: Completion Commands.  A list of completion commands.
-* Strict Completion::             Different types of completion.
-* Completion Styles::             How completion matches are chosen.
-* Options: Completion Options.    Options for completion.
+* Completion Example::       Examples of using completion.
+* Completion Commands::      A list of completion commands.
+* Completion Exit::          Completion and minibuffer text submission.
+* Completion Styles::        How completion matches are chosen.
+* Completion Options::       Options for completion.
 @end menu
 
 @node Completion Example
@@ -274,7 +274,7 @@ Complete up to one word from the minibuffer text before point
 arguments that often include spaces, such as file names.
 @item @key{RET}
 Submit the text in the minibuffer as the argument, possibly completing
-first (@code{minibuffer-complete-and-exit}).  @xref{Strict Completion}.
+first (@code{minibuffer-complete-and-exit}).  @xref{Completion Exit}.
 @item ?
 Display a list of completions (@code{minibuffer-completion-help}).
 @end table
@@ -337,42 +337,68 @@ While in the completion list buffer, this moves point to the previous
 completion alternative (@code{previous-completion}).
 @end table
 
-@node Strict Completion
-@subsection Strict Completion
+@node Completion Exit
+@subsection Completion Exit
 
-  There are three ways that the @key{RET}
-(@code{minibuffer-complete-and-exit}) completion command can act,
-depending on how the argument will be used.
+@kindex RET @r{(completion in minibuffer)}
+@findex minibuffer-complete-and-exit
+  When a command reads an argument using the minibuffer with
+completion, it also controls what happens when you type @key{RET}
+(@code{minibuffer-complete-and-exit}) to submit the argument.  There
+are four types of behavior:
 
 @itemize @bullet
 @item
-@dfn{Strict} completion accepts only known completion candidates.  For
-example, when @kbd{C-x k} reads the name of a buffer to kill, only the
-name of an existing buffer makes sense.  In strict completion,
-@key{RET} refuses to exit if the text in the minibuffer does not
-complete to an exact match.
+@dfn{Strict completion} accepts only exact completion matches.  Typing
+@key{RET} exits the minibuffer only if the minibuffer text is an exact
+match, or completes to one.  Otherwise, Emacs refuses to exit the
+minibuffer; instead it tries to complete, and if no completion can be
+done it momentarily displays @samp{[No match]} after the minibuffer
+text.  (You can still leave the minibuffer by typing @kbd{C-g} to
+cancel the command.)
+
+An example of a command that uses this behavior is @kbd{M-x}, since it
+is meaningless for it to accept a non-existent command name.
 
 @item
-@dfn{Cautious} completion is similar to strict completion, except that
-@key{RET} exits only if the text is an already exact match.
-Otherwise, @key{RET} does not exit, but it does complete the text.  If
-that completes to an exact match, a second @key{RET} will exit.
+@dfn{Cautious completion} is like strict completion, except @key{RET}
+exits only if the text is already an exact match.  If the text
+completes to an exact match, @key{RET} performs that completion but
+does not exit yet; you must type a second @key{RET} to exit.
 
 Cautious completion is used for reading file names for files that must
 already exist, for example.
 
 @item
-@dfn{Permissive} completion allows any input; the completion
-candidates are just suggestions.  For example, when @kbd{C-x C-f}
-reads the name of a file to visit, any file name is allowed, including
-nonexistent file (in case you want to create a file).  In permissive
-completion, @key{RET} does not complete, it just submits the argument
-as you have entered it.
-@end itemize
+@dfn{Permissive completion} allows any input; the completion
+candidates are just suggestions.  Typing @key{RET} does not complete,
+it just submits the argument as you have entered it.
 
-  Like the other completion commands, @key{RET} displays a list of all
-possible completions whenever it is supposed to complete but is unable
-to complete any further.
+@cindex minibuffer confirmation
+@cindex confirming in the minibuffer
+@item
+@dfn{Permissive completion with confirmation} is like permissive
+completion, with an exception: if you typed @key{TAB} and this
+completed the text up to some intermediate state (i.e. one that is not
+yet an exact completion match), typing @key{RET} right afterward does
+not submit the argument.  Instead, Emacs asks for confirmation by
+momentarily displaying @samp{[Confirm]} after the text; type @key{RET}
+again to confirm and submit the text.  This catches a common mistake,
+in which one types @key{RET} before realizing that @key{TAB} did not
+complete as far as desired.
+
+@vindex confirm-nonexistent-file-or-buffer
+You can tweak the confirmation behavior by customizing the variable
+@code{confirm-nonexistent-file-or-buffer}.  The default value,
+@code{after-completion}, gives the behavior we have just described.
+If you change it to @code{nil}, Emacs does not ask for confirmation,
+falling back on permissive completion.  If you change it to any other
+non-@code{nil} value, Emacs asks for confirmation whether or not the
+preceding command was @key{TAB}.
+
+This behavior is used by most commands that read file names, like
+@kbd{C-x C-f}, and commands that read buffer names, like @kbd{C-x b}.
+@end itemize
 
 @node Completion Styles
 @subsection How Completion Alternatives Are Chosen