Subject: RE: bug#37485: 27.0.50; C-m in describe-bindings

From: Drew Adams <[email-masked]>
Date: Mon, 23 Sep 2019 10:29:15 -0700 (PDT)

> But do you use RET instead of `C-m' in these keystrokes because that's
> what `describe-bindings' say or because you prefer to hit `RET'?
> 
> Anyway, I've grepped through the *.texi files, and there are 152 matches
> for `C-c C-m ...' and 8 for `C-c RET'.  And all of those 8 are for RET
> as the final character in the keystroke.
> 
> If you expand to "C-. C-m"/"C-. RET" it's 170/20.  (All those additional
> ones are from mule.texi.)
> 
> It seems the mode writers' intentions are pretty clear: They mean for
> the users to type C-c C-m ..., but `describe-bindings' tells them to type
> C-c RET.

My 2c:

If we show only C-m then users might not realize that
they can use RET.  If we show only RET then users might
not realize they can use C-m.  That's the way it goes.

In the _doc_ (e.g. *.texi) we can always remind users
that the two are equivalent (but not always equivalent
to <return>).  In particular, we can do that for a key
binding that uses it after another C- key (e.g. after
C-c).

But in C-m, C-b, etc., we should provide the same
key-description format, systematically.  It would be
confusing to sometimes use C-m and sometimes RET in
such contexts.  That could give users the false idea
that the two are different.

Emacs has always used RET in this case (key listings).
And in most cases the key is not used as a prefix key,
and it does not follow a C- key.  And most users (I
think) will recognize and use RET for such cases, even
if they use C-m after a C- key or as a prefix key.

So I'd vote for keeping RET in such lists of key
descriptions.  But I'd agree that it can help to point
out, in doc, that you can use C-m as an alternative.
Pointing that out is especially useful in a context
where the key follows a C- key, and possibly even
where it does not but it is used as a prefix key.

So "the mode writers" you mention aren't necessarily
wrong.  But it would be wrong to change key listings,
which are not specific to a given mode, to use C-m.

You might say that `C-h m' is all about documenting
the _mode_, so its output should reflect what "the
mode writers" use.  If that's the point then the mode
description (doc string) can simply add a sentence
reminding users that C-M = RET.  Such a case is not
a good reason not to keep key listings consistent.