bug#55050: 27.2; Doc strings for commands that do query-replacements

bug#55050: 27.2; Doc strings for commands that do query-replacements

[Drew Adams]

This is about the doc of commands, such as
`dired-do-find-regexp-and-replace', that use a query-replace dialog.
There are a bunch of such commands now.  For the most part, they don't
tell you anything about what to expect, in terms of a dialog.  In
particular, they don't reference the doc of `query-replace`, which is
(at least) where the dialog should be described.

The only saving grace is that there's a prompt that suggests that if you
hit `?' you might get some information about what you can do.  Assuming
you notice that prompt, of course.

The doc of all such commands should, directly or indirectly, tell you
about the keys you can use and what they do - what you learn by hitting
`?'.

See, for example, this user's question:

https://emacs.stackexchange.com/q/71451/105

In GNU Emacs 27.2 (build 1, x86_64-w64-mingw32)
 of 2021-03-26 built on CIRROCUMULUS
Repository revision: deef5efafb70f4b171265b896505b92b6eef24e6
Repository branch: HEAD
Windowing system distributor 'Microsoft Corp.', version 10.0.19043
System Description: Microsoft Windows 10 Pro (v10.0.2009.19043.1586)

bug#55050: 27.2; Doc strings for commands that do query-replacements

[Lars Ingebrigtsen]

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

> This is about the doc of commands, such as
> `dired-do-find-regexp-and-replace', that use a query-replace dialog.
> There are a bunch of such commands now.  For the most part, they don't
> tell you anything about what to expect, in terms of a dialog.  In
> particular, they don't reference the doc of `query-replace`, which is
> (at least) where the dialog should be described.

I've now linked the latter from the doc string of the former.

> The only saving grace is that there's a prompt that suggests that if you
> hit `?' you might get some information about what you can do.  Assuming
> you notice that prompt, of course.
>
> The doc of all such commands should, directly or indirectly, tell you
> about the keys you can use and what they do - what you learn by hitting
> `?'.

I don't think that would be particularly useful.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#55050: 27.2; Doc strings for commands that do query-replacements

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Thu, 21 Apr 2022 02:46:16 +0000
> 
> This is about the doc of commands, such as
> `dired-do-find-regexp-and-replace', that use a query-replace dialog.
> There are a bunch of such commands now.  For the most part, they don't
> tell you anything about what to expect, in terms of a dialog.  In
> particular, they don't reference the doc of `query-replace`, which is
> (at least) where the dialog should be described.
> 
> The only saving grace is that there's a prompt that suggests that if you
> hit `?' you might get some information about what you can do.  Assuming
> you notice that prompt, of course.

If you don't assume they pay attention to the prompt, why assume they
will read the doc string, which is much longer and whose instructions
it is therefore much easier to miss?

> The doc of all such commands should, directly or indirectly, tell you
> about the keys you can use and what they do - what you learn by hitting
> `?'.

It is not reasonable to show all the commands available for dealing
with matches: the list is very long, and will make the doc strings
unbearably long, especially for people who are interested in other
aspects of these commands than how to deal with matches.

So I added the minimal instructions to all the commands I found which
perform query-replace of some sort: how to accept a replacement and
how to skip it -- with a reference to 'h' that will show the full
instructions.  This, of course, is _in_addition_ to the already
existing link to 'query-replace'/'query-replace-regexp', which in
itself is a reference to that stuff.

> See, for example, this user's question:
> 
> https://emacs.stackexchange.com/q/71451/105

FTR, that question has nothing to do with the subject of this bug
report, it is about the user's confusion with the fact that Emacs
doesn't let users modify write-protected files, and what to do when
the user wants to modify such files even though they are read-only.

bug#55050: 27.2; Doc strings for commands that do query-replacements

[Juri Linkov]

> So I added the minimal instructions to all the commands I found which
> perform query-replace of some sort: how to accept a replacement and
> how to skip it -- with a reference to 'h' that will show the full
> instructions.  This, of course, is _in_addition_ to the already
> existing link to 'query-replace'/'query-replace-regexp', which in
> itself is a reference to that stuff.

Actually this change was in isearch-occur unrelated to query-replace.
Maybe you meant to add it to isearch-query-replace-regexp?

diff --git a/lisp/isearch.el b/lisp/isearch.el
index 34e3b69475..d829744c3a 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -2393,7 +2398,12 @@ isearch-occur
 command was a regular expression search, REGEXP is the regular
 expression used in that search.  If the last search command searched
 for a literal string, REGEXP is constructed by quoting all the special
-characters in that string."
+characters in that string.
+
+As each match is found, the user must type a character saying
+what to do with it.  Type SPC or `y' to replace the match,
+DEL or `n' to skip and go to the next match.  For more directions,
+type \\[help-command] at that time."
   (interactive
    (let* ((perform-collect (consp current-prefix-arg))
 	  (regexp (cond

bug#55050: 27.2; Doc strings for commands that do query-replacements

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: Drew Adams <drew.adams@oracle.com>,  55050-done@debbugs.gnu.org
> Date: Thu, 21 Apr 2022 19:04:42 +0300
> 
> > So I added the minimal instructions to all the commands I found which
> > perform query-replace of some sort: how to accept a replacement and
> > how to skip it -- with a reference to 'h' that will show the full
> > instructions.  This, of course, is _in_addition_ to the already
> > existing link to 'query-replace'/'query-replace-regexp', which in
> > itself is a reference to that stuff.
> 
> Actually this change was in isearch-occur unrelated to query-replace.
> Maybe you meant to add it to isearch-query-replace-regexp?

Yes, thanks; fixed.