When adding the description of the propagation of NOTMUCH_CONFIG, I missed that there was already a section on external commands, with a different title. --- doc/man1/notmuch.rst | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst index e0892e01..1fec4ee5 100644 --- a/doc/man1/notmuch.rst +++ b/doc/man1/notmuch.rst @@ -130,14 +130,16 @@ and to restore from that dump. The :any:`notmuch-config(1)` command can be used to get or set settings in the notmuch configuration file. -CUSTOM COMMANDS ---------------- +EXTERNAL COMMANDS +----------------- If the given command is not known to notmuch, notmuch tries to execute the external **notmuch-<subcommand>** in :envvar:`PATH` instead. This allows users to have their own notmuch related tools to be run via the notmuch command. By design, this does not allow notmuch's own commands -to be overridden using external commands. +to be overridden using external commands. The environment variable +:envvar:`NOTMUCH_CONFIG` will be set according to :option:`--config`, +if the latter is present. OPTION SYNTAX ------------- @@ -185,14 +187,6 @@ of notmuch. If set to a non-empty value, the notmuch library will print (to stderr) Xapian queries it constructs. -EXTERNAL COMMANDS -================= - -When given a subcommand `foo` not recognized as built-in, notmuch will -try to run the command (e.g. script) `notmuch-foo` in the user's -path. The :envvar:`NOTMUCH_CONFIG` will be set according to -:option:`--config`, if the latter is present. - SEE ALSO ======== -- 2.35.2
It should have one in any case, but in particular it is needed for the manual. --- emacs/notmuch-show.el | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/emacs/notmuch-show.el b/emacs/notmuch-show.el index 1bc3b319..a729ce77 100644 --- a/emacs/notmuch-show.el +++ b/emacs/notmuch-show.el @@ -1135,6 +1135,10 @@ is t, hide the part initially and show the button." (make-variable-buffer-local 'notmuch-show-previous-subject) (defun notmuch-show-choose-duplicate (duplicate) + "Display message file DUPLICATE in place of the current one. + +The numbering is consistent with that used by the CLI. An error +will be signaled if DUPLICATE is out of range." (interactive "Nduplicate: ") (let ((count (length (notmuch-show-get-prop :filename)))) (when (or (> duplicate count) -- 2.35.2
This is mainly motivated by the new emacs-UI features to select duplicates, but hopefully it will help demystify things for users of the CLI as well. --- doc/man1/notmuch.rst | 17 +++++++++++++++++ doc/notmuch-emacs.rst | 25 +++++++++++++++++++++++++ 2 files changed, 42 insertions(+) diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst index 1fec4ee5..4b146e41 100644 --- a/doc/man1/notmuch.rst +++ b/doc/man1/notmuch.rst @@ -155,6 +155,23 @@ equivalent: notmuch --config:alt-config config get user.name notmuch --config alt-config config get user.name +.. _duplicate-files: + +DUPLICATE MESSAGE FILES +======================= + +Notmuch considers the :mailheader:`Message-ID` to be the primary +identifier of message. Per :rfc:`5322` the :mailheader:`Message-ID` is +supposed to be globally unique, but this fails in two distinct +ways. When you receive copies of a message via a mechanism like +:mailheader:`Cc` or via a mailing list, the copies are typically +interchangeable. In the case of some broken mail sending software, the +same :mailheader:`Message-ID` is used for completely unrelated +messages. The options :option:`search --duplicate` and :option:`show +--duplicate` options provide the user with control over which message +file is displayed. Front ends will need to provide their own +interface, see e.g. :any:`emacs-show-duplicates`. + ENVIRONMENT =========== diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst index e69bd23d..162f62a4 100644 --- a/doc/notmuch-emacs.rst +++ b/doc/notmuch-emacs.rst @@ -431,6 +431,31 @@ in :ref:`notmuch-search`. ``c ?`` Show all available copying commands +.. _emacs-show-duplicates: + +Dealing with duplicates +----------------------- + +If there are are multiple files with the same :mailheader:`Message-ID` +(see :any:`duplicate-files`), then :any:`notmuch-show` displays the +number of duplicates and identifies the current duplicate. In the +following example duplicate 3 of 5 is displayed. + +.. code-block:: + :emphasize-lines: 1 + + M. Mustermann <max@example.com> (Sat, 30 Jul 2022 10:33:10 -0300) (inbox signed) 3/5 + Subject: Re: Multiple files per message in emacs + To: notmuch@notmuchmail.org + +To display a different message file with the same +:mailheader:`Message-ID`, the user can run the command +:emacscmd:`notmuch-show-choose-duplicate`, by default bound to `%`. + +.. emacscmd:: notmuch-show-choose-duplicate + + |docstring::notmuch-show-choose-duplicate| + .. _notmuch-tree: notmuch-tree -- 2.35.2
It should have one in any case, but in particular it is needed for the manual. --- I realized my first attempt at a docstring didn't work well in the manual. emacs/notmuch-show.el | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/emacs/notmuch-show.el b/emacs/notmuch-show.el index 1bc3b319..6653358c 100644 --- a/emacs/notmuch-show.el +++ b/emacs/notmuch-show.el @@ -1135,6 +1135,16 @@ is t, hide the part initially and show the button." (make-variable-buffer-local 'notmuch-show-previous-subject) (defun notmuch-show-choose-duplicate (duplicate) + "Display message file with index DUPLICATE in place of the current one. + +Message file indices are based on the order the files are +discovered by `notmuch new' (and hence are somewhat arbitrary), +and correspond to those passed to the \"\\-\\-duplicate\" arguments +to the CLI. + +When called interactively, the function will prompt for the index +of the file to display. An error will be signaled if the index +is out of range." (interactive "Nduplicate: ") (let ((count (length (notmuch-show-get-prop :filename)))) (when (or (> duplicate count) -- 2.35.2
David Bremner <david@tethera.net> writes:
> When adding the description of the propagation of NOTMUCH_CONFIG, I
> missed that there was already a section on external commands, with a
> different title.
This one patch applied to master
David Bremner <david@tethera.net> writes:
> This is mainly motivated by the new emacs-UI features to select
> duplicates, but hopefully it will help demystify things for users of
> the CLI as well.
applied the remaining two patches to master (with a tiny adjustment of
wording for the man output in the second patch).
d