changeset 7221:a2c7acc3be9c

*** empty log message ***

--- a/lispref/minibuf.texi	Sat Apr 30 06:05:51 1994 +0000
+++ b/lispref/minibuf.texi	Sat Apr 30 07:00:37 1994 +0000
@@ -41,7 +41,7 @@
 no minibuffer window, and sometimes a special kind of frame contains
 nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
 
-  The minibuffers window is normally a single line.  You can resize it
+  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
@@ -82,10 +82,10 @@
 @node Text from Minibuffer
 @section Reading Text Strings with the Minibuffer
 
-  Most often, the minibuffer is used to read text which is returned as a
-string.  It can also be used to read a Lisp object in textual form.  The
-most basic primitive for minibuffer input is
-@code{read-from-minibuffer}; it can do either one.
+  Most often, the minibuffer is used to read text as a string.  It can
+also be used to read a Lisp object in textual form.  The most basic
+primitive for minibuffer input is @code{read-from-minibuffer}; it can do
+either one.
 
 @defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist
 This function is the most general way to get input through the
@@ -140,7 +140,7 @@
 @group
 (read-string @var{prompt} @var{initial})
 @equiv{}
-(read-from-minibuffer @var{prompt} @var{initial} nil nil)
+(read-from-minibuffer @var{prompt} @var{initial} nil nil nil)
 @end group
 @end smallexample
 @end defun
@@ -223,8 +223,11 @@
 @cindex @kbd{?} in minibuffer
 @code{self-insert-and-exit}
 
-@item @kbd{M-n} and @kbd{M-p}
-@code{next-history-element} and @code{previous-history-element}
+@item @kbd{M-n}
+@code{next-history-element}
+
+@item @kbd{M-p}
+@code{previous-history-element}
 
 @item @kbd{M-r}
 @code{next-matching-history-element}
@@ -241,12 +244,11 @@
 minibuffer.
 
 @defun read-minibuffer prompt &optional initial
-  This function reads a Lisp object in the minibuffer and returns it,
+This function reads a Lisp object in the minibuffer and returns it,
 without evaluating it.  The arguments @var{prompt} and @var{initial} are
-used as in @code{read-from-minibuffer}; in particular, @var{initial}
-must be a string or @code{nil}.
+used as in @code{read-from-minibuffer}.
 
-  This is a simplified interface to the
+This is a simplified interface to the
 @code{read-from-minibuffer} function:
 
 @smallexample
@@ -281,11 +283,11 @@
 @end defun
 
 @defun eval-minibuffer prompt &optional initial
-  This function reads a Lisp expression in the minibuffer, evaluates it,
+This function reads a Lisp expression in the minibuffer, evaluates it,
 then returns the result.  The arguments @var{prompt} and @var{initial}
 are used as in @code{read-from-minibuffer}.
 
-  This function simply evaluates the result of a call to
+This function simply evaluates the result of a call to
 @code{read-minibuffer}:
 
 @smallexample
@@ -298,7 +300,7 @@
 @end defun
 
 @defun edit-and-eval-command prompt form
-  This function reads a Lisp expression in the minibuffer, and then
+This function reads a Lisp expression in the minibuffer, and then
 evaluates it.  The difference between this command and
 @code{eval-minibuffer} is that here the initial @var{form} is not
 optional and it is treated as a Lisp object to be converted to printed
