RE: Improving describe-mode and discoverability

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

> my proposal is to keep displaying mode docstrings. However, when a
> mode docstring includes a \\{mode-map} (which seems to be a very common
> thing to do), my proposal is to enhance the rendering of that \\{mode-map}
> construct to print an actually useful table.

So you are proposing a change to how \\{mode-map} is handled -
a replacement for the current behavior.

Personally, I don't have a problem with the way it is handled now.

I think that what you should do perhaps is to propose a new
(different) such construct, which produces the key binding plus
a one-line description instead of the key binding plus the command.

In that case, I probably wouldn't use that new construct, but
maybe others will.

To me, the key and the command name are the most important.
And the command names are linked to the full doc for the commands.

(And in my own code, keys between `..' are also so linked.)

> Of course, we could put this behaviour behind a flag.

If it is a new construct instead of a replacement for \\{...}
then there is no need for a flag.