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

["Drew Adams" <drew.adams@oracle.com>]

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