Merge tag 0.28.4

[notmuch] / doc / man1 / notmuch-show.rst

diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst
index 2b825ccc1ba713a8b434fb167d278d8a97ab324e..becd3e79929023b089a9e5542c15380961aae58f 100644 (file)
--- a/doc/man1/notmuch-show.rst
+++ b/doc/man1/notmuch-show.rst
@@ -71,7 +71,7 @@ Supported options for **show** include
 
             http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
 
 
             http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
 

-    **raw** (default if --part is given)
+    **raw** (default if ``--part`` is given)

         Write the raw bytes of the given MIME part of a message to
         standard out. For this format, it is an error to specify a
         query that matches more than one message.
         Write the raw bytes of the given MIME part of a message to
         standard out. For this format, it is an error to specify a
         query that matches more than one message.


@@ -105,40 +105,68 @@ Supported options for **show** include
 
 ``--verify``
     Compute and report the validity of any MIME cryptographic
 
 ``--verify``
     Compute and report the validity of any MIME cryptographic

-    signatures found in the selected content (ie. "multipart/signed"
+    signatures found in the selected content (e.g., "multipart/signed"

     parts). Status of the signature will be reported (currently only
     parts). Status of the signature will be reported (currently only

-    supported with --format=json and --format=sexp), and the
+    supported with ``--format=json`` and ``--format=sexp``), and the

     multipart/signed part will be replaced by the signed data.
 
     multipart/signed part will be replaced by the signed data.
 

-``--decrypt=(false|auto|true)``
+``--decrypt=(false|auto|true|stash)``

     If ``true``, decrypt any MIME encrypted parts found in the
     If ``true``, decrypt any MIME encrypted parts found in the

-    selected content (i.e. "multipart/encrypted" parts). Status of
+    selected content (e.g., "multipart/encrypted" parts). Status of

     the decryption will be reported (currently only supported
     the decryption will be reported (currently only supported

-    with --format=json and --format=sexp) and on successful
+    with ``--format=json`` and ``--format=sexp``) and on successful

     decryption the multipart/encrypted part will be replaced by
     the decrypted content.
 
     decryption the multipart/encrypted part will be replaced by
     the decrypted content.
 

+    ``stash`` behaves like ``true``, but upon successful decryption it
+    will also stash the message's session key in the database, and
+    index the cleartext of the message, enabling automatic decryption
+    in the future.
+

     If ``auto``, and a session key is already known for the
     message, then it will be decrypted, but notmuch will not try
     to access the user's keys.
 
     Use ``false`` to avoid even automatic decryption.
 
     If ``auto``, and a session key is already known for the
     message, then it will be decrypted, but notmuch will not try
     to access the user's keys.
 
     Use ``false`` to avoid even automatic decryption.
 

-    Non-automatic decryption expects a functioning
-    **gpg-agent(1)** to provide any needed credentials. Without
-    one, the decryption will fail.
-
-    Note: ``true`` implies --verify.
+    Non-automatic decryption (``stash`` or ``true``, in the absence of
+    a stashed session key) expects a functioning **gpg-agent(1)** to
+    provide any needed credentials. Without one, the decryption will
+    fail.
+
+    Note: setting either ``true`` or ``stash`` here implies
+    ``--verify``.
+
+    Here is a table that summarizes each of these policies:
+
+    +------------------------+-------+------+------+-------+
+    |                        | false | auto | true | stash |
+    +========================+=======+======+======+=======+
+    | Show cleartext if      |       |  X   |  X   |   X   |
+    | session key is         |       |      |      |       |
+    | already known          |       |      |      |       |
+    +------------------------+-------+------+------+-------+
+    | Use secret keys to     |       |      |  X   |   X   |
+    | show cleartext         |       |      |      |       |
+    +------------------------+-------+------+------+-------+
+    | Stash any newly        |       |      |      |   X   |
+    | recovered session keys,|       |      |      |       |
+    | reindexing message if  |       |      |      |       |
+    | found                  |       |      |      |       |
+    +------------------------+-------+------+------+-------+
+
+    Note: ``--decrypt=stash`` requires write access to the database.
+    Otherwise, ``notmuch show`` operates entirely in read-only mode.

 
     Default: ``auto``
 
 ``--exclude=(true|false)``
 
     Default: ``auto``
 
 ``--exclude=(true|false)``

-    Specify whether to omit threads only matching search.tag\_exclude
+    Specify whether to omit threads only matching search.exclude\_tags

     from the search results (the default) or not. In either case the
     excluded message will be marked with the exclude flag (except when
     output=mbox when there is nowhere to put the flag).
 
     from the search results (the default) or not. In either case the
     excluded message will be marked with the exclude flag (except when
     output=mbox when there is nowhere to put the flag).
 

-    If --entire-thread is specified then complete threads are returned
+    If ``--entire-thread`` is specified then complete threads are returned

     regardless (with the excluded flag being set when appropriate) but
     threads that only match in an excluded message are not returned
     when ``--exclude=true.``
     regardless (with the excluded flag being set when appropriate) but
     threads that only match in an excluded message are not returned
     when ``--exclude=true.``


@@ -148,18 +176,19 @@ Supported options for **show** include
 ``--body=(true|false)``
     If true (the default) **notmuch show** includes the bodies of the
     messages in the output; if false, bodies are omitted.
 ``--body=(true|false)``
     If true (the default) **notmuch show** includes the bodies of the
     messages in the output; if false, bodies are omitted.

-    ``--body=false`` is only implemented for the json and sexp formats
-    and it is incompatible with ``--part > 0.``
+    ``--body=false`` is only implemented for the text, json and sexp
+    formats and it is incompatible with ``--part > 0.``

 
     This is useful if the caller only needs the headers as body-less
     output is much faster and substantially smaller.
 
 ``--include-html``
 
     This is useful if the caller only needs the headers as body-less
     output is much faster and substantially smaller.
 
 ``--include-html``

-    Include "text/html" parts as part of the output (currently only
-    supported with --format=json and --format=sexp). By default,
-    unless ``--part=N`` is used to select a specific part or
-    ``--include-html`` is used to include all "text/html" parts, no
-    part with content type "text/html" is included in the output.
+    Include "text/html" parts as part of the output (currently
+    only supported with ``--format=text``, ``--format=json`` and
+    ``--format=sexp``). By default, unless ``--part=N`` is used to
+    select a specific part or ``--include-html`` is used to include all
+    "text/html" parts, no part with content type "text/html" is included
+    in the output.

 
 A common use of **notmuch show** is to display a single thread of email
 messages. For this, use a search term of "thread:<thread-id>" as can be
 
 A common use of **notmuch show** is to display a single thread of email
 messages. For this, use a search term of "thread:<thread-id>" as can be