@@ -306,21 +308,21 @@
 @code{prin1}, so if it is a string, double-quote characters (@samp{"})
 appear in the initial text.  @xref{Output Functions}.
 
-  The first thing @code{edit-and-eval-command} does is to activate the
+The first thing @code{edit-and-eval-command} does is to activate the
 minibuffer with @var{prompt} as the prompt.  Then it inserts the printed
 representation of @var{form} in the minibuffer, and lets the user edit.
 When the user exits the minibuffer, the edited text is read with
 @code{read} and then evaluated.  The resulting value becomes the value
 of @code{edit-and-eval-command}.
 
-  In the following example, we offer the user an expression with initial
+In the following example, we offer the user an expression with initial
 text which is a valid form already:
 
 @smallexample
 @group
 (edit-and-eval-command "Please edit: " '(forward-word 1))
 
-;; @r{After evaluating the preceding expression,} 
+;; @r{After evaluation of the preceding expression,} 
 ;;   @r{the following appears in the minibuffer:}
 @end group
 
@@ -343,9 +345,9 @@
 @cindex history list
 
 A @dfn{minibuffer history list} records previous minibuffer inputs so
-the user can reuse them conveniently.  A history list is a symbol, a
-variable whose value is a list of strings (previous inputs), most recent
-first.
+the user can reuse them conveniently.  A history list is actually a
+symbol, not a list; it is a variable whose value is a list of strings
+(previous inputs), most recent first.
 
 There are many separate history lists, used for different kinds of
 inputs.  It's the Lisp programmer's job to specify the right history
@@ -452,10 +454,15 @@
 @node Basic Completion
 @subsection Basic Completion Functions
 
+  The two functions @code{try-completion} and @code{all-completions}
+have nothing in themselves to do with minibuffers.  We describe them in
+this chapter so as to keep them near the higher-level completion
+features that do use the minibuffer.
+
 @defun try-completion string collection &optional predicate
 This function returns the longest common substring of all possible
 completions of @var{string} in @var{collection}.  The value of
-@var{collection} must be an alist, an obarray, or a function which
+@var{collection} must be an alist, an obarray, or a function that
 implements a virtual set of strings (see below).
 
 Completion compares @var{string} against each of the permissible
@@ -487,8 +494,8 @@
 (the @sc{car} of which is a string) or else it is a symbol (@emph{not} a
 symbol name) from the obarray.
 
-You can also use a function symbol as @var{collection}.  Then the
-function is solely responsible for performing completion;
+You can also use a symbol that is a function as @var{collection}.  Then
+the function is solely responsible for performing completion;
 @code{try-completion} returns whatever this function returns.  The
 function is called with three arguments: @var{string}, @var{predicate}
 and @code{nil}.  (The reason for the third argument is so that the same
@@ -541,7 +548,7 @@
 (try-completion 
  "foo"
  '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) 
-     'test)
+ 'test)
      @result{} "foobar"
 @end group
 @end smallexample
@@ -570,7 +577,7 @@
 (all-completions  
  "foo"
  '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
- (function test))
+ 'test)
      @result{} ("foobar1" "foobar2")
 @end group
 @end smallexample
@@ -581,11 +588,6 @@
 non-@code{nil}, Emacs does not consider case significant in completion.
 @end defvar
 
-  The two functions @code{try-completion} and @code{all-completions}
-have nothing in themselves to do with minibuffers.  We describe them in
-this chapter so as to keep them near the higher-level completion
-features that do use the minibuffer.
-
 @node Minibuffer Completion
 @subsection Completion and the Minibuffer
 
@@ -608,13 +610,14 @@
 won't exit unless the input completes to an element of @var{collection}.
 If @var{require-match} is neither @code{nil} nor @code{t}, then the exit
 commands won't exit unless the input typed is itself an element of
-@var{collection}.
+@var{collection}.  If @var{require-match} is @code{nil}, the exit
+commands work regardless of the input in the minibuffer.
 
 The function @code{completing-read} works by calling
 @code{read-minibuffer}.  It uses @code{minibuffer-local-completion-map}
 as the keymap if @var{require-match} is @code{nil}, and uses
 @code{minibuffer-local-must-match-map} if @var{require-match} is
-non-@code{nil}.
+non-@code{nil}.  @xref{Completion Commands}.
 
 The argument @var{hist} specifies which history list variable to use for
 saving the input and for minibuffer history commands.  It defaults to
@@ -635,7 +638,7 @@
 @end group
 
 @group
-;; @r{After evaluating the preceding expression,} 
+;; @r{After evaluation of the preceding expression,} 
 ;;   @r{the following appears in the minibuffer:}
 
 ---------- Buffer: Minibuffer ----------
@@ -649,22 +652,11 @@
 @code{completing-read} returns @code{barfoo}.
 
 The @code{completing-read} function binds three variables to pass
-information to the commands which actually do completion.  Here they
-are:
-
-@table @code
-@item minibuffer-completion-table
-This variable is bound to the @var{collection} argument.  It is passed
-to the @code{try-completion} function.
-
-@item minibuffer-completion-predicate
-This variable is bound to the @var{predicate} argument.  It is passed to
-the @code{try-completion} function.
-
-@item minibuffer-completion-confirm
-This variable is bound to the @var{require-match} argument.  It is used
-in the @code{minibuffer-complete-and-exit} function.
-@end table
+information to the commands that actually do completion.  These
+variables are @code{minibuffer-completion-table},
+@code{minibuffer-completion-predicate} and
+@code{minibuffer-completion-confirm}.  For more information about them,
+see @ref{Completion Commands}.
 @end defun
 
 @node Completion Commands
@@ -674,7 +666,7 @@
 the minibuffer to do completion.
 
 @defvar minibuffer-local-completion-map
-  @code{completing-read} uses this value as the local keymap when an
+@code{completing-read} uses this value as the local keymap when an
 exact match of one of the completions is not required.  By default, this
 keymap makes the following bindings:
 
@@ -690,13 +682,14 @@
 @end table
 
 @noindent
-with other characters bound as in @code{minibuffer-local-map}.
+with other characters bound as in @code{minibuffer-local-map}
+(@pxref{Text from Minibuffer}).
 @end defvar
 
 @defvar minibuffer-local-must-match-map
 @code{completing-read} uses this value as the local keymap when an
 exact match of one of the completions is required.  Therefore, no keys
-are bound to @code{exit-minibuffer}, the command which exits the
+are bound to @code{exit-minibuffer}, the command that exits the
 minibuffer unconditionally.  By default, this keymap makes the following
 bindings:
 
@@ -749,7 +742,9 @@
 This function completes the minibuffer contents, and exits if
 confirmation is not required, i.e., if
 @code{minibuffer-completion-confirm} is non-@code{nil}.  If confirmation
-@emph{is} required, it is given by repeating this command immediately.
+@emph{is} required, it is given by repeating this command
+immediately---the command is programmed to work without confirmation
+when run twice in succession.
 @end deffn
 
 @defvar minibuffer-completion-confirm
@@ -809,11 +804,11 @@
 is not inserted in the minibuffer as initial input.
 
 If @var{existing} is non-@code{nil}, then the name specified must be
-that of an  existing buffer.  The usual commands to exit the
-minibuffer do not exit if the text is not valid, and @key{RET} does
-completion to attempt to find a valid name.  (However, @var{default} is
-not checked for this; it is returned, whatever it is, if the user exits
-with the minibuffer empty.)
+that of an existing buffer.  The usual commands to exit the minibuffer
+do not exit if the text is not valid, and @key{RET} does completion to
+attempt to find a valid name.  (However, @var{default} is not checked
+for validity; it is returned, whatever it is, if the user exits with the
+minibuffer empty.)
 
 In the following example, the user enters @samp{minibuffer.t}, and
 then types @key{RET}.  The argument @var{existing} is @code{t}, and the
@@ -823,7 +818,7 @@
 @example
 (read-buffer "Buffer name? " "foo" t)
 @group
-;; @r{After evaluating the preceding expression,} 
+;; @r{After evaluation of the preceding expression,} 
 ;;   @r{the following prompt appears,}
 ;;   @r{with an empty minibuffer:}
 @end group
@@ -852,7 +847,7 @@
 (read-command "Command name? ")
 
 @group
-;; @r{After evaluating the preceding expression,} 
+;; @r{After evaluation of the preceding expression,} 
 ;;   @r{the following prompt appears with an empty minibuffer:}
 @end group
 
@@ -891,7 +886,7 @@
 @group
 (read-variable "Variable name? ")
 
-;; @r{After evaluating the preceding expression,} 
+;; @r{After evaluation of the preceding expression,} 
 ;;   @r{the following prompt appears,} 
 ;;   @r{with an empty minibuffer:}
 @end group
@@ -933,25 +928,29 @@
 This function reads a file name in the minibuffer, prompting with
 @var{prompt} and providing completion.  If @var{default} is
 non-@code{nil}, then the function returns @var{default} if the user just
-types @key{RET}.
+types @key{RET}.  @var{default} is not checked for validity; it is
+returned, whatever it is, if the user exits with the minibuffer empty.
 
-If @var{existing} is non-@code{nil}, then the name must refer to an
-existing file; then @key{RET} performs completion to make the name valid
-if possible, and then refuses to exit if it is not valid.  If the value
-of @var{existing} is neither @code{nil} nor @code{t}, then @key{RET}
-also requires confirmation after completion.
+If @var{existing} is non-@code{nil}, then the user must specify the name
+of an existing file; @key{RET} performs completion to make the name
+valid if possible, and then refuses to exit if it is not valid.  If the
+value of @var{existing} is neither @code{nil} nor @code{t}, then
+@key{RET} also requires confirmation after completion.  If
+@var{existing} is @code{nil}, then the name of a nonexistent file is
+acceptable.
 
 The argument @var{directory} specifies the directory to use for
-completion of relative file names.  Usually it is inserted in the
-minibuffer as initial input as well.  It defaults to the current
-buffer's value of @code{default-directory}.
+completion of relative file names.  If @code{insert-default-directory}
+is non-@code{nil}, @var{directory} is also inserted in the minibuffer as
+initial input.  It defaults to the current buffer's value of
+@code{default-directory}.
 
 @c Emacs 19 feature
 If you specify @var{initial}, that is an initial file name to insert in
-the buffer along with @var{directory}.  In this case, point goes after
-@var{directory}, before @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}.
+the buffer (after with @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}.
 
 Here is an example: 
 
@@ -959,7 +958,7 @@
 @group
 (read-file-name "The file is ")
 
-;; @r{After evaluating the preceding expression,} 
+;; @r{After evaluation of the preceding expression,} 
 ;;   @r{the following appears in the minibuffer:}
 @end group
 
@@ -1036,10 +1035,10 @@
 This is called @dfn{programmed completion}.
 
   To use this feature, pass a symbol with a function definition as the
-@var{collection} argument to @code{completing-read}.  This function
-arranges to pass your completion function along to @code{try-completion}
-and @code{all-completions}, which will then let your function do all the
-work.
+@var{collection} argument to @code{completing-read}.  The function
+@code{completing-read} arranges to pass your completion function along
+to @code{try-completion} and @code{all-completions}, which will then let
+your function do all the work.
 
   The completion function should accept three arguments:
 
@@ -1077,7 +1076,7 @@
 @end itemize
 
   It would be consistent and clean for completion functions to allow
-lambda expressions (lists which are functions) as well as function
+lambda expressions (lists tha are functions) as well as function
 symbols as @var{collection}, but this is impossible.  Lists as
 completion tables are already assigned another meaning---as alists.  It
 would be unreliable to fail to handle an alist normally because it is
@@ -1104,7 +1103,7 @@
 @code{y-or-n-p} does not; but it seems best to describe them together.
 
 @defun y-or-n-p prompt
-  This function asks the user a question, expecting input in the echo
+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
@@ -1113,35 +1112,35 @@
 is a single character, with no @key{RET} needed to terminate it.  Upper
 and lower case are equivalent.
 
-  ``Asking the question'' means printing @var{prompt} in the echo area,
+``Asking the question'' means printing @var{prompt} in the echo area,
 followed by the string @w{@samp{(y or n) }}.  If the input is not one of
 the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}},
 @kbd{@key{DEL}}, or something that quits), the function responds
 @samp{Please answer y or n.}, and repeats the request.
 
-  This function does not actually use the minibuffer, since it does not
+This function does not actually use the minibuffer, since it does not
 allow editing of the answer.  It actually uses the echo area (@pxref{The
 Echo Area}), which uses the same screen space as the minibuffer.  The
 cursor moves to the echo area while the question is being asked.
 
-  The answers and their meanings, even @samp{y} and @samp{n}, are not
+The answers and their meanings, even @samp{y} and @samp{n}, are not
 hardwired.  The keymap @code{query-replace-map} specifies them.
 @xref{Search and Replace}.
 
-  If @code{y-or-n-p} is called in a command that was invoked using the
+If @code{y-or-n-p} is called in a command that was invoked using the
 mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
 Loop Info}) is either @code{nil} or a mouse event---then it uses a
 dialog box or pop-up menu to ask the question.  In this case, it does
 not use keyboard input or the echo area.
 
