test: Expand multipart test to cover part output in all formats.

[notmuch] / notmuch.1

diff --git a/notmuch.1 b/notmuch.1
index 853b5eafab31cac83959e074713174f528d6475a..82b48c3b942758790017cf4a1e2cf957d637a7f4 100644 (file)
--- a/notmuch.1
+++ b/notmuch.1
@@ -248,11 +248,11 @@ matched message will be displayed.
 
 .RS 4
 .TP 4
-.B \-\-format=(text|json|mbox)
+.B \-\-format=(text|json|mbox|raw)
 
 .RS 4
 .TP 4
-.B text
+.BR text " (default for messages)"
 
 The default plain-text format has all text-content MIME parts
 decoded. Various components in the output,
@@ -260,7 +260,8 @@ decoded. Various components in the output,
 will be delimited by easily-parsed markers. Each marker consists of a
 Control-L character (ASCII decimal 12), the name of the marker, and
 then either an opening or closing brace, ('{' or '}'), to either open
-or close the component.
+or close the component. For a multipart MIME message, these parts will
+be nested.
 .RE
 .RS 4
 .TP 4
@@ -268,8 +269,9 @@ or close the component.
 
 The output is formatted with Javascript Object Notation (JSON). This
 format is more robust than the text format for automated
-processing. JSON output always includes all messages in a matching
-thread; in effect
+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
 .B \-\-format=json
 implies
 .B \-\-entire\-thread
@@ -287,6 +289,33 @@ an additional '>' character added. This reversible escaping
 is termed "mboxrd" format and described in detail here:
 http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
 .RE
+.RS 4
+.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 single part (\-\-part) the raw part content is output after
+performing any necessary MIME decoding.
+
+The raw format must only be used with search terms matching single
+message.
+.RE
+.RE
+
+.RS 4
+.TP 4
+.B \-\-part=N
+
+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.
+.RE
+
 A common use of
 .B notmuch show
 is to display a single thread of email messages. For this, use a
@@ -299,11 +328,8 @@ See the
 .B "SEARCH SYNTAX"
 section below for details of the supported syntax for <search-terms>.
 .RE
-.TP
-.BR cat  " <search-term>..."
-
-Output raw content of a single message matched by the search term.
-.TP
+.RS 4
+.TP 4
 .BR count " <search-term>..."
 
 Count messages matching the search terms.
@@ -520,6 +546,8 @@ terms to match against specific portions of an email, (where
 
        thread:<thread-id>
 
+       folder:<directory-path>
+
 The
 .B from:
 prefix is used to match the name or address of the sender of an email
@@ -563,6 +591,13 @@ internally by notmuch (and do not appear in email messages). These
 thread ID values can be seen in the first column of output from
 .B "notmuch search"
 
+The
+.B folder:
+prefix can be used to search for email message files that are
+contained within particular directories within the mail store. Only
+the directory components below the top-level mail database path are
+available to be searched.
+
 In addition to individual terms, multiple terms can be
 combined with Boolean operators (
 .BR and ", " or ", " not