Search nodes in Emacs manual

[Juri Linkov]

I checked search and replace related nodes of the Emacs manual
and found some omissions and inaccuracies.

1. (info "(emacs)Incremental Search")

1.1. This Info node doesn't mention the M-e key.  It could be documented
in the paragraph about the minibuffer in isearch mode.

1.2. M-s is listed among other keybindings, but currently is unbound in
isearch mode.  It can be replaced by other keybindings M-c and M-e.

2. (info "(emacs)Regexp Search")

M-r is not documented as a key to switch to regexp mode in isearch
invoked by C-s or C-r.

3. (info "(emacs)Replace")

The first paragraph of this node:

    Global search-and-replace operations are not needed often in Emacs, but
    they are available.  In addition to the simple `M-x replace-string'
    command which is like that found in most editors, there is a `M-x
    query-replace' command which finds each occurrence of the pattern and
    asks you whether to replace it.

Why search-and-replace is not needed often in Emacs?  The fact how
often users use search-and-replace completely depends on needs of 
every user, so, no such generalization is possible.

The whole paragraph looks like comparing Emacs with some ancient
editors which have no interactive query-replace operations and where
search-and-replace operations are the only convenient way to make
changes.  This looks very strange nowadays.

3. (info "(emacs)Unconditional Replace")

This node describes the command `replace-string', but the example
in the same node demonstrates the use of the `query-replace' command.
This could be changed to:

    M-x replace-string <RET> x <RET> @TEMP@ <RET>
    M-x replace-string <RET> y <RET> x <RET>
    M-x replace-string <RET> @TEMP@ <RET> y <RET>

But perhaps with the latest changes this example can be replaced
with more advanced like this:

    M-x replace-regexp <RET> \(x\|y\) <RET> \,(if (equal \& "x") "y" "x") <RET>

BTW, `replace-regexp' currently doesn't support evaluation of the
replacement string as `query-replace-regexp' now does, but I think
it should.



Index: man/search.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/man/search.texi,v
retrieving revision 1.44
diff -c -r1.44 search.texi
*** man/search.texi     19 May 2004 18:50:38 -0000      1.44
--- man/search.texi     18 Jun 2004 18:03:02 -0000
***************
*** 78,84 ****
  @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-s}, and some other
  meta-characters).
  
    Sometimes you search for @samp{FOO} and find one, but not the one you
--- 78,84 ----
  @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
***************
*** 95,102 ****
    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.  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
--- 95,104 ----
    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 you can 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
***************
*** 371,384 ****
  @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}), or by invoking @kbd{C-s} with a
! prefix argument (whose value does not matter).  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}), or @kbd{C-r} with a prefix argument.
  
    All of the control characters that do special things within an
  ordinary incremental search have the same function in incremental regexp
--- 381,396 ----
  @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 an incremental search invoked by @kbd{C-s}.  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 an incremental search invoked by @kbd{C-r}.
  
    All of the control characters that do special things within an
  ordinary incremental search have the same function in incremental regexp
***************
*** 923,933 ****
  @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 is like that found in most editors,
! 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
--- 935,945 ----
  @cindex string substitution
  @cindex global substitution
  
!   Global search-and-replace operations are sometimes needed in Emacs.
! 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
***************
*** 977,985 ****
    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 query-replace @key{RET} x @key{RET} @@TEMP@@ @key{RET}
! M-x query-replace @key{RET} y @key{RET} x @key{RET}
! M-x query-replace @key{RET} @@TEMP@@ @key{RET} y @key{RET}
  @end example
  
  @noindent
--- 989,997 ----
    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-x replace-string @key{RET} y @key{RET} x @key{RET}
! M-x replace-string @key{RET} @@TEMP@@ @key{RET} y @key{RET}
  @end example
  
  @noindent

-- 
Juri Linkov
http://www.jurta.org/emacs/