version: bump to 0.15.1

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

diff --git a/man/man1/notmuch-show.1 b/man/man1/notmuch-show.1
index d75d9710da0ade4483b65eda78f47bd4585edcd4..5d4ccfab3ec7174f6689d73cf31d09320bcba91b 100644 (file)
--- a/man/man1/notmuch-show.1
+++ b/man/man1/notmuch-show.1
@@ -1,6 +1,6 @@
-.TH NOTMUCH-SHOW 1 2012-02-29 "Notmuch 0.12~rc1"
+.TH NOTMUCH-SHOW 1 2013-01-24 "Notmuch 0.15.1"

 .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,16 +24,21 @@ 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
+and
+.B --format=sexp
+this defaults to true.  For other formats, this defaults to false.

 .RE
 
 .RS 4
 .TP 4
 .RE
 
 .RS 4
 .TP 4

-.B \-\-format=(text|json|mbox|raw)
+.B \-\-format=(text|json|sexp|mbox|raw)

 
 .RS 4
 .TP 4
 
 .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
 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
+.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
 
 .RE
 .RS 4


@@ -84,18 +109,32 @@ http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
 .TP 4
 .BR raw " (default for a single part, see \-\-part)"
 
 .TP 4
 .BR raw " (default for a single part, see \-\-part)"
 

-For a message, the original, raw content of the email message is
-output. Consumers of this format should expect to implement MIME
-decoding and similar functions.
+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.

 
 For a single part (\-\-part) the raw part content is output after
 
 For a single part (\-\-part) the raw part content is output after

-performing any necessary MIME decoding.
+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.
+
+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.
 .RE
 .RE
 
 
 The raw format must only be used with search terms matching single
 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
 .RS 4
 .TP 4
 .B \-\-part=N


@@ -103,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
 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
 .RE
 
 .RS 4


@@ -113,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
 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
 .RE
 
 .RS 4


@@ -123,16 +162,44 @@ signed data.
 
 Decrypt any MIME encrypted parts found in the selected content
 (ie. "multipart/encrypted" parts). Status of the decryption will be
 
 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 the multipart/encrypted part will be replaced
+by the decrypted content.  Implies --verify.

 .RE
 
 .RS 4
 .TP 4
 .RE
 
 .RS 4
 .TP 4

-.B \-\-no-exclude
+.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.

 
 

-Do not exclude the messages matching search.exclude_tags in the config file.
+.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 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
 .RE
 
 A common use of


@@ -143,10 +210,21 @@ column of output from the
 .B notmuch search
 command.
 
 .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),
 .SH SEE ALSO
 
 \fBnotmuch\fR(1), \fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1),

-\fBnotmuch-dump\fR(5), \fBnotmuch-hooks\fR(5), \fBnotmuch-new\fR(1),
-\fBnotmuch-part\fR(1), \fBnotmuch-reply\fR(1),
-\fBnotmuch-restore\fR(1), \fBnotmuch-search\fR(1),
-\fBnotmuch-search-terms\fR(7), \fBnotmuch-tag\fR(1)
+\fBnotmuch-dump\fR(1), \fBnotmuch-hooks\fR(5), \fBnotmuch-new\fR(1),
+\fBnotmuch-reply\fR(1), \fBnotmuch-restore\fR(1),
+\fBnotmuch-search\fR(1), \fBnotmuch-search-terms\fR(7),
+\fBnotmuch-tag\fR(1)