X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=man%2Fman1%2Fnotmuch-show.1;h=7697dfcc2eccc8db32a1771eee9a26acfeb8284f;hp=b81cce698379981b82b36623f98a6af856232b2b;hb=d6d3fa32f6b1491f84f44184c8c1e590656a2001;hpb=2ee1d8e1c70ce20728bc3faada389a4802636352

diff --git a/man/man1/notmuch-show.1 b/man/man1/notmuch-show.1
index b81cce69..7697dfcc 100644
--- a/man/man1/notmuch-show.1
+++ b/man/man1/notmuch-show.1
@@ -1,6 +1,6 @@
-.TH NOTMUCH-SHOW 1 2012-03-19 "Notmuch 0.12"
+.TH NOTMUCH-SHOW 1 2013-02-17 "Notmuch 0.15.2"
 .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
@@ -24,16 +24,21 @@ Supported options for
 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
+and
+.B --format=sexp
+this defaults to true.  For other formats, this defaults to false.
 .RE
 
 .RS 4
 .TP 4
-.B \-\-format=(text|json|mbox|raw)
+.B \-\-format=(text|json|sexp|mbox|raw)
 
 .RS 4
 .TP 4
@@ -55,11 +60,31 @@ 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
-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
-implies
-.B \-\-entire\-thread
+sets
+.B "\-\-entire\-thread"
+The caller can disable this behaviour by setting
+.B \-\-entire\-thread=false
+.RE
+.RS 4
+.TP 4
+.B sexp
+
+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
+sets
+.B "\-\-entire\-thread"
+The caller can disable this behaviour by setting
+.B \-\-entire\-thread=false
 
 .RE
 .RS 4
@@ -101,6 +126,15 @@ message.
 .RE
 .RE
 
+.RS 4
+.TP 4
+.BR \-\-format-version=N
+
+Use the specified structured output format version.  This is intended
+for programs that invoke \fBnotmuch\fR(1) internally.  If omitted, the
+latest supported version will be used.
+.RE
+
 .RS 4
 .TP 4
 .B \-\-part=N
@@ -108,7 +142,7 @@ message.
 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' or 'text' output formats.
+in the 'json', 'sexp' or 'text' output formats.
 .RE
 
 .RS 4
@@ -118,8 +152,8 @@ in the 'json' or 'text' output formats.
 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 the multipart/signed part will be replaced by the
-signed data.
+--format=json and --format=sexp), and the multipart/signed part
+will be replaced by the signed data.
 .RE
 
 .RS 4
@@ -128,16 +162,49 @@ signed data.
 
 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
-content.
+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.
+
+Decryption expects a functioning \fBgpg-agent\fR(1) to provide any
+needed credentials. Without one, the decryption will fail.
+
+Implies --verify.
+.RE
+
+.RS 4
+.TP 4
+.BR \-\-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
+.B --exclude=true.
+
+The default is
+.B --exclude=true.
+
 .RE
 
 .RS 4
 .TP 4
-.B \-\-no-exclude
+.B \-\-body=(true|false)
 
-Do not exclude the messages matching search.exclude_tags in the config file.
+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 and sexp formats 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
@@ -148,6 +215,17 @@ column of output from the
 .B notmuch search
 command.
 
+.SH EXIT STATUS
+
+This command supports the following special exit status codes
+
+.TP
+.B 20
+The requested format version is too old.
+.TP
+.B 21
+The requested format version is too new.
+
 .SH SEE ALSO
 
 \fBnotmuch\fR(1), \fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1),