Update news & manpages to notmuch version 0.16

[obsolete/notmuch-wiki] / manpages / notmuch-show-1.mdwn

diff --git a/manpages/notmuch-show-1.mdwn b/manpages/notmuch-show-1.mdwn
index 2cbeff95535cf07900253f96210a1f13fdf056c3..00666bd2358972120f1c0823b874f1d55f111433 100644 (file)
--- a/manpages/notmuch-show-1.mdwn
+++ b/manpages/notmuch-show-1.mdwn
@@ -29,10 +29,10 @@
 
                If true, <b>notmuch</b> <b>show</b> outputs all messages in the thread of any
                message  matching  the  search terms; if false, it outputs only
 
                If true, <b>notmuch</b> <b>show</b> outputs all messages in the thread of any
                message  matching  the  search terms; if false, it outputs only

-               the matching messages. For <b>--format=json</b> this defaults to true.
-               For other formats, this defaults to false.
+               the matching messages. For <b>--format=json</b> and <b>--format=sexp</b> this
+               defaults to true.  For other formats, this defaults to false.

 
 

-           <b>--format=(text|json|mbox|raw)</b>
+           <b>--format=(text|json|sexp|mbox|raw)</b>

 
                <b>text</b> (default for messages)
 
 
                <b>text</b> (default for messages)
 


@@ -52,63 +52,87 @@
                    automated processing. The  nested  structure  of  multipart
                    MIME  messages  is  reflected  in  nested  JSON  output. By
                    default JSON output includes all  messages  in  a  matching
                    automated processing. The  nested  structure  of  multipart
                    MIME  messages  is  reflected  in  nested  JSON  output. By
                    default JSON output includes all  messages  in  a  matching

-                   thread;   that   is,   by   default,   <b>--format=json</b>   sets
-                   <b>--entire-thread</b> The caller can disable  this  behaviour  by
-                   setting <b>--entire-thread=false</b>
+                   thread; that is, by default,
+
+                   <b>--format=json</b>  sets  <b>--entire-thread</b> The caller can disable
+                   this behaviour by setting <b>--entire-thread=false</b>
+
+               <b>sexp</b>
+
+                   The output is formatted as  an  S-Expression  (sexp).  This
+                   format  is  more  robust than the text format for automated
+                   processing. The nested structure of multipart MIME messages
+                   is  reflected in nested S-Expression output. By default, S-
+                   Expression output  includes  all  messages  in  a  matching
+                   thread; that is, by default,
+
+                   <b>--format=sexp</b>  sets  <b>--entire-thread</b> The caller can disable
+                   this behaviour by setting <b>--entire-thread=false</b>

 
                <b>mbox</b>
 
 
                <b>mbox</b>
 

-                   All  matching  messages are output in the traditional, Unix
-                   mbox format with each message  being  prefixed  by  a  line
-                   beginning  with  &quot;From  &quot;  and a blank line separating each
-                   message. Lines in the message content beginning with  &quot;From
-                   &quot;  (preceded  by  zero  or  more  &apos;&gt;&apos;  characters)  have an
-                   additional &apos;&gt;&apos; character added. This reversible escaping is
+                   All matching messages are output in the  traditional,  Unix
+                   mbox  format  with  each  message  being prefixed by a line
+                   beginning with &quot;From &quot; and a  blank  line  separating  each
+                   message.  Lines in the message content beginning with &quot;From
+                   &quot; (preceded by zero or more &apos;&gt;&apos; characters) have  an  addi-
+                   tional  &apos;&gt;&apos;  character  added.  This reversible escaping is

                    termed &quot;mboxrd&quot; format and described in detail here:
 
                    http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
 
                <b>raw</b> (default for a single part, see --part)
 
                    termed &quot;mboxrd&quot; format and described in detail here:
 
                    http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
 
                <b>raw</b> (default for a single part, see --part)
 

-                   For  a  message  or an attached message part, the original,
-                   raw content of the email message is  output.  Consumers  of
-                   this  format  should  expect to implement MIME decoding and
+                   For a message or an attached message  part,  the  original,
+                   raw  content  of  the email message is output. Consumers of
+                   this format should expect to implement  MIME  decoding  and

                    similar functions.
 
                    similar functions.
 

-                   For a single part (--part) the raw part content  is  output
-                   after  performing  any  necessary MIME decoding.  Note that
+                   For  a  single part (--part) the raw part content is output
+                   after performing any necessary MIME  decoding.   Note  that

                    messages with a simple body still have two parts: part 0 is
                    the whole message and part 1 is the body.
 
                    messages with a simple body still have two parts: part 0 is
                    the whole message and part 1 is the body.
 

-                   For  a multipart part, the part headers and body (including
+                   For a multipart part, the part headers and body  (including

                    all child parts) is output.
 
                    The raw format must only be used with search terms matching
                    single message.
 
                    all child parts) is output.
 
                    The raw format must only be used with search terms matching
                    single message.
 

