RE: Improving describe-mode and discoverability

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

> > 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.
> 
> Possibly because I was hoping for your help (and that of others, of course)
> to come up with a clear proposal :)

I've probably said too much here already.  Others will no doubt be more helpful.

> Here's an attempt. I propose that we:
> 
> 1. Introduce a new function variable `format-keymap-function'. It should be
> set to a function accepting one argument (a keymap) and rendering that
> keymap for display to the user.
> 
> 2. Change the way \\{...} formatting works to make it call out to the value
> of format-keymap-function.
> 
> 3. Set the default value of format-keymap-function to a new function,
> implemented to render keymaps as I demoed in previous messages.
> 
> I think this responds to your four points:
> 
> > 1. Whether to replace \\{...} with Clement's alternative
> > representation or to provide a different construct to show it.
> 
> I propose to replace the existing \\{} construct.
> 
> > 2. Whether to let users choose to show the result of \\{...}
> > differently (i.e., as it is shown currently or in Clement's
> > way).
> 
> I propose to let user customize the result, using `format-keymap-function'.

`keymap-format-function'?

> > 3. Whether to include \\{...} automatically for all modes,
> > whether it uses the original representation or Clement's
> > alternative.
> 
> I propose to not include it automatically; this is left to the mode author,
> or in any case to a separate proposal.
> 
> > 4. Whether including \\{...} automatically for all modes
> > should be a user option (regardless of which representation
> > is used).
> 
> I propose to not create such an option. This could be a separate proposal.
> 
> The current proposal is to not hardcode \\{} to produce a two-columns
> display, but instead to make it customizable. In addition, the proposal is
> to change the default to include the headers of docstrings, as demoed in
> previous emails.
> 
> Let me know if I can make this clearer :)

Much clearer; thanks.  (And I appreciate the lack of automatic use.)

For my part:

1. A user option for how to display \\{...} is not a bad idea.

2. The defcustom type could include a `choice' among: two predefined formats
(the current one and yours) and an arbitrary user-defined function.

(IMO, the default behavior should probably be what the behavior has been,
but that's another discussion.)

3. A problem I see with this is that there needs to be a way for code to
control the format in some cases - separately from users being able to
control the display in other cases.

4. For that, code could I guess bind the option around a given use of the
string.  (Would that handle all use cases?)

I'm writing this quickly without thinking much about it, so no doubt others
will see clearer.