-  In the following example, the user first types @kbd{q}, which is
+In the following example, the user first types @kbd{q}, which is
 invalid.  At the next prompt the user types @kbd{y}.
 
 @smallexample
 @group
 (y-or-n-p "Do you need a lift? ")
 
-;; @r{After evaluating the preceding expression,} 
+;; @r{After evaluation of the preceding expression,} 
 ;;   @r{the following prompt appears in the echo area:}
 @end group
 
@@ -1175,20 +1174,20 @@
 @end defun
 
 @defun yes-or-no-p prompt
-  This function asks the user a question, expecting input in minibuffer.
-It returns @code{t} if the user enters @samp{yes}, @code{nil} if the
-user types @samp{no}.  The user must type @key{RET} to finalize the
-response.  Upper and lower case are equivalent.
+This function asks the user a question, expecting input in the
+minibuffer.  It returns @code{t} if the user enters @samp{yes},
+@code{nil} if the user types @samp{no}.  The user must type @key{RET} to
+finalize the response.  Upper and lower case are equivalent.
 
-  @code{yes-or-no-p} starts by displaying @var{prompt} in the echo area,
+@code{yes-or-no-p} starts by displaying @var{prompt} in the echo area,
 followed by @w{@samp{(yes or no) }}.  The user must type one of the
 expected responses; otherwise, the function responds @samp{Please answer
 yes or no.}, waits about two seconds and repeats the request.
 
