TODO: Note that '=' should sometimes count from the end of the buffer.
[notmuch] / notmuch.1
index aeebdd1dce187276f355e9789ee4af882d83c181..e573749cd5988391c8d537ff3b8e5d90c6bbfde6 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
@@ -348,7 +373,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 +402,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
@@ -424,10 +449,13 @@ specify a date range to return messages from 2009-10-01 until the
 current time:
 
        $(date +%s -d 2009-10-01)..$(date +%s)
 current time:
 
        $(date +%s -d 2009-10-01)..$(date +%s)
-.SH ENVIRONMENT VARIABLES
-.IP NOTMUCH_CONFIG
-Specifies the location of the configuration file to override the default of
-.IR ~/.notmuch-config .
+.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