diff options
| author | David Bremner <david@tethera.net> | 2022-07-30 20:45:51 -0300 |
|---|---|---|
| committer | David Bremner <david@tethera.net> | 2022-08-11 07:32:04 -0300 |
| commit | bf64c48855f41833b57e0a770ad37f6a16a1193b (patch) | |
| tree | 53198f6cabfdbcc1e2be56a6996a8a326ed84326 | |
| parent | 5a47b5a884d594e74bb967dd8bb0500c7051bd79 (diff) | |
doc: add some documentation about duplicate files.
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.
| -rw-r--r-- | doc/man1/notmuch.rst | 17 | ||||
| -rw-r--r-- | doc/notmuch-emacs.rst | 25 |
2 files changed, 42 insertions, 0 deletions
diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst index 1fec4ee5..c488f12a 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. the Emacs front-end :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 |