Merge branch 'release'
authorDavid Bremner <david@tethera.net>
Sun, 31 Dec 2017 13:26:13 +0000 (09:26 -0400)
committerDavid Bremner <david@tethera.net>
Sun, 31 Dec 2017 13:26:13 +0000 (09:26 -0400)
Conflicts:
        doc/man1/notmuch-reply.rst
doc/man1/notmuch-show.rst

Conflicts taken from release (dkg's doc changes)

1  2 
doc/man1/notmuch-reply.rst
doc/man1/notmuch-show.rst

index 4c86a92f8196b041b9b69fb09bfe135f6cb5554d,1b62e075c29689a561d94be970db20bf12b8d474..b01698344fa69fcb484c3110c86f5deb72f4a8f8
@@@ -34,56 -34,64 +34,62 @@@ The resulting message template is outpu
  
  Supported options for **reply** include
  
 -    ``--format=``\ (**default**\ \|\ **json**\ \|\ **sexp**\ \|\ **headers-only**)
 -
 -        **default**
 -            Includes subject and quoted message body as an RFC 2822
 -            message.
 -
 -        **json**
 -            Produces JSON output containing headers for a reply message
 -            and the contents of the original message. This output can be
 -            used by a client to create a reply message intelligently.
 -
 -        **sexp**
 -            Produces S-Expression output containing headers for a reply
 -            message and the contents of the original message. This
 -            output can be used by a client to create a reply message
 -            intelligently.
 -
 -        **headers-only**
 -            Only produces In-Reply-To, References, To, Cc, and Bcc
 -            headers.
 -
 -    ``--format-version=N``
 -        Use the specified structured output format version. This is
 -        intended for programs that invoke **notmuch(1)** internally. If
 -        omitted, the latest supported version will be used.
 -
 -    ``--reply-to=``\ (**all**\ \|\ **sender**)
 -
 -        **all** (default)
 -            Replies to all addresses.
 -
 -        **sender**
 -            Replies only to the sender. If replying to user's own
 -            message (Reply-to: or From: header is one of the user's
 -            configured email addresses), try To:, Cc:, and Bcc: headers
 -            in this order, and copy values from the first that contains
 -            something other than only the user's addresses.
 +``--format=``\ (**default**\ \|\ **json**\ \|\ **sexp**\ \|\ **headers-only**)
 +    **default**
 +        Includes subject and quoted message body as an RFC 2822
 +        message.
 +
 +    **json**
 +        Produces JSON output containing headers for a reply message
 +        and the contents of the original message. This output can be
 +        used by a client to create a reply message intelligently.
 +
 +    **sexp**
 +        Produces S-Expression output containing headers for a reply
 +        message and the contents of the original message. This output
 +        can be used by a client to create a reply message
 +        intelligently.
 +
 +    **headers-only**
 +        Only produces In-Reply-To, References, To, Cc, and Bcc
 +        headers.
 +
 +``--format-version=N``
 +    Use the specified structured output format version. This is
 +    intended for programs that invoke **notmuch(1)** internally. If
 +    omitted, the latest supported version will be used.
 +
 +``--reply-to=``\ (**all**\ \|\ **sender**)
 +    **all** (default)
 +        Replies to all addresses.
 +
 +    **sender**
 +        Replies only to the sender. If replying to user's own message
 +        (Reply-to: or From: header is one of the user's configured
 +        email addresses), try To:, Cc:, and Bcc: headers in this
 +        order, and copy values from the first that contains something
 +        other than only the user's addresses.
  
- ``--decrypt``
-     Decrypt any MIME encrypted parts found in the selected content
-     (ie. "multipart/encrypted" parts). Status of the decryption will
-     be reported (currently only supported with --format=json and
-     --format=sexp) and on successful decryption the
-     multipart/encrypted part will be replaced by the decrypted
-     content.
-     If a session key is already known for the message, then it will be
-     decrypted automatically unless the user explicitly sets
-     ``--decrypt=false``.
-     Decryption expects a functioning **gpg-agent(1)** to provide any
-     needed credentials. Without one, the decryption will likely fail.
+     ``--decrypt=(false|auto|true)``
+         If ``true``, decrypt any MIME encrypted parts found in the
+         selected content (i.e., "multipart/encrypted" parts). Status
+         of the decryption will be reported (currently only supported
+         with --format=json and --format=sexp), and on successful
+         decryption the multipart/encrypted part will be replaced by
+         the decrypted content.
+         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 secret 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 likely fail.
+         Default: ``auto``
  
  See **notmuch-search-terms(7)** for details of the supported syntax for
  <search-terms>.
index 3bc8d17b0af778a257b02affdabd39e3b3f07306,7d2b38cbb97eb3c1dc1c61282330af75da5123c6..ad72a740252f126443fd9aa3382ba4952b68b250
@@@ -71,90 -75,97 +71,95 @@@ Supported options for **show** includ
  
              http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
  
 -        **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.
 -
 -            If the specified part is a leaf part, this outputs the
 -            body of the part after performing content transfer
 -            decoding (but no charset conversion). This is suitable for
 -            saving attachments, for example.
 -
 -            For a multipart or message part, the output includes the
 -            part headers as well as the body (including all child
 -            parts). No decoding is performed because multipart and
 -            message parts cannot have non-trivial content transfer
 -            encoding. Consumers of this may need to implement MIME
 -            decoding and similar functions.
 -
 -    ``--format-version=N``
 -        Use the specified structured output format version. This is
 -        intended for programs that invoke **notmuch(1)** internally. If
 -        omitted, the latest supported version will be used.
 -
 -    ``--part=N``
 -        Output the single decoded MIME part N of a single message. The
 -        search terms must match only a single message. Message parts are
 -        numbered in a depth-first walk of the message MIME structure,
 -        and are identified in the 'json', 'sexp' or 'text' output
 -        formats.
 -
 -        Note that even a message with no MIME structure or a single
 -        body part still has two MIME parts: part 0 is the whole
 -        message (headers and body) and part 1 is just the body.
 -
 -    ``--verify``
 -        Compute and report the validity of any MIME cryptographic
 -        signatures found in the selected content (ie. "multipart/signed"
 -        parts). Status of the signature will be reported (currently only
 -        supported with --format=json and --format=sexp), and the
 -        multipart/signed part will be replaced by the signed data.
 +    **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.
 +
 +        If the specified part is a leaf part, this outputs the body of
 +        the part after performing content transfer decoding (but no
 +        charset conversion). This is suitable for saving attachments,
 +        for example.
 +
 +        For a multipart or message part, the output includes the part
 +        headers as well as the body (including all child parts). No
 +        decoding is performed because multipart and message parts
 +        cannot have non-trivial content transfer encoding. Consumers
 +        of this may need to implement MIME decoding and similar
 +        functions.
 +
 +``--format-version=N``
 +    Use the specified structured output format version. This is
 +    intended for programs that invoke **notmuch(1)** internally. If
 +    omitted, the latest supported version will be used.
 +
 +``--part=N``
 +    Output the single decoded MIME part N of a single message. The
 +    search terms must match only a single message. Message parts are
 +    numbered in a depth-first walk of the message MIME structure, and
 +    are identified in the 'json', 'sexp' or 'text' output formats.
 +
 +    Note that even a message with no MIME structure or a single body
 +    part still has two MIME parts: part 0 is the whole message
 +    (headers and body) and part 1 is just the body.
 +
 +``--verify``
 +    Compute and report the validity of any MIME cryptographic
 +    signatures found in the selected content (ie. "multipart/signed"
 +    parts). Status of the signature will be reported (currently only
 +    supported with --format=json and --format=sexp), and the
 +    multipart/signed part will be replaced by the signed data.
  
- ``--decrypt``
-     Decrypt any MIME encrypted parts found in the selected content
-     (ie. "multipart/encrypted" parts). Status of the decryption will
-     be reported (currently only supported with --format=json and
-     --format=sexp) and on successful decryption the
-     multipart/encrypted part will be replaced by the decrypted
-     content.
-     If a session key is already known for the message, then it will be
-     decrypted automatically unless the user explicitly sets
-     ``--decrypt=false``.
-     Decryption expects a functioning **gpg-agent(1)** to provide any
-     needed credentials. Without one, the decryption will fail.
-     Implies --verify.
+     ``--decrypt=(false|auto|true)``
+         If ``true``, decrypt any MIME encrypted parts found in the
+         selected content (i.e. "multipart/encrypted" parts). Status of
+         the decryption will be reported (currently only supported
+         with --format=json and --format=sexp) and on successful
+         decryption the multipart/encrypted part will be replaced by
+         the decrypted content.
+         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.
+         Default: ``auto``
  
 -    ``--exclude=(true|false)``
 -        Specify whether to omit threads only matching
 -        search.tag\_exclude 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 regardless (with the excluded flag being set when
 -        appropriate) but threads that only match in an excluded message
 -        are not returned when ``--exclude=true.``
 -
 -        The default is ``--exclude=true.``
 -
 -    ``--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.``
 -
 -        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.
 +``--exclude=(true|false)``
 +    Specify whether to omit threads only matching search.tag\_exclude
 +    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
 +    regardless (with the excluded flag being set when appropriate) but
 +    threads that only match in an excluded message are not returned
 +    when ``--exclude=true.``
 +
 +    The default is ``--exclude=true.``
 +
 +``--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.``
 +
 +    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.
  
  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