Emacs documentation updates v2

Emacs documentation updates v2

[David Bremner]

Sorry to send the second version so quickly, but I skipped two patches
which will probably make id:20240814105741.1456503-1-david@tethera.net
impossible to apply cleanly.

[PATCH v2 1/4] doc/emacs: start a section on notmuch-message-mode

[David Bremner]

This is mostly just copying docstrings, but putting them into sections
makes them more discoverable.
---
 doc/conf.py           |  2 +-
 doc/notmuch-emacs.rst | 57 ++++++++++++++++++++++++++++++++++++-------
 2 files changed, 49 insertions(+), 10 deletions(-)

diff --git a/doc/conf.py b/doc/conf.py
index ee1b336a..5270011d 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -47,7 +47,7 @@ if tags.has('WITH_EMACS'):
     # Hacky reimplementation of include to workaround limitations of
     # sphinx-doc
     lines = ['.. include:: /../emacs/rstdoc.rsti\n\n'] # in the source tree
-    for file in ('notmuch.rsti', 'notmuch-lib.rsti', 'notmuch-hello.rsti', 'notmuch-show.rsti', 'notmuch-tag.rsti', 'notmuch-tree.rsti'):
+    for file in ('notmuch.rsti', 'notmuch-lib.rsti', 'notmuch-hello.rsti', 'notmuch-show.rsti', 'notmuch-tag.rsti', 'notmuch-tree.rsti', 'notmuch-maildir-fcc.rsti'):
         lines.extend(open(rsti_dir+'/'+file))
     rst_epilog = ''.join(lines)
     del lines
diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
index 91af6d14..48f87458 100644
--- a/doc/notmuch-emacs.rst
+++ b/doc/notmuch-emacs.rst
@@ -671,6 +671,54 @@ Keybindings are the same as :any:`notmuch-tree`.
    See also :el:defcustom:`notmuch-search-result-format` and
    :el:defcustom:`notmuch-tree-result-format`.
 
+notmuch-message
+===============
+
+Notmuch uses a slighly customized version of the standard emacs email
+composition mode info:message.
+
+.. _notmuch-emacs-drafts:
+
+Drafts
+------
+
+.. el:define-key:: C-x C-p
+                   M-x notmuch-draft-postpone
+
+   Postpone (save and bury) a draft.
+
+.. el:define-key:: C-x C-s
+                   M-x notmuch-draft-save
+
+   Save a draft and continue editing.
+
+.. _notmuch-emacs-replies:
+
+.. _notmuch-emacs-fcc:
+
+Fcc
+---
+
+.. el:defcustom:: notmuch-fcc-dirs
+
+   |docstring::notmuch-fcc-dirs|
+
+.. el:defcustom:: notmuch-maildir-use-notmuch-insert
+
+   |docstring::notmuch-maildir-use-notmuch-insert|
+
+Replies
+-------
+
+.. el:defcustom:: message-dont-reply-to-names
+
+       When composing mail replies, Emacs's message mode uses the
+       variable :code:`message-dont-reply-to-names` to exclude
+       recipients matching a given collection of regular expressions
+       or satisfying an arbitrary predicate.  Notmuch's MUA inherits
+       this standard mechanism and will honour your customization of
+       this variable.
+
 Global key bindings
 ===================
 
@@ -770,15 +818,6 @@ Sending Mail
        :code:`compose-mail`.  To use ``notmuch`` for this, customize this
        variable to the symbol :code:`notmuch-user-agent`.
 
-.. el:defcustom:: message-dont-reply-to-names
-
-       When composing mail replies, Emacs's message mode uses the
-       variable :code:`message-dont-reply-to-names` to exclude
-       recipients matching a given collection of regular expressions
-       or satisfying an arbitrary predicate.  Notmuch's MUA inherits
-       this standard mechanism and will honour your customization of
-       this variable.
-
 Init File
 ---------
 
-- 
2.43.0

[PATCH v2 2/4] doc/emacs: refactor navigation commands

[David Bremner]

The amount of space saved here is minimal, but I want to migrate to a
more topic focused manual, as opposed to long alphabetical lists of
commands.
---
 doc/notmuch-emacs.rst | 52 ++++++++++++++++++++-----------------------
 1 file changed, 24 insertions(+), 28 deletions(-)

diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
index 48f87458..bf862697 100644
--- a/doc/notmuch-emacs.rst
+++ b/doc/notmuch-emacs.rst
@@ -320,6 +320,27 @@ pressing RET after positioning the cursor on a hidden part.
 
     :ref:`show-copy`
 
