Commit a70e06c1 authored by Chong Yidong's avatar Chong Yidong
Browse files

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.
parent a7dee7e7
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> 2011-10-21 Chong Yidong <cyd@gnu.org>
* files.texi (File Names, Visiting, Interlocking): Copyedits. * files.texi (File Names, Visiting, Interlocking): Copyedits.
......
...@@ -7,11 +7,11 @@ ...@@ -7,11 +7,11 @@
@cindex buffers @cindex buffers
The text you are editing in Emacs resides in an object called a 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 @dfn{buffer}. Each time you visit a file, a buffer is used to hold
file's text. Each time you invoke Dired, a buffer is created to hold the the file's text. Each time you invoke Dired, a buffer is used to hold
directory listing. If you send a message with @kbd{C-x m}, a buffer named the directory listing. If you send a message with @kbd{C-x m}, a
@samp{*mail*} is used to hold the text of the message. When you ask for a buffer 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*}. 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 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 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 ...@@ -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 matters in buffer names. Most buffers are made by visiting files, and
their names are derived from the files' names; however, you can also 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 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 has several buffers, including one named @samp{*scratch*}, which can
file and can be used for evaluating Lisp expressions in Emacs be used for evaluating Lisp expressions and is not associated with any
(@pxref{Lisp Interaction}). file (@pxref{Lisp Interaction}).
@cindex selected buffer @cindex selected buffer
@cindex current buffer @cindex current buffer
At any time, one and only one buffer is @dfn{current}. This is also At any time, one and only one buffer is @dfn{selected}; we call it
called the @dfn{selected buffer}. We often say that a command the @dfn{current buffer}. We sometimes say that a command operates on
operates on ``the buffer''; this really means that the command ``the buffer''; this really means that it operates on the current
operates on the current buffer (most commands do). When there is only buffer. When there is only one Emacs window, the buffer displayed in
one Emacs window, the buffer displayed in that window is current. that window is current. When there are multiple windows, the buffer
When there are multiple windows present, the buffer displayed in the displayed in the @dfn{selected window} is current. @xref{Windows}.
@dfn{selected window} is current. @xref{Windows}.
Aside from its textual contents, each buffer records several pieces
Each buffer records individually what file it is visiting (if any), of information, such as what file it is visiting (if any), whether it
whether it is modified, and what major mode and minor modes are in is modified, and what major mode and minor modes are in effect
effect (@pxref{Major Modes}). Any Emacs variable can be made (@pxref{Modes}). These are stored in @dfn{buffer-local
@dfn{local to} a particular buffer, meaning its value in that buffer variables}---variables that can have a different value in each buffer.
can be different from the value in other buffers. @xref{Locals}. @xref{Locals}.
@cindex buffer size, maximum @cindex buffer size, maximum
A buffer's size cannot be larger than some maximum, which is defined A buffer's size cannot be larger than some maximum, which is defined
by the largest buffer position representable by the @dfn{Emacs by the largest buffer position representable by @dfn{Emacs integers}.
integer} data type. This is because Emacs tracks buffer positions This is because Emacs tracks buffer positions using that data type.
using that data type. For typical 64-bit machines, the maximum buffer size For typical 64-bit machines, this maximum buffer size is @math{2^61 -
enforced by the data types is @math{2^61 - 2} bytes, or about 2 EiB. 2} bytes, or about 2 EiB. For typical 32-bit machines, the maximum is
For typical 32-bit machines, the maximum is @math{2^29 - 2} bytes, or usually @math{2^29 - 2} bytes, or about 512 MiB. Buffer sizes are
about 512 MiB. Buffer sizes are also limited by the size of Emacs's also limited by the amount of memory present in the system.
virtual memory.
@menu @menu
* Select Buffer:: Creating a new buffer or reselecting an old one. * Select Buffer:: Creating a new buffer or reselecting an old one.
...@@ -76,9 +75,9 @@ Similar, but select @var{buffer} in another window ...@@ -76,9 +75,9 @@ Similar, but select @var{buffer} in another window
Similar, but select @var{buffer} in a separate frame Similar, but select @var{buffer} in a separate frame
(@code{switch-to-buffer-other-frame}). (@code{switch-to-buffer-other-frame}).
@item C-x @key{LEFT} @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} @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 @item C-u M-g M-g
@itemx C-u M-g g @itemx C-u M-g g
Read a number @var{n} and move to line @var{n} in the most recently 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. ...@@ -87,28 +86,21 @@ selected buffer other than the current buffer.
@kindex C-x b @kindex C-x b
@findex switch-to-buffer @findex switch-to-buffer
To select the buffer named @var{bufname}, type @kbd{C-x b The @kbd{C-x b} (@code{switch-to-buffer}) command reads a buffer
@var{bufname} @key{RET}}. This runs the command name using the minibuffer. Then it makes that buffer current, and
@code{switch-to-buffer} with argument @var{bufname}. While entering displays it in the currently-selected window. An empty input
the buffer name, you can use the usual minibuffer completion and specifies the buffer that was current most recently among those not
history commands (@pxref{Minibuffer}). An empty input specifies the now displayed in any window. If you specify a buffer that does not
buffer that was current most recently among those not now displayed in exist, @kbd{C-x b} creates a new, empty buffer that is not visiting
any window. any file, and selects it for editing.
@cindex minibuffer confirmation While entering the buffer name, you can use the usual completion and
@cindex confirming in the minibuffer history commands (@pxref{Minibuffer}). Note that @kbd{C-x b}, and
If you specify a buffer that does not exist, @kbd{C-x b} creates a related commands, use ``permissive completion with confirmation'' for
new, empty buffer that is not visiting any file, and selects it for minibuffer completion: if you type @key{RET} immediately after
editing. First, however, Emacs might prompt you for confirmation, in completing up to a nonexistent buffer name, Emacs prints
case you entered the wrong buffer name. Emacs asks for confirmation @samp{[Confirm]} and you must type a second @key{RET} to submit that
only if the last key you typed, before submitting the minibuffer input buffer name. @xref{Completion Exit}, for details.
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.
One reason to create a new buffer is to use it for making temporary 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. notes. If you try to save it, Emacs asks for the file name to use.
......
...@@ -893,11 +893,12 @@ Move to a date specified in the Ethiopic calendar ...@@ -893,11 +893,12 @@ Move to a date specified in the Ethiopic calendar
(@code{calendar-ethiopic-goto-date}). (@code{calendar-ethiopic-goto-date}).
@end table @end table
These commands ask you for a date on the other calendar, move point to These commands ask you for a date on the other calendar, move point
the Gregorian calendar date equivalent to that date, and display the to the Gregorian calendar date equivalent to that date, and display
other calendar's date in the echo area. Emacs uses strict completion the other calendar's date in the echo area. Emacs uses strict
(@pxref{Strict Completion}) whenever it asks you to type a month name, so you completion (@pxref{Completion Exit}) whenever it asks you to type a
don't have to worry about the spelling of Hebrew, Islamic, or French names. month name, so you don't have to worry about the spelling of Hebrew,
Islamic, or French names.
@c FIXME move? @c FIXME move?
@findex calendar-hebrew-list-yahrzeits @findex calendar-hebrew-list-yahrzeits
...@@ -993,7 +994,7 @@ occurrence of that combination. Use @kbd{g m n c} to move point to the ...@@ -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 next occurrence of a combination. These commands signal an error if the
haab/tzolkin date combination you have typed is impossible. 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 asks you to type a Mayan name, so you don't have to worry about
spelling. spelling.
......
...@@ -281,7 +281,7 @@ Completion ...@@ -281,7 +281,7 @@ Completion
* Completion Example:: Examples of using completion. * Completion Example:: Examples of using completion.
* Completion Commands:: A list of completion commands. * 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 Styles:: How completion matches are chosen.
* Completion Options:: Options for completion. * Completion Options:: Options for completion.
......
...@@ -49,11 +49,18 @@ on file directories. ...@@ -49,11 +49,18 @@ on file directories.
@cindex default file name @cindex default file name
Many Emacs commands that operate on a file require you to specify Many Emacs commands that operate on a file require you to specify
the file name, using the minibuffer (@pxref{Minibuffer File}). You the file name, using the minibuffer (@pxref{Minibuffer File}).
can use @dfn{completion} to specify long file names
(@pxref{Completion}); note that file name completion ignores file While in the minibuffer, you can use the usual completion and
names whose extensions appear in the variable 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}). @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 @cindex default directory
@vindex default-directory @vindex default-directory
...@@ -152,9 +159,9 @@ that you visit. ...@@ -152,9 +159,9 @@ that you visit.
@kindex C-x C-f @kindex C-x C-f
@findex find-file @findex find-file
To visit a file, type @kbd{C-x C-f} (@code{find-file}) and use the 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}). minibuffer to enter the name of the desired file. While in the
While in the minibuffer, you can abort the command by typing minibuffer, you can abort the command by typing @kbd{C-g}. @xref{File
@kbd{C-g}. Names}, for details about entering file names into minibuffers.
If the specified file exists but the system does not allow you to 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, 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 ...@@ -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 actually contains wildcard characters. You can disable the wildcard
feature by customizing @code{find-file-wildcards}. 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 @kindex C-x C-v
@findex find-alternate-file @findex find-alternate-file
If you visit the wrong file unintentionally by typing its name If you visit the wrong file unintentionally by typing its name
...@@ -382,10 +370,10 @@ Wrote /u/rms/gnu/gnu.tasks ...@@ -382,10 +370,10 @@ Wrote /u/rms/gnu/gnu.tasks
@end example @end example
@noindent @noindent
If the selected buffer is not modified (no changes have been made in it 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, since the buffer was created or last saved), saving is not really
because it would have no effect. Instead, @kbd{C-x C-s} displays a message done, because it would have no effect. Instead, @kbd{C-x C-s}
like this in the echo area: displays a message like this in the echo area:
@example @example
(No changes need to be saved) (No changes need to be saved)
......
...@@ -219,11 +219,11 @@ is sometimes available in ordinary buffers too. @xref{Symbol ...@@ -219,11 +219,11 @@ is sometimes available in ordinary buffers too. @xref{Symbol
Completion}. Completion}.
@menu @menu
* Example: Completion Example. Examples of using completion. * Completion Example:: Examples of using completion.
* Commands: Completion Commands. A list of completion commands. * 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 Styles:: How completion matches are chosen.
* Options: Completion Options. Options for completion. * Completion Options:: Options for completion.
@end menu @end menu
@node Completion Example @node Completion Example
...@@ -274,7 +274,7 @@ Complete up to one word from the minibuffer text before point ...@@ -274,7 +274,7 @@ Complete up to one word from the minibuffer text before point
arguments that often include spaces, such as file names. arguments that often include spaces, such as file names.
@item @key{RET} @item @key{RET}
Submit the text in the minibuffer as the argument, possibly completing 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 ? @item ?
Display a list of completions (@code{minibuffer-completion-help}). Display a list of completions (@code{minibuffer-completion-help}).
@end table @end table
...@@ -337,42 +337,68 @@ While in the completion list buffer, this moves point to the previous ...@@ -337,42 +337,68 @@ While in the completion list buffer, this moves point to the previous
completion alternative (@code{previous-completion}). completion alternative (@code{previous-completion}).
@end table @end table
@node Strict Completion @node Completion Exit
@subsection Strict Completion @subsection Completion Exit
There are three ways that the @key{RET} @kindex RET @r{(completion in minibuffer)}
(@code{minibuffer-complete-and-exit}) completion command can act, @findex minibuffer-complete-and-exit
depending on how the argument will be used. 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 @itemize @bullet
@item @item
@dfn{Strict} completion accepts only known completion candidates. For @dfn{Strict completion} accepts only exact completion matches. Typing
example, when @kbd{C-x k} reads the name of a buffer to kill, only the @key{RET} exits the minibuffer only if the minibuffer text is an exact
name of an existing buffer makes sense. In strict completion, match, or completes to one. Otherwise, Emacs refuses to exit the
@key{RET} refuses to exit if the text in the minibuffer does not minibuffer; instead it tries to complete, and if no completion can be
complete to an exact match. 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 @item
@dfn{Cautious} completion is similar to strict completion, except that @dfn{Cautious completion} is like strict completion, except @key{RET}
@key{RET} exits only if the text is an already exact match. exits only if the text is already an exact match. If the text
Otherwise, @key{RET} does not exit, but it does complete the text. If completes to an exact match, @key{RET} performs that completion but
that completes to an exact match, a second @key{RET} will exit. 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 Cautious completion is used for reading file names for files that must
already exist, for example. already exist, for example.
@item @item
@dfn{Permissive} completion allows any input; the completion @dfn{Permissive completion} allows any input; the completion
candidates are just suggestions. For example, when @kbd{C-x C-f} candidates are just suggestions. Typing @key{RET} does not complete,
reads the name of a file to visit, any file name is allowed, including it just submits the argument as you have entered it.
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
Like the other completion commands, @key{RET} displays a list of all @cindex minibuffer confirmation
possible completions whenever it is supposed to complete but is unable @cindex confirming in the minibuffer
to complete any further. @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 @node Completion Styles
@subsection How Completion Alternatives Are Chosen @subsection How Completion Alternatives Are Chosen
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment