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>
* files.texi (File Names, Visiting, Interlocking): Copyedits.
......
......@@ -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.
......
......@@ -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.
......
......@@ -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.
......
......@@ -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)
......
......@@ -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 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.
* Options: Completion Options. Options for completion.
* 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
......
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