From: Drew Adams <drew.adams@oracle.com>
To: "Clément Pit--Claudel" <clement.pit@gmail.com>,
"Dmitry Gutov" <dgutov@yandex.ru>,
"Emacs developers" <emacs-devel@gnu.org>
Subject: RE: Improving describe-mode and discoverability
Date: Thu, 23 Jun 2016 17:05:55 -0700 (PDT) [thread overview]
Message-ID: <531a7bec-28af-4c4c-aa85-1d13e84c98be@default> (raw)
In-Reply-To: <576C7326.1020502@gmail.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.
next prev parent reply other threads:[~2016-06-24 0:05 UTC|newest]
Thread overview: 15+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-06-23 18:29 Improving describe-mode and discoverability Clément Pit--Claudel
2016-06-23 18:46 ` Robert Weiner
2016-06-23 18:52 ` Clément Pit--Claudel
2016-06-23 19:11 ` Robert Weiner
2016-06-23 19:36 ` Clément Pit--Claudel
2016-06-23 20:26 ` Drew Adams
2016-06-23 21:50 ` Clément Pit--Claudel
2016-06-23 22:07 ` Drew Adams
2016-06-23 22:10 ` Dmitry Gutov
2016-06-23 22:27 ` Clément Pit--Claudel
2016-06-23 23:15 ` Drew Adams
2016-06-23 23:39 ` Clément Pit--Claudel
2016-06-24 0:05 ` Drew Adams [this message]
2016-06-24 2:59 ` Clément Pit--Claudel
2016-07-06 17:47 ` John Wiegley
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=531a7bec-28af-4c4c-aa85-1d13e84c98be@default \
--to=drew.adams@oracle.com \
--cc=clement.pit@gmail.com \
--cc=dgutov@yandex.ru \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.