fix notmuch_message_file_get_header

[notmuch] / notmuch.1

diff --git a/notmuch.1 b/notmuch.1
index 282ad9896bc6a64004f0c4b16fed2e15ba00b48a..0e6a2edcc2c76c17f796a4d6f375bb4411e4bfef 100644 (file)
--- a/notmuch.1
+++ b/notmuch.1
@@ -146,6 +146,12 @@ Supported options for
 include
 .RS 4
 .TP 4
 include
 .RS 4
 .TP 4

+.BR \-\-format= ( json | text )
+
+Presents the results in either JSON or plain-text (default).
+.RE
+.RS 4
+.TP 4

 .BR \-\-sort= ( newest\-first | oldest\-first )
 
 This option can be used to present results in either chronological order
 .BR \-\-sort= ( newest\-first | oldest\-first )
 
 This option can be used to present results in either chronological order


@@ -194,7 +200,14 @@ matched message will be displayed.
 .RE
 
 .RS 4
 .RE
 
 .RS 4

-The  output format  is plain-text,  with all  text-content  MIME parts
+.TP 4
+.B \-\-format=(json|text)
+
+.RS 4
+.TP 4
+.B text
+
+The default plain-text format  has  text-content  MIME parts

 decoded. Various components in the output,
 .RB ( message ", " header ", " body ", " attachment ", and MIME " part ),
 will be delimited by easily-parsed markers. Each marker consists of a
 decoded. Various components in the output,
 .RB ( message ", " header ", " body ", " attachment ", and MIME " part ),
 will be delimited by easily-parsed markers. Each marker consists of a


@@ -202,6 +215,18 @@ 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.
 
 then either an opening or closing brace, ('{' or '}'), to either open
 or close the component.
 

+.RE
+.RS 4
+.TP 4
+.B json
+
+Format output as Javascript Object Notation (JSON). JSON output always
+includes all messages in a matching thread; in effect
+.B \-\-format=json
+implies
+.B \-\-entire\-thread
+
+.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


@@ -231,12 +256,12 @@ takes an existing set of messages and constructs a suitable mail
 template. The Reply-to header (if any, otherwise From:) is used for
 the To: address. Vales from the To: and Cc: headers are copied, but
 not including any of the current user's email addresses (as configured
 template. The Reply-to header (if any, otherwise From:) is used for
 the To: address. Vales from the To: and Cc: headers are copied, but
 not including any of the current user's email addresses (as configured

-in primary_mail or other_email in the .notmuch-config file) in the
+in primary_mail or other_email in the .notmuch\-config file) in the

 recipient list
 
 It also builds a suitable new subject, including Re: at the front (if
 not already present), and adding the message IDs of the messages being
 recipient list
 
 It also builds a suitable new subject, including Re: at the front (if
 not already present), and adding the message IDs of the messages being

-replied to to the References list and setting the In-Reply-To: field
+replied to to the References list and setting the In\-Reply\-To: field

 correctly.
 
 Finally, the original contents of the emails are quoted by prefixing
 correctly.
 
 Finally, the original contents of the emails are quoted by prefixing


@@ -255,8 +280,8 @@ include
 .BR default
 Includes subject and quoted message body.
 .TP
 .BR default
 Includes subject and quoted message body.
 .TP

-.BR headers-only
-Only produces In-Reply-To, References, To, Cc, and Bcc headers.
+.BR headers\-only
+Only produces In\-Reply\-To, References, To, Cc, and Bcc headers.

 .RE
 
 See the
 .RE
 
 See the


@@ -280,18 +305,18 @@ contents.
 
 .RS 4
 .TP 4
 
 .RS 4
 .TP 4

-.BR tag " +<tag>|-<tag> [...] [--] <search-term>..."
+.BR tag " +<tag>|\-<tag> [...] [\-\-] <search-term>..."

 
 Add/remove tags for all messages matching the search terms.
 
 
 Add/remove tags for all messages matching the search terms.
 

-Tags prefixed by '+' are added while those prefixed by '-' are
+Tags prefixed by '+' are added while those prefixed by '\-' are

 removed. For each message, tag removal is performed before tag
 addition.
 
 The beginning of <search-terms> is recognized by the first
 removed. For each message, tag removal is performed before tag
 addition.
 
 The beginning of <search-terms> is recognized by the first

