cli: address: Add --filter-by option to configure address filtering

[notmuch.git] / doc / man1 / notmuch-address.rst

diff --git a/doc/man1/notmuch-address.rst b/doc/man1/notmuch-address.rst
index 359616e0dc5f70215794a448a388a04075ced8b9..14034249c9622b4d5e12750bf3dd997f75f80814 100644 (file)
--- a/doc/man1/notmuch-address.rst
+++ b/doc/man1/notmuch-address.rst
@@ -11,7 +11,8 @@ DESCRIPTION
 ===========
 
 Search for messages matching the given search terms, and display the
-addresses from them. Duplicate addresses are filtered out.
+addresses from them. Duplicate addresses are filtered out. Filtering
+can be configured with the --filter-by option.
 
 See **notmuch-search-terms(7)** for details of the supported syntax for
 <search-terms>.
@@ -32,28 +33,28 @@ Supported options for **address** include
     ``--output=(sender|recipients|count)``
 
         Controls which information appears in the output. This option
-       can be given multiple times to combine different outputs.
-       Omitting this option is equivalent to
-       --output=sender --output=recipients.
+        can be given multiple times to combine different outputs.
+        When neither --output=sender nor --output=recipients is
+        given, --output=sender is implied.
 
-       **sender**
+        **sender**
             Output all addresses from the *From* header.
 
-           Note: Searching for **sender** should be much faster than
-           searching for **recipients**, because sender addresses are
-           cached directly in the database whereas other addresses
-           need to be fetched from message files.
+            Note: Searching for **sender** should be much faster than
+            searching for **recipients**, because sender addresses are
+            cached directly in the database whereas other addresses
+            need to be fetched from message files.
 
-       **recipients**
+        **recipients**
             Output all addresses from the *To*, *Cc* and *Bcc*
             headers.
 
-       **count**
-           Print the count of how many times was the address
-           encountered during search.
+        **count**
+            Print the count of how many times was the address
+            encountered during search.
 
-           Note: With this option, addresses are printed only after
-           the whole search is finished. This may take long time.
+            Note: With this option, addresses are printed only after
+            the whole search is finished. This may take long time.
 
     ``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
         This option can be used to present results in either
@@ -63,7 +64,7 @@ Supported options for **address** include
         By default, results will be displayed in reverse chronological
         order, (that is, the newest results will be displayed first).
 
-       This option has no effect when used with --output=count.
+        This option is not supported with --output=count.
 
     ``--exclude=(true|false)``
         A message is called "excluded" if it matches at least one tag in
@@ -77,6 +78,39 @@ Supported options for **address** include
         **false** allows excluded messages to match search terms and
         appear in displayed results.
 
+    ``--filter-by=``\ (**nameaddr**\ \|\ **name** \|\ **addr**\ \|\ **addrfold**\ \|\ **nameaddrfold**\)
+
+       Controls how to filter out duplicate addresses. The filtering
+       algorithm receives a sequence of email addresses and outputs
+       the same sequence without the addresses that are considered a
+       duplicate of a previously output address. What is considered a
+       duplicate depends on how the two addresses are compared:
+
+       **nameaddr** means that both name and address parts are
+       compared in case-sensitive manner. Therefore, all same looking
+       addresses strings are considered duplicate. This is the
+       default.
+
+       **name** means that only the name part is compared (in
+       case-sensitive manner). For example, the addresses "John Doe
+       <me@example.com>" and "John Doe <john@doe.name>" will be
+       considered duplicate.
+
+       **addr** means that only the address part is compared (in
+       case-sensitive manner). For example, the addresses "John Doe
+       <john@example.com>" and "Dr. John Doe <john@example.com>" will
+       be considered duplicate.
+
+       **addrfold** is like **addr**, but comparison is done in
+       canse-insensitive manner. For example, the addresses "John Doe
+       <john@example.com>" and "Dr. John Doe <JOHN@EXAMPLE.COM>" will
+       be considered duplicate.
+
+       **nameaddrfold** is like **nameaddr**, but address comparison
+       is done in canse-insensitive manner. For example, the
+       addresses "John Doe <john@example.com>" and "John Doe
+       <JOHN@EXAMPLE.COM>" will be considered duplicate.
+
 EXIT STATUS
 ===========
 
@@ -95,4 +129,4 @@ SEE ALSO
 **notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
 **notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
 **notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**,
-***notmuch-search(1)**
+**notmuch-search(1)**