should query-replace-regexp-eval be in the manual?

should query-replace-regexp-eval be in the manual?

[Drew Adams]

`query-replace-regexp-eval' is not mentioned in either the Emacs manual or
the Emacs-Lisp manual. Should it be? Should it be compared/contrasted with
using `\,' with `query-replace-regexp'?

(Please, no knee-jerk followups saying that the manuals need not mention
every command. I'm not suggesting such a need. I'm asking about this
command - just asking.)

Re: should query-replace-regexp-eval be in the manual?

[Alan Mackenzie]

Hi, Drew!

On Fri, Apr 13, 2007 at 09:41:53AM -0700, Drew Adams wrote:
> `query-replace-regexp-eval' is not mentioned in either the Emacs manual
> or the Emacs-Lisp manual. Should it be? Should it be
> compared/contrasted with using `\,' with `query-replace-regexp'?

Hmm.  I didn't know about this command (which supports the notion it
should be documented).  It was actually introduced in Emacs 21.  More
precisely, it was written by Christopher J. Madsen and committed on
1999-08-03.

Is the command useful?  I get the feeling it was written for some fairly
specific task, but somehow hasn't gelled.  Then again, a short while ago
I went through my personal log files replacing things like "2005/6/2"
with "2005-06-02" and I did this with a rather tortuous sequence of
C-M-%'s.  Maybe q-r-r-eval would have done the job more efficiently.

Thinking about it, I believe it _should_ be documented in the Emacs
manual, and that description should contain an example.

Drew, do you actually use this command?  If so, how?

> (Please, no knee-jerk followups saying that the manuals need not
> mention every command. I'm not suggesting such a need. I'm asking about
> this command - just asking.)

:-)

-- 
Alan.

RE: should query-replace-regexp-eval be in the manual?

[Drew Adams]

> Drew, do you actually use this command?  If so, how?

I haven't used it yet - except a few times to try it out, after stumbling
upon it in the source code. It worked fine.

For those who are familiar with this command and with using `\,' with
`query-replace-regexp': Could you compare/contrast these two in terms of use
cases?

Re: should query-replace-regexp-eval be in the manual?

[David Kastrup]

"Drew Adams" <drew.adams@oracle.com> writes:

>> Drew, do you actually use this command?  If so, how?
>
> I haven't used it yet - except a few times to try it out, after stumbling
> upon it in the source code. It worked fine.
>
> For those who are familiar with this command and with using `\,' with
> `query-replace-regexp': Could you compare/contrast these two in terms of use
> cases?

query-replace-regexp-eval can do nothing that one can't achieve with a
use of a \, expression in query-replace-regexp.

In contrast to query-replace-regexp-eval, \, does not necessitate
deciding in advance that you are going to need Lisp for a job, and
you'll only need to use Lisp for those parts of the expression where
it is necessary.

I came up with the idea of \, after stumbling upon
query-replace-regexp-eval and noticing that the typical usage pattern
was to start something with C-M-%, type stuff into it, then do a
combination of C-k, C-g, C-M-Esc or other things I don't remember
right now, in order to restart the whole process using
query-replace-regexp-eval instead.  And query-replace-regexp-eval does
not have a keybinding of its own.

Basically it has been my experience that query-replace-regexp-eval is
a nice idea, but in practice quite unusable.  \, achieves a similar
purpose but with a much more convenient interface.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: should query-replace-regexp-eval be in the manual?

[David Kastrup]

David Kastrup <dak@gnu.org> writes:

> Basically it has been my experience that query-replace-regexp-eval
> is a nice idea, but in practice quite unusable.  \, achieves a
> similar purpose but with a much more convenient interface.

To get back to the original question: since \, has all of the
functionality of query-replace-regexp-eval with a more convenient
interface, query-replace-regexp-eval could be considered obsolete or
at least obscure.

Since we tell people how to do the same thing more flexibly with \, I
don't think that query-replace-regexp-eval deserves a place in the
manual.  It would be a lot of additional explanation without any
conceivable benefit to the user.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: should query-replace-regexp-eval be in the manual?

[Lennart Borgman (gmail)]

David Kastrup wrote:
> David Kastrup <dak@gnu.org> writes:
> 
>> Basically it has been my experience that query-replace-regexp-eval
>> is a nice idea, but in practice quite unusable.  \, achieves a
>> similar purpose but with a much more convenient interface.
> 
> To get back to the original question: since \, has all of the
> functionality of query-replace-regexp-eval with a more convenient
> interface, query-replace-regexp-eval could be considered obsolete or
> at least obscure.
> 
> Since we tell people how to do the same thing more flexibly with \, I
> don't think that query-replace-regexp-eval deserves a place in the
> manual.  It would be a lot of additional explanation without any
> conceivable benefit to the user.

After reading this I think it would be a good idea to tell in the doc 
string for query-replace-regexp-eval to use query-replace-regexp + \ 
instead.

