RE: Improving describe-mode and discoverability

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

> >>> 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.
> >
> > I'd prefer a flag (or just the new behavior). There's no need to split the
> > community here: if I user likes this output, they'll want to see it in all
> > mode descriptions, not just the ones that opted in.
> 
> I think I agree. Drew, wouldn't you think that this is something the user
> should choose, instead of the mode author?
> As a user, I'd like consistent rendering; as a mode author, I'd rather not
> argue with my users about one which one looks best for each one of my modes.

I probably don't have a good enough idea of what you have in mind.

I think:

1. A writer of a mode should be able to decide what is said in the
mode doc.

2. Ideally, a user should be able to decide what that looks like,
including perhaps, what parts of it to show.


What do we do TODAY?  See (elisp) `Major Mode Conventions'.
There it says:

 "The documentation string may include the special documentation
  substrings, `\[COMMAND]', `\{KEYMAP}', and `\<KEYMAP>', which
  allow the help display to adapt automatically to the user's own
  key bindings.  *Note Keys in Documentation::."

Note: *MAY* include `\{KEYMAP}'.

We do not automatically and systematically show a list of the
bindings in the help for every mode.  The decision of whether to
include that for any given mode is up to the mode writer.  It is
not up to the user, today.

I would probably have no problem with that being changed to being
a user option.  But in that case, if a user turns this display
of keys off, does that override the current situation of a mode
writer having deemed that the keys should be shown for some mode?

There are really a few issues raised implicitly by Clement:

1. Whether to replace \\{...} with Clement's alternative
representation or to provide a different construct to show it.

2. Whether to let users choose to show the result of \\{...}
differently (i.e., as it is shown currently or in Clement's
way).

3. Whether to include \\{...} automatically for all modes,
whether it uses the original representation or Clement's
alternative.

4. Whether including \\{...} automatically for all modes
should be a user option (regardless of which representation
is used).

I don't have answers now for all of those, and I'm not even
sure which of them are are actually being proposed.

Personally, I have no problem with the _current_ situation,
and so far I have not heard a clear alternative proposal
that sounds better to me.