Notmuch Emacs 0.31.2 documentation and keybinding suggestions

Notmuch Emacs 0.31.2 documentation and keybinding suggestions

[Jorge P. de Morais Neto]

Hi.  I would like to report the following documentation and keybinding
imperfections:

The info page
[[info:notmuch-emacs.info#notmuch-hello key bindings]] says that
<backspace> moves to the previous widget, but that key is actually bound
to `delete-backward-char'.  To move to the previous widget I use <C-M-i>
or <S-iso-lefttab>.  And why does <S-iso-lefttab> move backward but
<S-C-i> (which ought to be equivalent to <S-iso-lefttab>, no?) moves forward?

Also, it seems that <SPC> moves forward and <DEL> moves backward, but
<S-SPC> does nothing useful.  For consistency with Emacs Info Mode,
Emacs View Mode, and some other applications such as Firefox, perhaps
<S-SPC> should move backward too.

The introduction of help buffer for Notmuch-Show (reached by hitting
<?>) describes the <SPC> command without mentioning that it can archive
the thread; only in <SPC> specific description (which does not fit in
the same window; one has to scroll) does it mention the archiving
behavior.  I believe the archiving behavior should also be mentioned in
the introduction, lest the user unwittingly archive a thread she wasn't
supposed to.  Also, the description for <u> is empty (this also happens
in the help buffer for Notmuch-Hello).

In the same help buffer, the description of <c ?> says "Show help for a
subkeymap."  Would it not be better to drop the "a", leaving "Show help
for subkeymap." ?

Finally, the binding for <C-tab> in Notmuch-Show and Notmuch-Hello
inconveniently clobbers the tab-bar-mode binding for that key.  Should
not Notmuch be content with <C-M-i>/<ESC tab>/<S-iso-lefttab> (and
possibly <S-C-i>) and leave <C-Tab> alone?

Regards

-- 
- <https://jorgemorais.gitlab.io/justice-for-rms/>
- If an email of mine arrives at your spam box, please notify me.
- Please adopt free/libre formats like PDF, ODF, Org, LaTeX, Opus, WebM and 7z.
- Free/libre software for Replicant, LineageOS and Android: https://f-droid.org
- [[https://www.gnu.org/philosophy/free-sw.html][What is free software?]]

Re: Notmuch Emacs 0.31.2 documentation and keybinding suggestions

[David Bremner]

"Jorge P. de Morais Neto" <jorge+list@disroot.org> writes:

> Hi.  I would like to report the following documentation and keybinding
> imperfections:
>
> The info page
> [[info:notmuch-emacs.info#notmuch-hello key bindings]] says that
> <backspace> moves to the previous widget, but that key is actually bound
> to `delete-backward-char'.

Apparently Tomi "corrected" <backtab> to <backspace> in
703dec7754da477b.

> To move to the previous widget I use <C-M-i>
> or <S-iso-lefttab>.

On the other hand, the keybinding in the code is to "C-<tab>", which
explains the above. To really be <backtab>, it should be S-tab.

> And why does <S-iso-lefttab> move backward but
> <S-C-i> (which ought to be equivalent to <S-iso-lefttab>, no?) moves forward?

You'd think they'd be equivalent, but actually they are not. You can use
C-h k to test, even in a GUI/X11 emacs.

> Also, it seems that <SPC> moves forward and <DEL> moves backward, but
> <S-SPC> does nothing useful.  For consistency with Emacs Info Mode,
> Emacs View Mode, and some other applications such as Firefox, perhaps
> <S-SPC> should move backward too.

I note that S-SPC is not accesible in terminals. But if there's
concensus that is is useful I don't mind adding it.

> The introduction of help buffer for Notmuch-Show (reached by hitting
> <?>) describes the <SPC> command without mentioning that it can archive
> the thread; only in <SPC> specific description (which does not fit in
> the same window; one has to scroll) does it mention the archiving
> behavior.  I believe the archiving behavior should also be mentioned in
> the introduction, lest the user unwittingly archive a thread she wasn't
> supposed to.

I personally don't think archiving is that destructive, if someone wants
to improve this wording, it is the docstring for notmuch-show-mode

> Also, the description for <u> is empty (this also happens
> in the help buffer for Notmuch-Hello).

Yes, that's a bug as the function "notmuch-unthreaded" lacks a
docstring. I think the original author of that code doesn't use emacs
anymore, so someone else is welcome to contribute one.

> In the same help buffer, the description of <c ?> says "Show help for a
> subkeymap."  Would it not be better to drop the "a", leaving "Show help
> for subkeymap." ?

This is the docstring for notmuch-subkeymap-help. In that context I
think it's better with the "a".

> Finally, the binding for <C-tab> in Notmuch-Show and Notmuch-Hello
> inconveniently clobbers the tab-bar-mode binding for that key.  Should
> not Notmuch be content with <C-M-i>/<ESC tab>/<S-iso-lefttab> (and
> possibly <S-C-i>) and leave <C-Tab> alone?
>

Notmuch has used the binding since 2010 (almost 10 years before
tab-bar-mode existed), so people might be used to it; on other hand it
does seem redundant since the binding S-tab is also there. I'm not a
very serious user of notmuch-hello mode, and I don't use tab-bar-mode at
all, so I'd welcome feedback from other people about how attached they
are to C-tab.

Re: Notmuch Emacs 0.31.2 documentation and keybinding suggestions

[Jose Antonio Ortega Ruiz]

On Sun, Oct 10 2021, David Bremner wrote:


[...]

>> Finally, the binding for <C-tab> in Notmuch-Show and Notmuch-Hello
>> inconveniently clobbers the tab-bar-mode binding for that key.  Should
>> not Notmuch be content with <C-M-i>/<ESC tab>/<S-iso-lefttab> (and
>> possibly <S-C-i>) and leave <C-Tab> alone?
>>
>
> Notmuch has used the binding since 2010 (almost 10 years before
> tab-bar-mode existed), so people might be used to it; on other hand it
> does seem redundant since the binding S-tab is also there. I'm not a
> very serious user of notmuch-hello mode, and I don't use tab-bar-mode at
> all, so I'd welcome feedback from other people about how attached they
> are to C-tab.

fwiw, i'm a regular user of hello, and i never use C-TAB (in any of its
forms).  i don't use tab-bar-mode though.

Re: Notmuch Emacs 0.31.2 documentation and keybinding suggestions

[Jorge P. de Morais Neto]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: 0001-emacs-Two-small-clarifications-for-notmuch-show-mode.patch --]
[-- Type: text/x-diff, Size: 1921 bytes --]

