TODO: Note that '=' should sometimes count from the end of the buffer.

[notmuch] / notmuch.1

diff --git a/notmuch.1 b/notmuch.1
index 04bd0cf184cbaf4689dcdecb919fc9a02a46b0ac..e573749cd5988391c8d537ff3b8e5d90c6bbfde6 100644 (file)
--- a/notmuch.1
+++ b/notmuch.1
@@ -109,14 +109,6 @@ whenever new mail is delivered and you wish to incorporate it into the
 database. These subsequent runs will be much quicker than the initial
 run.
 
 database. These subsequent runs will be much quicker than the initial
 run.
 

-Note:
-.B notmuch new
-runs (other than the first run) will skip any read-only directories,
-so you can use that to mark directories that will not receive any new
-mail (and make
-.B notmuch new
-even faster).
-

 Invoking
 .B notmuch
 with no command argument will run
 Invoking
 .B notmuch
 with no command argument will run


@@ -154,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


@@ -169,6 +167,8 @@ when sorting by
 .B newest\-first
 the threads will be sorted by the newest message in each thread.
 
 .B newest\-first
 the threads will be sorted by the newest message in each thread.
 

+.RE
+.RS 4

 By default, results will be displayed in reverse chronological order,
 (that is, the newest results will be displayed first).
 
 By default, results will be displayed in reverse chronological order,
 (that is, the newest results will be displayed first).
 


@@ -177,7 +177,7 @@ See the
 section below for details of the supported syntax for <search-terms>.
 .RE
 .TP
 section below for details of the supported syntax for <search-terms>.
 .RE
 .TP

-.BR show " <search-term>..."
+.BR show " [options...] <search-term>..."

 
 Shows all messages matching the search terms.
 
 
 Shows all messages matching the search terms.
 


@@ -187,7 +187,27 @@ message in date order). The output is not indented by default, but
 depth tags are printed so that proper indentation can be performed by
 a post-processor (such as the emacs interface to notmuch).
 
 depth tags are printed so that proper indentation can be performed by
 a post-processor (such as the emacs interface to notmuch).
 

-The  output format  is plain-text,  with all  text-content  MIME parts
+Supported options for
+.B show
+include
+.RS 4
+.TP 4
+.B \-\-entire\-thread
+
+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.
+.RE
+
+.RS 4
+.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


@@ -195,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


@@ -207,6 +239,7 @@ See the
 .B "SEARCH SYNTAX"
 section below for details of the supported syntax for <search-terms>.
 .RE
 .B "SEARCH SYNTAX"
 section below for details of the supported syntax for <search-terms>.
 .RE

+.RE

 
 The
 .B reply
 
 The
 .B reply


@@ -340,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>
 


@@ -369,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


@@ -416,6 +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
+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