Re: Improving describe-mode and discoverability

[Clément Pit--Claudel]

On 2016-06-23 19:15, Drew Adams wrote:
> 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 :)

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'.

> 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 :)
Clément.

signature.asc
Description: OpenPGP digital signature