Re: Improving describe-mode and discoverability

["Clément Pit--Claudel" <clement.pit@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 1987 bytes --]

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.


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]