+.. el:define-key:: +
+                   -
+
+    Add or remove arbitrary tags from the current message.
+
+.. el:define-key:: !
+
+    |docstring::notmuch-show-toggle-elide-non-matching|
+
+.. el:define-key:: ?
+
+    Display full set of key bindings
+
+.. _show-navigation:
+
+Navigation
+----------
+
+The following motion/navigation bindings are also available in
+:ref:`notmuch-tree` and :ref:`notmuch-unthreaded`.
+
 .. el:define-key:: N
 
     Move to next message
@@ -336,18 +357,9 @@ pressing RET after positioning the cursor on a hidden part.
 
     Move to previous matching message
 
-.. el:define-key:: +
-                   -
-
-    Add or remove arbitrary tags from the current message.
-
-.. el:define-key:: !
-
-    |docstring::notmuch-show-toggle-elide-non-matching|
 
-.. el:define-key:: ?
-
-    Display full set of key bindings
+Configuration
+-------------
 
 Display of messages can be controlled by the following variables; see also :ref:`show-large`.
 
@@ -522,7 +534,7 @@ notmuch-tree
 ``notmuch-tree-mode`` displays the results of a "notmuch tree" of your
 email archives. Each line in the buffer represents a single
 message giving the relative date, the author, subject, and any
-tags.
+tags. For common navigation commands see :ref:`show-navigation`.
 
 .. el:define-key:: c
 
@@ -532,22 +544,6 @@ tags.
 
    Displays that message.
 
-.. el:define-key:: N
-
-    Move to next message
-
-.. el:define-key:: P
-
-    Move to previous message
-
-.. el:define-key:: n
-
-    Move to next matching message
-
-.. el:define-key:: p
-
-    Move to previous matching message
-
 .. el:define-key:: o
    M-x notmuch-tree-toggle-order
 
-- 
2.43.0

[PATCH v2 3/4] doc/emacs: update keybindings list for 'e'

[David Bremner]

The mention of notmuch-tree-button-activate seems to have been an
error / obsolete.
---
 devel/emacs-keybindings.org | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/devel/emacs-keybindings.org b/devel/emacs-keybindings.org
index d8b443e6..ac98cb66 100644
--- a/devel/emacs-keybindings.org
+++ b/devel/emacs-keybindings.org
@@ -5,7 +5,7 @@
 | b            | notmuch-search-scroll-down                   | notmuch-show-resend-message                           | notmuch-show-resend-message                |
 | c            | notmuch-search-stash-map                     | notmuch-show-stash-map                                | notmuch-show-stash-map                     |
 | d            |                                              |                                                       |                                            |
-| e            |                                              |                                                       | (notmuch-tree-button-activate)             |
+| e            |                                              | notmuch-show-resume-message                           | notmuch-tree-resume-message                |
 | f            |                                              | notmuch-show-forward-message                          | notmuch-show-forward-message               |
 | g            |                                              |                                                       |                                            |
 | h            |                                              | notmuch-show-toggle-visibility-headers                |                                            |
-- 
2.43.0

[PATCH v2 4/4] doc/emacs: start subsection on message level actions

[David Bremner]

In particular this gives a place for documenting how to resume editing
drafts.
---
 doc/notmuch-emacs.rst | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
index bf862697..9c2dab47 100644
--- a/doc/notmuch-emacs.rst
+++ b/doc/notmuch-emacs.rst
@@ -357,6 +357,42 @@ The following motion/navigation bindings are also available in
 
     Move to previous matching message
 
+Actions
+-------
+
+The following actions on messages are also available in
+:ref:`notmuch-tree` and :ref:`notmuch-unthreaded`.
+
+.. el:define-key:: b
+                   M-x notmuch-show-resend-message
+
+   Resend (*bounce*) message.
+
+.. el:define-key:: e
+
+   Resume *editing* a message in :ref:`notmuch-message`. This is
+   particularly useful for :ref:`notmuch-emacs-drafts`, but can be
+   used for other messages as well.
+
+.. el:define-key:: f
+                   M-x notmuch-show-forward-message
+
+   Forward (as a MIME attachment) message
+
+.. el:define-key:: r
+                   M-x notmuch-show-reply-to-sender
+
+   Reply to sender (only) using :ref:`notmuch-message`
+
+.. el:define-key:: w
+                   M-x notmuch-show-save-attachments
+
+   |docstring::notmuch-show-save-attachments|
+
+.. el:define-key:: R
+                   M-x notmuch-show-reply
+
+   |docstring::notmuch-show-reply|
 
 Configuration
 -------------
@@ -667,6 +703,8 @@ Keybindings are the same as :any:`notmuch-tree`.
    See also :el:defcustom:`notmuch-search-result-format` and
    :el:defcustom:`notmuch-tree-result-format`.
 
+.. _notmuch-message:
+
 notmuch-message
 ===============
 
-- 
2.43.0