(Regexp Replace): Rewrite description of \# \, and \?.

1 files changed, 40 insertions, 29 deletions

diff --git a/man/search.texi b/man/search.texi
index 6eafedf7749..4577ac4b33e 100644
--- a/man/search.texi
+++ b/man/search.texi
@@ -993,13 +993,15 @@ in your text.
 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.
-@samp{\@var{d}} in @var{newstring}, where @var{d} is a digit, stands for
-whatever matched the @var{d}th parenthesized grouping in @var{regexp}.
-To include a @samp{\} in the text to replace with, you must enter
-@samp{\\}.  For example,
+  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.  @samp{\@var{d}} 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}
@@ -1014,17 +1016,26 @@ M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET}
 @end example
 
 @noindent
-performs the inverse transformation.
-
-  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{n}} refer to
-match and submatch strings like described above (though @var{n} may
-exceed 9 here, and you get @code{nil} if nothing matches).  @samp{\#&}
-and @samp{\#@var{n}} refer to 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{\,}.
+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, which ought to be a string, 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 counts as part of the symbol name, so the value replaces
+them both.
+
+  Inside such an expression, @samp{\&} and @samp{\@var{n}} used as
+subexpressions refer respectively to the entire match as a string, and
+to a submatch as a string.  @var{n} may exceed 9 here, and the value
+of @samp{\@var{n}} is @code{nil} if subexpression @var{n} did not
+match.  You can also use @samp{\#&} and @samp{\#@var{n}} refer to
+those matches converted to numbers (this is valid when the match or
+submatch has the form of a number).  @samp{\#} 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:
@@ -1034,21 +1045,21 @@ M-x replace-regexp @key{RET} \(x\)\|y @key{RET}
 \,(if \1 "y" "x") @key{RET}
 @end example
 
-  One function that comes handy in Lisp replacements is @samp{format}
-(@pxref{Formatting Strings,,,elisp, GNU 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
+  The @code{format} function (@pxref{Formatting Strings,,,elisp, GNU
+Emacs Lisp Reference Manual}) comes in handy for computing replacement
+strings for @samp{\,}.  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} ^.\@{0,72\@}$ @key{RET}
 \,(format "%-72sABC%05d" \& \#) @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 are performed before @samp{\?} gets
-executed.  For example,
+  If you want to enter part of the replacement string by hand each
+time, use @samp{\?} in the replacement string.  Each replacement will
+enter a recursive edit, with point at the position where the @samp{\?}
+was.  For example,
 
 @example
 M-x replace-regexp @key{RET} \footnote@{ @key{RET}
@@ -1058,8 +1069,8 @@ M-x replace-regexp @key{RET} \footnote@{ @key{RET}
 @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{\#}.
+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