[Emacs-diffs] trunk r116441: Some read-regexp doc

[Glenn Morris]

------------------------------------------------------------
revno: 116441
revision-id: address@hidden
parent: address@hidden
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Thu 2014-02-13 23:36:42 -0800
message:
  Some read-regexp doc
  
  * lisp/replace.el (map-query-replace-regexp)
  (read-regexp-defaults-function, read-regexp): Doc fixes.
  
  * etc/NEWS: Related edits.
modified:
  etc/NEWS                       news-20100311060928-aoit31wvzf25yr1z-1
  lisp/ChangeLog                 changelog-20091113204419-o5vbwnq5f7feedwu-1432
  lisp/replace.el                replace.el-20091113204419-o5vbwnq5f7feedwu-119

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2014-02-13 08:26:45 +0000
+++ b/etc/NEWS  2014-02-14 07:36:42 +0000
@@ -251,12 +251,6 @@
 ** `emacs-bzr-version' has been renamed to `emacs-repository-version',
 and works for git too, if you fetch the repository notes.
 
-** `read-regexp-defaults-function' defines a function to provide default
-values for reading regexps by commands like `rgrep', `lgrep' `occur',
-`highlight-regexp', etc.  You can customize this to specify a function
-that provides a default value from the regexp last history element,
-or from the symbol found at point.
-
 +++
 ** New option `load-prefer-newer' affects how the `load' function chooses
 the file to load.  If this is non-nil, then when both .el and .elc
@@ -1090,6 +1084,9 @@
 +++
 ** 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.
+
 ** Completion changes
 
 *** The separator for `completing-read-multiple' can now be a regexp.

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2014-02-14 06:59:24 +0000
+++ b/lisp/ChangeLog    2014-02-14 07:36:42 +0000
@@ -1,5 +1,8 @@
 2014-02-14  Glenn Morris  <address@hidden>
 
+       * replace.el (map-query-replace-regexp)
+       (read-regexp-defaults-function, read-regexp): Doc fixes.
+
        * dired.el (dired-read-regexp):
        * faces.el (list-faces-display):
        * misearch.el (multi-isearch-read-matching-buffers)

=== modified file 'lisp/replace.el'
--- a/lisp/replace.el   2014-02-10 01:34:22 +0000
+++ b/lisp/replace.el   2014-02-14 07:36:42 +0000
@@ -450,6 +450,7 @@
 
 Non-interactively, TO-STRINGS may be a list of replacement strings.
 
+Interactively, reads the regexp using `read-regexp'.
 Use \\<minibuffer-local-map>\\[next-history-element] \
 to pull the last incremental search regexp to the minibuffer
 that reads REGEXP.
@@ -627,17 +628,16 @@
   "History of regexp for occur's collect operation")
 
 (defcustom read-regexp-defaults-function nil
-  "Function that provides default regexp(s) for regexp reading commands.
-This function should take no arguments and return one of nil, a
-regexp or a list of regexps.  The return value of this function is used
-as DEFAULTS param of `read-regexp'.  This function is called only during
-interactive use.
-
-If you need different defaults for different commands,
-use `this-command' to identify the command under execution.
-
-You can customize `read-regexp-defaults-function' to the value
-`find-tag-default-as-regexp' to highlight a symbol at point."
+  "Function that provides default regexp(s) for `read-regexp'.
+This function should take no arguments and return one of: nil, a
+regexp, or a list of regexps.  Interactively, `read-regexp' uses
+the return value of this function for its DEFAULT argument.
+
+As an example, set this variable to `find-tag-default-as-regexp'
+to default to the symbol at point.
+
+To provide different default regexps for different commands,
+the function that you set this to can check `this-command'."
   :type '(choice
          (const :tag "No default regexp reading function" nil)
          (const :tag "Latest regexp history" regexp-history-last)
@@ -647,7 +647,7 @@
                         find-tag-default-as-regexp)
          (function-item :tag "Tag at point as symbol regexp"
                         find-tag-default-as-symbol-regexp)
-         (function :tag "Function to provide default for read-regexp"))
+         (function :tag "Your choice of function"))
   :group 'matching
   :version "24.4")
 
@@ -666,21 +666,35 @@
 
 (defun read-regexp (prompt &optional defaults history)
   "Read and return a regular expression as a string.
-When PROMPT doesn't end with a colon and space, it adds a final \": \".
-If the first element of DEFAULTS is non-nil, it's added to the prompt.
-
-Optional arg DEFAULTS has the form (DEFAULT . SUGGESTIONS)
-or simply DEFAULT where DEFAULT, if non-nil, should be a string that
-is returned as the default value when the user enters empty input.
-SUGGESTIONS is a list of strings that can be inserted into
-the minibuffer using \\<minibuffer-local-map>\\[next-history-element].  \
-The values supplied in SUGGESTIONS
-are prepended to the list of standard suggestions returned by
-`read-regexp-suggestions'.  The default values can be customized
-by `read-regexp-defaults-function'.
-
-Optional arg HISTORY is a symbol to use for the history list.
-If HISTORY is nil, `regexp-history' is used."
+Prompt with the string PROMPT.  If PROMPT ends in \":\" (followed by
+optional whitespace), use it as-is.  Otherwise, add \": \" to the end,
+possible preceded by the default result (see below).
+
+The optional argument DEFAULTS can be either: nil, a string, a list
+of strings, or a symbol.  We use DEFAULTS to construct the default
+return value in case of empty input.
+
+If DEFAULTS is a string, we use it as-is.
+
+If DEFAULTS is a list of strings, the first element is the
+default return value, but all the elements are accessible
+using the history command \\<minibuffer-local-map>\\[next-history-element].
+
+If DEFAULTS is a non-nil symbol, then if `read-regexp-defaults-function'
+is non-nil, we use that in place of DEFAULTS in the following:
+  If DEFAULTS is the symbol `regexp-history-last', we use the first
+  element of HISTORY (if specified) or `regexp-history'.
+  If DEFAULTS is a function, we call it with no arguments and use
+  what it returns, which should be either nil, a string, or a list of strings.
+
+We append the standard values from `read-regexp-suggestions' to DEFAULTS
+before using it.
+
+If the first element of DEFAULTS is non-nil (and if PROMPT does not end
+in \":\", followed by optional whitespace), we add it to the prompt.
+
+The optional argument HISTORY is a symbol to use for the history list.
+If nil, uses `regexp-history'."
   (let* ((defaults
           (if (and defaults (symbolp defaults))
               (cond