RE: should query-replace-regexp-eval be in the manual?

[Drew Adams]

> > For those who are familiar with this command and with using `\,' with
> > `query-replace-regexp': Could you compare/contrast these two in
> > terms of use cases?
>
> query-replace-regexp-eval can do nothing that one can't achieve with a
> use of a \, expression in query-replace-regexp.
>
> In contrast to query-replace-regexp-eval, \, does not necessitate
> deciding in advance that you are going to need Lisp for a job, and
> you'll only need to use Lisp for those parts of the expression where
> it is necessary.
>
> I came up with the idea of \, after stumbling upon
> query-replace-regexp-eval and noticing that the typical usage pattern
> was to start something with C-M-%, type stuff into it, then do a
> combination of C-k, C-g, C-M-Esc or other things I don't remember
> right now, in order to restart the whole process using
> query-replace-regexp-eval instead.  And query-replace-regexp-eval does
> not have a keybinding of its own.
>
> Basically it has been my experience that query-replace-regexp-eval is
> a nice idea, but in practice quite unusable.  \, achieves a similar
> purpose but with a much more convenient interface.

That's pretty much what I expected, but I wasn't sure if I wasn't perhaps
missing something.

> To get back to the original question: since \, has all of the
> functionality of query-replace-regexp-eval with a more convenient
> interface, query-replace-regexp-eval could be considered obsolete or
> at least obscure.

In that case, why keep `query-replace-regexp-eval'? You seem to be saying
that there really is no separate use case for it. That's an argument for
deprecating it.

The (minor) advantage I see for it is the case that you hint at: It saves
having to use the `\,...' syntax, when you know that you want Lisp
evaluation (and only Lisp evaluation, for the entire replacement).

That is, the interface of `query-replace-regexp' is more convenient _in
general_, because it is more general and flexible. But it requires extra
syntax (`\,...') whenever you want only Lisp eval. For that reason, someone
might want to bind `query-replace-regexp-eval' to a key, to save some extra
syntax (`\,...').

I think that these are the only reasonable options:

1. Get rid of `query-replace-regexp-eval', since you can always use the
`\,...' syntax to get the same effect (and more).

2. Keep `query-replace-regexp-eval', and mention in its doc string that it
is a shortcut that gives the effect of using `query-replace-regexp' with
(only) `\,...'.

If we choose #2, then the question is whether to mention
`query-replace-regexp-eval' in the manual. It's not strictly needed, because
users can find it via `apropos'.

> Since we tell people how to do the same thing more flexibly with \, I
> don't think that query-replace-regexp-eval deserves a place in the
> manual.  It would be a lot of additional explanation without any
> conceivable benefit to the user.

On the other hand, it could be described briefly in the manual in this way,
and that might make things clearer:

 `query-replace-regexp-eval' - Query-replace text that matches
  a regexp by the result of evaluating a Lisp sexp, taken as
  a string. You are prompted for the regexp and the sexp. You
  can get the same effect by using the more general command
  `query-replace-regexp', enclosing the sexp within `\,...'.

That makes clear what it does, and what its specific use case is. And it is
not "a lot of additional explanation".

I won't argue strongly for inclusion in the manual. But I will point out
that "more flexibly" comes at the (minor) cost of using extra syntax for
simple eval-only cases, and not bothering with that syntax can be a (minor)
convenience - that's a user choice.

I vote for 1) keeping it and 2) documenting it in the terms mentioned above.

BTW, `query-replace-regexp', with `\,...' and all the rest, is one of the
truly great features offered in Emacs 22, IMO. Bravo!

RE: should query-replace-regexp-eval be in the manual?

[Drew Adams]

> >> Basically it has been my experience that query-replace-regexp-eval
> >> is a nice idea, but in practice quite unusable.  \, achieves a
> >> similar purpose but with a much more convenient interface.
> >
> > To get back to the original question: since \, has all of the
> > functionality of query-replace-regexp-eval with a more convenient
> > interface, query-replace-regexp-eval could be considered obsolete or
> > at least obscure.
> >
> > Since we tell people how to do the same thing more flexibly with \, I
> > don't think that query-replace-regexp-eval deserves a place in the
> > manual.  It would be a lot of additional explanation without any
> > conceivable benefit to the user.
>
> After reading this I think it would be a good idea to tell in the doc
> string for query-replace-regexp-eval to use query-replace-regexp + \
> instead.

There is never any sense in saying to use something else instead, unless it
has truly been deprecated.

The question is whether this has a use on its own, which would keep it from
being deprecated. In that case, the doc string should explain what that use
is.

I think that it probably does merit keeping. It has the advantage of simpler
syntax, for the use case to which it applies: replacement by an evaled sexp
(only).

