Commit 9d2754f5 authored by Glenn Morris's avatar Glenn Morris

Small edits for doc/lispref/minibuf.texi

* doc/lispref/minibuf.texi: Standardize metasyntactic variables
("history", etc).
Use Texinfo-recommended form of quote+punctuation.
(Intro to Minibuffers): First minibuffer is #1, not #0.
Mention minibuffer-inactive-mode.
(Text from Minibuffer): Copyedits.
(Minibuffer History, Programmed Completion): Fix @var usage.
parent 02a540a1
2012-04-19 Glenn Morris <rgm@gnu.org>
* minibuf.texi: Standardize metasyntactic variables ("history", etc).
Use Texinfo-recommended form of quote+punctuation.
(Intro to Minibuffers): First minibuffer is #1, not #0.
Mention minibuffer-inactive-mode.
(Text from Minibuffer): Copyedits.
(Minibuffer History, Programmed Completion): Fix @var usage.
2012-04-18 Glenn Morris <rgm@gnu.org>
* processes.texi (Serial Ports, Byte Packing, Bindat Spec)
......
......@@ -60,8 +60,10 @@ boundary between the prompt and the actual text.
The minibuffer's window is normally a single line; it grows
automatically if the contents require more space. You can explicitly
@c FIXME? Works in 23.4, not 24.0.95. (Bug#11276)
resize it temporarily with the window sizing commands; it reverts to
its normal size when the minibuffer is exited. You can resize it
@c FIXME? Doesn't work in any version of Emacs?
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
......@@ -73,9 +75,9 @@ of variables such as @code{this-command} and @code{last-command}
code that uses the minibuffer, if you do not want that to change them.
Under some circumstances, a command can use a minibuffer even if
there is an active minibuffer; such minibuffers are called a
there is an active minibuffer; such a minibuffer is called a
@dfn{recursive minibuffer}. The first minibuffer is named
@w{@samp{ *Minibuf-0*}}. Recursive minibuffers are named by
@w{@samp{ *Minibuf-1*}}. Recursive minibuffers are named by
incrementing the number at the end of the name. (The names begin with
a space so that they won't show up in normal buffer lists.) Of
several recursive minibuffers, the innermost (or most recently
......@@ -91,6 +93,14 @@ to be done. @xref{Text from Minibuffer}, for the non-completion
minibuffer local maps. @xref{Completion Commands}, for the minibuffer
local maps for completion.
@findex minibuffer-inactive-mode
@vindex minibuffer-inactive-mode-map
@cindex inactive minibuffer
When a minibuffer is inactive, it's major mode is
@code{minibuffer-inactive-mode}, with keymap
@code{minibuffer-inactive-mode-map}. This is only really useful if
the minibuffer is in a separate frame. @xref{Minibuffers and Frames}.
When Emacs is running in batch mode, any request to read from the
minibuffer actually reads a line from the standard input descriptor that
was supplied when Emacs was started.
......@@ -111,7 +121,7 @@ middle of a Lisp function. Instead, do all minibuffer input as part of
reading the arguments for a command, in the @code{interactive}
specification. @xref{Defining Commands}.
@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method
@defun read-from-minibuffer prompt &optional initial keymap read history default inherit-input-method
This function is the most general way to get input from the
minibuffer. By default, it accepts arbitrary text and returns it as a
string; however, if @var{read} is non-@code{nil}, then it uses
......@@ -119,8 +129,8 @@ string; however, if @var{read} is non-@code{nil}, then it uses
Functions}).
The first thing this function does is to activate a minibuffer and
display it with @var{prompt-string} as the prompt. This value must be a
string. Then the user can edit text in the minibuffer.
display it with @var{prompt} (which must be a string) as the
prompt. Then the user can edit text in the minibuffer.
When the user types a command to exit the minibuffer,
@code{read-from-minibuffer} constructs the return value from the text in
......@@ -132,7 +142,7 @@ reads the text and returns the resulting Lisp object, unevaluated.
The argument @var{default} specifies default values to make available
through the history commands. It should be a string, a list of
strings, or @code{nil}. The string or strings become the minibuffer's
``future history,'' available to the user with @kbd{M-n}.
``future history'', available to the user with @kbd{M-n}.
If @var{read} is non-@code{nil}, then @var{default} is also used
as the input to @code{read}, if the user enters empty input.
......@@ -149,12 +159,13 @@ value of @code{minibuffer-local-map} is used as the keymap. Specifying
a keymap is the most important way to customize the minibuffer for
various applications such as completion.
The argument @var{hist} specifies which history list variable to use
The argument @var{history} specifies a history list variable to use
for saving the input and for history commands used in the minibuffer.
It defaults to @code{minibuffer-history}. @xref{Minibuffer History}.
It defaults to @code{minibuffer-history}. You can optionally specify
a starting position in the history list as well. @xref{Minibuffer History}.
If the variable @code{minibuffer-allow-text-properties} is
non-@code{nil}, then the string which is returned includes whatever text
non-@code{nil}, then the string that is returned includes whatever text
properties were present in the minibuffer. Otherwise all the text
properties are stripped when the value is returned.
......@@ -164,9 +175,9 @@ the setting of @code{enable-multibyte-characters} (@pxref{Text
Representations}) from whichever buffer was current before entering the
minibuffer.
Use of @var{initial-contents} is mostly deprecated; we recommend using
Use of @var{initial} is mostly deprecated; we recommend using
a non-@code{nil} value only in conjunction with specifying a cons cell
for @var{hist}. @xref{Initial Input}.
for @var{history}. @xref{Initial Input}.
@end defun
@defun read-string prompt &optional initial history default inherit-input-method
......@@ -179,11 +190,11 @@ The optional argument @var{default} is used as in
@code{read-from-minibuffer}, except that, if non-@code{nil}, it also
specifies a default value to return if the user enters null input. As
in @code{read-from-minibuffer} it should be a string, a list of
strings, or @code{nil} which is equivalent to an empty string. When
strings, or @code{nil}, which is equivalent to an empty string. When
@var{default} is a string, that string is the default value. When it
is a list of strings, the first string is the default value. (All
these strings are available to the user in the ``future minibuffer
history.'')
history''.)
This function works by calling the
@code{read-from-minibuffer} function:
......@@ -202,16 +213,16 @@ This function works by calling the
@end smallexample
@end defun
@defun read-regexp prompt &optional default-value
@defun read-regexp prompt &optional default
This function reads a regular expression as a string from the
minibuffer and returns it. The argument @var{prompt} is used as in
@code{read-from-minibuffer}. The keymap used is
@code{minibuffer-local-map}, and @code{regexp-history} is used as the
history list (@pxref{Minibuffer History, regexp-history}).
The optional argument @var{default-value} specifies a default value to
The optional argument @var{default} specifies a default value to
return if the user enters null input; it should be a string, or
@code{nil} which is equivalent to an empty string.
@code{nil}, which is equivalent to an empty string.
In addition, @code{read-regexp} collects a few useful candidates for
input and passes them to @code{read-from-minibuffer}, to make them
......@@ -235,9 +246,9 @@ function, after computing the list of defaults as described above.
@end defun
@defvar minibuffer-allow-text-properties
If this variable is @code{nil}, then @code{read-from-minibuffer} strips
all text properties from the minibuffer input before returning it.
This variable also affects @code{read-string}. However,
If this variable is @code{nil}, then @code{read-from-minibuffer}
and @code{read-string} strip all text properties from the minibuffer
input before returning it. However,
@code{read-no-blanks-input} (see below), as well as
@code{read-minibuffer} and related functions (@pxref{Object from
Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all
......@@ -275,6 +286,12 @@ default, it makes the following bindings:
@item @kbd{M-r}
@code{previous-matching-history-element}
@ignore
@c Does not seem worth/appropriate mentioning.
@item @kbd{C-@key{TAB}}
@code{file-cache-minibuffer-complete}
@end ignore
@end table
@end defvar
......@@ -305,6 +322,8 @@ This function discards text properties, regardless of the value of
@end smallexample
@end defun
@c Slightly unfortunate name, suggesting it might be related to the
@c Nextstep port...
@defvar minibuffer-local-ns-map
This built-in variable is the keymap used as the minibuffer local keymap
in the function @code{read-no-blanks-input}. By default, it makes the
......@@ -441,7 +460,7 @@ is a list of strings (previous inputs), most recent first.
kinds of inputs. It's the Lisp programmer's job to specify the right
history list for each use of the minibuffer.
You specify a minibuffer history list with the optional @var{hist}
You specify a minibuffer history list with the optional @var{history}
argument to @code{read-from-minibuffer} or @code{completing-read}.
Here are the possible values for it:
......@@ -457,7 +476,7 @@ Specifying 0 for @var{startpos} is equivalent to just specifying the
symbol @var{variable}. @code{previous-history-element} will display
the most recent element of the history list in the minibuffer. If you
specify a positive @var{startpos}, the minibuffer history functions
behave as if @code{(elt @var{variable} (1- @var{STARTPOS}))} were the
behave as if @code{(elt @var{variable} (1- @var{startpos}))} were the
history element currently shown in the minibuffer.
For consistency, you should also specify that element of the history
......@@ -465,7 +484,7 @@ as the initial minibuffer contents, using the @var{initial} argument
to the minibuffer input function (@pxref{Initial Input}).
@end table
If you don't specify @var{hist}, then the default history list
If you don't specify @var{history}, then the default history list
@code{minibuffer-history} is used. For other standard history lists,
see below. You can also create your own history list variable; just
initialize it to @code{nil} before the first use.
......@@ -560,7 +579,7 @@ A history list for arguments that are Lisp expressions to evaluate.
@section Initial Input
Several of the functions for minibuffer input have an argument called
@var{initial} or @var{initial-contents}. This is a mostly-deprecated
@var{initial}. This is a mostly-deprecated
feature for specifying that the minibuffer should start out with
certain text, instead of empty as usual.
......@@ -577,7 +596,7 @@ to offer useful default inputs to the user.
There is just one situation where you should specify a string for an
@var{initial} argument. This is when you specify a cons cell for the
@var{hist} or @var{history} argument. @xref{Minibuffer History}.
@var{history} argument. @xref{Minibuffer History}.
@var{initial} can also be a cons cell of the form @code{(@var{string}
. @var{position})}. This means to insert @var{string} in the
......@@ -663,7 +682,7 @@ If @var{collection} is an alist (@pxref{Association Lists}), the
permissible completions are the elements of the alist that are either
strings, or conses whose @sc{car} is a string or symbol.
Symbols are converted to strings using @code{symbol-name}. Other
elements of the alist are ignored. (Remember that in Emacs Lisp, the
elements of the alist are ignored. (Remember that in Emacs Lisp, the
elements of alists do not @emph{have} to be conses.) In particular, a
list of strings is allowed, even though we usually do not
think of such lists as alists.
......@@ -880,7 +899,7 @@ Here is a usage example:
This section describes the basic interface for reading from the
minibuffer with completion.
@defun completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method
@defun completing-read prompt collection &optional predicate require-match initial history default inherit-input-method
This function reads a string in the minibuffer, assisting the user by
providing completion. It activates the minibuffer with prompt
@var{prompt}, which must be a string.
......@@ -935,13 +954,13 @@ The function @code{completing-read} uses
@code{minibuffer-local-must-match-map} if @var{require-match} is
non-@code{nil}. @xref{Completion Commands}.
The argument @var{hist} specifies which history list variable to use for
The argument @var{history} specifies which history list variable to use for
saving the input and for minibuffer history commands. It defaults to
@code{minibuffer-history}. @xref{Minibuffer History}.
The argument @var{initial} is mostly deprecated; we recommend using a
non-@code{nil} value only in conjunction with specifying a cons cell
for @var{hist}. @xref{Initial Input}. For default input, use
for @var{history}. @xref{Initial Input}. For default input, use
@var{default} instead.
If the argument @var{inherit-input-method} is non-@code{nil}, then the
......@@ -1545,17 +1564,17 @@ The file is @point{}
@end example
@end defopt
@defun read-shell-command prompt &optional initial-contents hist &rest args
@defun read-shell-command prompt &optional initial history &rest args
This function reads a shell command from the minibuffer, prompting
with @var{prompt} and providing intelligent completion. It completes
the first word of the command using candidates that are appropriate
for command names, and the rest of the command words as file names.
This function uses @code{minibuffer-local-shell-command-map} as the
keymap for minibuffer input. The @var{hist} argument specifies the
keymap for minibuffer input. The @var{history} argument specifies the
history list to use; if is omitted or @code{nil}, it defaults to
@code{shell-command-history} (@pxref{Minibuffer History,
shell-command-history}). The optional argument @var{initial-contents}
shell-command-history}). The optional argument @var{initial}
specifies the initial content of the minibuffer (@pxref{Initial
Input}). The rest of @var{args}, if present, are used as the
@var{default} and @var{inherit-input-method} arguments in
......@@ -1727,9 +1746,10 @@ some completion alternative; @code{nil} otherwise.
@item (boundaries . @var{suffix})
This specifies a @code{completion-boundaries} operation. The function
should return @code{(boundaries START . END)}, where START is the
position of the beginning boundary in the specified string, and END is
the position of the end boundary in SUFFIX.
should return @code{(boundaries @var{start} . @var{end})}, where
@var{start} is the position of the beginning boundary in the specified
string, and @var{end} is the position of the end boundary in
@var{suffix}.
@item metadata
This specifies a request for information about the state of the
......@@ -1891,7 +1911,7 @@ the call.
This function asks the user a question, expecting input in the echo
area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the
user types @kbd{n}. This function also accepts @key{SPC} to mean yes
and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit,'' like
and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit'', like
@kbd{C-g}, because the question might look like a minibuffer and for
that reason the user might try to use @kbd{C-]} to get out. The answer
is a single character, with no @key{RET} needed to terminate it. Upper
......@@ -1952,10 +1972,10 @@ We show successive lines of echo area messages, but only one actually
appears on the screen at a time.
@end defun
@defun y-or-n-p-with-timeout prompt seconds default-value
@defun y-or-n-p-with-timeout prompt seconds default
Like @code{y-or-n-p}, except that if the user fails to answer within
@var{seconds} seconds, this function stops waiting and returns
@var{default-value}. It works by setting up a timer; see @ref{Timers}.
@var{default}. It works by setting up a timer; see @ref{Timers}.
The argument @var{seconds} may be an integer or a floating point number.
@end defun
......@@ -2081,7 +2101,7 @@ answer); @var{function} is a function of one argument (an object from
When the user responds with @var{char}, @code{map-y-or-n-p} calls
@var{function}. If it returns non-@code{nil}, the object is considered
``acted upon,'' and @code{map-y-or-n-p} advances to the next object in
``acted upon'', and @code{map-y-or-n-p} advances to the next object in
@var{list}. If it returns @code{nil}, the prompt is repeated for the
same object.
......
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