Re: Search/Replace manual changes.

[Juri Linkov]

David Kastrup <address@hidden> writes:
>  @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}
> +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

I think this example should be removed from the Emacs manual completely.
Using three commands to exchange words is too clumsy.  When reading
the Emacs manual the users will mis-spend their time at understanding
and remembering this example not knowing that a better method to do this
is shown in the next chapter.

If an example for `replace-string' is absolutely necessary we could
write a better example.  If not necessary, no example is still better
than a bad example.

> +  You can also use arbitrary Lisp expressions evaluated at replacement
> +time by placing @samp{\,} before them in the replacement string.  Inside
> +of those expressions, the symbols @samp{\&} and @address@hidden refer to
> +match and submatch strings like described above (a submatch not matching
> +anything will be @samp{nil}), and @samp{\&#} and @address@hidden to

This looks like a typo: this should be @samp{\#&} and @address@hidden

> +those strings converted to numbers.  @samp{\#} is short for
> address@hidden, the number of already completed replacements.
> +This particular shorthand can also be used outside of @samp{\,}.
> +
> +  Repeating our example to exchange @samp{x} and @samp{y}, we can thus
> +do it also this way:
> +
> address@hidden
> +M-x replace-regexp @key{RET} \(x\)\|y @key{RET}
> +\,(if \1 "y" "x") @key{RET}
> address@hidden example
> +
> +  Another feature you can use in the replacement string of Regexp
> +commands is @samp{\?}.  In that case you will be allowed to edit the
> +replacement string at the given position before the replacement gets
> +performed.  Lisp style replacements have already been done before
> address@hidden is executed.  For example,
> +
> address@hidden
> +M-x replace-regexp @key{RET} address@hidden @key{RET}
> +\&address@hidden:address@hidden @key{RET}
> address@hidden example
> +
> address@hidden
> +will add labels starting with @address@hidden:address@hidden to occurences of
> address@hidden@{}, but letting you edit each replacement before
> +performing it.  If you want labels starting at 1, use @samp{\,(1+ \#)}
> +instead of @samp{\#}.
> +
> +As another example, to add consecutively numbered strings like
> address@hidden to column 73 to~80 (unless they are already occupied),
> +you can use
> +
> address@hidden
> +M-x replace-regexp @key{RET} address@hidden,address@hidden @key{RET}
> +\,(format "%-72sABC%05d" \& \#) @key{RET}
> address@hidden example

Do we really need this ancient punched card 80-column filling example?
Perhaps there are enough examples already.  The previous example with
adding labels shows most features: \&, \# and \?.  It have no \,
but \, could be added to the same example as well, e.g.:

M-x replace-regexp @key{RET} address@hidden @key{RET}
\&address@hidden:\,(format "%05d" (1+ \#))address@hidden @key{RET}

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