Search nodes in Emacs manual

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/

Re: Search nodes in Emacs manual

[David Kastrup]

Juri Linkov <juri@jurta.org> writes:

> 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>

Cute.  Of course \(x\|y\) is shorter as [xy]

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

It already does in my current code, but as I said, I am currently
trying to get a grip about how to deal with the replacement history
properly.

If I don't manage that, I'll basically leave the old (problematic)
behavior, which is somewhat exacerbated by having \?, and thus more
of a possibility of the user getting the search/replacement confused
if he is mean.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Search nodes in Emacs manual

[Richard Stallman]

	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?

In some editors, these commands are the main way to make changes.
In Emacs, you make most changes directly.

These changes are good, except:

    ! 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}.

...search ring, type @kbd{M-e}.

    ! (@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}.

...within a forward incremental search.

    ! or @kbd{M-r} within an incremental search invoked by @kbd{C-r}.

...within a backward incremental search.

    !   Global search-and-replace operations are sometimes needed in Emacs.

That statement is does not really tell the user anything.  So it makes
no sense to include this text.  Either leave the old text, or write
new text that makes more sense.

Re: Search nodes in Emacs manual

[Juri Linkov]

David Kastrup <dak@gnu.org> writes:
> Juri Linkov <juri@jurta.org> writes:
>> 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>
>
> Cute.  Of course \(x\|y\) is shorter as [xy]

I intended to make it as an example of exchanging words which might
be more useful than exchanging characters.  So that example
could be rewritten as something like below, and be placed into
(info "(emacs)Regexp Replace") instead of the current
(info "(emacs)Unconditional Replace"), or to the same node
where you might document this new feature.

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

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

Re: Search nodes in Emacs manual

[David Kastrup]

Juri Linkov <juri@jurta.org> writes:

> David Kastrup <dak@gnu.org> writes:
> > Juri Linkov <juri@jurta.org> writes:
> >> 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>
> >
> > Cute.  Of course \(x\|y\) is shorter as [xy]
> 
> I intended to make it as an example of exchanging words which might
> be more useful than exchanging characters.  So that example
> could be rewritten as something like below, and be placed into
> (info "(emacs)Regexp Replace") instead of the current
> (info "(emacs)Unconditional Replace"), or to the same node
> where you might document this new feature.
> 
>   M-x replace-regexp <RET> \(ab\|cd\) <RET>
>                            \,(if (equal \& "ab") "cd" "ab") <RET>

You'd better use string=, or font-lock might surprise you.

How about

M-x replace-regexp <RET> \(\(ab\)\|cd\) <RET>
                         \,(if \2 "cd" "ab") <RET>

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Search nodes in Emacs manual

[Juri Linkov]

David Kastrup <dak@gnu.org> writes:
> How about
>
> M-x replace-regexp <RET> \(\(ab\)\|cd\) <RET>
>                          \,(if \2 "cd" "ab") <RET>

Very nice!

You only need to remove redundant parens and this example can be added
to the Emacs manual.

M-x replace-regexp <RET> \(ab\)\|cd <RET> \,(if \1 "cd" "ab") <RET>

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

Re: Search nodes in Emacs manual

[Juri Linkov]

David Kastrup <dak@gnu.org> writes:
> Juri Linkov <juri@jurta.org> writes:
>> BTW, `replace-regexp' currently doesn't support evaluation of the
>> replacement string as `query-replace-regexp' now does, but I think
>> it should.
>
> It already does in my current code, but as I said, I am currently
> trying to get a grip about how to deal with the replacement history
> properly.

I also noticed that the command `map-query-replace-regexp' can be
rewritten using the feature of replacement string evaluation
with a very simple replacement expression like:

    (nth (mod (/ \# 2) 3) '("ab" "cd" "ef"))

where 2 means how many times to use each replacement string before
rotating to the next (this is the third arg of `map-query-replace-regexp'),
and 3 is the length of the word list.

Perhaps, 33 lines of `map-query-replace-regexp' and 12 lines of
`replace-loop-through-replacements' should be simplified with a few
lines using the evaluation feature.  Below is an example how
`map-query-replace-regexp' could basically look: (the first line of
variables below are just sample values, they will be replaced with
input values if such a rewrite of `map-query-replace-regexp' is ok).

(let* ((regexp "[a-z]+") (to-string "ab cd df") (n 2) start end
       (to-strings (split-string to-string " " t))
       (replacements `(nth (mod (/ replace-count ,n) ,(length to-strings))
                           ',to-strings)))
  (perform-replace regexp
                   (cons 'replace-eval-replacement replacements)
                   t t nil nil nil start end))

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