-argument that begins with neither '+' nor '-'. Support for
-an initial search term beginning with '+' or '-' is provided
-by allowing the user to specify a "--" argument to separate
+argument that begins with neither '+' nor '\-'. Support for
+an initial search term beginning with '+' or '\-' is provided
+by allowing the user to specify a "\-\-" argument to separate

 the tags from the search terms.
 
 See the
 the tags from the search terms.
 
 See the


@@ -328,6 +353,32 @@ So if you've previously been using sup for mail, then the
 .B "notmuch restore"
 command provides you a way to import all of your tags (or labels as
 sup calls them).
 .B "notmuch restore"
 command provides you a way to import all of your tags (or labels as
 sup calls them).

+.RE
+
+The
+.B part
+command can used to output a single part of a multi-part MIME message.
+
+.RS 4
+.TP 4
+.BR part " \-\-part=<part-number> <search-term>..."
+
+Output a single MIME part of a message.
+
+A single decoded MIME part, with no encoding or framing, is output to
+stdout. The search terms must match only a single message, otherwise
+this command will fail.
+
+The part number should match the part "id" field output by the
+"\-\-format=json" option of "notmuch show". If the message specified by
+the search terms does not include a part with the specified "id" there
+will be no output.
+
+See the
+.B "SEARCH SYNTAX"
+section below for details of the supported syntax for <search-terms>.
+.RE
+

 .SH SEARCH SYNTAX
 Several notmuch commands accept a common syntax for search terms.
 
 .SH SEARCH SYNTAX
 Several notmuch commands accept a common syntax for search terms.
 


@@ -348,7 +399,7 @@ terms to match against specific portions of an email, (where
 
        attachment:<word>
 
 
        attachment:<word>
 

-       tag:<tag>
+       tag:<tag> (or is:<tag>)

 
        id:<message-id>
 
 
        id:<message-id>
 


@@ -377,7 +428,7 @@ prefix can be used to search for specific filenames (or extensions) of
 attachments to email messages.
 
 For
 attachments to email messages.
 
 For

-.BR tag: ,
+.BR tag: " and " is:

 valid tag values include
 .BR inbox " and " unread
 by default for new messages added by
 valid tag values include
 .BR inbox " and " unread
 by default for new messages added by


@@ -387,7 +438,7 @@ as well as any other tag values added manually with
 
 For
 .BR id: ,
 
 For
 .BR id: ,

-message ID values are the literal contents of the Message-ID: header
+message ID values are the literal contents of the Message\-ID: header

 of email messages, but without the '<', '>' delimiters.
 
 The
 of email messages, but without the '<', '>' delimiters.
 
 The


@@ -416,14 +467,21 @@ particular time range, (based on the Date: header) with a syntax of:
        <intial-timestamp>..<final-timestamp>
 
 Each timestamp is a number representing the number of seconds since
        <intial-timestamp>..<final-timestamp>
 
 Each timestamp is a number representing the number of seconds since

-1970-01-01 00:00:00 UTC. This is not the most convenient means of
+1970\-01\-01 00:00:00 UTC. This is not the most convenient means of

 expressing date ranges, but until notmuch is fixed to accept a more
 convenient form, one can use the date program to construct
 timestamps. For example, with the bash shell the folowing syntax would
 expressing date ranges, but until notmuch is fixed to accept a more
 convenient form, one can use the date program to construct
 timestamps. For example, with the bash shell the folowing syntax would

-specify a date range to return messages from 2009-10-01 until the
+specify a date range to return messages from 2009\-10\-01 until the

 current time:
 
 current time:
 

-       $(date +%s -d 2009-10-01)..$(date +%s)
+       $(date +%s \-d 2009\-10\-01)..$(date +%s)
+.SH ENVIRONMENT
+The following environment variables can be used to control the
+behavior of notmuch.
+.TP
+.B NOTMUCH_CONFIG
+Specifies the location of the notmuch configuration file. Notmuch will
+use ${HOME}/.notmuch\-config if this variable is not set.

 .SH SEE ALSO
 The emacs-based interface to notmuch (available as
 .B notmuch.el
 .SH SEE ALSO
 The emacs-based interface to notmuch (available as
 .B notmuch.el