manpages (for 0.14) update

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

diff --git a/manpages/notmuch-show-1.mdwn b/manpages/notmuch-show-1.mdwn
index 168f94a01e2ecb2375b822494276407c8ed99beb..2cbeff95535cf07900253f96210a1f13fdf056c3 100644 (file)
--- a/manpages/notmuch-show-1.mdwn
+++ b/manpages/notmuch-show-1.mdwn
@@ -25,59 +25,62 @@
 
        Supported options for <b>show</b> include
 
 
        Supported options for <b>show</b> include
 

-           <b>--entire-thread</b>
+           <b>--entire-thread=(true|false)</b>

 
 

-               By default only those messages that match the search terms will
-               be displayed. With this option, all messages in the same thread
-               as any matched message will be displayed.
+               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.

 
            <b>--format=(text|json|mbox|raw)</b>
 
                <b>text</b> (default for messages)
 
 
            <b>--format=(text|json|mbox|raw)</b>
 
                <b>text</b> (default for messages)
 

-                   The default plain-text format  has  all  text-content  MIME
-                   parts  decoded. Various components in the output, (<b>message</b>,
+                   The  default  plain-text  format  has all text-content MIME
+                   parts decoded. Various components in the output,  (<b>message</b>,

                    <b>header</b>, <b>body</b>, <b>attachment</b>, and MIME <b>part</b>), will be delimited
                    <b>header</b>, <b>body</b>, <b>attachment</b>, and MIME <b>part</b>), will be delimited

-                   by  easily-parsed  markers.  Each marker consists of a Con-
-                   trol-L character  (ASCII  decimal  12),  the  name  of  the
-                   marker,  and  then either an opening or closing brace, (&apos;{&apos;
-                   or &apos;}&apos;), to either open or close the component. For a  mul-
+                   by easily-parsed markers. Each marker consists  of  a  Con-
+                   trol-L  character  (ASCII  decimal  12),  the  name  of the
+                   marker, and then either an opening or closing  brace,  (&apos;{&apos;
+                   or  &apos;}&apos;), to either open or close the component. For a mul-

                    tipart MIME message, these parts will be nested.
 
                <b>json</b>
 
                    tipart MIME message, these parts will be nested.
 
                <b>json</b>
 

-                   The  output  is  formatted  with Javascript Object Notation
+                   The output is formatted  with  Javascript  Object  Notation

                    (JSON). This format is more robust than the text format for
                    (JSON). This format is more robust than the text format for

-                   automated  processing.  The  nested  structure of multipart
-                   MIME messages is reflected in nested JSON output. JSON out-
-                   put  always  includes all messages in a matching thread; in
-                   effect <b>--format=json</b> implies <b>--entire-thread</b>
+                   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>

 
                <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  addi-
-                   tional  &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
+                   additional &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
                    all child parts) is output.
 
                    The raw format must only be used with search terms matching


@@ -86,52 +89,62 @@
            <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-
+               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.
 
            <b>--verify</b>
 
                mats.
 
            <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-
                ly supported with --format=json), and the multipart/signed part
                will be replaced by the signed data.
 
            <b>--decrypt</b>
 
                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.
 
            <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-
+               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.
 
            <b>--exclude=(true|false)</b>
 
                crypted content.  Implies --verify.
 
            <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>
 
                not returned when <b>--exclude=true.</b>
 
                The default is <b>--exclude=true.</b>
 

-       A  common  use  of  <b>notmuch</b> <b>show</b> is to display a single thread of email
+           <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>
+
+               This  is  useful  if the caller only needs the headers as body-
+               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

        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>SEE ALSO</h2>
 <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>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.13.2</h2>
+<h2>Notmuch 0.14</h2>