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.