[Emacs-diffs] /srv/bzr/emacs/trunk r106161: Reorganize confirm-nonexistent-file-or-buffer documentation in Emacs manual.

[Chong Yidong]

------------------------------------------------------------
revno: 106161
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sat 2011-10-22 09:17:33 +0800
message:
  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.
modified:
  doc/emacs/ChangeLog
  doc/emacs/buffers.texi
  doc/emacs/calendar.texi
  doc/emacs/emacs.texi
  doc/emacs/files.texi
  doc/emacs/mini.texi

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-10-21 14:45:34 +0000
+++ b/doc/emacs/ChangeLog       2011-10-22 01:17:33 +0000
@@ -1,3 +1,14 @@
+2011-10-22  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * files.texi (File Names, Visiting, Interlocking): Copyedits.

=== modified file 'doc/emacs/buffers.texi'
--- a/doc/emacs/buffers.texi    2011-10-21 14:45:34 +0000
+++ b/doc/emacs/buffers.texi    2011-10-22 01:17:33 +0000
@@ -7,11 +7,11 @@
 
 @cindex buffers
   The text you are editing in Emacs resides in an object called a
address@hidden  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
address@hidden 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*}.
address@hidden  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 @@
 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
address@hidden window} is current.  @xref{Windows}.
+  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}.
 
-  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
address@hidden to} a particular buffer, meaning its value in that buffer
-can be different from the value in other buffers.  @xref{Locals}.
+  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.
address@hidden
 
 @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 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 @@
 
 @kindex C-x b
 @findex switch-to-buffer
-  To select the buffer named @var{bufname}, type @kbd{C-x b
address@hidden @key{RET}}.  This runs the command
address@hidden 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.
+  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.
 
address@hidden minibuffer confirmation
address@hidden 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
address@hidden again to confirm and visit the buffer.  @xref{Visiting}, for
-information about modifying this behavior.
+  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
address@hidden 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.

=== modified file 'doc/emacs/calendar.texi'
--- a/doc/emacs/calendar.texi   2011-08-25 16:30:46 +0000
+++ b/doc/emacs/calendar.texi   2011-10-22 01:17:33 +0000
@@ -893,11 +893,12 @@
 (@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 @@
 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.
 

=== modified file 'doc/emacs/emacs.texi'
--- a/doc/emacs/emacs.texi      2011-10-18 21:11:17 +0000
+++ b/doc/emacs/emacs.texi      2011-10-22 01:17:33 +0000
@@ -281,7 +281,7 @@
 
 * 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.
 

=== modified file 'doc/emacs/files.texi'
--- a/doc/emacs/files.texi      2011-10-21 14:45:34 +0000
+++ b/doc/emacs/files.texi      2011-10-22 01:17:33 +0000
@@ -49,11 +49,18 @@
 
 @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
address@hidden and you must type a second @key{RET} to confirm.
address@hidden Exit}, for details.
 
 @cindex default directory
 @vindex default-directory
@@ -152,9 +159,9 @@
 @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
address@hidden
+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 @@
 actually contains wildcard characters.  You can disable the wildcard
 feature by customizing @code{find-file-wildcards}.
 
address@hidden minibuffer confirmation
address@hidden confirming in the minibuffer
address@hidden 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
address@hidden 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
address@hidden controls whether Emacs asks
-for confirmation before visiting a new file.  The default value,
address@hidden, gives the behavior we have just described.
-If the value is @code{nil}, Emacs never asks for confirmation; for any
-other address@hidden 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 @@
 @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)

=== modified file 'doc/emacs/mini.texi'
--- a/doc/emacs/mini.texi       2011-10-09 21:00:42 +0000
+++ b/doc/emacs/mini.texi       2011-10-22 01:17:33 +0000
@@ -219,11 +219,11 @@
 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 @@
 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,43 +337,69 @@
 completion alternative (@code{previous-completion}).
 @end table
 
address@hidden Strict Completion
address@hidden Strict Completion
address@hidden Completion Exit
address@hidden 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.
address@hidden RET @r{(completion in minibuffer)}
address@hidden 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
address@hidden 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,
address@hidden refuses to exit if the text in the minibuffer does not
-complete to an exact match.
address@hidden completion} accepts only exact completion matches.  Typing
address@hidden 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
address@hidden completion is similar to strict completion, except that
address@hidden 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.
address@hidden 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
address@hidden 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.
address@hidden 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.
+
address@hidden minibuffer confirmation
address@hidden confirming in the minibuffer
address@hidden
address@hidden 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.
+
address@hidden confirm-nonexistent-file-or-buffer
+You can tweak the confirmation behavior by customizing the variable
address@hidden  The default value,
address@hidden, 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
address@hidden 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
address@hidden C-f}, and commands that read buffer names, like @kbd{C-x b}.
 @end itemize
 
-  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.
-
 @node Completion Styles
 @subsection How Completion Alternatives Are Chosen
 @cindex completion style