(Searching and Matching): Move node.

Rearrange contents and add overall explanation.
(Searching and Case): Move node.
(Searching and Matching): Update menu.

1 files changed, 196 insertions, 262 deletions

diff --git a/lispref/searching.texi b/lispref/searching.texi
index e702469a14b..84de54984ae 100644
--- a/lispref/searching.texi
+++ b/lispref/searching.texi
@@ -16,13 +16,13 @@ portions of it.
 
 @menu
 * String Search::         Search for an exact match.
+* Searching and Case::    Case-independent or case-significant searching.
 * Regular Expressions::   Describing classes of strings.
 * Regexp Search::         Searching for a match for a regexp.
 * POSIX Regexps::         Searching POSIX-style for the longest match.
-* Search and Replace::    Internals of @code{query-replace}.
 * Match Data::            Finding out which part of the text matched,
                             after a string or regexp search.
-* Searching and Case::    Case-independent or case-significant searching.
+* Search and Replace::    Commands that loop, searching and replacing.
 * Standard Regexps::      Useful regexps for finding sentences, pages,...
 @end menu
 
@@ -157,6 +157,53 @@ except that it searches backward and normally leaves point at the
 beginning of the match.
 @end deffn
 
+@node Searching and Case
+@section Searching and Case
+@cindex searching and case
+
+  By default, searches in Emacs ignore the case of the text they are
+searching through; if you specify searching for @samp{FOO}, then
+@samp{Foo} or @samp{foo} is also considered a match.  This applies to
+regular expressions, too; thus, @samp{[aB]} would match @samp{a} or
+@samp{A} or @samp{b} or @samp{B}.
+
+  If you do not want this feature, set the variable
+@code{case-fold-search} to @code{nil}.  Then all letters must match
+exactly, including case.  This is a buffer-local variable; altering the
+variable affects only the current buffer.  (@xref{Intro to
+Buffer-Local}.)  Alternatively, you may change the value of
+@code{default-case-fold-search}, which is the default value of
+@code{case-fold-search} for buffers that do not override it.
+
+  Note that the user-level incremental search feature handles case
+distinctions differently.  When given a lower case letter, it looks for
+a match of either case, but when given an upper case letter, it looks
+for an upper case letter only.  But this has nothing to do with the
+searching functions used in Lisp code.
+
+@defopt case-replace
+This variable determines whether the higher level replacement
+functions should preserve case.  If the variable is @code{nil}, that
+means to use the replacement text verbatim.  A non-@code{nil} value
+means to convert the case of the replacement text according to the
+text being replaced.
+
+This variable is used by passing it as an argument to the function
+@code{replace-match}.  @xref{Replacing Match}.
+@end defopt
+
+@defopt case-fold-search
+This buffer-local variable determines whether searches should ignore
+case.  If the variable is @code{nil} they do not ignore case; otherwise
+they do ignore case.
+@end defopt
+
+@defvar default-case-fold-search
+The value of this variable is the default value for
+@code{case-fold-search} in buffers that do not override it.  This is the
+same as @code{(default-value 'case-fold-search)}.
+@end defvar
+
 @node Regular Expressions
 @section Regular Expressions
 @cindex regular expression
@@ -1070,231 +1117,15 @@ backtracking specified by the POSIX standard for regular expression
 matching.
 @end defun
 
-@ignore
-@deffn Command delete-matching-lines regexp
-This function is identical to @code{delete-non-matching-lines}, save
-that it deletes what @code{delete-non-matching-lines} keeps.
-
-In the example below, point is located on the first line of text.
-
-@example
-@group
----------- Buffer: foo ----------
-We hold these truths
-to be self-evident,
-that all men are created
-equal, and that they are
----------- Buffer: foo ----------
-@end group
-
-@group
-(delete-matching-lines "the")
-     @result{} nil
-
----------- Buffer: foo ----------
-to be self-evident,
-that all men are created
----------- Buffer: foo ----------
-@end group
-@end example
-@end deffn
-
-@deffn Command flush-lines regexp
-This function is the same as @code{delete-matching-lines}.
-@end deffn
-
-@defun delete-non-matching-lines regexp
-This function deletes all lines following point which don't
-contain a match for the regular expression @var{regexp}.
-@end defun
-
-@deffn Command keep-lines regexp
-This function is the same as @code{delete-non-matching-lines}.
-@end deffn
-
-@deffn Command how-many regexp
-This function counts the number of matches for @var{regexp} there are in
-the current buffer following point.  It prints this number in
-the echo area, returning the string printed.
-@end deffn
-
-@deffn Command count-matches regexp
-This function is a synonym of @code{how-many}.
-@end deffn
-
-@deffn Command list-matching-lines regexp &optional nlines
-This function is a synonym of @code{occur}.
-Show all lines following point containing a match for @var{regexp}.
-Display each line with @var{nlines} lines before and after,
-or @code{-}@var{nlines} before if @var{nlines} is negative.
-@var{nlines} defaults to @code{list-matching-lines-default-context-lines}.
-Interactively it is the prefix arg.
-
-The lines are shown in a buffer named @samp{*Occur*}.
-It serves as a menu to find any of the occurrences in this buffer.
-@kbd{C-h m} (@code{describe-mode}) in that buffer gives help.
-@end deffn
-
-@defopt list-matching-lines-default-context-lines
-Default value is 0.
-Default number of context lines to include around a @code{list-matching-lines}
-match.  A negative number means to include that many lines before the match.
-A positive number means to include that many lines both before and after.
-@end defopt
-@end ignore
-
-@node Search and Replace
-@section Search and Replace
-@cindex replacement
-
-@defun replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start
-This function copies @var{string} and searches it for matches for
-@var{regexp}, and replaces them with @var{rep}.  It returns the
-modified copy.  If @var{start} is non-@code{nil}, the search for
-matches starts at that index in @var{string}, so matches starting
-before that index are not changed.
-
-This function uses @code{replace-match} to do the replacement, and it
-passes the optional arguments @var{fixedcase}, @var{literal} and
-@var{subexp} along to @code{replace-match}.
-
-Instead of a string, @var{rep} can be a function.  In that case,
-@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
-of matching @var{regexp} against a substring of @var{string}.
-@end defun
-
-@defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end
-This function is the guts of @code{query-replace} and related
-commands.  It searches for occurrences of @var{from-string} in the
-text between positions @var{start} and @var{end} and replaces some or
-all of them.  If @var{start} is @code{nil} (or omitted), point is used
-instead, and the end of the buffer's accessible portion is used for
-@var{end}.
-
-If @var{query-flag} is @code{nil}, it replaces all
-occurrences; otherwise, it asks the user what to do about each one.
-
-If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is
-considered a regular expression; otherwise, it must match literally.  If
-@var{delimited-flag} is non-@code{nil}, then only replacements
-surrounded by word boundaries are considered.
-
-The argument @var{replacements} specifies what to replace occurrences
-with.  If it is a string, that string is used.  It can also be a list of
-strings, to be used in cyclic order.
-
-If @var{replacements} is a cons cell, @code{(@var{function}
-. @var{data})}, this means to call @var{function} after each match to
-get the replacement text.  This function is called with two arguments:
-@var{data}, and the number of replacements already made.
-
-If @var{repeat-count} is non-@code{nil}, it should be an integer.  Then
-it specifies how many times to use each of the strings in the
-@var{replacements} list before advancing cyclically to the next one.
-
-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.
-
-Normally, the keymap @code{query-replace-map} defines the possible user
-responses for queries.  The argument @var{map}, if non-@code{nil}, is a
-keymap to use instead of @code{query-replace-map}.
-
-@strong{Usage note:} Do not use this function in your own programs
-unless you want to do something very similar to what
-@code{query-replace} does, including setting the mark and possibly
-querying the user.  For most purposes a simple loop like, for
-instance:
-
-@example
-(while (re-search-forward "foo[ \t]+bar" nil t)
-  (replace-match "foobar"))
-@end example
-
-@noindent
-is preferable.  It runs faster and avoids side effects, such as
-setting the mark.  @xref{Replacing Match,, Replacing the Text that
-Matched}, for a description of @code{replace-match}.
-@end defun
-
-@defvar query-replace-map
-This variable holds a special keymap that defines the valid user
-responses for @code{query-replace} and related functions, as well as
-@code{y-or-n-p} and @code{map-y-or-n-p}.  It is unusual in two ways:
-
-@itemize @bullet
-@item
-The ``key bindings'' are not commands, just symbols that are meaningful
-to the functions that use this map.
-
-@item
-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.''
-@end itemize
-@end defvar
-
-Here are the meaningful ``bindings'' for @code{query-replace-map}.
-Several of them are meaningful only for @code{query-replace} and
-friends.
-
-@table @code
-@item act
-Do take the action being considered---in other words, ``yes.''
-
-@item skip
-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.''
-
-@item act-and-exit
-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
-to the next question.
-
-@item automatic
-Answer this question and all subsequent questions in the series with
-``yes,'' without further user interaction.
-
-@item backup
-Move back to the previous place that a question was asked about.
-
-@item edit
-Enter a recursive edit to deal with this question---instead of any
-other action that would normally be taken.
-
-@item delete-and-edit
-Delete the text being considered, then enter a recursive edit to replace
-it.
-
-@item recenter
-Redisplay and center the window, then ask the same question again.
-
-@item quit
-Perform a quit right away.  Only @code{y-or-n-p} and related functions
-use this answer.
-
-@item help
-Display some help, then ask again.
-@end table
-
 @node Match Data
 @section The Match Data
 @cindex match data
 
   Emacs keeps track of the start and end positions of the segments of
-text found during a search.  This means, for example, that you can
-search for a complex pattern, such as a date in an Rmail message, and
-then extract parts of the match under control of the pattern.
+text found during a search; this is called the @dfn{match data}.
+Thanks to the match data, you can search for a complex pattern, such
+as a date in a mail message, and then extract parts of the match under
+control of the pattern.
 
   Because the match data normally describe the most recent search only,
 you must be careful not to do another search inadvertently between the
@@ -1313,8 +1144,8 @@ match data around it, to prevent it from being overwritten.
 @node Replacing Match
 @subsection Replacing the Text that Matched
 
-  This function replaces the text matched by the last search with
-@var{replacement}.
+  This function replaces all or part of the text matched by the last
+search.  It works by means of the match data.
 
 @cindex case in replacements
 @defun replace-match replacement &optional fixedcase literal string subexp
@@ -1661,53 +1492,156 @@ associated with it still exists.
 @end smallexample
 @end ignore
 
-@node Searching and Case
-@section Searching and Case
-@cindex searching and case
+@node Search and Replace
+@section Search and Replace
+@cindex replacement
 
-  By default, searches in Emacs ignore the case of the text they are
-searching through; if you specify searching for @samp{FOO}, then
-@samp{Foo} or @samp{foo} is also considered a match.  This applies to
-regular expressions, too; thus, @samp{[aB]} would match @samp{a} or
-@samp{A} or @samp{b} or @samp{B}.
+  If you want to find all matches for a regexp in part of the buffer,
+and replace them, the best way is to write an explicit loop using
+@code{re-search-forward} and @code{replace-match}, like this:
 
-  If you do not want this feature, set the variable
-@code{case-fold-search} to @code{nil}.  Then all letters must match
-exactly, including case.  This is a buffer-local variable; altering the
-variable affects only the current buffer.  (@xref{Intro to
-Buffer-Local}.)  Alternatively, you may change the value of
-@code{default-case-fold-search}, which is the default value of
-@code{case-fold-search} for buffers that do not override it.
+@example
+(while (re-search-forward "foo[ \t]+bar" nil t)
+  (replace-match "foobar"))
+@end example
 
-  Note that the user-level incremental search feature handles case
-distinctions differently.  When given a lower case letter, it looks for
-a match of either case, but when given an upper case letter, it looks
-for an upper case letter only.  But this has nothing to do with the
-searching functions used in Lisp code.
+@noindent
+@xref{Replacing Match,, Replacing the Text that Matched}, for a
+description of @code{replace-match}.
 
-@defopt case-replace
-This variable determines whether the higher level replacement
-functions should preserve case.  If the variable is @code{nil}, that
-means to use the replacement text verbatim.  A non-@code{nil} value
-means to convert the case of the replacement text according to the
-text being replaced.
+  However, replacing matches in a string is more complex, especially
+if you want to do it efficiently.  So Emacs provides a function to do
+this.
 
-This variable is used by passing it as an argument to the function
-@code{replace-match}.  @xref{Replacing Match}.
-@end defopt
+@defun replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start
+This function copies @var{string} and searches it for matches for
+@var{regexp}, and replaces them with @var{rep}.  It returns the
+modified copy.  If @var{start} is non-@code{nil}, the search for
+matches starts at that index in @var{string}, so matches starting
+before that index are not changed.
 
-@defopt case-fold-search
-This buffer-local variable determines whether searches should ignore
-case.  If the variable is @code{nil} they do not ignore case; otherwise
-they do ignore case.
-@end defopt
+This function uses @code{replace-match} to do the replacement, and it
+passes the optional arguments @var{fixedcase}, @var{literal} and
+@var{subexp} along to @code{replace-match}.
 
-@defvar default-case-fold-search
-The value of this variable is the default value for
-@code{case-fold-search} in buffers that do not override it.  This is the
-same as @code{(default-value 'case-fold-search)}.
+Instead of a string, @var{rep} can be a function.  In that case,
+@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
+of matching @var{regexp} against a substring of @var{string}.
+@end defun
+
+  If you want to write a command along the lines of @code{query-replace},
+you can use @code{perform-replace} to do the work.
+
+@defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end
+This function is the guts of @code{query-replace} and related
+commands.  It searches for occurrences of @var{from-string} in the
+text between positions @var{start} and @var{end} and replaces some or
+all of them.  If @var{start} is @code{nil} (or omitted), point is used
+instead, and the end of the buffer's accessible portion is used for
+@var{end}.
+
+If @var{query-flag} is @code{nil}, it replaces all
+occurrences; otherwise, it asks the user what to do about each one.
+
+If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is
+considered a regular expression; otherwise, it must match literally.  If
+@var{delimited-flag} is non-@code{nil}, then only replacements
+surrounded by word boundaries are considered.
+
+The argument @var{replacements} specifies what to replace occurrences
+with.  If it is a string, that string is used.  It can also be a list of
+strings, to be used in cyclic order.
+
+If @var{replacements} is a cons cell, @code{(@var{function}
+. @var{data})}, this means to call @var{function} after each match to
+get the replacement text.  This function is called with two arguments:
+@var{data}, and the number of replacements already made.
+
+If @var{repeat-count} is non-@code{nil}, it should be an integer.  Then
+it specifies how many times to use each of the strings in the
+@var{replacements} list before advancing cyclically to the next one.
+
+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.
+
+Normally, the keymap @code{query-replace-map} defines the possible
+user responses for queries.  The argument @var{map}, if
+non-@code{nil}, specifies a keymap to use instead of
+@code{query-replace-map}.
+@end defun
+
+@defvar query-replace-map
+This variable holds a special keymap that defines the valid user
+responses for @code{perform-replace} and the commands that use it, as
+well as @code{y-or-n-p} and @code{map-y-or-n-p}.  This map is unusual
+in two ways:
+
+@itemize @bullet
+@item
+The ``key bindings'' are not commands, just symbols that are meaningful
+to the functions that use this map.
+
+@item
+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.''
+@end itemize
 @end defvar
 
+Here are the meaningful ``bindings'' for @code{query-replace-map}.
+Several of them are meaningful only for @code{query-replace} and
+friends.
+
+@table @code
+@item act
+Do take the action being considered---in other words, ``yes.''
+
+@item skip
+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.''
+
+@item act-and-exit
+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
+to the next question.
+
+@item automatic
+Answer this question and all subsequent questions in the series with
+``yes,'' without further user interaction.
+
+@item backup
+Move back to the previous place that a question was asked about.
+
+@item edit
+Enter a recursive edit to deal with this question---instead of any
+other action that would normally be taken.
+
+@item delete-and-edit
+Delete the text being considered, then enter a recursive edit to replace
+it.
+
+@item recenter
+Redisplay and center the window, then ask the same question again.
+
+@item quit
+Perform a quit right away.  Only @code{y-or-n-p} and related functions
+use this answer.
+
+@item help
+Display some help, then ask again.
+@end table
+
 @node Standard Regexps
 @section Standard Regular Expressions Used in Editing
 @cindex regexps used standardly in editing