From edf36bb0d276d2cebe1e3b01dc953b508043a71f Mon Sep 17 00:00:00 2001
From: "Jorge P. de Morais Neto" <jorge+git@disroot.org>
Date: Thu, 28 Oct 2021 19:33:34 -0300
Subject: [PATCH] emacs: Two small clarifications for notmuch-show-mode's
 docstring

- Prominently inform that `notmuch-show-advance-and-archive' can
  archive the current thread
- Clarify that `notmuch-show-next-message' and
  `notmuch-show-previous-message' change the "unread" tag.

Signed-off-by: Jorge P. de Morais Neto <jorge@disroot.org>
---
 emacs/notmuch-show.el | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/emacs/notmuch-show.el b/emacs/notmuch-show.el
index 4de3e423..b4afb076 100644
--- a/emacs/notmuch-show.el
+++ b/emacs/notmuch-show.el
@@ -1532,13 +1532,14 @@ which \\[notmuch-show-next-button] and \\[notmuch-show-previous-button] are help
 
 Reading the thread sequentially is well-supported by pressing
 \\[notmuch-show-advance-and-archive]. This will scroll the current message (if necessary), advance
-to the next message, or advance to the next thread (if already on
-the last message of a thread).
+to the next message, or archive current thread and advance to the next
+(if already on the last message of a thread).
 
 Other commands are available to read or manipulate the thread
 more selectively, (such as '\\[notmuch-show-next-message]' and '\\[notmuch-show-previous-message]' to advance to messages
-without removing any tags, and '\\[notmuch-show-archive-thread]' to archive an entire thread
-without scrolling through with \\[notmuch-show-advance-and-archive]).
+without removing any tags other than \"unread\", and
+'\\[notmuch-show-archive-thread]' to archive an entire thread without
+scrolling through with \\[notmuch-show-advance-and-archive]).
 
 You can add or remove arbitrary tags from the current message with
 '\\[notmuch-show-add-tag]' or '\\[notmuch-show-remove-tag]'.
-- 
2.33.1


[-- Attachment #2: Type: text/plain, Size: 3383 bytes --]

Hi.  I apologize for the delay and reply below:

>> And why does <S-iso-lefttab> move backward but <S-C-i> (which ought
>> to be equivalent to <S-iso-lefttab>, no?) moves forward?
>
> You'd think they'd be equivalent, but actually they are not.  You can
> use C-h k to test, even in a GUI/X11 emacs.

I am aware that ~C-h k~ differentiates between <S-C-i> and <backtab> (or
<S-iso-lefttab>), but I still think that, intuitively, since <C-i> is
equivalent to <tab>, then the user expects <S-C-i> to be equivalent to
<backtab>.  There is no use in <S-C-i> having the same behavior as
<C-i>.  And if the user is navigating forward with <C-i>, then, if she
moves past the target and thus needs to go backward, it is convenient to
press <Shift> and hit <C-i> again (and vice-versa).  And <S-C-i> moving
backwards is consistent with Org Mode tables, where <S-C-i> moves
backward but <C-M-i> is bound to `complete-symbol'.