-  @code{yes-or-no-p} requires more work from the user than
+@code{yes-or-no-p} requires more work from the user than
 @code{y-or-n-p} and is appropriate for more crucial decisions.
 
-  If @code{yes-or-no-p} is called in a command that was invoked using
+If @code{yes-or-no-p} is called in a command that was invoked using
 the mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
 Loop Info}) is either @code{nil} or a mouse event---then it uses a
 dialog box or pop-up menu to ask the question.  In this case, it does
@@ -1200,7 +1199,7 @@
 @group
 (yes-or-no-p "Do you really want to remove everything? ")
 
-;; @r{After evaluating the preceding expression,} 
+;; @r{After evaluation of the preceding expression,} 
 ;;   @r{the following prompt appears,} 
 ;;   @r{with an empty minibuffer:}
 @end group
@@ -1230,6 +1229,13 @@
 @node Multiple Queries
 @section Asking Multiple Y-or-N Questions
 
+  When you have a series of similar questions to ask, such as ``Do you
+want to save this buffer'' for each buffer in turn, you should use
+@code{map-y-or-n-p} to ask the collection of questions, rather than
+asking each question individually.  This gives the user certain
+convenient facilities such as the ability to answer the whole series at
+once.
+
 @defun map-y-or-n-p prompter actor list &optional help action-alist
 This function, new in Emacs 19, asks the user a series of questions,
 reading a single-character answer in the echo area for each one.
