* Search/Replace manual changes.
@ 2004-06-24 13:44 David Kastrup
2004-06-24 16:07 ` Juri Linkov
0 siblings, 1 reply; 6+ messages in thread
From: David Kastrup @ 2004-06-24 13:44 UTC (permalink / raw)
[-- 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
^ permalink raw reply [flat|nested] 6+ messages in thread* Re: Search/Replace manual changes.
2004-06-24 13:44 Search/Replace manual changes David Kastrup
@ 2004-06-24 16:07 ` Juri Linkov
2004-06-24 22:00 ` David Kastrup
2004-06-25 23:56 ` Richard Stallman
0 siblings, 2 replies; 6+ messages in thread
From: Juri Linkov @ 2004-06-24 16:07 UTC (permalink / raw)
Cc: emacs-devel
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/
^ permalink raw reply [flat|nested] 6+ messages in thread* Re: Search/Replace manual changes.
2004-06-24 16:07 ` Juri Linkov
@ 2004-06-24 22:00 ` David Kastrup
2004-06-25 0:18 ` Juri Linkov
2004-06-25 23:56 ` Richard Stallman
1 sibling, 1 reply; 6+ messages in thread
From: David Kastrup @ 2004-06-24 22:00 UTC (permalink / raw)
Cc: emacs-devel
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
^ permalink raw reply [flat|nested] 6+ messages in thread* Re: Search/Replace manual changes.
2004-06-24 22:00 ` David Kastrup
@ 2004-06-25 0:18 ` Juri Linkov
2004-06-25 7:28 ` David Kastrup
0 siblings, 1 reply; 6+ messages in thread
From: Juri Linkov @ 2004-06-25 0:18 UTC (permalink / raw)
Cc: emacs-devel
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/
^ permalink raw reply [flat|nested] 6+ messages in thread* Re: Search/Replace manual changes.
2004-06-25 0:18 ` Juri Linkov
@ 2004-06-25 7:28 ` David Kastrup
0 siblings, 0 replies; 6+ messages in thread
From: David Kastrup @ 2004-06-25 7:28 UTC (permalink / raw)
Cc: emacs-devel
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Search/Replace manual changes.
2004-06-24 16:07 ` Juri Linkov
2004-06-24 22:00 ` David Kastrup
@ 2004-06-25 23:56 ` Richard Stallman
1 sibling, 0 replies; 6+ messages in thread
From: Richard Stallman @ 2004-06-25 23:56 UTC (permalink / raw)
Cc: dak, emacs-devel
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.
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2004-06-25 23:56 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2004-06-24 13:44 Search/Replace manual changes David Kastrup
2004-06-24 16:07 ` Juri Linkov
2004-06-24 22:00 ` David Kastrup
2004-06-25 0:18 ` Juri Linkov
2004-06-25 7:28 ` David Kastrup
2004-06-25 23:56 ` Richard Stallman
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).