But maybe I should not press this point further.

>> Also, it seems that <SPC> moves forward and <DEL> moves backward, but
>> <S-SPC> does nothing useful.  For consistency with Emacs Info Mode,
>> Emacs View Mode, and some other applications such as Firefox, perhaps
>> <S-SPC> should move backward too.
>
> I note that S-SPC is not accesible in terminals.  But if there's
> concensus that is is useful I don't mind adding it.

Binding S-SPC to something useful does not help on a text terminal, but
does no harm either; and it helps on the GUI, which most people use.

>> The introduction of help buffer for Notmuch-Show (reached by hitting
>> <?>) describes the <SPC> command without mentioning that it can archive
>> the thread; only in <SPC> specific description (which does not fit in
>> the same window; one has to scroll) does it mention the archiving
>> behavior.  I believe the archiving behavior should also be mentioned in
>> the introduction, lest the user unwittingly archive a thread she wasn't
>> supposed to.
>
> I personally don't think archiving is that destructive, if someone wants
> to improve this wording, it is the docstring for notmuch-show-mode

See the attached patch---which also adds another minor clarification.

>> Finally, the binding for <C-tab> in Notmuch-Show and Notmuch-Hello
>> inconveniently clobbers the tab-bar-mode binding for that key.  Should
>> not Notmuch be content with <C-M-i>/<ESC tab>/<S-iso-lefttab> (and
>> possibly <S-C-i>) and leave <C-Tab> alone?
>>
>
> Notmuch has used the binding since 2010 (almost 10 years before
> tab-bar-mode existed), so people might be used to it; on other hand it
> does seem redundant since the binding S-tab is also there.  I'm not a
> very serious user of notmuch-hello mode, and I don't use tab-bar-mode at
> all, so I'd welcome feedback from other people about how attached they
> are to C-tab.

In my opinion, vanilla Emacs keybindings (even if recent) should not be
overridden without strong reason.

Feel free to give feedback on whether I am nitpicking, especially if the
feedback is reasonably detailed.

Regards!

-- 
- Many people hate injustice but few check the facts.  This provokes
  misinformation.  Ask me about <https://stallmansupport.org>
- Please adopt free/libre formats like PDF, Org, LaTeX, ODF, Opus, WebM and 7z.
- Libre apps for AOSP (Replicant, LineageOS, etc.) and Android: F-Droid
- https://www.gnu.org/philosophy/free-sw.html "What is free software?"

[-- Attachment #3: Type: text/plain, Size: 0 bytes --]

[PATCH] emacs: add minimal docstring for notmuch-unthreaded

[David Bremner]

The missing docstring causes a blank in the notmuch-help display
[1]. Since the function is a simple wrapper for notmuch-tree, it seems
fair to forward the reader there for more detailed information.

[1]: id:878sape5a9.fsf@disroot.org
---
 emacs/notmuch-tree.el | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/emacs/notmuch-tree.el b/emacs/notmuch-tree.el
index 001a367d..7fa73d40 100644
--- a/emacs/notmuch-tree.el
+++ b/emacs/notmuch-tree.el
@@ -1206,6 +1206,9 @@ The arguments are:
 
 (defun notmuch-unthreaded (&optional query query-context target buffer-name
 				     open-target)
+  "Display threads matching QUERY in unthreaded view.
+
+See function NOTMUCH-TREE for documentation of the arguments"
   (interactive)
   (notmuch-tree query query-context target buffer-name open-target t))
 
-- 
2.33.0

[PATCH] emacs: improve notmuch-*-from-current-query docstrings

[David Bremner]

Err on the side of providing better user documentation, rather than
documentation for developers.
---
 emacs/notmuch.el | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/emacs/notmuch.el b/emacs/notmuch.el
index 2ef67c0e..fa061693 100644
--- a/emacs/notmuch.el
+++ b/emacs/notmuch.el
@@ -535,12 +535,12 @@ thread."
       (message "End of search results."))))
 
 (defun notmuch-tree-from-search-current-query ()
-  "Call notmuch tree with the current query."
+  "Tree view of current query."
   (interactive)
   (notmuch-tree notmuch-search-query-string))
 
 (defun notmuch-unthreaded-from-search-current-query ()
-  "Call notmuch tree with the current query."
+  "Unthreaded view of current query."
   (interactive)
   (notmuch-unthreaded notmuch-search-query-string))
 