@@ -1328,16 +1334,24 @@
 
 @deffn Command previous-matching-history-element pattern
 This command replaces the minibuffer contents with the value of the
-previous (older) history element that matches @var{pattern}.
+previous (older) history element that matches @var{pattern} (a regular
+expression).
 @end deffn
 
 @deffn Command next-matching-history-element pattern
-This command replaces the minibuffer contents with the value of the
-next (newer) history element that matches @var{pattern}.
+This command replaces the minibuffer contents with the value of the next
+(newer) history element that matches @var{pattern} (a regular
+expression).
 @end deffn
 
 @defvar minibuffer-setup-hook
 This is a normal hook that is run whenever the minibuffer is entered.
+@xref{Hooks}.
+@end defvar
+
+@defvar minibuffer-setup-hook
+This is a normal hook that is run whenever the minibuffer is exited.
+@xref{Hooks}.
 @end defvar
 
 @defvar minibuffer-help-form
@@ -1383,9 +1397,19 @@
 returns zero.
 @end defun
 
+@defun minibuffer-prompt
+This function returns the prompt string of the currently active
+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.
+@end defun
+
 @defopt enable-recursive-minibuffers
 If this variable is non-@code{nil}, you can invoke commands (such as
-@code{find-file}) which use minibuffers even while in the minibuffer
+@code{find-file}) that use minibuffers even while in the minibuffer
 window.  Such invocation produces a recursive editing level for a new
 minibuffer.  The outer-level minibuffer is invisible while you are
 editing the inner one.
@@ -1398,7 +1422,7 @@
 
 @c Emacs 19 feature
 If a command name has a property @code{enable-recursive-minibuffers}
-which is non-@code{nil}, then the command can use the minibuffer to read
+that is non-@code{nil}, then the command can use the minibuffer to read
 arguments even if it is invoked from the minibuffer.  The minibuffer
 command @code{next-matching-history-element} (normally bound to
 @kbd{M-s} in the minibuffer) uses this feature.