Re: Notmuch Emacs 0.31.2 documentation and keybinding suggestions

[Jorge P. de Morais Neto <jorge+list@disroot.org>]

[-- 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 --]