bug#1111: describe-key's key notation display inconsistency

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

> > I've said before (not in this thread, most likely)
> > that I think that the Emacs manuals should use the
> > exact same notation that Emacs itself uses
> > interactively.
> >
> > That means the manuals should use <C-return>, not
> > C-<return>.  But they don't.
> 
> Having Emacs print C-<return>, as suggested in the OP,
> would also solve the consistency, yes?

Yes, of course.  At the cost of a lot of code
changes, not to mention user mind changes. ;-)

[We could also change Elisp to use only
M-expressions, not S-expressions (sexps) -
e.g. car('(1 2)) instead of (car '(1 2)), to
more closely fit syntax expectations outside
Lisp.]

https://en.wikipedia.org/wiki/M-expression

> I think it's a bit more readable, so I would
> be in favour of that.

To me it's less readable, but tastes vary.

`C-x <right>' is noticeably different from
`<C-right>'.

`C-x <right>' is not so noticeably different
from `C-<right> (to me, at least).

---

> > FWIW, I've also argued that we do not need
> > angle-bracket notation at all.  We can drop
> > it and still be completely unambiguous and
> > consistent.
> 
> That assumes all function key names are longer
> than one letter, right?

Yes.  But we already have the symbol for the
corresponding event, which presumably has the
same potential problem.

E.g., the event that corresponds to the key
described as `<right>' is the symbol `right'
(no angle brackets).  The event that
corresponds to the key described as `<M-F3>'
is `M-f3'.

Presumably the key described as `<M-D>' (or
`M-<D>', per Xah), where `<D>' is a function
key, would correspond to event `M-d', which
might already be problematic (no?).

(And we would anyway distinguish function
keys `<D>' and `<M-D>' via the bracket syntax,
as `[M-d]'.  It would only be the (proposed)
standard key description where naked `d' and
`M-d' could be ambiguous.)

We could also make it explicitly conventional
for a function key (including a fake function
key, for a menu item) to have more than one
character.  We have no such convention, AFAICT,
but have you ever come across a single-char
function-key name?

Or we could just leave `d' ambiguous, in the
rare case that there might be an `d' function
key as well as the `d' character key.

I'd bet that there are no such anomalous
function keys today (or in the past).  Do you
know of any?  And do we even know whether all
of Emacs works OK with such a function key?

Anyway, going naked ain't gonna happen.
That's been made clear.

BTW, since Emacs 22, `single-key-description'
takes an optional arg NO-ANGLES, which does
what you might expect.  Here is the reason
given (in (elisp) `Describing Characters'):

 If the optional argument NO-ANGLES is non-'nil',
 the angle brackets around function keys and
 event symbols are omitted; this is for
 compatibility with old versions of Emacs which
 didn't use the brackets.

(I don't think angle brackets are ever used
around event symbols, so I'm guessing that
"and event symbols" is wrong, there.)