[Emacs-diffs] Changes to emacs/man/search.texi [gnus-5_10-branch]

[Miles Bader]

Index: emacs/man/search.texi
diff -c /dev/null emacs/man/search.texi:1.50.2.1
*** /dev/null   Sat Sep  4 12:03:08 2004
--- emacs/man/search.texi       Sat Sep  4 12:01:15 2004
***************
*** 0 ****
--- 1,1326 ----
+ @c This is part of the Emacs manual.
+ @c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000, 2001
+ @c   Free Software Foundation, Inc.
+ @c See file emacs.texi for copying conditions.
+ @node Search, Fixit, Display, Top
+ @chapter Searching and Replacement
+ @cindex searching
+ @cindex finding strings within text
+ 
+   Like other editors, Emacs has commands for searching for occurrences of
+ a string.  The principal search command is unusual in that it is
+ @dfn{incremental}; it begins to search before you have finished typing the
+ search string.  There are also nonincremental search commands more like
+ those of other editors.
+ 
+   Besides the usual @code{replace-string} command that finds all
+ occurrences of one string and replaces them with another, Emacs has a
+ more flexible replacement command called @code{query-replace}, which
+ asks interactively which occurrences to replace.
+ 
+ @menu
+ * Incremental Search::                Search happens as you type the string.
+ * Nonincremental Search::     Specify entire string and then search.
+ * Word Search::                       Search for sequence of words.
+ * Regexp Search::             Search for match for a regexp.
+ * Regexps::                   Syntax of regular expressions.
+ * Search Case::                       To ignore case while searching, or not.
+ * Configuring Scrolling::     Scrolling within incremental search.
+ * Replace::                   Search, and replace some or all matches.
+ * Other Repeating Search::    Operating on all matches for some regexp.
+ @end menu
+ 
+ @node Incremental Search, Nonincremental Search, Search, Search
+ @section Incremental Search
+ 
+ @cindex incremental search
+   An incremental search begins searching as soon as you type the first
+ character of the search string.  As you type in the search string, Emacs
+ shows you where the string (as you have typed it so far) would be
+ found.  When you have typed enough characters to identify the place you
+ want, you can stop.  Depending on what you plan to do next, you may or
+ may not need to terminate the search explicitly with @key{RET}.
+ 
+ @c WideCommands
+ @table @kbd
+ @item C-s
+ Incremental search forward (@code{isearch-forward}).
+ @item C-r
+ Incremental search backward (@code{isearch-backward}).
+ @end table
+ 
+ @kindex C-s
+ @findex isearch-forward
+   @kbd{C-s} starts a forward incremental search.  It reads characters
+ from the keyboard, and moves point past the next occurrence of those
+ characters.  If you type @kbd{C-s} and then @kbd{F}, that puts the
+ cursor after the first @samp{F} (the first following the starting point, since
+ this is a forward search).  Then if you type an @kbd{O}, you will see
+ the cursor move just after the first @samp{FO} (the @samp{F} in that
+ @samp{FO} may or may not be the first @samp{F}).  After another
+ @kbd{O}, the cursor moves after the first @samp{FOO} after the place
+ where you started the search.  At each step, the buffer text that
+ matches the search string is highlighted, if the terminal can do that;
+ the current search string is always displayed in the echo area.
+ 
+   If you make a mistake in typing the search string, you can cancel
+ characters with @key{DEL}.  Each @key{DEL} cancels the last character of
+ search string.  This does not happen until Emacs is ready to read another
+ input character; first it must either find, or fail to find, the character
+ you want to erase.  If you do not want to wait for this to happen, use
+ @kbd{C-g} as described below.
+ 
+   When you are satisfied with the place you have reached, you can type
+ @key{RET}, which stops searching, leaving the cursor where the search
+ brought it.  Also, any command not specially meaningful in searches
+ stops the searching and is then executed.  Thus, typing @kbd{C-a}
+ would exit the search and then move to the beginning of the line.
+ @key{RET} is necessary only if the next command you want to type is a
+ printing character, @key{DEL}, @key{RET}, or another character that is
+ special within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s},
+ @kbd{C-y}, @kbd{M-y}, @kbd{M-r}, @kbd{M-c}, @kbd{M-e}, and some other
+ meta-characters).
+ 
+   Sometimes you search for @samp{FOO} and find one, but not the one you
+ expected to find.  There was a second @samp{FOO} that you forgot
+ about, before the one you were aiming for.  In this event, type
+ another @kbd{C-s} to move to the next occurrence of the search string.
+ You can repeat this any number of times.  If you overshoot, you can
+ cancel some @kbd{C-s} characters with @key{DEL}.
+ 
+   After you exit a search, you can search for the same string again by
+ typing just @kbd{C-s C-s}: the first @kbd{C-s} is the key that invokes
+ incremental search, and the second @kbd{C-s} means ``search again.''
+ 
+   To reuse earlier search strings, use the @dfn{search ring}.  The
+ commands @kbd{M-p} and @kbd{M-n} move through the ring to pick a search
+ string to reuse.  These commands leave the selected search ring element
+ in the minibuffer, where you can edit it.  To edit the current search
+ string in the minibuffer without replacing it with items from the
+ search ring, type @kbd{M-e}.  Type @kbd{C-s} or @kbd{C-r}
+ to terminate editing the string and search for it.
+ 
+   If your string is not found at all, the echo area says @samp{Failing
+ I-Search}.  The cursor is after the place where Emacs found as much of your
+ string as it could.  Thus, if you search for @samp{FOOT}, and there is no
+ @samp{FOOT}, you might see the cursor after the @samp{FOO} in @samp{FOOL}.
+ At this point there are several things you can do.  If your string was
+ mistyped, you can rub some of it out and correct it.  If you like the place
+ you have found, you can type @key{RET} or some other Emacs command to
+ remain there.  Or you can type @kbd{C-g}, which
+ removes from the search string the characters that could not be found (the
+ @samp{T} in @samp{FOOT}), leaving those that were found (the @samp{FOO} in
+ @samp{FOOT}).  A second @kbd{C-g} at that point cancels the search
+ entirely, returning point to where it was when the search started.
+ 
+   An upper-case letter in the search string makes the search
+ case-sensitive.  If you delete the upper-case character from the search
+ string, it ceases to have this effect.  @xref{Search Case}.
+ 
+   To search for a newline, type @kbd{C-j}.  To search for another
+ control character, such as control-S or carriage return, you must quote
+ it by typing @kbd{C-q} first.  This function of @kbd{C-q} is analogous
+ to its use for insertion (@pxref{Inserting Text}): it causes the
+ following character to be treated the way any ``ordinary'' character is
+ treated in the same context.  You can also specify a character by its
+ octal code: enter @kbd{C-q} followed by a sequence of octal digits.
+ 
+ @cindex searching for address@hidden characters
+ @cindex input method, during incremental search
+   To search for address@hidden characters, you must use an input method
+ (@pxref{Input Methods}).  If an input method is enabled in the
+ current buffer when you start the search, you can use it while you
+ type the search string also.  Emacs indicates that by including the
+ input method mnemonic in its prompt, like this:
+ 
+ @example
+ I-search address@hidden:
+ @end example
+ 
+ @noindent
+ @findex isearch-toggle-input-method
+ @findex isearch-toggle-specified-input-method
+ where @var{im} is the mnemonic of the active input method.  You can
+ toggle (enable or disable) the input method while you type the search
+ string with @kbd{C-\} (@code{isearch-toggle-input-method}).  You can
+ turn on a certain (non-default) input method with @kbd{C-^}
+ (@code{isearch-toggle-specified-input-method}), which prompts for the
+ name of the input method.  The input method you enable during
+ incremental search remains enabled in the current buffer afterwards.
+ 
+   If a search is failing and you ask to repeat it by typing another
+ @kbd{C-s}, it starts again from the beginning of the buffer.
+ Repeating a failing reverse search with @kbd{C-r} starts again from
+ the end.  This is called @dfn{wrapping around}, and @samp{Wrapped}
+ appears in the search prompt once this has happened.  If you keep on
+ going past the original starting point of the search, it changes to
+ @samp{Overwrapped}, which means that you are revisiting matches that
+ you have already seen.
+ 
+ @cindex quitting (in search)
+   The @kbd{C-g} ``quit'' character does special things during searches;
+ just what it does depends on the status of the search.  If the search has
+ found what you specified and is waiting for input, @kbd{C-g} cancels the
+ entire search.  The cursor moves back to where you started the search.  If
+ @kbd{C-g} is typed when there are characters in the search string that have
+ not been found---because Emacs is still searching for them, or because it
+ has failed to find them---then the search string characters which have not
+ been found are discarded from the search string.  With them gone, the
+ search is now successful and waiting for more input, so a second @kbd{C-g}
+ will cancel the entire search.
+ 
+   You can change to searching backwards with @kbd{C-r}.  If a search fails
+ because the place you started was too late in the file, you should do this.
+ Repeated @kbd{C-r} keeps looking for more occurrences backwards.  A
+ @kbd{C-s} starts going forwards again.  @kbd{C-r} in a search can be canceled
+ with @key{DEL}.
+ 
+ @kindex C-r
+ @findex isearch-backward
+   If you know initially that you want to search backwards, you can use
+ @kbd{C-r} instead of @kbd{C-s} to start the search, because @kbd{C-r} as
+ a key runs a command (@code{isearch-backward}) to search backward.  A
+ backward search finds matches that are entirely before the starting
+ point, just as a forward search finds matches that begin after it.
+ 
+   The characters @kbd{C-w} and @kbd{C-y} can be used in incremental
+ search to grab text from the buffer into the search string.  This
+ makes it convenient to search for another occurrence of text at point.
+ @kbd{C-w} copies the character or word after point as part of the
+ search string, advancing point over it.  (The decision, whether to
+ copy a character or a word, is heuristic.)  Another @kbd{C-s} to
+ repeat the search will then search for a string including that
+ character or word.
+ 
+   @kbd{C-y} is similar to @kbd{C-w} but copies all the rest of the
+ current line into the search string.  Both @kbd{C-y} and @kbd{C-w}
+ convert the text they copy to lower case if the search is currently
+ not case-sensitive; this is so the search remains case-insensitive.
+ 
+   @kbd{C-M-w} and @kbd{C-M-y} modify the search string by only one
+ character at a time: @kbd{C-M-w} deletes the last character from the
+ search string and @kbd{C-M-y} copies the character after point to the
+ end of the search string.  An alternative method to add the character
+ after point into the search string is to enter the minibuffer by
+ @kbd{M-e} and to type @kbd{C-f} at the end of the search string in the
+ minibuffer.
+ 
+   The character @kbd{M-y} copies text from the kill ring into the search
+ string.  It uses the same text that @kbd{C-y} as a command would yank.
+ @kbd{Mouse-2} in the echo area does the same.
+ @xref{Yanking}.
+ 
+   When you exit the incremental search, it sets the mark to where point
+ @emph{was}, before the search.  That is convenient for moving back
+ there.  In Transient Mark mode, incremental search sets the mark without
+ activating it, and does so only if the mark is not already active.
+ 
+   @kbd{M-%} typed in incremental search invokes @code{query-replace}
+ or @code{query-replace-regexp} (depending on search mode) with the
+ current search string used as the string to replace.
+ 
+ @cindex lazy search highlighting
+ @vindex isearch-lazy-highlight
+   When you pause for a little while during incremental search, it
+ highlights all other possible matches for the search string.  This
+ makes it easier to anticipate where you can get to by typing @kbd{C-s}
+ or @kbd{C-r} to repeat the search.  The short delay before highlighting
+ other matches helps indicate which match is the current one.
+ If you don't like this feature, you can turn it off by setting
+ @code{isearch-lazy-highlight} to @code{nil}.
+ 
+ @vindex isearch-lazy-highlight-face
+ @cindex faces for highlighting search matches
+   You can control how this highlighting looks by customizing the faces
+ @code{isearch} (used for the current match) and
+ @code{isearch-lazy-highlight-face} (for all the other matches).
+ 
+ @vindex isearch-mode-map
+   To customize the special characters that incremental search understands,
+ alter their bindings in the keymap @code{isearch-mode-map}.  For a list
+ of bindings, look at the documentation of @code{isearch-mode} with
+ @kbd{C-h f isearch-mode @key{RET}}.
+ 
+ @subsection Scrolling During Incremental Search
+ 
+   Vertical scrolling during incremental search can be enabled by
+ setting the customizable variable @code{isearch-allow-scroll} to a
+ address@hidden value.
+ 
+   You can then use the vertical scroll-bar or certain keyboard
+ commands such as @address@hidden (@code{scroll-down}),
+ @address@hidden (@code{scroll-up}) and @kbd{C-l} (@code{recenter})
+ within the search, thus letting you see more of the text near the
+ current match.  You must run these commands via their key sequences to
+ stay in the search---typing M-x @var{comand-name} will always
+ terminate a search.
+ 
+   You can give prefix arguments to these commands in the usual way.
+ The current match cannot be scrolled out of the window---this is
+ intentional.
+ 
+   Several other commands, such as @kbd{C-x 2}
+ (@code{split-window-vertically}) and @kbd{C-x ^}
+ (@code{enlarge-window}) which don't scroll the window, are
+ nevertheless made available under this rubric, since they are likewise
+ handy during a search.
+ 
+   For a list of commands which are configured as scrolling commands by
+ default and instructions on how thus to configure other commands, see
+ @ref{Configuring Scrolling}.
+ 
+ @subsection Slow Terminal Incremental Search
+ 
+   Incremental search on a slow terminal uses a modified style of display
+ that is designed to take less time.  Instead of redisplaying the buffer at
+ each place the search gets to, it creates a new single-line window and uses
+ that to display the line that the search has found.  The single-line window
+ comes into play as soon as point moves outside of the text that is already
+ on the screen.
+ 
+   When you terminate the search, the single-line window is removed.
+ Emacs then redisplays the window in which the search was done, to show
+ its new position of point.
+ 
+ @vindex search-slow-speed
+   The slow terminal style of display is used when the terminal baud rate is
+ less than or equal to the value of the variable @code{search-slow-speed},
+ initially 1200.  See @code{baud-rate} in @ref{Display Custom}.
+ 
+ @vindex search-slow-window-lines
+   The number of lines to use in slow terminal search display is controlled
+ by the variable @code{search-slow-window-lines}.  Its normal value is 1.
+ 
+ @node Nonincremental Search, Word Search, Incremental Search, Search
+ @section Nonincremental Search
+ @cindex nonincremental search
+ 
+   Emacs also has conventional nonincremental search commands, which require
+ you to type the entire search string before searching begins.
+ 
+ @table @kbd
+ @item C-s @key{RET} @var{string} @key{RET}
+ Search for @var{string}.
+ @item C-r @key{RET} @var{string} @key{RET}
+ Search backward for @var{string}.
+ @end table
+ 
+   To do a nonincremental search, first type @kbd{C-s @key{RET}}.  This
+ enters the minibuffer to read the search string; terminate the string
+ with @key{RET}, and then the search takes place.  If the string is not
+ found, the search command signals an error.
+ 
+   When you type @kbd{C-s @key{RET}}, the @kbd{C-s} invokes incremental
+ search as usual.  That command is specially programmed to invoke
+ nonincremental search, @code{search-forward}, if the string you
+ specify is empty.  (Such an empty argument would otherwise be
+ useless.)  But it does not call @code{search-forward} right away.  First
+ it checks the next input character to see if is @kbd{C-w},
+ which specifies a word search.
+ @ifinfo
+ @xref{Word Search}.
+ @end ifinfo
+ @kbd{C-r @key{RET}} does likewise, for a reverse incremental search.
+ 
+ @findex search-forward
+ @findex search-backward
+   Forward and backward nonincremental searches are implemented by the
+ commands @code{search-forward} and @code{search-backward}.  These
+ commands may be bound to keys in the usual manner.  The feature that you
+ can get to them via the incremental search commands exists for
+ historical reasons, and to avoid the need to find key sequences
+ for them.
+ 
+ @node Word Search, Regexp Search, Nonincremental Search, Search
+ @section Word Search
+ @cindex word search
+ 
+   Word search searches for a sequence of words without regard to how the
+ words are separated.  More precisely, you type a string of many words,
+ using single spaces to separate them, and the string can be found even
+ if there are multiple spaces, newlines, or other punctuation characters
+ between these words.
+ 
+   Word search is useful for editing a printed document made with a text
+ formatter.  If you edit while looking at the printed, formatted version,
+ you can't tell where the line breaks are in the source file.  With word
+ search, you can search without having to know them.
+ 
+ @table @kbd
+ @item C-s @key{RET} C-w @var{words} @key{RET}
+ Search for @var{words}, ignoring details of punctuation.
+ @item C-r @key{RET} C-w @var{words} @key{RET}
+ Search backward for @var{words}, ignoring details of punctuation.
+ @end table
+ 
+   Word search is a special case of nonincremental search and is invoked
+ with @kbd{C-s @key{RET} C-w}.  This is followed by the search string,
+ which must always be terminated with @key{RET}.  Being nonincremental,
+ this search does not start until the argument is terminated.  It works
+ by constructing a regular expression and searching for that; see
+ @ref{Regexp Search}.
+ 
+   Use @kbd{C-r @key{RET} C-w} to do backward word search.
+ 
+ @findex word-search-forward
+ @findex word-search-backward
+   Forward and backward word searches are implemented by the commands
+ @code{word-search-forward} and @code{word-search-backward}.  These
+ commands may be bound to keys in the usual manner.  They are available
+ via the incremental search commands both for historical reasons and
+ to avoid the need to find suitable key sequences for them.
+ 
+ @node Regexp Search, Regexps, Word Search, Search
+ @section Regular Expression Search
+ @cindex regular expression
+ @cindex regexp
+ 
+   A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern
+ that denotes a class of alternative strings to match, possibly
+ infinitely many.  GNU Emacs provides both incremental and
+ nonincremental ways to search for a match for a regexp.
+ 
+ @kindex C-M-s
+ @findex isearch-forward-regexp
+ @kindex C-M-r
+ @findex isearch-backward-regexp
+   Incremental search for a regexp is done by typing @kbd{C-M-s}
+ (@code{isearch-forward-regexp}), by invoking @kbd{C-s} with a
+ prefix argument (whose value does not matter), or by typing @kbd{M-r}
+ within a forward incremental search.  This command reads a
+ search string incrementally just like @kbd{C-s}, but it treats the
+ search string as a regexp rather than looking for an exact match
+ against the text in the buffer.  Each time you add text to the search
+ string, you make the regexp longer, and the new regexp is searched
+ for.  To search backward for a regexp, use @kbd{C-M-r}
+ (@code{isearch-backward-regexp}), @kbd{C-r} with a prefix argument,
+ or @kbd{M-r} within a backward incremental search.
+ 
+   All of the control characters that do special things within an
+ ordinary incremental search have the same function in incremental regexp
+ search.  Typing @kbd{C-s} or @kbd{C-r} immediately after starting the
+ search retrieves the last incremental search regexp used; that is to
+ say, incremental regexp and non-regexp searches have independent
+ defaults.  They also have separate search rings that you can access with
+ @kbd{M-p} and @kbd{M-n}.
+ 
+   If you type @key{SPC} in incremental regexp search, it matches any
+ sequence of whitespace characters, including newlines.  If you want
+ to match just a space, type @kbd{C-q @key{SPC}}.
+ 
+   Note that adding characters to the regexp in an incremental regexp
+ search can make the cursor move back and start again.  For example, if
+ you have searched for @samp{foo} and you add @samp{\|bar}, the cursor
+ backs up in case the first @samp{bar} precedes the first @samp{foo}.
+ 
+ @findex re-search-forward
+ @findex re-search-backward
+   Nonincremental search for a regexp is done by the functions
+ @code{re-search-forward} and @code{re-search-backward}.  You can invoke
+ these with @kbd{M-x}, or bind them to keys, or invoke them by way of
+ incremental regexp search with @kbd{C-M-s @key{RET}} and @kbd{C-M-r
+ @key{RET}}.
+ 
+   If you use the incremental regexp search commands with a prefix
+ argument, they perform ordinary string search, like
+ @code{isearch-forward} and @code{isearch-backward}.  @xref{Incremental
+ Search}.
+ 
+ @node Regexps, Search Case, Regexp Search, Search
+ @section Syntax of Regular Expressions
+ @cindex syntax of regexps
+ 
+   This manual describes regular expression features that users
+ typically want to use.  There are additional features that are
+ mainly used in Lisp programs; see @ref{Regular Expressions,,,
+ elisp, The Emacs Lisp Reference Manual}.
+ 
+   Regular expressions have a syntax in which a few characters are
+ special constructs and the rest are @dfn{ordinary}.  An ordinary
+ character is a simple regular expression which matches that same
+ character and nothing else.  The special characters are @samp{$},
+ @samp{^}, @samp{.}, @samp{*}, @samp{+}, @samp{?}, @samp{[}, @samp{]} and
+ @samp{\}.  Any other character appearing in a regular expression is
+ ordinary, unless a @samp{\} precedes it.  (When you use regular
+ expressions in a Lisp program, each @samp{\} must be doubled, see the
+ example near the end of this section.)
+ 
+   For example, @samp{f} is not a special character, so it is ordinary, and
+ therefore @samp{f} is a regular expression that matches the string
+ @samp{f} and no other string.  (It does @emph{not} match the string
+ @samp{ff}.)  Likewise, @samp{o} is a regular expression that matches
+ only @samp{o}.  (When case distinctions are being ignored, these regexps
+ also match @samp{F} and @samp{O}, but we consider this a generalization
+ of ``the same string,'' rather than an exception.)
+ 
+   Any two regular expressions @var{a} and @var{b} can be concatenated.  The
+ result is a regular expression which matches a string if @var{a} matches
+ some amount of the beginning of that string and @var{b} matches the rest of
+ the address@hidden
+ 
+   As a simple example, we can concatenate the regular expressions @samp{f}
+ and @samp{o} to get the regular expression @samp{fo}, which matches only
+ the string @samp{fo}.  Still trivial.  To do something nontrivial, you
+ need to use one of the special characters.  Here is a list of them.
+ 
+ @table @asis
+ @item @kbd{.}@: @r{(Period)}
+ is a special character that matches any single character except a newline.
+ Using concatenation, we can make regular expressions like @samp{a.b}, which
+ matches any three-character string that begins with @samp{a} and ends with
+ @address@hidden
+ 
+ @item @kbd{*}
+ is not a construct by itself; it is a postfix operator that means to
+ match the preceding regular expression repetitively as many times as
+ possible.  Thus, @samp{o*} matches any number of @samp{o}s (including no
+ @samp{o}s).
+ 
+ @samp{*} always applies to the @emph{smallest} possible preceding
+ expression.  Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
+ @samp{fo}.  It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
+ 
+ The matcher processes a @samp{*} construct by matching, immediately,
+ as many repetitions as can be found.  Then it continues with the rest
+ of the pattern.  If that fails, backtracking occurs, discarding some
+ of the matches of the @samp{*}-modified construct in case that makes
+ it possible to match the rest of the pattern.  For example, in matching
+ @samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first
+ tries to match all three @samp{a}s; but the rest of the pattern is
+ @samp{ar} and there is only @samp{r} left to match, so this try fails.
+ The next alternative is for @samp{a*} to match only two @samp{a}s.
+ With this choice, the rest of the regexp matches address@hidden
+ 
+ @item @kbd{+}
+ is a postfix operator, similar to @samp{*} except that it must match
+ the preceding expression at least once.  So, for example, @samp{ca+r}
+ matches the strings @samp{car} and @samp{caaaar} but not the string
+ @samp{cr}, whereas @samp{ca*r} matches all three strings.
+ 
+ @item @kbd{?}
+ is a postfix operator, similar to @samp{*} except that it can match the
+ preceding expression either once or not at all.  For example,
+ @samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
+ 
+ @item @kbd{*?}, @kbd{+?}, @kbd{??}
+ @cindex non-greedy regexp matching
+ are non-greedy variants of the operators above.  The normal operators
+ @samp{*}, @samp{+}, @samp{?} are @dfn{greedy} in that they match as
+ much as they can, as long as the overall regexp can still match.  With
+ a following @samp{?}, they are non-greedy: they will match as little
+ as possible.
+ 
+ Thus, both @samp{ab*} and @samp{ab*?} can match the string @samp{a}
+ and the string @samp{abbbb}; but if you try to match them both against
+ the text @samp{abbb}, @samp{ab*} will match it all (the longest valid
+ match), while @samp{ab*?}  will match just @samp{a} (the shortest
+ valid match).
+ 
+ Non-greedy operators match the shortest possible string starting at a
+ given starting point; in a forward search, though, the earliest
+ possible starting point for match is always the one chosen.  Thus, if
+ you search for @samp{a.*?$} against the text @samp{abbab} followed by
+ a newline, it matches the whole string.  Since it @emph{can} match
+ starting at the first @samp{a}, it does.
+ 
+ @item @address@hidden@address@hidden
+ is a postfix operator that specifies repetition @var{n} times---that
+ is, the preceding regular expression must match exactly @var{n} times
+ in a row.  For example, @address@hidden@}} matches the string @samp{xxxx}
+ and nothing else.
+ 
+ @item @address@hidden@var{n},@address@hidden
+ is a postfix operator that specifies repetition between @var{n} and
+ @var{m} times---that is, the preceding regular expression must match
+ at least @var{n} times, but no more than @var{m} times.  If @var{m} is
+ omitted, then there is no upper limit, but the preceding regular
+ expression must match at least @var{n} address@hidden 
@address@hidden,address@hidden is
+ equivalent to @samp{?}. @* @address@hidden,address@hidden is equivalent to
+ @samp{*}. @* @address@hidden,address@hidden is equivalent to @samp{+}.
+ 
+ @item @kbd{[ @dots{} ]}
+ is a @dfn{character set}, which begins with @samp{[} and is terminated
+ by @samp{]}.  In the simplest case, the characters between the two
+ brackets are what this set can match.
+ 
+ Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and
+ @samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s
+ (including the empty string), from which it follows that @samp{c[ad]*r}
+ matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
+ 
+ You can also include character ranges in a character set, by writing the
+ starting and ending characters with a @samp{-} between them.  Thus,
+ @samp{[a-z]} matches any lower-case @acronym{ASCII} letter.  Ranges may be
+ intermixed freely with individual characters, as in @samp{[a-z$%.]},
+ which matches any lower-case @acronym{ASCII} letter or @samp{$}, @samp{%} or
+ period.
+ 
+ Note that the usual regexp special characters are not special inside a
+ character set.  A completely different set of special characters exists
+ inside character sets: @samp{]}, @samp{-} and @samp{^}.
+ 
+ To include a @samp{]} in a character set, you must make it the first
+ character.  For example, @samp{[]a]} matches @samp{]} or @samp{a}.  To
+ include a @samp{-}, write @samp{-} as the first or last character of the
+ set, or put it after a range.  Thus, @samp{[]-]} matches both @samp{]}
+ and @samp{-}.
+ 
+ To include @samp{^} in a set, put it anywhere but at the beginning of
+ the set.  (At the beginning, it complements the set---see below.)
+ 
+ When you use a range in case-insensitive search, you should write both
+ ends of the range in upper case, or both in lower case, or both should
+ be non-letters.  The behavior of a mixed-case range such as @samp{A-z}
+ is somewhat ill-defined, and it may change in future Emacs versions.
+ 
+ @item @kbd{[^ @dots{} ]}
+ @samp{[^} begins a @dfn{complemented character set}, which matches any
+ character except the ones specified.  Thus, @samp{[^a-z0-9A-Z]} matches
+ all characters @emph{except} @acronym{ASCII} letters and digits.
+ 
+ @samp{^} is not special in a character set unless it is the first
+ character.  The character following the @samp{^} is treated as if it
+ were first (in other words, @samp{-} and @samp{]} are not special there).
+ 
+ A complemented character set can match a newline, unless newline is
+ mentioned as one of the characters not to match.  This is in contrast to
+ the handling of regexps in programs such as @code{grep}.
+ 
+ @item @kbd{^}
+ is a special character that matches the empty string, but only at the
+ beginning of a line in the text being matched.  Otherwise it fails to
+ match anything.  Thus, @samp{^foo} matches a @samp{foo} that occurs at
+ the beginning of a line.
+ 
+ For historical compatibility reasons, @samp{^} can be used with this
+ meaning only at the beginning of the regular expression, or after
+ @samp{\(} or @samp{\|}.
+ 
+ @item @kbd{$}
+ is similar to @samp{^} but matches only at the end of a line.  Thus,
+ @samp{x+$} matches a string of one @samp{x} or more at the end of a line.
+ 
+ For historical compatibility reasons, @samp{$} can be used with this
+ meaning only at the end of the regular expression, or before @samp{\)}
+ or @samp{\|}.
+ 
+ @item @kbd{\}
+ has two functions: it quotes the special characters (including
+ @samp{\}), and it introduces additional special constructs.
+ 
+ Because @samp{\} quotes special characters, @samp{\$} is a regular
+ expression that matches only @samp{$}, and @samp{\[} is a regular
+ expression that matches only @samp{[}, and so on.
+ @end table
+ 
+ Note: for historical compatibility, special characters are treated as
+ ordinary ones if they are in contexts where their special meanings make no
+ sense.  For example, @samp{*foo} treats @samp{*} as ordinary since there is
+ no preceding expression on which the @samp{*} can act.  It is poor practice
+ to depend on this behavior; it is better to quote the special character 
anyway,
+ regardless of where it address@hidden
+ 
+ For the most part, @samp{\} followed by any character matches only that
+ character.  However, there are several exceptions: two-character
+ sequences starting with @samp{\} that have special meanings.  The second
+ character in the sequence is always an ordinary character when used on
+ its own.  Here is a table of @samp{\} constructs.
+ 
+ @table @kbd
+ @item \|
+ specifies an alternative.  Two regular expressions @var{a} and @var{b}
+ with @samp{\|} in between form an expression that matches some text if
+ either @var{a} matches it or @var{b} matches it.  It works by trying to
+ match @var{a}, and if that fails, by trying to match @var{b}.
+ 
+ Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
+ but no other address@hidden
+ 
+ @samp{\|} applies to the largest possible surrounding expressions.  Only a
+ surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
+ @samp{\|address@hidden
+ 
+ Full backtracking capability exists to handle multiple uses of @samp{\|}.
+ 
+ @item \( @dots{} \)
+ is a grouping construct that serves three purposes:
+ 
+ @enumerate
+ @item
+ To enclose a set of @samp{\|} alternatives for other operations.
+ Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}.
+ 
+ @item
+ To enclose a complicated expression for the postfix operators @samp{*},
+ @samp{+} and @samp{?} to operate on.  Thus, @samp{ba\(na\)*} matches
+ @samp{bananana}, etc., with any (zero or more) number of @samp{na}
+ address@hidden
+ 
+ @item
+ To record a matched substring for future reference.
+ @end enumerate
+ 
+ This last application is not a consequence of the idea of a
+ parenthetical grouping; it is a separate feature that is assigned as a
+ second meaning to the same @samp{\( @dots{} \)} construct.  In practice
+ there is usually no conflict between the two meanings; when there is
+ a conflict, you can use a ``shy'' group.
+ 
+ @item \(?: @dots{} \)
+ @cindex shy group, in regexp
+ specifies a ``shy'' group that does not record the matched substring;
+ you can't refer back to it with @address@hidden  This is useful
+ in mechanically combining regular expressions, so that you
+ can add groups for syntactic purposes without interfering with
+ the numbering of the groups that were written by the user.
+ 
+ @item address@hidden
+ matches the same text that matched the @var{d}th occurrence of a
+ @samp{\( @dots{} \)} construct.
+ 
+ After the end of a @samp{\( @dots{} \)} construct, the matcher remembers
+ the beginning and end of the text matched by that construct.  Then,
+ later on in the regular expression, you can use @samp{\} followed by the
+ digit @var{d} to mean ``match the same text matched the @var{d}th time
+ by the @samp{\( @dots{} \)} construct.''
+ 
+ The strings matching the first nine @samp{\( @dots{} \)} constructs
+ appearing in a regular expression are assigned numbers 1 through 9 in
+ the order that the open-parentheses appear in the regular expression.
+ So you can use @samp{\1} through @samp{\9} to refer to the text matched
+ by the corresponding @samp{\( @dots{} \)} constructs.
+ 
+ For example, @samp{\(.*\)\1} matches any newline-free string that is
+ composed of two identical halves.  The @samp{\(.*\)} matches the first
+ half, which may be anything, but the @samp{\1} that follows must match
+ the same exact text.
+ 
+ If a particular @samp{\( @dots{} \)} construct matches more than once
+ (which can easily happen if it is followed by @samp{*}), only the last
+ match is recorded.
+ 
+ @item \`
+ matches the empty string, but only at the beginning of the string or
+ buffer (or its accessible portion) being matched against.
+ 
+ @item \'
+ matches the empty string, but only at the end of the string or buffer
+ (or its accessible portion) being matched against.
+ 
+ @item \=
+ matches the empty string, but only at point.
+ 
+ @item \b
+ matches the empty string, but only at the beginning or
+ end of a word.  Thus, @samp{\bfoo\b} matches any occurrence of
+ @samp{foo} as a separate word.  @samp{\bballs?\b} matches
+ @samp{ball} or @samp{balls} as a separate address@hidden
+ 
+ @samp{\b} matches at the beginning or end of the buffer
+ regardless of what text appears next to it.
+ 
+ @item \B
+ matches the empty string, but @emph{not} at the beginning or
+ end of a word.
+ 
+ @item \<
+ matches the empty string, but only at the beginning of a word.
+ @samp{\<} matches at the beginning of the buffer only if a
+ word-constituent character follows.
+ 
+ @item \>
+ matches the empty string, but only at the end of a word.  @samp{\>}
+ matches at the end of the buffer only if the contents end with a
+ word-constituent character.
+ 
+ @item \w
+ matches any word-constituent character.  The syntax table
+ determines which characters these are.  @xref{Syntax}.
+ 
+ @item \W
+ matches any character that is not a word-constituent.
+ 
+ @item \_<
+ matches the empty string, but only at the beginning of a symbol.  A
+ symbol is a sequence of one or more word or symbol constituent
+ characters.  @samp{\_<} matches at the beginning of the buffer only if
+ a symbol-constituent character follows.
+ 
+ @item \_>
+ matches the empty string, but only at the end of a symbol.  @samp{\_>}
+ matches at the end of the buffer only if the contents end with a
+ symbol-constituent character.
+ 
+ @item address@hidden
+ matches any character whose syntax is @var{c}.  Here @var{c} is a
+ character that designates a particular syntax class: thus, @samp{w}
+ for word constituent, @samp{-} or @samp{ } for whitespace, @samp{.}
+ for ordinary punctuation, etc.  @xref{Syntax}.
+ 
+ @item address@hidden
+ matches any character whose syntax is not @var{c}.
+ 
+ @cindex categories of characters
+ @cindex characters which belong to a specific language
+ @findex describe-categories
+ @item address@hidden
+ matches any character that belongs to the category @var{c}.  For
+ example, @samp{\cc} matches Chinese characters, @samp{\cg} matches
+ Greek characters, etc.  For the description of the known categories,
+ type @kbd{M-x describe-categories @key{RET}}.
+ 
+ @item address@hidden
+ matches any character that does @emph{not} belong to category
+ @var{c}.
+ @end table
+ 
+   The constructs that pertain to words and syntax are controlled by the
+ setting of the syntax table (@pxref{Syntax}).
+ 
+   Here is a complicated regexp, stored in @code{sentence-end} and used
+ by Emacs to recognize the end of a sentence together with any
+ whitespace that follows.  We show its Lisp syntax to distinguish the
+ spaces from the tab characters.  In Lisp syntax, the string constant
+ begins and ends with a double-quote.  @samp{\"} stands for a
+ double-quote as part of the regexp, @samp{\\} for a backslash as part
+ of the regexp, @samp{\t} for a tab, and @samp{\n} for a newline.
+ 
+ @example
+ "[.?!][]\"')]*\\($\\| $\\|\t\\|  \\)[ \t\n]*"
+ @end example
+ 
+ @noindent
+ This contains four parts in succession: a character set matching
+ period, @samp{?}, or @samp{!}; a character set matching
+ close-brackets, quotes, or parentheses, repeated zero or more times; a
+ set of alternatives within backslash-parentheses that matches either
+ end-of-line, a space at the end of a line, a tab, or two spaces; and a
+ character set matching whitespace characters, repeated any number of
+ times.
+ 
+   To enter the same regexp in incremental search, you would type
+ @key{TAB} to enter a tab, and @kbd{C-j} to enter a newline.  You would
+ also type single backslashes as themselves, instead of doubling them
+ for Lisp syntax.  In commands that use ordinary minibuffer input to
+ read a regexp, you would quote the @kbd{C-j} by preceding it with a
+ @kbd{C-q} to prevent @kbd{C-j} from exiting the minibuffer.
+ 
+ @ignore
+ @c I commented this out because it is missing vital information
+ @c and therefore useless.  For instance, what do you do to *use* the
+ @c regular expression when it is finished?  What jobs is this good for?
+ @c  -- rms
+ 
+ @findex re-builder
+ @cindex authoring regular expressions
+   For convenient interactive development of regular expressions, you
+ can use the @kbd{M-x re-builder} command.  It provides a convenient
+ interface for creating regular expressions, by giving immediate visual
+ feedback.  The buffer from which @code{re-builder} was invoked becomes
+ the target for the regexp editor, which pops in a separate window.  At
+ all times, all the matches in the target buffer for the current
+ regular expression are highlighted.  Each parenthesized sub-expression
+ of the regexp is shown in a distinct face, which makes it easier to
+ verify even very complex regexps.  (On displays that don't support
+ colors, Emacs blinks the cursor around the matched text, as it does
+ for matching parens.)
+ @end ignore
+ 
+ @node Search Case, Configuring Scrolling, Regexps, Search
+ @section Searching and Case
+ 
+   Incremental searches in Emacs normally ignore the case of the text
+ they are searching through, if you specify the text in lower case.
+ Thus, if you specify searching for @samp{foo}, then @samp{Foo} and
+ @samp{foo} are also considered a match.  Regexps, and in particular
+ character sets, are included: @samp{[ab]} would match @samp{a} or
+ @samp{A} or @samp{b} or @address@hidden
+ 
+   An upper-case letter anywhere in the incremental search string makes
+ the search case-sensitive.  Thus, searching for @samp{Foo} does not find
+ @samp{foo} or @samp{FOO}.  This applies to regular expression search as
+ well as to string search.  The effect ceases if you delete the
+ upper-case letter from the search string.
+ 
+   Typing @kbd{M-c} within an incremental search toggles the case
+ sensitivity of that search.  The effect does not extend beyond the
+ current incremental search to the next one, but it does override the
+ effect of including an upper-case letter in the current search.
+ 
+ @vindex case-fold-search
+   If you set the variable @code{case-fold-search} to @code{nil}, then
+ all letters must match exactly, including case.  This is a per-buffer
+ variable; altering the variable affects only the current buffer, but
+ there is a default value which you can change as well.  @xref{Locals}.
+ This variable applies to nonincremental searches also, including those
+ performed by the replace commands (@pxref{Replace}) and the minibuffer
+ history matching commands (@pxref{Minibuffer History}).
+ 
+ @node Configuring Scrolling, Replace, Search Case, Search
+ @section Configuring Scrolling
+ @cindex scrolling in incremental search
+ @vindex isearch-allow-scroll
+ 
+ Scrolling, etc., during incremental search is enabled by setting the
+ customizable variable @code{isearch-allow-scroll} to a address@hidden value.
+ 
+ @c See Subject: Info file:  How do I get an itemized list without blank lines?
+ @c Date: Sat, 12 Apr 2003 09:45:31 +0000  in gnu.emacs.help
+ @subsection Standard scrolling commands
+ Here is the list of commands which are configured by default to be
+ ``scrolling'' commands in an incremental search, together with their
+ usual bindings:
+ @subsubsection Commands which scroll the window:
+ @table @asis
+ @item @code{scroll-bar-toolkit-scroll} (@address@hidden@key{mouse-1}} in 
X-Windows)
+ @itemx @code{mac-handle-scroll-bar-event} (@address@hidden@key{mouse-1}} on a 
Mac)
+ @itemx @code{w32-handle-scroll-bar-event} (@address@hidden@key{mouse-1}} in 
MS-Windows)
+ @item @code{recenter} (@kbd{C-l}) @xref{Scrolling}.
+ @itemx @code{reposition-window} (@kbd{C-M-l}) @xref{Scrolling}.
+ @itemx @code{scroll-up} (@address@hidden) @xref{Scrolling}.
+ @itemx @code{scroll-down} (@address@hidden) @xref{Scrolling}.
+ @end table
+ 
+ @subsubsection Commands which act on the other window:
+ @table @asis
+ @item @code{list-buffers} (@kbd{C-x C-b}) @xref{List Buffers}.
+ @itemx @code{scroll-other-window} (@kbd{C-M-v}) @xref{Other Window}.
+ @itemx @code{scroll-other-window-down} (@kbd{C-M-S-v}) @xref{Other Window}.
+ @itemx @code{beginning-of-buffer-other-window} (@address@hidden)
+ @itemx @code{end-of-buffer-other-window} (@address@hidden)
+ @end table
+ 
+ @subsubsection Commands which change the window layout:
+ @table @asis
+ @item @code{delete-other-windows} (@kbd{C-x 1}) @xref{Change Window}.
+ @itemx @code{balance-windows} (@kbd{C-x +}) @xref{Change Window}.
+ @itemx @code{split-window-vertically} (@kbd{C-x 2}) @xref{Split Window}.
+ @itemx @code{enlarge-window} (@kbd{C-x ^}) @xref{Change Window}.
+ @end table
+ 
+ @subsection Configuring other commands as scrolling commands
+ To do this, set a command's isearch-scroll property to the value t.
+ For example:
+ 
+ @example
+ @code{(put 'my-command 'isearch-scroll t)}
+ @end example
+ 
+ You should only thus configure commands which are ``safe'': i.e., they
+ won't leave emacs in an inconsistent state when executed within a
+ search---that is to say, the following things may be changed by a
+ command only temporarily, and must be restored before the command
+ finishes:
+ 
+ @enumerate
+ @item
+ Point.
+ @item
+ The buffer contents.
+ @item
+ The selected window and selected frame.
+ @item
+ The current match-data.  @xref{Match Data,,, elisp, The Emacs Lisp
+ Reference Manual}.
+ @end enumerate
+ 
+ Additionally, the command must not delete the current window and must
+ not itself attempt an incremental search.  It may, however, change the
+ window's size, or create or delete other windows and frames.
+ 
+ Note that an attempt by a command to scroll the text
+ @emph{horizontally} won't work, although it will do no harm---any such
+ scrolling will be overridden and nullified by the display code.
+ 
+ @node Replace, Other Repeating Search, Configuring Scrolling, Search
+ @section Replacement Commands
+ @cindex replacement
+ @cindex search-and-replace commands
+ @cindex string substitution
+ @cindex global substitution
+ 
+   Global search-and-replace operations are not needed often in Emacs,
+ but they are available.  In addition to the simple @kbd{M-x
+ replace-string} command which replaces all occurrences,
+ there is a @kbd{M-x query-replace} command which finds each occurrence
+ of the pattern and asks you whether to replace it.
+ 
+   The replace commands normally operate on the text from point to the
+ end of the buffer; however, in Transient Mark mode (@pxref{Transient
+ Mark}), when the mark is active, they operate on the region.  The
+ replace commands all replace one string (or regexp) with one
+ replacement string.  It is possible to perform several replacements in
+ parallel using the command @code{expand-region-abbrevs}
+ (@pxref{Expanding Abbrevs}).
+ 
+ @menu
+ * Unconditional Replace::     Replacing all matches for a string.
+ * Regexp Replace::            Replacing all matches for a regexp.
+ * Replacement and Case::      How replacements preserve case of letters.
+ * Query Replace::             How to use querying.
+ @end menu
+ 
+ @node Unconditional Replace, Regexp Replace, Replace, Replace
+ @subsection Unconditional Replacement
+ @findex replace-string
+ @findex replace-regexp
+ 
+ @table @kbd
+ @item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} 
@key{RET}
+ Replace every occurrence of @var{string} with @var{newstring}.
+ @item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} 
@key{RET}
+ Replace every match for @var{regexp} with @var{newstring}.
+ @end table
+ 
+   To replace every instance of @samp{foo} after point with @samp{bar},
+ use the command @kbd{M-x replace-string} with the two arguments
+ @samp{foo} and @samp{bar}.  Replacement happens only in the text after
+ point, so if you want to cover the whole buffer you must go to the
+ beginning first.  All occurrences up to the end of the buffer are
+ replaced; to limit replacement to part of the buffer, narrow to that
+ part of the buffer before doing the replacement (@pxref{Narrowing}).
+ In Transient Mark mode, when the region is active, replacement is
+ limited to the region (@pxref{Transient Mark}).
+ 
+   When @code{replace-string} exits, it leaves point at the last
+ occurrence replaced.  It sets the mark to the prior position of point
+ (where the @code{replace-string} command was issued); use @kbd{C-u
+ address@hidden to move back there.
+ 
+   A numeric argument restricts replacement to matches that are surrounded
+ by word boundaries.  The argument's value doesn't matter.
+ 
+   What if you want to exchange @samp{x} and @samp{y}: replace every @samp{x} 
with a @samp{y} and vice versa?  You can do it this way:
+ 
+ @example
+ M-x replace-string @key{RET} x @key{RET} @@TEMP@@ @key{RET}
+ M-< M-x replace-string @key{RET} y @key{RET} x @key{RET}
+ M-< M-x replace-string @key{RET} @@TEMP@@ @key{RET} y @key{RET}
+ @end example
+ 
+ @noindent
+ This works provided the string @samp{@@TEMP@@} does not appear
+ in your text.
+ 
+ @node Regexp Replace, Replacement and Case, Unconditional Replace, Replace
+ @subsection Regexp Replacement
+ 
+   The @kbd{M-x replace-string} command replaces exact matches for a
+ single string.  The similar command @kbd{M-x replace-regexp} replaces
+ any match for a specified pattern.
+ 
+   In @code{replace-regexp}, the @var{newstring} need not be constant:
+ it can refer to all or part of what is matched by the @var{regexp}.
+ @samp{\&} in @var{newstring} stands for the entire match being
+ replaced.  @address@hidden in @var{newstring}, where @var{d} is a
+ digit, stands for whatever matched the @var{d}th parenthesized
+ grouping in @var{regexp}.  @samp{\#} refers to the count of
+ replacements already made in this command, as a decimal number.  In
+ the first replacement, @samp{\#} stands for @samp{0}; in the second,
+ for @samp{1}; and so on.  For example,
+ 
+ @example
+ M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET}
+ @end example
+ 
+ @noindent
+ replaces (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr}
+ with @samp{cddr-safe}.
+ 
+ @example
+ M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET}
+ @end example
+ 
+ @noindent
+ performs the inverse transformation.  To include a @samp{\} in the
+ text to replace with, you must enter @samp{\\}.
+ 
+   You can also use Lisp expressions to calculate parts of the
+ replacement string.  To do this, write @samp{\,} followed by the
+ expression in the replacement string.  Each replacement calculates the
+ value of the expression and converts it to text without quoting (if
+ it's a string, this means using the string's contents), and uses it in
+ the replacement string in place of the expression itself.  If the
+ expression is a symbol, one space in the replacement string after the
+ symbol name goes with the symbol name, so the value replaces them
+ both.
+ 
+   Inside such an expression, you can use some special sequences.
+ @samp{\&} and @address@hidden refer here, as usual, to the entire
+ match as a string, and to a submatch as a string.  @var{n} may be
+ multiple digits, and the value of @address@hidden is @code{nil} if
+ subexpression @var{n} did not match.  You can also use @samp{\#&} and
+ @address@hidden to refer to those matches as numbers (this is valid
+ when the match or submatch has the form of a numeral).  @samp{\#} here
+ too stands for the number of already-completed replacements.
+ 
+   Repeating our example to exchange @samp{x} and @samp{y}, we can thus
+ do it also this way:
+ 
+ @example
+ M-x replace-regexp @key{RET} \(x\)\|y @key{RET}
+ \,(if \1 "y" "x") @key{RET}
+ @end example
+ 
+   For computing replacement strings for @samp{\,}, the @code{format}
+ function is often useful (@pxref{Formatting Strings,,, elisp, The Emacs
+ Lisp Reference Manual}).  For example, to add consecutively numbered
+ strings like @samp{ABC00042} to columns 73 @w{to 80} (unless they are
+ already occupied), you can use
+ 
+ @example
+ M-x replace-regexp @key{RET} address@hidden,address@hidden @key{RET}
+ \,(format "%-72sABC%05d" \& \#) @key{RET}
+ @end example
+ 
+   If you want to enter part of the replacement string by hand each
+ time, use @samp{\?} in the replacement string.  Each replacement will
+ ask you to edit the replacement string in the minibuffer, putting
+ point where the @samp{\?} was.  For example,
+ 
+ @example
+ M-x replace-regexp @key{RET} address@hidden @key{RET}
+ \&address@hidden:address@hidden @key{RET}
+ @end example
+ 
+ @noindent
+ will add labels starting with @address@hidden:address@hidden to occurrences of
+ @address@hidden, but letting you edit each replacement before
+ performing it.  To number the labels starting at 1, use @samp{\,(1+
+ \#)} instead of @samp{\#}.
+ 
+ @node Replacement and Case, Query Replace, Regexp Replace, Replace
+ @subsection Replace Commands and Case
+ 
+   If the first argument of a replace command is all lower case, the
+ command ignores case while searching for occurrences to
+ replace---provided @code{case-fold-search} is address@hidden  If
+ @code{case-fold-search} is set to @code{nil}, case is always significant
+ in all searches.
+ 
+ @vindex case-replace
+   In addition, when the @var{newstring} argument is all or partly lower
+ case, replacement commands try to preserve the case pattern of each
+ occurrence.  Thus, the command
+ 
+ @example
+ M-x replace-string @key{RET} foo @key{RET} bar @key{RET}
+ @end example
+ 
+ @noindent
+ replaces a lower case @samp{foo} with a lower case @samp{bar}, an
+ all-caps @samp{FOO} with @samp{BAR}, and a capitalized @samp{Foo} with
+ @samp{Bar}.  (These three alternatives---lower case, all caps, and
+ capitalized, are the only ones that @code{replace-string} can
+ distinguish.)
+ 
+   If upper-case letters are used in the replacement string, they remain
+ upper case every time that text is inserted.  If upper-case letters are
+ used in the first argument, the second argument is always substituted
+ exactly as given, with no case conversion.  Likewise, if either
+ @code{case-replace} or @code{case-fold-search} is set to @code{nil},
+ replacement is done without case conversion.
+ 
+ @node Query Replace,, Replacement and Case, Replace
+ @subsection Query Replace
+ @cindex query replace
+ 
+ @table @kbd
+ @item M-% @var{string} @key{RET} @var{newstring} @key{RET}
+ @itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} 
@key{RET}
+ Replace some occurrences of @var{string} with @var{newstring}.
+ @item C-M-% @var{regexp} @key{RET} @var{newstring} @key{RET}
+ @itemx M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} 
@var{newstring} @key{RET}
+ Replace some matches for @var{regexp} with @var{newstring}.
+ @end table
+ 
+ @kindex M-%
+ @findex query-replace
+   If you want to change only some of the occurrences of @samp{foo} to
+ @samp{bar}, not all of them, then you cannot use an ordinary
+ @code{replace-string}.  Instead, use @kbd{M-%} (@code{query-replace}).
+ This command finds occurrences of @samp{foo} one by one, displays each
+ occurrence and asks you whether to replace it.  Aside from querying,
+ @code{query-replace} works just like @code{replace-string}.  It
+ preserves case, like @code{replace-string}, provided
+ @code{case-replace} is address@hidden, as it normally is.  A numeric
+ argument means consider only occurrences that are bounded by
+ word-delimiter characters.
+ 
+ @kindex C-M-%
+ @findex query-replace-regexp
+   @kbd{C-M-%} performs regexp search and replace 
(@code{query-replace-regexp}).
+ 
+   The characters you can type when you are shown a match for the string
+ or regexp are:
+ 
+ @ignore @c Not worth it.
+ @kindex SPC @r{(query-replace)}
+ @kindex DEL @r{(query-replace)}
+ @kindex , @r{(query-replace)}
+ @kindex RET @r{(query-replace)}
+ @kindex . @r{(query-replace)}
+ @kindex ! @r{(query-replace)}
+ @kindex ^ @r{(query-replace)}
+ @kindex C-r @r{(query-replace)}
+ @kindex C-w @r{(query-replace)}
+ @kindex C-l @r{(query-replace)}
+ @end ignore
+ 
+ @c WideCommands
+ @table @kbd
+ @item @key{SPC}
+ to replace the occurrence with @var{newstring}.
+ 
+ @item @key{DEL}
+ to skip to the next occurrence without replacing this one.
+ 
+ @item , @r{(Comma)}
+ to replace this occurrence and display the result.  You are then asked
+ for another input character to say what to do next.  Since the
+ replacement has already been made, @key{DEL} and @key{SPC} are
+ equivalent in this situation; both move to the next occurrence.
+ 
+ You can type @kbd{C-r} at this point (see below) to alter the replaced
+ text.  You can also type @kbd{C-x u} to undo the replacement; this exits
+ the @code{query-replace}, so if you want to do further replacement you
+ must use @kbd{C-x @key{ESC} @key{ESC} @key{RET}} to restart
+ (@pxref{Repetition}).
+ 
+ @item @key{RET}
+ to exit without doing any more replacements.
+ 
+ @item .@: @r{(Period)}
+ to replace this occurrence and then exit without searching for more
+ occurrences.
+ 
+ @item !
+ to replace all remaining occurrences without asking again.
+ 
+ @item ^
+ to go back to the position of the previous occurrence (or what used to
+ be an occurrence), in case you changed it by mistake or want to
+ reexamine it.
+ 
+ @item C-r
+ to enter a recursive editing level, in case the occurrence needs to be
+ edited rather than just replaced with @var{newstring}.  When you are
+ done, exit the recursive editing level with @kbd{C-M-c} to proceed to
+ the next occurrence.  @xref{Recursive Edit}.
+ 
+ @item C-w
+ to delete the occurrence, and then enter a recursive editing level as in
+ @kbd{C-r}.  Use the recursive edit to insert text to replace the deleted
+ occurrence of @var{string}.  When done, exit the recursive editing level
+ with @kbd{C-M-c} to proceed to the next occurrence.
+ 
+ @item e
+ to edit the replacement string in the minibuffer.  When you exit the
+ minibuffer by typing @key{RET}, the minibuffer contents replace the
+ current occurrence of the pattern.  They also become the new
+ replacement string for any further occurrences.
+ 
+ @item C-l
+ to redisplay the screen.  Then you must type another character to
+ specify what to do with this occurrence.
+ 
+ @item C-h
+ to display a message summarizing these options.  Then you must type
+ another character to specify what to do with this occurrence.
+ @end table
+ 
+   Some other characters are aliases for the ones listed above: @kbd{y},
+ @kbd{n} and @kbd{q} are equivalent to @key{SPC}, @key{DEL} and
+ @key{RET}.
+ 
+   Aside from this, any other character exits the @code{query-replace},
+ and is then reread as part of a key sequence.  Thus, if you type
+ @kbd{C-k}, it exits the @code{query-replace} and then kills to end of
+ line.
+ 
+   To restart a @code{query-replace} once it is exited, use @kbd{C-x
+ @key{ESC} @key{ESC}}, which repeats the @code{query-replace} because it
+ used the minibuffer to read its arguments.  @xref{Repetition, C-x ESC
+ ESC}.
+ 
+   See also @ref{Transforming File Names}, for Dired commands to rename,
+ copy, or link files by replacing regexp matches in file names.
+ 
+ @node Other Repeating Search,, Replace, Search
+ @section Other Search-and-Loop Commands
+ 
+   Here are some other commands that find matches for a regular
+ expression.  They all ignore case in matching, if the pattern contains
+ no upper-case letters and @code{case-fold-search} is address@hidden
+ Aside from @code{occur} and its variants, all operate on the text from
+ point to the end of the buffer, or on the active region in Transient
+ Mark mode.
+ 
+ @findex list-matching-lines
+ @findex occur
+ @findex multi-occur
+ @findex multi-occur-by-filename-regexp
+ @findex how-many
+ @findex delete-non-matching-lines
+ @findex delete-matching-lines
+ @findex flush-lines
+ @findex keep-lines
+ 
+ @table @kbd
+ @item M-x occur @key{RET} @var{regexp} @key{RET}
+ Display a list showing each line in the buffer that contains a match
+ for @var{regexp}.  To limit the search to part of the buffer, narrow
+ to that part (@pxref{Narrowing}).  A numeric argument @var{n}
+ specifies that @var{n} lines of context are to be displayed before and
+ after each matching line.
+ 
+ @kindex RET @r{(Occur mode)}
+ @kindex o @r{(Occur mode)}
+ @kindex C-o @r{(Occur mode)}
+ The buffer @samp{*Occur*} containing the output serves as a menu for
+ finding the occurrences in their original context.  Click
+ @kbd{Mouse-2} on an occurrence listed in @samp{*Occur*}, or position
+ point there and type @key{RET}; this switches to the buffer that was
+ searched and moves point to the original of the chosen occurrence.
+ @kbd{o} and @kbd{C-o} display the match in another window; @kbd{C-o}
+ does not select it.
+ 
+ Occur mode supports the @code{next-error} functionality described in
+ in @ref{Compilation Mode}.
+ 
+ @item M-x list-matching-lines
+ Synonym for @kbd{M-x occur}.
+ 
+ @item M-x multi-occur @key{RET} @var{buffers} @key{RET} @var{regexp} @key{RET}
+ This function is just like @code{occur}, except it is able to search
+ through multiple buffers.
+ 
+ @item M-x multi-occur-by-filename-regexp @key{RET} @var{bufregexp} @key{RET} 
@var{regexp} @key{RET}
+ This function is similar to @code{multi-occur}, except the buffers to
+ search are specified by a regexp on their filename.
+ 
+ @item M-x how-many @key{RET} @var{regexp} @key{RET}
+ Print the number of matches for @var{regexp} that exist in the buffer
+ after point.  In Transient Mark mode, if the region is active, the
+ command operates on the region instead.
+ 
+ @item M-x flush-lines @key{RET} @var{regexp} @key{RET}
+ Delete each line that contains a match for @var{regexp}, operating on
+ the text after point.  In Transient Mark mode, if the region is
+ active, the command operates on the region instead.
+ 
+ @item M-x keep-lines @key{RET} @var{regexp} @key{RET}
+ Delete each line that @emph{does not} contain a match for
+ @var{regexp}, operating on the text after point.  In Transient Mark
+ mode, if the region is active, the command operates on the region
+ instead.
+ @end table
+ 
+   You can also search multiple files under control of a tags table
+ (@pxref{Tags Search}) or through Dired @kbd{A} command
+ (@pxref{Operating on Files}), or ask the @code{grep} program to do it
+ (@pxref{Grep Searching}).
+ 
+ @ignore
+    arch-tag: fd9d8e77-66af-491c-b212-d80999613e3e
+ @end ignore