* Completion:: How to invoke and customize completion.
* Yes-or-No Queries:: Asking a question with a simple answer.
* Multiple Queries:: Asking a series of similar questions.
-* Reading a Password:: Function for reading a password.
+* Reading a Password:: Reading a password from the terminal.
* Minibuffer Misc:: Various customization hooks and variables.
@end menu
to minibuffers. The name of a minibuffer always has the form @w{@samp{
*Minibuf-@var{number}}}, and it cannot be changed. Minibuffers are
displayed only in special windows used only for minibuffers; these
-windows always appear at the bottom of a frame. (Sometime frames have
+windows always appear at the bottom of a frame. (Sometimes frames have
no minibuffer window, and sometimes a special kind of frame contains
nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
- The minibuffer's window is normally a single line. You can resize it
-temporarily with the window sizing commands; it reverts to its normal
-size when the minibuffer is exited. You can resize it permanently by
-using the window sizing commands in the frame's other window, when the
-minibuffer is not active. If the frame contains just a minibuffer, you
-can change the minibuffer's size by changing the frame's size.
+ The text in the minibuffer always starts with the @dfn{prompt string},
+the text that was specified by the program that is using the minibuffer
+to tell the user what sort of input to type. This text is marked
+read-only so you won't accidentally delete or change it. In other
+respects, it is an ordinary part of the buffer contents, but certain
+functions such as @code{erase-buffer}, @code{buffer-string},
+@code{beginning-of-line}, @code{forward-word}, @code{forward-sentence},
+and @code{forward-paragraph}, treat it a little bit specially. (In
+older Emacs versions, the prompt was displayed using a special mechanism
+and was not part of the buffer contents.)
+
+@c ???
+ The minibuffer's window is normally a single line; it grows
+automatically if necessary if the contents require more space. You can
+explicitly resize it temporarily with the window sizing commands; it
+reverts to its normal size when the minibuffer is exited. You can
+resize it permanently by using the window sizing commands in the frame's
+other window, when the minibuffer is not active. If the frame contains
+just a minibuffer, you can change the minibuffer's size by changing the
+frame's size.
If a command uses a minibuffer while there is an active minibuffer,
this is called a @dfn{recursive minibuffer}. The first minibuffer is
properties are stripped when the value is returned.
If the argument @var{inherit-input-method} is non-@code{nil}, then the
-minibuffer inherits the current buffer's input method (@pxref{Input
-Methods}) and the setting of @code{enable-multibyte-characters}
-(@pxref{Text Representations}) from whichever buffer was current before
-entering the minibuffer.
+minibuffer inherits the current input method (@pxref{Input Methods}) and
+the setting of @code{enable-multibyte-characters} (@pxref{Text
+Representations}) from whichever buffer was current before entering the
+minibuffer.
If @var{initial-contents} is a string, @code{read-from-minibuffer}
inserts it into the minibuffer, leaving point at the end, before the
@end defun
@defvar minibuffer-allow-text-properties
-If this variable is non-@code{nil}, then @code{read-from-minibuffer}
-strips all text properties from the string before returning the string.
+If this variable is @code{nil}, then @code{read-from-minibuffer} strips
+all text properties from the minibuffer input before returning it.
Since all minibuffer input uses @code{read-from-minibuffer}, this
variable applies to all minibuffer input.
+
+Note that the completion functions discard text properties unconditionally,
+regardless of the value of this variable.
@end defvar
@defvar minibuffer-local-map
In most cases, we recommend using @var{default}, and not @var{initial}.
If the argument @var{inherit-input-method} is non-@code{nil}, then the
-minibuffer inherits the current buffer's input method (@pxref{Input
+minibuffer inherits the current input method (@pxref{Input
Methods}) and the setting of @code{enable-multibyte-characters}
(@pxref{Text Representations}) from whichever buffer was current before
entering the minibuffer.
@end defun
@node Completion Commands
-@subsection Minibuffer Commands That Do Completion
+@subsection Minibuffer Commands that Do Completion
This section describes the keymaps, commands and user options used in
the minibuffer to do completion.
@end defun
See also the functions @code{read-coding-system} and
-@code{read-non-nil-coding-system}, in @ref{Lisp and Coding Systems}.
+@code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems}.
@node Reading File Names
@subsection Reading File Names
@c Emacs 19 feature
If you specify @var{initial}, that is an initial file name to insert in
-the buffer (after with @var{directory}, if that is inserted). In this
+the buffer (after @var{directory}, if that is inserted). In this
case, point goes at the beginning of @var{initial}. The default for
@var{initial} is @code{nil}---don't insert any file name. To see what
@var{initial} does, try the command @kbd{C-x C-v}. @strong{Note:} we
@node Reading a Password
@section Reading a Password
+@cindex passwords, reading
- This function is useful for reading passwords.
+ To read a password to pass to another program, you can use the
+function @code{read-passwd}.
-@defun read-password prompt default
-@tindex read-password
-This function reads a password, echoing @samp{.} in the echo area
-for each character entered, and returns it as a string. It prompts
-with @var{prompt}, and returns @var{default} if the user enters the
-null string.
+@tindex read-passwd
+@defun read-passwd prompt &optional confirm default
+This function reads a password, prompting with @var{prompt}. It does
+not echo the password as the user types it; instead, it echoes @samp{.}
+for each character in the password.
+
+The optional argument @var{confirm}, if non-@code{nil}, says to read the
+password twice and insist it must be the same both times. If it isn't
+the same, the user has to type it over and over until the last two
+times match.
+
+The optional argument @var{default} specifies the default password to
+return if the user enters empty input. If @var{default} is @code{nil},
+then @code{read-passwd} returns the null string in that case.
@end defun
@node Minibuffer Misc
minibuffer. If no minibuffer is active, it returns @code{nil}.
@end defun
-@defun minibuffer-prompt-width
-This function returns the display width of the prompt string of the
-currently active minibuffer. If no minibuffer is active, it returns 0.
+@tindex minubuffer-prompt-end
+@defun minubuffer-prompt-end
+This function, available starting in Emacs 21, returns the current
+position of the end of the minibuffer prompt, if a minibuffer is
+current. Otherwise, it returns zero.
+@end defun
+
+@defun minubuffer-prompt-width
+This function returns the current display-width of the minibuffer
+prompt, if a minibuffer is current. Otherwise, it returns zero.
@end defun
@defvar minibuffer-setup-hook