-- 
2.33.0

Re: [PATCH] emacs: add minimal docstring for notmuch-unthreaded

[David Bremner]

David Bremner <david@tethera.net> writes:

> The missing docstring causes a blank in the notmuch-help display
> [1]. Since the function is a simple wrapper for notmuch-tree, it seems
> fair to forward the reader there for more detailed information.

series applied to master.

d

[PATCH] emacs: drop C-tab binding in hello mode, document <backtab>.

[David Bremner]

The <backtab> binding has always been there, but the docs were
apparently mistakenly changed to say <backspace> [1]

Revert to <backtab> in the documentation.

The commit also drops the C-<tab> binding, since it seems redundant
and it (apparently) interferes with tabbar mode.

[1]: 703dec7754da477b5683867c88cb940b8553be91.
---
 doc/notmuch-emacs.rst  | 2 +-
 emacs/notmuch-hello.el | 1 -
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
index 12ee25e5..64f601f3 100644
--- a/doc/notmuch-emacs.rst
+++ b/doc/notmuch-emacs.rst
@@ -56,7 +56,7 @@ notmuch-hello key bindings
 ``<tab>``
     Move to the next widget (button or text entry field)
 
-``<backspace>``
+``<backstab>``
     Move to the previous widget.
 
 ``<return>``
diff --git a/emacs/notmuch-hello.el b/emacs/notmuch-hello.el
index 71487bd9..acd48c9b 100644
--- a/emacs/notmuch-hello.el
+++ b/emacs/notmuch-hello.el
@@ -702,7 +702,6 @@ with `notmuch-hello-query-counts'."
   ;; that when we modify map it does not modify widget-keymap).
   (let ((map (make-composed-keymap (list (make-sparse-keymap) widget-keymap))))
     (set-keymap-parent map notmuch-common-keymap)
-    (define-key map (kbd "<C-tab>") 'widget-backward)
     map)
   "Keymap for \"notmuch hello\" buffers.")
 
-- 
2.33.0

Re: [PATCH] emacs: drop C-tab binding in hello mode, document <backtab>.

[Ralph Seichter]

* David Bremner:

> -``<backspace>``
> +``<backstab>``

Are you sure you mean "backstab" with an "s"? I am currently watching a
newbie play Dark Souls, so I am unsure. ;-)

-Ralph

Re: [PATCH] emacs: drop C-tab binding in hello mode, document <backtab>.

[David Bremner]

Ralph Seichter <ralph@ml.seichter.de> writes:

> * David Bremner:
>
>> -``<backspace>``
>> +``<backstab>``
>
> Are you sure you mean "backstab" with an "s"? I am currently watching a
> newbie play Dark Souls, so I am unsure. ;-)
>

Hah, thanks for the correction.

d

[PATCH v2] emacs: drop C-tab binding in hello mode, document <backtab>.

[David Bremner]

The <backtab> binding has always been there, but the docs were
apparently mistakenly changed to say <backspace> [1]

Revert to <backtab> in the documentation.

The commit also drops the C-<tab> binding, since it seems redundant
and it interferes with tab-bar-mode.

[1]: 703dec7754da477b5683867c88cb940b8553be91.
---
 doc/notmuch-emacs.rst  | 2 +-
 emacs/notmuch-hello.el | 1 -
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
index 12ee25e5..22aee340 100644
--- a/doc/notmuch-emacs.rst
+++ b/doc/notmuch-emacs.rst
@@ -56,7 +56,7 @@ notmuch-hello key bindings
 ``<tab>``
     Move to the next widget (button or text entry field)
 
-``<backspace>``
+``<backtab>``
     Move to the previous widget.
 
 ``<return>``
diff --git a/emacs/notmuch-hello.el b/emacs/notmuch-hello.el
index 71487bd9..acd48c9b 100644
--- a/emacs/notmuch-hello.el
+++ b/emacs/notmuch-hello.el
@@ -702,7 +702,6 @@ with `notmuch-hello-query-counts'."
   ;; that when we modify map it does not modify widget-keymap).
   (let ((map (make-composed-keymap (list (make-sparse-keymap) widget-keymap))))
     (set-keymap-parent map notmuch-common-keymap)
-    (define-key map (kbd "<C-tab>") 'widget-backward)
     map)
   "Keymap for \"notmuch hello\" buffers.")
 
