man: show: update man page for entire-thread and json.

[notmuch] / man / man1 / notmuch-show.1

diff --git a/man/man1/notmuch-show.1 b/man/man1/notmuch-show.1
index 928e03cc5d2c5be67051fbfe1d0dcc0a0641e335..765b22c630c0c939f2e3c9fa2375ac16820a4660 100644 (file)
--- a/man/man1/notmuch-show.1
+++ b/man/man1/notmuch-show.1
@@ -1,6 +1,6 @@
-.TH NOTMUCH-SHOW 1 2012-05-25 "Notmuch 0.13.1"
+.TH NOTMUCH-SHOW 1 2012-06-01 "Notmuch 0.13.2"

 .SH NAME
 .SH NAME

-notmuch-show \- Show messages matching the given search terms.
+notmuch-show \- show messages matching the given search terms

 .SH SYNOPSIS
 
 .B notmuch show
 .SH SYNOPSIS
 
 .B notmuch show


@@ -24,11 +24,14 @@ Supported options for
 include
 .RS 4
 .TP 4
 include
 .RS 4
 .TP 4

-.B \-\-entire\-thread
+.B \-\-entire\-thread=(true|false)

 
 

-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 show
+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
+this defaults to true.  For other formats, this defaults to false.

 .RE
 
 .RS 4
 .RE
 
 .RS 4


@@ -55,11 +58,13 @@ be nested.
 The output is formatted with Javascript Object Notation (JSON). This
 format is more robust than the text format for automated
 processing. The nested structure of multipart MIME messages is
 The output is formatted with Javascript Object Notation (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 output always includes all
-messages in a matching thread; in effect
+reflected in nested JSON output. By default JSON output includes all
+messages in a matching thread; that is, by default,

 .B \-\-format=json
 .B \-\-format=json

-implies
-.B \-\-entire\-thread
+sets
+.B "\-\-entire\-thread"
+The caller can disable this behaviour by setting
+.B \-\-entire\-thread=false

 
 .RE
 .RS 4
 
 .RE
 .RS 4


@@ -130,7 +135,7 @@ 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 the
 multipart/encrypted part will be replaced by the decrypted
 (ie. "multipart/encrypted" parts). Status of the decryption will be
 reported (currently only supported with --format=json) and the
 multipart/encrypted part will be replaced by the decrypted

-content.
+content.  Implies --verify.

 .RE
 
 .RS 4
 .RE
 
 .RS 4


@@ -152,6 +157,22 @@ The default is
 
 .RE
 
 
 .RE
 

+.RS 4
+.TP 4
+.B \-\-body=(true|false)
+
+If true (the default)
+.B notmuch show
+includes the bodies of the messages in the output; if false,
+bodies are omitted.
+.B --body=false
+is only implemented for the json format and it is incompatible with
+.B --part > 0.
+
+This is useful if the caller only needs the headers as body-less
+output is much faster and substantially smaller.
+.RE
+

 A common use of
 .B notmuch show
 is to display a single thread of email messages. For this, use a
 A common use of
 .B notmuch show
 is to display a single thread of email messages. For this, use a