[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

RE: Improving describe-mode and discoverability

From: Drew Adams
Subject: RE: Improving describe-mode and discoverability
Date: Thu, 23 Jun 2016 17:05:55 -0700 (PDT)

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


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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]