[Emacs-diffs] /srv/bzr/emacs/trunk r107696: Doc and lispref updates related to searching

[Glenn Morris]

------------------------------------------------------------
revno: 107696
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Wed 2012-03-28 12:30:12 -0700
message:
  Doc and lispref updates related to searching
  
  * doc/lispref/searching.texi (Regexp Functions, Regexp Search):
  (Simple Match Data, Saving Match Data, Standard Regexps): Copyedits.
  (Regexp Functions): Mention regexp-opt is not guaranteed.
  Mention regexp-opt-charset.
  (Regexp Search): Recommend against looking-back.
  (Search and Replace): Use Texinfo recommended quote convention.
  Add more query-replace-map items.  List multi-query-replace-map items.
  
  * lisp/replace.el (query-replace-map): Doc fix.
  
  * admin/FOR-RELEASE: Related markup.
modified:
  admin/FOR-RELEASE
  doc/lispref/ChangeLog
  doc/lispref/searching.texi
  lisp/ChangeLog
  lisp/replace.el

=== modified file 'admin/FOR-RELEASE'
--- a/admin/FOR-RELEASE 2012-03-18 15:02:12 +0000
+++ b/admin/FOR-RELEASE 2012-03-28 19:30:12 +0000
@@ -220,7 +220,7 @@
 package.texi      rgm
 positions.texi    cyd
 processes.texi
-searching.texi    
+searching.texi    rgm
 sequences.texi    cyd
 streams.texi      cyd
 strings.texi      cyd

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-03-28 07:57:42 +0000
+++ b/doc/lispref/ChangeLog     2012-03-28 19:30:12 +0000
@@ -1,9 +1,15 @@
 2012-03-28  Glenn Morris  <address@hidden>
 
        * searching.texi (Regular Expressions, Regexp Special):
-       (Regexp Backslash, Regexp Example): Copyedits.
+       (Regexp Backslash, Regexp Example, Regexp Functions, Regexp Search):
+       (Simple Match Data, Saving Match Data, Standard Regexps): Copyedits.
        (Regexp Special): Mention collation.
        Clarify char classes with an example.
+       (Regexp Functions): Mention regexp-opt is not guaranteed.
+       Mention regexp-opt-charset.
+       (Regexp Search): Recommend against looking-back.
+       (Search and Replace): Use Texinfo recommended quote convention.
+       Add more query-replace-map items.  List multi-query-replace-map items.
 
 2012-03-27  Martin Rudalics  <address@hidden>
 

=== modified file 'doc/lispref/searching.texi'
--- a/doc/lispref/searching.texi        2012-03-28 08:02:53 +0000
+++ b/doc/lispref/searching.texi        2012-03-28 19:30:12 +0000
@@ -902,7 +902,7 @@
 @var{string}.  Using this regular expression in @code{looking-at} will
 succeed only if the next characters in the buffer are @var{string};
 using it in a search function will succeed if the text being searched
-contains @var{string}.
+contains @var{string}.  @xref{Regexp Search}.
 
 This allows you to request an exact string match or search when calling
 a function that wants a regular expression.
@@ -931,7 +931,11 @@
 This function returns an efficient regular expression that will match
 any of the strings in the list @var{strings}.  This is useful when you
 need to make matching or searching as fast as possible---for example,
-for Font Lock mode.
+for Font Lock address@hidden that @code{regexp-opt} does not
+guarantee that its result is absolutely the most efficient form
+possible.  A hand-tuned regular expression can sometimes be slightly
+more efficient, but is almost never worth the effort.}.
address@hidden See eg http://debbugs.gnu.org/2816
 
 If the optional argument @var{paren} is address@hidden, then the
 returned regular expression is always enclosed by at least one
@@ -947,7 +951,7 @@
 (but not as efficient):
 
 @example
