doc: add some documentation about duplicate files.

[notmuch] / doc / man1 / notmuch.rst

diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst
index e0892e01667be75a8ae66ab3a89ad737ad9f12e8..c488f12a9e7a58193486b5dd5fdf76fe31f62057 100644 (file)
--- 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
 -------------
@@ -153,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
 ===========
 
@@ -185,14 +204,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
 ========