+           <b>--format-version=N</b>
+
+               Use the specified structured output format  version.   This  is
+               intended  for  programs  that invoke <a href='../notmuch-1/'>notmuch</a>(1) internally.  If
+               omitted, the latest supported version will be used.
+

            <b>--part=N</b>
 
                Output the single decoded MIME part N of a single message.  The
            <b>--part=N</b>
 
                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 struc-
-               ture, and are identified in the &apos;json&apos; or  &apos;text&apos;  output  for-
-               mats.
+               search  terms  must match only a single message.  Message parts
+               are numbered in a depth-first walk of the message  MIME  struc-
+               ture, and are identified in the &apos;json&apos;, &apos;sexp&apos; or &apos;text&apos; output
+               formats.

 
            <b>--verify</b>
 
 
            <b>--verify</b>
 

-               Compute  and report the validity of any MIME cryptographic sig-
-               natures found in the selected content  (ie.  &quot;multipart/signed&quot;
+               Compute and report the validity of any MIME cryptographic  sig-
+               natures  found  in the selected content (ie. &quot;multipart/signed&quot;

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

-               ly supported with --format=json), and the multipart/signed part
-               will be replaced by the signed data.
+               ly  supported  with  --format=json  and --format=sexp), and the
+               multipart/signed part will be replaced by the signed data.

 
            <b>--decrypt</b>
 
 
            <b>--decrypt</b>
 

-               Decrypt  any MIME encrypted parts found in the selected content
-               (ie. &quot;multipart/encrypted&quot; parts).  Status  of  the  decryption
-               will  be reported (currently only supported with --format=json)
-               and the multipart/encrypted part will be replaced  by  the  de-
-               crypted content.  Implies --verify.
+               Decrypt any MIME encrypted parts found in the selected  content
+               (ie.  &quot;multipart/encrypted&quot;  parts).  Status  of the decryption
+               will be reported (currently only supported  with  --format=json
+               and  --format=sexp)  and  on  successful  decryption the multi-
+               part/encrypted part will be replaced by the decrypted content.
+
+               Decryption expects a functioning <b>gpg-agent</b>(1)  to  provide  any
+               needed credentials. Without one, the decryption will fail.
+
+               Implies --verify.

 
            <b>--exclude=(true|false)</b>
 
 
            <b>--exclude=(true|false)</b>
 


@@ -129,8 +153,8 @@
 
                If true (the default) <b>notmuch</b> <b>show</b> includes the bodies  of  the
                messages   in   the  output;  if  false,  bodies  are  omitted.
 
                If true (the default) <b>notmuch</b> <b>show</b> includes the bodies  of  the
                messages   in   the  output;  if  false,  bodies  are  omitted.

-               <b>--body=false</b> is only implemented for the json format and it  is
-               incompatible with <b>--part</b> &gt<b>&</b>gt; <b>0.</b>
+               <b>--body=false</b> is only implemented for the json and sexp  formats
+               and it is incompatible with <b>--part</b> &gt<b>&</b>gt; <b>0.</b>

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


@@ -140,11 +164,21 @@
        seen in the first column of output from the <b>notmuch</b> <b>search</b> command.
 </pre>
 
        seen in the first column of output from the <b>notmuch</b> <b>search</b> command.
 </pre>
 

+<h2>EXIT STATUS</h2>
+<pre>
+       This command supports the following special exit status codes
+
+       <b>20</b>     The requested format version is too old.
+
+       <b>21</b>     The requested format version is too new.
+</pre>
+

 <h2>SEE ALSO</h2>
 <pre>
        <a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1),  <a href='../notmuch-hooks-5/'>not-</a>
 <h2>SEE ALSO</h2>
 <pre>
        <a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1),  <a href='../notmuch-hooks-5/'>not-</a>

-       <a href='../notmuch-hooks-5/'>much-hooks</a>(5),  <a href='../notmuch-new-1/'>notmuch-new</a>(1),  <a href='../notmuch-reply-1/'>notmuch-reply</a>(1),  <a href='../notmuch-restore-1/'>notmuch-restore</a>(1),
-       <a href='../notmuch-search-1/'>notmuch-search</a>(1), <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
+       <a href='../notmuch-hooks-5/'>much-hooks</a>(5),   <a href='../notmuch-insert-1/'>notmuch-insert</a>(1),  <a href='../notmuch-new-1/'>notmuch-new</a>(1),  <a href='../notmuch-reply-1/'>notmuch-reply</a>(1),
+       <a href='../notmuch-restore-1/'>notmuch-restore</a>(1),  <a href='../notmuch-search-1/'>notmuch-search</a>(1),  <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7),  <a href='../notmuch-tag-1/'>not-</a>
+       <a href='../notmuch-tag-1/'>much-tag</a>(1)

 </pre>
 
 </pre>
 

-<h2>Notmuch 0.14</h2>
+<h2>Notmuch 0.16</h2>