manpages 0.15

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

diff --git a/manpages/notmuch-show-1.mdwn b/manpages/notmuch-show-1.mdwn
index 2cbeff95535cf07900253f96210a1f13fdf056c3..f5df8494cf8506752f05c3d7f666bc9814c5dac6 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,99 +52,127 @@
                    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 the multipart/encrypted part will be re-
+               placed by the decrypted content.  Implies --verify.

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

-               Specify  whether  to  omit threads only matching search.tag_ex-
-               clude 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
+               Specify whether to omit threads  only  matching  search.tag_ex-
+               clude  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).
 
                flag).
 

-               If  --entire-thread  is specified then complete threads are re-
+               If --entire-thread is specified then complete threads  are  re-

                turned regardless (with the excluded flag being set when appro-
                turned regardless (with the excluded flag being set when appro-

-               priate)  but threads that only match in an excluded message are
+               priate) but threads that only match in an excluded message  are

                not returned when <b>--exclude=true.</b>
 
                The default is <b>--exclude=true.</b>
 
            <b>--body=(true|false)</b>
 
                not returned when <b>--exclude=true.</b>
 
                The default is <b>--exclude=true.</b>
 
            <b>--body=(true|false)</b>
 

-               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>
+               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 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-
+               This is useful if the caller only needs the  headers  as  body-

                less output is much faster and substantially smaller.
 
                less output is much faster and substantially smaller.
 

-       A common use of <b>notmuch</b> <b>show</b> is to display a  single  thread  of  email
+       A  common  use  of  <b>notmuch</b> <b>show</b> is to display a single thread of email

        messages. For this, use a search term of &quot;thread:&lt;thread-id&gt;&quot; as can be
        seen in the first column of output from the <b>notmuch</b> <b>search</b> command.
 </pre>
 
        messages. For this, use a search term of &quot;thread:&lt;thread-id&gt;&quot; as can be
        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>
 <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-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)
 </pre>
 
        <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)
 </pre>
 

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