notmuch: Add a new "notmuch config" command for querying configuration.

[notmuch] / notmuch.1

diff --git a/notmuch.1 b/notmuch.1
index 0e6a2edcc2c76c17f796a4d6f375bb4411e4bfef..41f7c7e450826a703e8d14585d09d1a17849dbe7 100644 (file)
--- a/notmuch.1
+++ b/notmuch.1
@@ -126,7 +126,7 @@ syntax. See the
 section below for more details on the supported syntax.
 
 The
-.BR search " and "show
+.BR search ", " show " and " count
 commands are used to query the email database.
 .RS 4
 .TP 4
@@ -201,13 +201,13 @@ matched message will be displayed.
 
 .RS 4
 .TP 4
-.B \-\-format=(json|text)
+.B \-\-format=(text|json|mbox)
 
 .RS 4
 .TP 4
 .B text
 
-The default plain-text format  has  text-content  MIME parts
+The default plain-text format has all 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
@@ -220,12 +220,27 @@ or close the component.
 .TP 4
 .B json
 
-Format output as Javascript Object Notation (JSON). JSON output always
-includes all messages in a matching thread; in effect
+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
 .B \-\-format=json
 implies
 .B \-\-entire\-thread
 
+.RE
+.RS 4
+.TP 4
+.B mbox
+
+All matching messages are output in the traditional, Unix mbox format
+with each message being prefixed by a line beginning with "From " and
+a blank line separating each message. Lines in the message content
+beginning with "From " (preceded by zero or more '>' characters) have
+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
 A common use of
 .B notmuch show
@@ -239,6 +254,16 @@ See the
 .B "SEARCH SYNTAX"
 section below for details of the supported syntax for <search-terms>.
 .RE
+.TP
+.BR count " <search-term>..."
+
+Count messages matching the search terms.
+
+The number of matching messages is output to stdout.
+
+With no search terms, a count of all messages in the database will be
+displayed.
+.RE
 .RE
 
 The
@@ -379,6 +404,34 @@ See the
 section below for details of the supported syntax for <search-terms>.
 .RE
 
+The
+.B config
+command can be used to get settings from the notmuch configuration
+file.
+
+.RS 4
+.TP 4
+.BR "config get " <section> . <item>
+
+Get settings from the notmuch configuration file.
+
+The value of the specified configuration item is printed to stdout. If
+the item has multiple values, each value is separated by a newline
+character.
+
+Available configuration items include at least
+
+       database.path
+
+       user.name
+
+       user.primary_email
+
+       user.other_email
+
+       new.tags
+.RE
+
 .SH SEARCH SYNTAX
 Several notmuch commands accept a common syntax for search terms.
 
@@ -387,6 +440,9 @@ which will match all messages that contain all of the given
 terms/phrases in the body, the subject, or any of the sender or
 recipient headers.
 
+As a special case, a search string consisting of exactly a single
+asterisk ("*") will match all messages.
+
 In addition to free text, the following prefixes can be used to force
 terms to match against specific portions of an email, (where
 <brackets> indicate user-supplied values):