IOW:
- `query-regexp-replace' is best all 'round: flexible, general
- `query-regexp-replace-eval' has a simpler UI when you are
  using only eval-replacement - no need to use `\,...'.

Re: should query-replace-regexp-eval be in the manual?

[Robert J. Chassell]

The discussion of query-replace-regexp presumes using it
interactively.  That does not necessarily follow, although I suppose
interactive use is most common.

For example

    M-C-% or.*ry RET \,(format "strange %s" \#)

is

    (query-replace-regexp "or.*ry"
                          '(replace-eval-replacement
                            replace-quote
                            (format "strange %s" replace-count)))

[i.e., convert "ordinary" or something like it to "strange" plus a number]

When you are writing Emacs Lisp expressions, it is simpler to use
`query-replace-regexp-eval'.  The same result will come from invoking

    (query-replace-regexp-eval "or.*ary"
                               '(format "strange %s" replace-count))

I recommend leaving it in the source.  Perhaps (a short) mention in
the manual is useful, although I do not feel strongly about that.

--
    Robert J. Chassell                          GnuPG Key ID: 004B4AC8
    bob@rattlesnake.com                         bob@gnu.org
    http://www.rattlesnake.com                  http://www.teak.cc

Re: should query-replace-regexp-eval be in the manual?

[Stefan Monnier]

> The discussion of query-replace-regexp presumes using it
> interactively.  That does not necessarily follow, although I suppose
> interactive use is most common.

Not only that, but non-interactive uses of query-replace commands is
generally deprecated in favor of while/search/replace-match loops.


        Stefan

Re: should query-replace-regexp-eval be in the manual?

[Richard Stallman]

    Basically it has been my experience that query-replace-regexp-eval is
    a nice idea, but in practice quite unusable.  \, achieves a similar
    purpose but with a much more convenient interface.

Could you write some text to document the \ feature in the Emacs Manual?

    To get back to the original question: since \, has all of the
    functionality of query-replace-regexp-eval with a more convenient
    interface, query-replace-regexp-eval could be considered obsolete or
    at least obscure.

I think its doc string should mention that the \ feature is more
convenient for interactive use, and the function should be marked
obsolete.

Re: should query-replace-regexp-eval be in the manual?

[David Kastrup]

Richard Stallman <rms@gnu.org> writes:

>     Basically it has been my experience that query-replace-regexp-eval is
>     a nice idea, but in practice quite unusable.  \, achieves a similar
>     purpose but with a much more convenient interface.
>
> Could you write some text to document the \ feature in the Emacs Manual?

\, has been documented in
(info "(emacs) Regexp Replace")
the Emacs manual pretty much since its inception.

>     To get back to the original question: since \, has all of the
>     functionality of query-replace-regexp-eval with a more convenient
>     interface, query-replace-regexp-eval could be considered obsolete or
>     at least obscure.
>
> I think its doc string should mention that the \ feature is more
> convenient for interactive use, and the function should be marked
> obsolete.

Since the only advantage appears to be with non-interactive use, and
for non-interactive use, the query-replace functions are not
recommended, I'll put something to this effect into the doc string.

As to obsoletion: its main effect would appear to be a byte-compiler
warning.  So perhaps something like

(make-obsolete 'query-replace-regexp-eval
  "For interactive use, use the special `\\,' feature of
`query-replace-regexp' instead.  Non-interactively, a loop
using `search-forward-regexp' and `replace-match' is
preferred." "22.1")

would be ok, even though we had no `deprecation' before `obsoletion'
and `\,' is new in Emacs 22.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: should query-replace-regexp-eval be in the manual?

[Richard Stallman]

Please make the changes you proposed.

Re: should query-replace-regexp-eval be in the manual?

[David Kastrup]

Richard Stallman <rms@gnu.org> writes:

> Please make the changes you proposed.

Done.  I mentioned this in NEWS.  I am not sure about the DOC string
of `query-replace-regexp-eval', though: since it is obsoleted, would
it be appropriate to have all the info except that of its deprecation
be ripped from it?

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: should query-replace-regexp-eval be in the manual?

[Richard Stallman]

    Done.  I mentioned this in NEWS.  I am not sure about the DOC string
    of `query-replace-regexp-eval', though: since it is obsoleted, would
    it be appropriate to have all the info except that of its deprecation
    be ripped from it?

Our general policy is to retain the information about a function
and what it does, when we make it obsolete.  I see no reason to make
a special exception for this function.  So please do not delete anything.

Re: should query-replace-regexp-eval be in the manual?

[David Kastrup]

Richard Stallman <rms@gnu.org> writes:

>     Done.  I mentioned this in NEWS.  I am not sure about the DOC string
>     of `query-replace-regexp-eval', though: since it is obsoleted, would
>     it be appropriate to have all the info except that of its deprecation
>     be ripped from it?
>
> Our general policy is to retain the information about a function and
> what it does, when we make it obsolete.  I see no reason to make a
> special exception for this function.

Oh, I was not asking for an exception, but rather about the rule.

> So please do not delete anything.

Done.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum