Search/Replace manual changes.

Search/Replace manual changes.

[David Kastrup]

[-- Attachment #1: Type: text/plain, Size: 177 bytes --]


Ok, here are revised manual entries.  I am checking them in now, so
you can take changes from there.  I think that the added examples are
instructive enough to keep them all.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Type: text/x-patch, Size: 3021 bytes --]

--- search.texi	21 May 2004 00:24:35 +0200	1.44
+++ search.texi	24 Jun 2004 15:19:43 +0200	
@@ -977,9 +977,9 @@
   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}
+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
 
 @noindent
@@ -1016,6 +1016,49 @@
 @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{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
+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
+
 @node Replacement and Case, Query Replace, Regexp Replace, Replace
 @subsection Replace Commands and Case
 
@@ -1126,9 +1169,8 @@
 
 @item ^
 to go back to the position of the previous occurrence (or what used to
-be an occurrence), in case you changed it by mistake.  This works by
-popping the mark ring.  Only one @kbd{^} in a row is meaningful, because
-only one previous replacement position is kept during @code{query-replace}.
+be an occurrence), in case you changed it by mistake or want to
+reexamine it.
 
 @item C-r
 to enter a recursive editing level, in case the occurrence needs to be

[-- Attachment #3: Type: text/plain, Size: 51 bytes --]


-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

[-- Attachment #4: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: Search/Replace manual changes.

[Juri Linkov]

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/

Re: Search/Replace manual changes.

[David Kastrup]

Juri Linkov <juri@jurta.org> writes:

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

But the method in the next chapter requires a basic Lisp
understanding.  It is an advanced technique.  Granted, probably one of
the easiest, and probably a nice incentive for learning, but it is
still an advanced technique.  I don't think we should remove an
example for swapping strings that is accessible also to the beginner.

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

Right.  I'll fix that.

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

It is a non-trivial, yet short example for using "format", which is
certainly another highlight to utilize in the context of `\,'.  In
particular because of the possibilities for using the field widths.

Apart from which I find the example amusing.  It's so "wouldn't it
have been nice if we had this 40 years ago"ish.  And you recognized
it immediately...

> M-x replace-regexp @key{RET} \footnote@{ @key{RET}
> \&\\label@{fn:\,(format "%05d" (1+ \#))\?@} @key{RET}

I prefer having two quite easy examples rather than cramming
everything into one.  If people see a lot of weirdness all too early
and at once, they will just skip it and think "that's rocket science,
anyhow".

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Search/Replace manual changes.

[Juri Linkov]

David Kastrup <dak@gnu.org> writes:
> Juri Linkov <juri@jurta.org> writes:
>> 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.
>
> But the method in the next chapter requires a basic Lisp
> understanding.  It is an advanced technique.  Granted, probably one of
> the easiest, and probably a nice incentive for learning, but it is
> still an advanced technique.

It's not difficult even for beginners to substitute own values
for "x" and "y".

> I don't think we should remove an example for swapping strings that
> is accessible also to the beginner.

This is a bad example.  It teaches Emacs users to use Emacs inefficiently.

If this is a really very frequent operation that needed to be
documented in the Emacs manual then we should implement a new command
in replace.el and document it:

M-x swap-strings RET x RET y RET

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

Re: Search/Replace manual changes.

[David Kastrup]

Juri Linkov <juri@jurta.org> writes:

> David Kastrup <dak@gnu.org> writes:
> > Juri Linkov <juri@jurta.org> writes:
> >> 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.
> >
> > But the method in the next chapter requires a basic Lisp
> > understanding.  It is an advanced technique.  Granted, probably one of
> > the easiest, and probably a nice incentive for learning, but it is
> > still an advanced technique.
> 
> It's not difficult even for beginners to substitute own values
> for "x" and "y".

But the beginner would not want to look up the required Lisp strings
for a simple operation each time in the manual.  The above is just a
_trick_: once you are told it, it sticks.  And it is a short, yet not
non-trivial combination of things.

What kind of example would you prefer?

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Search/Replace manual changes.

[Richard Stallman]

    I think this example should be removed from the Emacs manual completely.
    Using three commands to exchange words is too clumsy.

I don't agree.  This is going to help people think about the command.
Also, it is not an unreasonable method for doing the job.
It calls for a little thought, but no special knowledge.