From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id EAdcN8fC5WIVEQEAbAwnHQ (envelope-from ) for ; Sun, 31 Jul 2022 01:46:15 +0200 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id 2C80N8fC5WKlEgEAauVa8A (envelope-from ) for ; Sun, 31 Jul 2022 01:46:15 +0200 Received: from mail.notmuchmail.org (yantan.tethera.net [IPv6:2a01:4f9:c011:7a79::1]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id A02829A42 for ; Sun, 31 Jul 2022 01:46:15 +0200 (CEST) Received: from yantan.tethera.net (localhost [127.0.0.1]) by mail.notmuchmail.org (Postfix) with ESMTP id 1C9835F3E2; Sat, 30 Jul 2022 23:46:06 +0000 (UTC) Received: from fethera.tethera.net (fethera.tethera.net [198.245.60.197]) by mail.notmuchmail.org (Postfix) with ESMTP id BD1A75F38B for ; Sat, 30 Jul 2022 23:46:02 +0000 (UTC) Received: by fethera.tethera.net (Postfix, from userid 1001) id 037605FBC0; Sat, 30 Jul 2022 19:46:01 -0400 (EDT) Received: (nullmailer pid 2623922 invoked by uid 1000); Sat, 30 Jul 2022 23:45:58 -0000 From: David Bremner To: notmuch@notmuchmail.org Subject: [PATCH 3/3] doc: add some documentation about duplicate files. Date: Sat, 30 Jul 2022 20:45:51 -0300 Message-Id: <20220730234551.2623885-3-david@tethera.net> X-Mailer: git-send-email 2.35.2 In-Reply-To: <20220730234551.2623885-1-david@tethera.net> References: <20220730234551.2623885-1-david@tethera.net> MIME-Version: 1.0 Message-ID-Hash: AZJXAVFUKTBPWCPI7B2H65OV5UZ67A3P X-Message-ID-Hash: AZJXAVFUKTBPWCPI7B2H65OV5UZ67A3P X-MailFrom: bremner@tethera.net X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-notmuch.notmuchmail.org-0; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.3 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Migadu-Flow: FLOW_IN X-Migadu-To: larch@yhetil.org X-Migadu-Country: DE ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1659224775; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-owner:list-unsubscribe:list-subscribe:list-post; bh=cGkQGMr/Kcelb+7N4sImx6bcoklXzFNcoEdJyFkRbN8=; b=Swvsg4C/7RbsIhxCnyuHzKPkYMnDAsnlBo14qp7mnIy+pmL//p5W3PPnMTFZH3eGvc1F5Q pcnozCPehrDq2L5wl4Hlg6ghlQvuSjZo6jaBWSs6jyPrW+xYISj7JEB2Bh0T8TNrXKRI+w 7xIj7ZrY+oNkX+fjNe7Wmly1Qj7739ajRwtldxNGGZplKKtqk152RBDCGYFVbavUFvLDTT E6AvH35qYW4MZE+urpQrVNFRI+bEVM6LS3wHFuq+htiYgIxQTqpiWgu+rGaTy6iHaul/f6 VqJ/oXevld/tPqEvyDKG3BAJgMMooD6dkB6zaXHvEo85AVlvBznDkPqTIHuAJQ== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1659224775; a=rsa-sha256; cv=none; b=Dj2NHEMEpadH7j3L19fLQmTPqgDABJh6AlgFT3tQQeCfxhOuHZE8syon/PuVJ7tlTevBOg Km0L6ArlQSZ9k///eJgFld5efciXGwrsbI+Zoz7wmppKlx7lJa292IBr+os7fqAGGZLL4V xKgxQgIgtj7P+3R4L2TynlP0dWktMe9UwE3CdyBpyv2jNAVmcnIpLGIsNW+IpGA4eUfw85 r6wpslajRfg+4IbZh0poEi/3LigUmcaJ356QI17ZI/ZJKE745MCDV5NQknCoHE85Xz/byK 6Ca3Is7vbwC5/rrYtefSQ9+dFZrAsaNXT60VI9E/UVC8m54nhOUHmn821E9wsg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=none; dmarc=none; spf=pass (aspmx1.migadu.com: domain of notmuch-bounces@notmuchmail.org designates 2a01:4f9:c011:7a79::1 as permitted sender) smtp.mailfrom=notmuch-bounces@notmuchmail.org X-Migadu-Spam-Score: -1.32 Authentication-Results: aspmx1.migadu.com; dkim=none; dmarc=none; spf=pass (aspmx1.migadu.com: domain of notmuch-bounces@notmuchmail.org designates 2a01:4f9:c011:7a79::1 as permitted sender) smtp.mailfrom=notmuch-bounces@notmuchmail.org X-Migadu-Queue-Id: A02829A42 X-Spam-Score: -1.32 X-Migadu-Scanner: scn0.migadu.com X-TUID: 1u/hi5tKisPh 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 (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