[PATCH] Fix notmuch-describe-key

[Matt Armstrong]

Sheng Yang <yangsheng6810 at gmail.com> writes:

> Matt Armstrong <marmstrong at google.com> writes:
>
>> I think it would be great if someone worked with upstream Emacs to make
>> the `documentation' function do something useful for evil mode and
>> spacemacs.  If that happened, then all packages would benefit.  Porting
>> things like counsel-descbinds into packages like notmuch can work but
>> does not feel like the right long term solution to me.
>
> I guess the problem does not come from `documentation' function itself.
> I will investigate a bit more.
>
> What if we filter the key bindings and show only those that are binded
> to notmuch functions? Maybe those functions that matches "^notmuch-"?
> This only shows related key bindings related to notmuch, and the list
> would not be long anyway.

Yes, that could be a practical and pragmatic solution.  I do not oppose
it, but see my one note about this below.

I suggested improving core Emacs help functions earlier simply because I
think the core help system should be better, which would reduce the
reasons we see packages like notmuch and counsel trying to do a better
job.  For example, if core Emacs understood the approaches taken by
evil-mode to bind keys it could do a better job with help.  Emacs help
already does a "bad" job with other modal key maps (e.g. the help for
the ESC key is displayed as an almost useless "Prefix Command" by Emacs
today).

Improving all this is a long term solution -- any fix to Emacs itself
takes years to be available to everyone.

But take M-x describe-mode in a notmuch-search buffer.  It shows me the
list below.  Clearly the original intent of the notmuch help functions
were to make that more useful, but something is going wrong in the
spacemacs case.

I'm not sure why.  Emacs lisp is so flexible that anything could be
happening.  For example, spacemacs could be installing advice around the
`documentation' function that modifies the behavior in a way that makes
sense for spacemacs but confuses the notmuch code.  I am not sure why so
many spacemacs bindings see to be in the notmuch key maps.  Who knows.
:)

One problem with filtering the command list is shown below.  I have
bound a command of my own, my-notmuch-search-mute-thread, to the key
map.  I find it useful to have that included in the help output.


RET             notmuch-search-show-thread
ESC             Prefix Command
SPC             notmuch-search-scroll-up
*               notmuch-search-tag-all
+               notmuch-search-add-tag
-               notmuch-search-remove-tag
<               notmuch-search-first-thread
=               notmuch-refresh-this-buffer
>               notmuch-search-last-thread
?               notmuch-help
G               notmuch-poll-and-refresh-this-buffer
R               notmuch-search-reply-to-thread
Z               notmuch-tree-from-search-current-query
a               notmuch-search-archive-thread
b               notmuch-search-scroll-down
c               notmuch-search-stash-map
g               notmuch-refresh-this-buffer
j               notmuch-jump-search
k               notmuch-tag-jump
l               notmuch-search-filter
m               my-notmuch-search-mute-thread
n               notmuch-search-next-thread
o               notmuch-search-toggle-order
p               notmuch-search-previous-thread
q               notmuch-bury-or-kill-this-buffer
r               notmuch-search-reply-to-thread-sender
s               notmuch-search
t               notmuch-search-filter-by-tag
x               notmuch-bury-or-kill-this-buffer
z               notmuch-tree
DEL             notmuch-search-scroll-down
<mouse-1>       notmuch-search-show-thread

c ?             notmuch-subkeymap-help
c i             notmuch-search-stash-thread-id
c q             notmuch-stash-query

M-=             notmuch-refresh-all-buffers