(Text from Minibuffer): Document `read-regexp'.

(Completion Commands, Reading File Names): Rename
`minibuffer-local-must-match-filename-map' to
`minibuffer-local-filename-must-match-map'.
(Minibuffer Completion): The `require-match' argument to `completing-read'
can now have the value `confirm-only'.

3 files changed, 57 insertions, 8 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index cc74a973792..7e1ba05893b 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,12 @@
 2008-10-18  Eli Zaretskii  <eliz@gnu.org>
 
+        * minibuf.texi (Text from Minibuffer): Document `read-regexp'.
+        (Completion Commands, Reading File Names): Rename
+        `minibuffer-local-must-match-filename-map' to
+        `minibuffer-local-filename-must-match-map'.
+        (Minibuffer Completion): The `require-match' argument to
+        `completing-read' can now have the value `confirm-only'.
+
         * windows.texi (Displaying Buffers): Minor wording fix.
         (Choosing Window): `split-height-threshold' can now be nil.
         Document `split-width-threshold'.  `pop-up-frames' can have the
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index a5076a2b7e4..55b6f77262a 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -101,9 +101,11 @@ was supplied when Emacs was started.
 
   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.  There are also specialized commands for reading
-commands, variables, file names, etc. (@pxref{Completion}).
+primitive for minibuffer input is @code{read-from-minibuffer}; it can
+do either one.  Regular expressions (@pxref{Regular Expressions}) are
+a special kind of strings; use @code{read-regexp} for their minibuffer
+input.  There are also specialized commands for reading commands,
+variables, file names, etc.@: (@pxref{Completion}).
 
   In most cases, you should not call minibuffer input functions in the
 middle of a Lisp function.  Instead, do all minibuffer input as part of
@@ -201,6 +203,40 @@ This function works by calling the
 @end smallexample
 @end defun
 
+@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}, if non-@code{nil}, 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
+@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.  To this
+default @code{read-regexp} adds a few other useful candidates, and
+passes them to @code{read-from-minibuffer} to make them available to
+the user as the ``future minibuffer history list'' (@pxref{Minibuffer
+History, future list,, emacs, The GNU Emacs Manual}).  These
+candidates are:
+
+@itemize @minus
+@item
+The Word or symbol at point.
+@item
+The last regexp used in an incremental search.
+@item
+The last string used in an incremental search.
+@item
+The last string or pattern used in query-replace commands.
+@end itemize
+
+This function works by calling the @code{read-from-minibuffer}
+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.
@@ -839,9 +875,12 @@ of test-completion}.
 If @var{require-match} is @code{nil}, the exit commands work regardless
 of the input in the minibuffer.  If @var{require-match} is @code{t}, the
 usual minibuffer exit commands 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 already in the buffer matches an element of @var{collection}.
+an element of @var{collection}.  If @var{require-match} is
+@code{confirm-only}, the user can exit with any input, but she will
+asked for a confirmation if the input is not an element of
+@var{collection}.  Any other value of @var{require-match} behaves like
+@code{t}, except that the exit commands won't exit if it does non-null
+completion.
 
 However, empty input is always permitted, regardless of the value of
 @var{require-match}; in that case, @code{completing-read} returns the
@@ -1058,7 +1097,7 @@ except that it does not bind @key{SPC}.  This keymap is used by the
 function @code{read-file-name}.
 @end defvar
 
-@defvar minibuffer-local-must-match-filename-map
+@defvar minibuffer-local-filename-must-match-map
 This is like @code{minibuffer-local-must-match-map}
 except that it does not bind @key{SPC}.  This keymap is used by the
 function @code{read-file-name}.
@@ -1257,7 +1296,7 @@ acceptable.
 @code{read-file-name} uses
 @code{minibuffer-local-filename-completion-map} as the keymap if
 @var{existing} is @code{nil}, and uses
-@code{minibuffer-local-must-match-filename-map} if @var{existing} is
+@code{minibuffer-local-filename-must-match-map} if @var{existing} is
 non-@code{nil}.  @xref{Completion Commands}.
 
 The argument @var{directory} specifies the directory to use for
diff --git a/etc/NEWS b/etc/NEWS
index b2e73354061..48e430f902b 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1247,10 +1247,12 @@ functions `read-from-minibuffer', `read-string', `read-command',
 are available for inserting into the minibuffer by typing `M-n'.
 For empty input these functions return the first element of this list.
 
++++
 *** New function `read-regexp' uses the regexp history and some useful
 regexp defaults (string at point, last Isearch/replacement regexp/string)
 via M-n when reading a regexp in the minibuffer.
 
++++
 *** minibuffer-local-must-match-filename-map is now named
 minibuffer-local-filename-must-match-map.
 
@@ -1259,6 +1261,7 @@ Since this means the returned list is not properly nil-terminated, this
 is an incompatible change and is thus enabled by the new variable
 completion-all-completions-with-base-size.
 
++++
 *** The `require-match' argument to `completing-read' accepts a new value
 `confirm-only'.