[Emacs-diffs] Changes to emacs/man/search.texi

[Richard M . Stallman]

Index: emacs/man/search.texi
diff -c emacs/man/search.texi:1.46 emacs/man/search.texi:1.47
*** emacs/man/search.texi:1.46  Fri Jun 25 11:02:08 2004
--- emacs/man/search.texi       Fri Jun 25 21:27:55 2004
***************
*** 993,1005 ****
  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.
! @address@hidden 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,
  
  @example
  M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET}
--- 993,1007 ----
  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.  @address@hidden 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,1030 ****
  @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 @address@hidden 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 @address@hidden 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{\,}.
  
    Repeating our example to exchange @samp{x} and @samp{y}, we can thus
  do it also this way:
--- 1016,1041 ----
  @end example
  
  @noindent
! 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 @address@hidden 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 @address@hidden is @code{nil} if subexpression @var{n} did not
! match.  You can also use @samp{\#&} and @address@hidden 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,1054 ****
  \,(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
  
  @example
  M-x replace-regexp @key{RET} address@hidden,address@hidden @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,
  
  @example
  M-x replace-regexp @key{RET} address@hidden @key{RET}
--- 1045,1065 ----
  \,(if \1 "y" "x") @key{RET}
  @end example
  
!   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} address@hidden,address@hidden @key{RET}
  \,(format "%-72sABC%05d" \& \#) @key{RET}
  @end 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} address@hidden @key{RET}
***************
*** 1058,1065 ****
  @noindent
  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{\#}.
  
  @node Replacement and Case, Query Replace, Regexp Replace, Replace
  @subsection Replace Commands and Case
--- 1069,1076 ----
  @noindent
  will add labels starting with @address@hidden:address@hidden to occurences of
  @address@hidden, but letting you edit each replacement before
! 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