-- 
2.33.0

Re: [PATCH v2] emacs: drop C-tab binding in hello mode, document <backtab>.

[Tomi Ollila]

On Sat, Oct 30 2021, David Bremner wrote:

> The <backtab> binding has always been there, but the docs were
> apparently mistakenly changed to say <backspace> [1]
>
> Revert to <backtab> in the documentation.
>
> The commit also drops the C-<tab> binding, since it seems redundant
> and it interferes with tab-bar-mode.
>
> [1]: 703dec7754da477b5683867c88cb940b8553be91.

I am not against :D

> ---
>  doc/notmuch-emacs.rst  | 2 +-
>  emacs/notmuch-hello.el | 1 -
>  2 files changed, 1 insertion(+), 2 deletions(-)
>
> diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
> index 12ee25e5..22aee340 100644
> --- a/doc/notmuch-emacs.rst
> +++ b/doc/notmuch-emacs.rst
> @@ -56,7 +56,7 @@ notmuch-hello key bindings
>  ``<tab>``
>      Move to the next widget (button or text entry field)
>  
> -``<backspace>``
> +``<backtab>``
>      Move to the previous widget.
>  
>  ``<return>``
> diff --git a/emacs/notmuch-hello.el b/emacs/notmuch-hello.el
> index 71487bd9..acd48c9b 100644
> --- a/emacs/notmuch-hello.el
> +++ b/emacs/notmuch-hello.el
> @@ -702,7 +702,6 @@ with `notmuch-hello-query-counts'."
>    ;; that when we modify map it does not modify widget-keymap).
>    (let ((map (make-composed-keymap (list (make-sparse-keymap) widget-keymap))))
>      (set-keymap-parent map notmuch-common-keymap)
> -    (define-key map (kbd "<C-tab>") 'widget-backward)
>      map)
>    "Keymap for \"notmuch hello\" buffers.")
>  
> -- 
> 2.33.0

Re: [PATCH v2] emacs: drop C-tab binding in hello mode, document <backtab>.

[David Bremner]

David Bremner <david@tethera.net> writes:

> The <backtab> binding has always been there, but the docs were
> apparently mistakenly changed to say <backspace> [1]
>
> Revert to <backtab> in the documentation.
>
> The commit also drops the C-<tab> binding, since it seems redundant
> and it interferes with tab-bar-mode.
>
> [1]: 703dec7754da477b5683867c88cb940b8553be91.

Applied to master.

d

Re: Notmuch Emacs 0.31.2 documentation and keybinding suggestions

[David Bremner]

"Jorge P. de Morais Neto" <jorge+list@disroot.org> writes:

> Hi.  I would like to report the following documentation and keybinding
> imperfections:
>
> The info page
> [[info:notmuch-emacs.info#notmuch-hello key bindings]] says that
> <backspace> moves to the previous widget, but that key is actually bound
> to `delete-backward-char'.  To move to the previous widget I use <C-M-i>
> or <S-iso-lefttab>.  And why does <S-iso-lefttab> move backward but
> <S-C-i> (which ought to be equivalent to <S-iso-lefttab>, no?) moves forward?
>
> Also, it seems that <SPC> moves forward and <DEL> moves backward, but
> <S-SPC> does nothing useful.  For consistency with Emacs Info Mode,
> Emacs View Mode, and some other applications such as Firefox, perhaps
> <S-SPC> should move backward too.
>
> The introduction of help buffer for Notmuch-Show (reached by hitting
> <?>) describes the <SPC> command without mentioning that it can archive
> the thread; only in <SPC> specific description (which does not fit in
> the same window; one has to scroll) does it mention the archiving
> behavior.  I believe the archiving behavior should also be mentioned in
> the introduction, lest the user unwittingly archive a thread she wasn't
> supposed to.  Also, the description for <u> is empty (this also happens
> in the help buffer for Notmuch-Hello).
>
> In the same help buffer, the description of <c ?> says "Show help for a
> subkeymap."  Would it not be better to drop the "a", leaving "Show help
> for subkeymap." ?
>
> Finally, the binding for <C-tab> in Notmuch-Show and Notmuch-Hello
> inconveniently clobbers the tab-bar-mode binding for that key.  Should
> not Notmuch be content with <C-M-i>/<ESC tab>/<S-iso-lefttab> (and
> possibly <S-C-i>) and leave <C-Tab> alone?
>

I think I've fixed all I'm going to in 0.34.1-37-gc0115288 (should be
part of 0.35). If you think there are specific things that important and
still unresolved, please send one message per issue, it's much easier to
keep track of that way.

d