Re: Search/Replace manual changes.

[Juri Linkov <juri@jurta.org>]

David Kastrup <dak@gnu.org> 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 @samp{\@var{d}} refer to
> +match and submatch strings like described above (a submatch not matching
> +anything will be @samp{nil}), and @samp{\&#} and @samp{\@var{d}#} to

This looks like a typo: this should be @samp{\#&} and @samp{\#@var{d}}.

> +those strings converted to numbers.  @samp{\#} is short for
> +@samp{replace-count}, 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:
> +
> +@example
> +M-x replace-regexp @key{RET} \(x\)\|y @key{RET}
> +\,(if \1 "y" "x") @key{RET}
> +@end 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
> +@samp{\?} is executed.  For example,
> +
> +@example
> +M-x replace-regexp @key{RET} \footnote@{ @key{RET}
> +\&\\label@{fn:\#\?@} @key{RET}
> +@end example
> +
> +@noindent
> +will add labels starting with @samp{\label@{fn:0@}} to occurences of
> +@samp{\footnote@{}, 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
> +@samp{ABC00042} to column 73 to~80 (unless they are already occupied),
> +you can use
> +
> +@example
> +M-x replace-regexp @key{RET} ^.\@{0,72\@}$ @key{RET}
> +\,(format "%-72sABC%05d" \& \#) @key{RET}
> +@end 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} \footnote@{ @key{RET}
\&\\label@{fn:\,(format "%05d" (1+ \#))\?@} @key{RET}

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