Re: [PATCH] Fix notmuch-describe-key

[Matt Armstrong <marmstrong@google.com>]

Sheng Yang <yangsheng6810@gmail.com> writes:

> For the second case, I mean the call of notmuch-help fails with the
> following error:
>
> notmuch-documentation-first-line: Symbol’s function definition is void: aya-persist-snippet
>
> Sorry for the confusion. Other void functions include the following for me
>
> spacemacs/search-pt-grep-region-or-symbol
> spacemacs/search-pt-grep
> spacemacs/search-rg-grep-region-or-symbol
> spacemacs/search-rg-grep
> spacemacs/search-ack-grep-region-or-symbol
> spacemacs/search-ack-grep

Thank you, that makes sense to me now.


> I think either is fine: notmuch-documentation-first-line is only
> called from notmuch-describe-key, we can do it in either function. The
> advantage of fixing it in notmuch-describe-key is that we can avoid
> some lines that have key bindings without description.

I agree.  Given all this, I think your patch looks good.


> Here are some known problems that are not fixed by this patch:
> 1. For me, 600+ lines of help are produced by notmuch-hello, which is a
> lot. (Maybe not as much, as counsel-desbinds tells me there are 3000+
> key bindings)

It is interesting that your help buffer displays 600 lines.  The intent
of the notmuch help is to display help for the notmuch commands, not the
myriad of other key bindings available.

I use vanilla Emacs (not spacemacs, not evil mode, etc.), and the help
buffers are about a page long.  For example, in a search buffer the key
bindings display as this:

Complete list of currently available key bindings:

?	Display help for the current notmuch mode.
q	Undisplay the current buffer.
s	Search for messages.
z	Display threads matching QUERY in Tree View.
g	Refresh the current buffer.
=	Refresh the current buffer.
M-=	Invoke ‘notmuch-refresh-this-buffer’ on all notmuch major-mode buffers.
G	Invoke ‘notmuch-poll’ to import mail, then refresh the current buffer.
j	Jump to a saved search by shortcut key.
x	Undisplay the current buffer.
DEL	Move backward through the search results by one window’s worth.
b	Move backward through the search results by one window’s worth.
SPC	Move forward through search results by one window’s worth.
<	Select the first thread in the search results.
>	Select the last thread in the search results.
p	Select the previous thread in the search results.
n	Select the next thread in the search results.
r	Begin composing a reply to the entire current thread in a new buffer.
R	Begin composing a reply-all to the entire current thread in a new buffer.
o	Toggle the current search order.
c i	Copy thread ID of current thread to kill-ring.
c q	Copy current query to kill-ring.
c ?	Show help for a subkeymap.
t	Filter the current search results based on a single tag.
l	Filter or LIMIT the current search results based on an additional query string.
k	Create a jump menu for tagging operations.
*	Add/remove tags from all messages in current search buffer.
a	Archive the currently selected thread or region.
C-u a	Un-archive the currently selected thread.
-	Change tags for the current thread or region (defaulting to remove).
+	Change tags for the current thread or region (defaulting to add).
RET	Display the currently selected thread.
Z	Call notmuch tree with the current query
m	Mute the currently selected thread or region.


> 2. Key bindings using leader key (in spacemacs, it is ESC) are not
> shown correctly: instead of showing "SPC q q", notmuch-help shows "q q"
> for a key binding <SPC q q>. 
> 3. Some lines show key bindings with no explanation. Possibly because no
> doc string is available for these functions.
>
> If we do not need to stick to the current implementation of
> notmuch-help, a simple way is to port counsel-desbinds or
> counsel--desbinds-cands from counsel.el.

Yes, I can believe that spacemacs and/or evil mode do not display useful
help when using "vanilla" Emacs commands to display the help, since
vanilla Emacs doesn't understand the approach.

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.