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.
This commit is contained in:
Chong Yidong
parent
a7dee7e773
commit
a70e06c117
6 changed files with 135 additions and 117 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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}.
|
||||
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
|
||||
@dfn{local 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.
|
||||
@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.
|
||||
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.
|
||||
|
||||
@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.
|
||||
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 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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue