[Emacs-diffs] trunk r116454: Some doc for read-regexp

[Glenn Morris]

------------------------------------------------------------
revno: 116454
revision-id: address@hidden
parent: address@hidden
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Sun 2014-02-16 18:12:50 -0800
message:
  Some doc for read-regexp
  
  * doc/lispref/minibuf.texi (Text from Minibuffer):
  Update read-regexp details.
  Mention read-regexp-defaults-function.
  
  * etc/NEWS: Related markup.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/minibuf.texi       
minibuf.texi-20091113204419-o5vbwnq5f7feedwu-6199
  etc/NEWS                       news-20100311060928-aoit31wvzf25yr1z-1

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-02-13 08:26:01 +0000
+++ b/doc/lispref/ChangeLog     2014-02-17 02:12:50 +0000
@@ -1,3 +1,8 @@
+2014-02-17  Glenn Morris  <address@hidden>
+
+       * minibuf.texi (Text from Minibuffer): Update read-regexp details.
+       Mention read-regexp-defaults-function.
+
 2014-02-13  Glenn Morris  <address@hidden>
 
        * debugging.texi (Debugger Commands): Tiny edits.

=== modified file 'doc/lispref/minibuf.texi'
--- a/doc/lispref/minibuf.texi  2014-02-06 01:22:38 +0000
+++ b/doc/lispref/minibuf.texi  2014-02-17 02:12:50 +0000
@@ -211,40 +211,81 @@
 @end smallexample
 @end defun
 
address@hidden read-regexp prompt &optional default history
address@hidden read-regexp prompt &optional defaults history
 This function reads a regular expression as a string from the
-minibuffer and returns it.  The argument @var{prompt} is used as in
address@hidden
-
-The optional argument @var{default} specifies a default value to
-return if the user enters null input; it should be a string, or
address@hidden, which is equivalent to an empty string.
+minibuffer and returns it.  If the minibuffer prompt string
address@hidden does not end in @samp{:} (followed by optional
+whitespace), the function adds @samp{: } to the end, preceded by the
+default return value (see below), if that is non-empty.
+
+The optional argument @var{defaults} controls the default value to
+return if the user enters null input, and should be one of: a string;
address@hidden, which is equivalent to an empty string; a list of strings;
+or a symbol.
+
+If @var{defaults} is a symbol, @code{read-regexp} consults the value
+of the variable @code{read-regexp-defaults-function} (see below), and
+if that is address@hidden uses it in preference to @var{defaults}.
+The value in this case should be either:
+
address@hidden @minus
address@hidden
address@hidden, which means to use the first element of
+the appropriate minibuffer history list (see below).
+
address@hidden
+A function of no arguments, whose return value (which should be
address@hidden, a string, or a list of strings) becomes the value of
address@hidden
address@hidden itemize
+
address@hidden now ensures that the result of processing
address@hidden is a list (i.e., if the value is @code{nil} or a
+string, it converts it to a list of one element).  To this list,
address@hidden then appends a few potentially useful candidates for
+input.  These are:
+
address@hidden @minus
address@hidden
+The word or symbol at point.
address@hidden
+The last regexp used in an incremental search.
address@hidden
+The last string used in an incremental search.
address@hidden
+The last string or pattern used in query-replace commands.
address@hidden itemize
+
+The function now has a list of regular expressions that it passes to
address@hidden to obtain the user's input.  The first
+element of the list is the default result in case of empty input.  All
+elements of the list are available to the user as the ``future
+minibuffer history list'' (@pxref{Minibuffer History, future list,,
+emacs, The GNU Emacs Manual}).
 
 The optional argument @var{history}, if address@hidden, is a symbol
 specifying a minibuffer history list to use (@pxref{Minibuffer
 History}).  If it is omitted or @code{nil}, the history list defaults
 to @code{regexp-history}.
address@hidden defun
 
address@hidden also collects a few useful candidates for input 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:
address@hidden read-regexp-defaults-function
+The function @code{read-regexp} may use the value of this variable to
+determine its list of default regular expressions.  If address@hidden,
+the value of this variable should be either:
 
 @itemize @minus
 @item
-The word or symbol at point.
address@hidden
-The last regexp used in an incremental search.
address@hidden
-The last string used in an incremental search.
address@hidden
-The last string or pattern used in query-replace commands.
+The symbol @code{regexp-history-last}.
+
address@hidden
+A function of no arguments that returns either @code{nil}, a string,
+or a list of strings.
 @end itemize
 
-This function works by calling the @code{read-from-minibuffer}
-function, after computing the list of defaults as described above.
address@hidden defun
address@hidden
+See @code{read-regexp} above for details of how these values are used.
address@hidden defvar
 
 @defvar minibuffer-allow-text-properties
 If this variable is @code{nil}, then @code{read-from-minibuffer}

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2014-02-15 22:50:45 +0000
+++ b/etc/NEWS  2014-02-17 02:12:50 +0000
@@ -1097,6 +1097,7 @@
 +++
 ** New function `get-pos-property'.
 
++++
 ** `read-regexp' now uses the new variable `read-regexp-defaults-function'
 as a function to call to provide default values.