-(defun regexp-opt (strings paren)
+(defun regexp-opt (strings &optional paren)
   (let ((open-paren (if paren "\\(" ""))
         (close-paren (if paren "\\)" "")))
     (concat open-paren
@@ -962,6 +966,19 @@
 shy groups (@pxref{Regexp Backslash}).
 @end defun
 
address@hidden Supposedly an internal regexp-opt function, but table.el uses it 
at least.
address@hidden regexp-opt-charset chars
+This function returns a regular expression matching a character in the
+list of characters @var{chars}.
+
address@hidden
+(regexp-opt-charset '(?a ?b ?c ?d ?e))
+     @result{} "[a-e]"
address@hidden example
address@hidden defun
+
address@hidden Internal functions: regexp-opt-group
+
 @node Regexp Search
 @section Regular Expression Searching
 @cindex regular expression searching
@@ -1104,8 +1121,7 @@
 succeed only starting with the first character following point.  The
 result is @code{t} if so, @code{nil} otherwise.
 
-This function does not move point, but it updates the match data, which
-you can access using @code{match-beginning} and @code{match-end}.
+This function does not move point, but it does update the match data.
 @xref{Match Data}.  If you need to test for a match without modifying
 the match data, use @code{looking-at-p}, described below.
 
@@ -1126,8 +1142,8 @@
 @end defun
 
 @defun looking-back regexp &optional limit greedy
-This function returns @code{t} if @var{regexp} matches text before
-point, ending at point, and @code{nil} otherwise.
+This function returns @code{t} if @var{regexp} matches the text
+immediately before point (i.e., ending at point), and @code{nil} otherwise.
 
 Because regular expression matching works only going forward, this is
 implemented by searching backwards from point for a match that ends at
@@ -1155,6 +1171,11 @@
      @result{} nil
 @end group
 @end example
+
address@hidden http://debbugs.gnu.org/5689
+As a general recommendation, try to avoid using @code{looking-back}
+wherever possible, since it is slow.  For this reason, there are no
+plans to add a @code{looking-back-p} function.
 @end defun
 
 @defun looking-at-p regexp
@@ -1178,6 +1199,7 @@
 @node POSIX Regexps
 @section POSIX Regular Expression Searching
 
address@hidden backtracking and POSIX regular expressions
   The usual regular expression functions do backtracking when necessary
 to handle the @samp{\|} and repetition constructs, but they continue
 this only until they find @emph{some} match.  Then they succeed and
@@ -1350,12 +1372,16 @@
 query the match data immediately after searching, before calling any
 other function that might perform another search.  Alternatively, you
 may save and restore the match data (@pxref{Saving Match Data}) around
-the call to functions that could perform another search.
+the call to functions that could perform another search.  Or use the
+functions that explicitly do not modify the match data;
+e.g. @code{string-match-p}.
 
address@hidden This is an old comment and presumably there is no prospect of 
this
address@hidden changing now.  But still the advice stands.
   A search which fails may or may not alter the match data.  In the
-past, a failing search did not do this, but we may change it in the
-future.  So don't try to rely on the value of the match data after
-a failing search.
+current implementation, it does not, but we may change it in the
+future.  Don't try to rely on the value of the match data after a
+failing search.
 
 @defun match-string count &optional in-string
 This function returns, as a string, the text matched in the last search
@@ -1369,7 +1395,7 @@
 you should omit @var{in-string} or pass @code{nil} for it; but you
 should make sure that the current buffer when you call
 @code{match-string} is the one in which you did the searching or
-matching.
+matching.  Failure to follow this advice will lead to incorrect results.
 
 The value is @code{nil} if @var{count} is out of range, or for a
 subexpression inside a @samp{\|} alternative that wasn't used or a
@@ -1382,7 +1408,7 @@
 @end defun
 
 @defun match-beginning count
-This function returns the position of the start of text matched by the
+This function returns the position of the start of the text matched by the
 last regular expression searched for, or a subexpression of it.
 
 If @var{count} is zero, then the value is the position of the start of
@@ -1475,7 +1501,7 @@
 
 @defun match-data &optional integers reuse reseat
 This function returns a list of positions (markers or integers) that
-record all the information on what text the last search matched.
+record all the information on the text that the last search matched.
 Element zero is the position of the beginning of the match for the
 whole expression; element one is the position of the end of the match
 for the expression.  The next two elements are the positions of the
@@ -1544,6 +1570,7 @@
 If @var{reseat} is address@hidden, all markers on the @var{match-list} list
 are reseated to point to nowhere.
 
address@hidden TODO Make it properly obsolete.
 @findex store-match-data
 @code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
 @end defun
@@ -1551,7 +1578,7 @@
 @node Saving Match Data
 @subsection Saving and Restoring the Match Data
 
-  When you call a function that may do a search, you may need to save
+  When you call a function that may search, you may need to save
 and restore the match data around that call, if you want to preserve the
 match data from an earlier search for later use.  Here is an example
 that shows the problem that arises if you fail to save the match data:
@@ -1560,8 +1587,7 @@
 @group
 (re-search-forward "The \\(cat \\)")
      @result{} 48
-(foo)                   ; @r{Perhaps @code{foo} does}
-                        ;   @r{more searching.}
+(foo)                   ; @address@hidden does more searching.}
 (match-end 0)
      @result{} 61              ; @r{Unexpected result---not 48!}
 @end group
@@ -1654,7 +1680,7 @@
 @code{replace-regexp-in-string} calls @var{rep} for each match,
 passing the text of the match as its sole argument.  It collects the
 value @var{rep} returns and passes that to @code{replace-match} as the
-replacement string.  The match-data at this point are the result
+replacement string.  The match data at this point are the result
 of matching @var{regexp} against a substring of @var{string}.
 @end defun
 
@@ -1692,7 +1718,7 @@
 
 If @var{from-string} contains upper-case letters, then
 @code{perform-replace} binds @code{case-fold-search} to @code{nil}, and
-it uses the @code{replacements} without altering the case of them.
+it uses the @var{replacements} without altering their case.
 
 Normally, the keymap @code{query-replace-map} defines the possible
 user responses for queries.  The argument @var{map}, if
@@ -1722,7 +1748,7 @@
 Prefix keys are not supported; each key binding must be for a
 single-event key sequence.  This is because the functions don't use
 @code{read-key-sequence} to get the input; instead, they read a single
-event and look it up ``by hand.''
+event and look it up ``by hand''.
 @end itemize
 @end defvar
 
@@ -1732,26 +1758,30 @@
 
 @table @code
 @item act
-Do take the action being considered---in other words, ``yes.''
+Do take the action being considered---in other words, ``yes''.
 
 @item skip
-Do not take action for this question---in other words, ``no.''
+Do not take action for this question---in other words, ``no''.
 
 @item exit
-Answer this question ``no,'' and give up on the entire series of
-questions, assuming that the answers will be ``no.''
+Answer this question ``no'', and give up on the entire series of
+questions, assuming that the answers will be ``no''.
+
address@hidden exit-prefix
+Like @code{exit}, but add the key that was pressed to
address@hidden
 
 @item act-and-exit
-Answer this question ``yes,'' and give up on the entire series of
-questions, assuming that subsequent answers will be ``no.''
+Answer this question ``yes'', and give up on the entire series of
+questions, assuming that subsequent answers will be ``no''.
 
 @item act-and-show
-Answer this question ``yes,'' but show the results---don't advance yet
+Answer this question ``yes'', but show the results---don't advance yet
 to the next question.
 
 @item automatic
 Answer this question and all subsequent questions in the series with
-``yes,'' without further user interaction.
+``yes'', without further user interaction.
 
 @item backup
 Move back to the previous place that a question was asked about.
@@ -1760,6 +1790,9 @@
 Enter a recursive edit to deal with this question---instead of any
 other action that would normally be taken.
 
address@hidden edit-replacement
+Edit the replacement for this question in the minibuffer.
+
 @item delete-and-edit
 Delete the text being considered, then enter a recursive edit to replace
 it.
@@ -1778,7 +1811,18 @@
 @defvar multi-query-replace-map
 This variable holds a keymap that extends @code{query-replace-map} by
 providing additional keybindings that are useful in multi-buffer
-replacements.
+replacements.  The additional ``bindings'' are:
+
address@hidden @code
address@hidden automatic-all
+Answer this question and all subsequent questions in the series with
+``yes'', without further user interaction, for all remaining buffers.
+
address@hidden exit-current
+Answer this question ``no'', and give up on the entire series of
+questions for the current buffer.  Continue to the next buffer in the
+sequence.
address@hidden table
 @end defvar
 
 @defvar replace-search-function
@@ -1841,8 +1885,8 @@
 the end of a sentence, including the whitespace following the
 sentence.  (All paragraph boundaries also end sentences, regardless.)
 
-If the value is @code{nil}, the default, then the function
address@hidden has to construct the regexp.  That is why you
+If the value is @code{nil}, as it is by default, then the function
address@hidden constructs the regexp.  That is why you
 should always call the function @code{sentence-end} to obtain the
 regexp to be used to recognize the end of a sentence.
 @end defopt
@@ -1852,6 +1896,6 @@
 if address@hidden  Otherwise it returns a default value based on the
 values of the variables @code{sentence-end-double-space}
 (@pxref{Definition of sentence-end-double-space}),
address@hidden and
address@hidden, and
 @code{sentence-end-without-space}.
 @end defun

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-03-28 10:12:02 +0000
+++ b/lisp/ChangeLog    2012-03-28 19:30:12 +0000
@@ -1,3 +1,7 @@
+2012-03-28  Glenn Morris  <address@hidden>
+
+       * replace.el (query-replace-map): Doc fix.
+
 2012-03-28  Andreas Schwab  <address@hidden>
 
        * vc/vc-git.el (vc-git-state): Don't try to match all of the diff

=== modified file 'lisp/replace.el'
--- a/lisp/replace.el   2012-03-11 10:27:53 +0000
+++ b/lisp/replace.el   2012-03-28 19:30:12 +0000
@@ -1594,8 +1594,8 @@
   "Keymap that defines the responses to questions in `query-replace'.
 The \"bindings\" in this map are not commands; they are answers.
 The valid answers include `act', `skip', `act-and-show',
-`exit', `act-and-exit', `edit', `delete-and-edit', `recenter',
-`automatic', `backup', `exit-prefix', and `help'.")
+`exit', `act-and-exit', `edit', `edit-replacement', `delete-and-edit',
+`recenter', `automatic', `backup', `exit-prefix', `quit', and `help'.")
 
 (defvar multi-query-replace-map
   (let ((map (make-sparse-keymap)))