> If the replacement string had uppercase chars then I always
     got the same message, which was very long - too long to read
     in the short time it was displayed.  Could we shorten that
     message, please? 
Yes, I am looking for more ideas to get a better, shorter message.

>  And could we maybe have it logged to
     *Messages*, so that if someone doesn't have time to read it
     s?he can look it up?
Only for the messages where toggling is not possible, the message can be logged to *Messages*. Sounds good?

> If the replacement string had no uppercase chars then I always
     got the same message (about case-fold-search being nil).
The toggling is not unconditional. Toggling case-replace/nocasify is very picky!
So I had to put that (cond ..) statement there to handle the picky scenarios where toggling cannot happen even if the user wanted to.

For the above case, nocasify will stay t regardless of the value of case-replace IF the user has set case-fold-search to nil.
So the user will first need to do M-c (toggle case-fold-search to t) and then do M-r. That too will not work IF the user has used upper case letter in the search/regexp string or the replacement string.

This is the ideal case for M-r to always toggle nocasify
1. case-fold-search is t
2. all lower case in search/regexp string
3. all lower case in replacement string

>   What is `M-r' really supposed to do?  I don't see how it is a
   toggle, if repeating it always gives the same message, given
   the same replacement string.  Can you describe what the toggling
   or cycling among states is supposed to do/mean?

As described above, we cannot unconditionally toggle nocasify.. it depends on a bunch of conditions to be right.

>   I think Juri is right, that it should be the following, because
   `lookup-key' can return a number if the key is too long:

   ((commandp def t)          ; User-defined key, invoke it.
    (call-interactively def))

I agree. Will make the change.

> If one of you could replace the paragraphs of the doc that I
   mentioned by just a statement that search is controlled by
   `case-fold-search', that would be good. You could then add
   that you can toggle this using `M-c' etc. IOW, (1) those
   paragraphs are useless, and (2) now we have something more
   to say about case sensitivity.

Case fold toggling is also a bit picky but the results are obvious, and M-c can force toggle case-fold-search.

But default, search-upper-case is t. So if the user has a string with an upper case in the search field of query-replace, case-fold-search will be set to nil automatically (even if it is `t` by default). Then M-r will not work in the beginning. User can, though, use M-c to toggle case-fold-search first and then M-r if they wish.

I found the current documentation useful while working on this patch and testing it out. But I will give it a one more read to try to improve it.

On Wed, Jun 3, 2015 at 12:39 AM Drew Adams <drew.adams@oracle.com> wrote:
> I tested this out and the M-c and M-r bindings work great. It now
> also gives clear info on what the user should expect after that
> binding is used. Please give it a try. I have still kept this line
>
>  (def (call-interactively def)) ; User-defined key, invoke it.
>
> as it could be useful to bind any other function from outside
> that does not need internal variables.

1. I'm OK with whatever you guys come up with.  Thanks for working
   on this.

2. I tried it only a little.  When I tried `M-r':

   * If the replacement string had uppercase chars then I always
     got the same message, which was very long - too long to read
     in the short time it was displayed.  Could we shorten that
     message, please?  And could we maybe have it logged to
     *Messages*, so that if someone doesn't have time to read it
     s?he can look it up?

   * If the replacement string had no uppercase chars then I always
     got the same message (about case-fold-search being nil).

   What is `M-r' really supposed to do?  I don't see how it is a
   toggle, if repeating it always gives the same message, given
   the same replacement string.  Can you describe what the toggling
   or cycling among states is supposed to do/mean?

3. Wrt this:

      I have still kept this line
      (def (call-interactively def)) ; User-defined key, invoke it.
      as it could be useful to bind any other function from outside
      that does not need internal variables.

   I think Juri is right, that it should be the following, because
   `lookup-key' can return a number if the key is too long:

   ((commandp def t)          ; User-defined key, invoke it.
    (call-interactively def))

4. If one of you could replace the paragraphs of the doc that I
   mentioned by just a statement that search is controlled by
   `case-fold-search', that would be good. You could then add
   that you can toggle this using `M-c' etc. IOW, (1) those
   paragraphs are useless, and (2) now we have something more
   to say about case sensitivity.