initial splitting of notmuch.1

We mostly just cut and paste the command descriptions into individual
files, with a short header added to each one.

The splitting into subdirectories is to support the use of ./man as an
element in MANPATH, e.g. for testing.

12 files changed, 889 insertions, 0 deletions

diff --git a/man/man1/notmuch-config.1 b/man/man1/notmuch-config.1
new file mode 100644
index 00000000..20389f7c
--- /dev/null
+++ b/man/man1/notmuch-config.1
@@ -0,0 +1,51 @@
+.TH NOTMUCH-CONFIG 1 2011-12-04 "Notmuch 0.10.2"
+.SH NAME
+notmuch-config \- Output a single part of a multipart MIME message.
+.SH SYNOPSIS
+
+.B notmuch config get
+.RI  "<" section "> . <" item ">"
+
+.B notmuch config set
+.RI  "<" section "> . <" item "> [" value "]"
+
+.SH DESCRIPTION
+
+The
+.B config
+command can be used to get or set settings int the notmuch
+configuration file.
+
+
+.RS 4
+.TP 4
+.BR "config get " <section> . <item>
+
+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
+
+.RS 4
+.TP 4
+.BR "config set " <section> . "<item> [values ...]"
+
+The specified configuration item is set to the given value.  To
+specify a multiple-value item, provide each value as a separate
+command-line argument.
+
+If no values are provided, the specified configuration item will be
+removed from the configuration file.
+.RE
diff --git a/man/man1/notmuch-count.1 b/man/man1/notmuch-count.1
new file mode 100644
index 00000000..c0478393
--- /dev/null
+++ b/man/man1/notmuch-count.1
@@ -0,0 +1,39 @@
+.TH NOTMUCH-COUNT 1 2011-12-04 "Notmuch 0.10.2"
+.SH NAME
+notmuch-count \- Count messages matching the given search terms.
+.SH SYNOPSIS
+
+.B notmuch count
+.RI  [ options "... ] <" search-term ">..."
+
+.SH DESCRIPTION
+
+Count messages matching the search terms.
+
+The number of matching messages (or threads) is output to stdout.
+
+With no search terms, a count of all messages (or threads) in the database will
+be displayed.
+
+Supported options for
+.B count
+include
+.RS 4
+.TP 4
+.B \-\-output=(messages|threads)
+
+.RS 4
+.TP 4
+.B messages
+
+Output the number of matching messages. This is the default.
+.RE
+.RS 4
+.TP 4
+.B threads
+
+Output the number of matching threads.
+.RE
+.RE
+.RE
+.RE
diff --git a/man/man1/notmuch-dump.1 b/man/man1/notmuch-dump.1
new file mode 100644
index 00000000..9dc311f6
--- /dev/null
+++ b/man/man1/notmuch-dump.1
@@ -0,0 +1,57 @@
+.TH NOTMUCH-DUMP 1 2011-12-04 "Notmuch 0.10.2"
+.SH NAME
+notmuch-dump \- Creates a plain-text dump of the tags of each message.
+
+.SH SYNOPSIS
+
+.B "notmuch dump"
+.RI "[ <" filename "> ] [--]"
+.RI "[ <" search-term ">...]"
+
+.B "notmuch restore"
+.RB [ "--accumulate" ]
+.RI "[ <" filename "> ]"
+
+.SH DESCRIPTION
+
+.TP
+.BR dump " [<filename>]"
+
+Dump tags for messages matching the given search terms.
+
+Output is to the given filename, if any, or to stdout.  Note that
+using the filename argument is deprecated.
+
+These tags are the only data in the notmuch database that can't be
+recreated from the messages themselves.  The output of notmuch dump is
+therefore the only critical thing to backup (and much more friendly to
+incremental backup than the native database files.)
+
+With no search terms, a dump of all messages in the database will be
+generated.  A "--" argument instructs notmuch that the
+remaining arguments are search terms.
+
+.TP
+.BR restore " [--accumulate] [<filename>]"
+
+Restores the tags from the given file (see
+.BR "notmuch dump" ")."
+
+The input is read from the given filename, if any, or from stdin.
+
+Note: The dump file format is specifically chosen to be
+compatible with the format of files produced by sup-dump.
+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).
+
+The --accumulate switch causes the union of the existing and new tags to be
+applied, instead of replacing each message's tags as they are read in from the
+dump file.
+.RE
+
+See the
+.B "SEARCH SYNTAX"
+section below for details of the supported syntax for <search-terms>.
+.RE
diff --git a/man/man1/notmuch-new.1 b/man/man1/notmuch-new.1
new file mode 100644
index 00000000..9c11375e
--- /dev/null
+++ b/man/man1/notmuch-new.1
@@ -0,0 +1,59 @@
+.TH NOTMUCH-NEW 1 2011-12-04 "Notmuch 0.10.2"
+.SH NAME
+notmuch-new \- Incorporate new mail into the notmuch database.
+.SH SYNOPSIS
+
+.B notmuch new
+.RB "[" --no-hooks "]"
+
+.SH DESCRIPTION
+
+Find and import any new messages to the database.
+
+The
+.B new
+command scans all sub-directories of the database, performing
+full-text indexing on new messages that are found. Each new message
+will automatically be tagged with both the
+.BR inbox " and " unread
+tags.
+
+You should run
+.B "notmuch new"
+once after first running
+.B "notmuch setup"
+to create the initial database. The first run may take a long time if
+you have a significant amount of mail (several hundred thousand
+messages or more). Subsequently, you should run
+.B "notmuch new"
+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.
+
+Invoking
+.B notmuch
+with no command argument will run
+.B new
+if
+.B "notmuch setup"
+has previously been completed, but
+.B "notmuch new"
+has not previously been run.
+
+
+The
+.B new
+command supports hooks. See the
+.B "HOOKS"
+section below for more details on hooks.
+
+Supported options for
+.B new
+include
+.RS 4
+.TP 4
+.BR \-\-no\-hooks
+
+Prevents hooks from being run.
+.RE
+.RE
diff --git a/man/man1/notmuch-part.1 b/man/man1/notmuch-part.1
new file mode 100644
index 00000000..67c4b5ed
--- /dev/null
+++ b/man/man1/notmuch-part.1
@@ -0,0 +1,28 @@
+.TH NOTMUCH-PART 1 2011-12-04 "Notmuch 0.10.2"
+.SH NAME
+notmuch-part \- Output a single part of a multipart MIME message.
+.SH SYNOPSIS
+
+.B notmuch part
+.BI "\-\-part=" "<part-number>"
+.RI < search-terms >
+
+.SH DESCRIPTION
+
+The
+.B part
+command can used to output a single part of a multipart MIME 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
diff --git a/man/man1/notmuch-reply.1 b/man/man1/notmuch-reply.1
new file mode 100644
index 00000000..eb23925b
--- /dev/null
+++ b/man/man1/notmuch-reply.1
@@ -0,0 +1,60 @@
+.TH NOTMUCH-REPLY 1 2011-12-04 "Notmuch 0.10.2"
+.SH NAME
+notmuch-reply \- Constructs a reply template for a set of messages.
+
+.SH SYNOPSIS
+
+.B notmuch reply
+.RI "[" options "...] <" search-term ">..."
+
+.SH DESCRIPTION
+
+Constructs a reply template for a set of messages.
+
+To make replying to email easier,
+.B notmuch reply
+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
+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
+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
+each line with '> ' and included in the body.
+
+The resulting message template is output to stdout.
+
+Supported options for
+.B reply
+include
+.RS
+.TP 4
+.BR \-\-format= ( default | headers\-only )
+.RS
+.TP 4
+.BR default
+Includes subject and quoted message body.
+.TP
+.BR headers\-only
+Only produces In\-Reply\-To, References, To, Cc, and Bcc headers.
+.RE
+
+See the
+.B "SEARCH SYNTAX"
+section below for details of the supported syntax for <search-terms>.
+
+Note: It is most common to use
+.B "notmuch reply"
+with a search string matching a single message, (such as
+id:<message-id>), but it can be useful to reply to several messages at
+once. For example, when a series of patches are sent in a single
+thread, replying to the entire thread allows for the reply to comment
+on issue found in multiple patches.
+.RE
+.RE
diff --git a/man/man1/notmuch-search.1 b/man/man1/notmuch-search.1
new file mode 100644
index 00000000..efb63a1c
--- /dev/null
+++ b/man/man1/notmuch-search.1
@@ -0,0 +1,116 @@
+.TH NOTMUCH-SEARCH 1 2011-12-04 "Notmuch 0.10.2"
+.SH NAME
+notmuch-search \- Search for messages matching the given search terms.
+.SH SYNOPSIS
+
+.B notmuch search
+.RI  [  options "...] <" search-term ">..."
+
+.SH DESCRIPTION
+
+Search for messages matching the given search terms, and display as
+results the threads containing the matched messages.
+
+The output consists of one line per thread, giving a thread ID, the
+date of the newest (or oldest, depending on the sort option) matched
+message in the thread, the number of matched messages and total
+messages in the thread, the names of all participants in the thread,
+and the subject of the newest (or oldest) message.
+
+Supported options for
+.B search
+include
+.RS 4
+.TP 4
+.BR \-\-format= ( json | text )
+
+Presents the results in either JSON or plain-text (default).
+.RE
+
+.RS 4
+.TP 4
+.B \-\-output=(summary|threads|messages|files|tags)
+
+.RS 4
+.TP 4
+.B summary
+
+Output a summary of each thread with any message matching the search
+terms. The summary includes the thread ID, date, the number of
+messages in the thread (both the number matched and the total number),
+the authors of the thread and the subject.
+.RE
+.RS 4
+.TP 4
+.B threads
+
+Output the thread IDs of all threads with any message matching the
+search terms, either one per line (\-\-format=text) or as a JSON array
+(\-\-format=json).
+.RE
+.RS 4
+.TP 4
+.B messages
+
+Output the message IDs of all messages matching the search terms,
+either one per line (\-\-format=text) or as a JSON array
+(\-\-format=json).
+.RE
+.RS 4
+.TP 4
+.B files
+
+Output the filenames of all messages matching the search terms, either
+one per line (\-\-format=text) or as a JSON array (\-\-format=json).
+.RE
+.RS 4
+.TP 4
+.B tags
+
+Output all tags that appear on any message matching the search terms,
+either one per line (\-\-format=text) or as a JSON array
+(\-\-format=json).
+.RE
+.RE
+
+.RS 4
+.TP 4
+.BR \-\-sort= ( newest\-first | oldest\-first )
+
+This option can be used to present results in either chronological order
+.RB ( oldest\-first )
+or reverse chronological order
+.RB ( newest\-first ).
+
+Note: The thread order will be distinct between these two options
+(beyond being simply reversed). When sorting by
+.B oldest\-first
+the threads will be sorted by the oldest message in each thread, but
+when sorting by
+.B newest\-first
+the threads will be sorted by the newest message in each thread.
+
+By default, results will be displayed in reverse chronological order,
+(that is, the newest results will be displayed first).
+.RE
+
+.RS 4
+.TP 4
+.BR \-\-offset=[\-]N
+
+Skip displaying the first N results. With the leading '\-', start at the Nth
+result from the end.
+.RE
+
+.RS 4
+.TP 4
+.BR \-\-limit=N
+
+Limit the number of displayed results to N.
+.RE
+
+.RS 4
+See the
+.B "SEARCH SYNTAX"
+section below for details of the supported syntax for <search-terms>.
+.RE
diff --git a/man/man1/notmuch-show.1 b/man/man1/notmuch-show.1
new file mode 100644
index 00000000..701186ee
--- /dev/null
+++ b/man/man1/notmuch-show.1
@@ -0,0 +1,140 @@
+.TH NOTMUCH-SHOW 1 2011-12-04 "Notmuch 0.10.2"
+.SH NAME
+notmuch-show \- Show messages matching the given search terms.
+.SH SYNOPSIS
+
+.B notmuch show
+.RI "[" options "...] <" search-term ">..."
+
+.SH DESCRIPTION
+
+Shows all messages matching the search terms.
+
+The messages will be grouped and sorted based on the threading (all
+replies to a particular message will appear immediately after that
+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).
+
+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=(text|json|mbox|raw)
+
+.RS 4
+.TP 4
+.BR text " (default for messages)"
+
+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
+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. For a multipart MIME message, these parts will
+be nested.
+.RE
+.RS 4
+.TP 4
+.B json
+
+The output is formatted with Javascript Object Notation (JSON). This
+format is more robust than the text format for automated
+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
+
+.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:
+
+.nf
+.nh
+http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
+.hy
+.fi
+.
+.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
+
+.RS 4
+.TP 4
+.B \-\-verify
+
+Compute and report the validity of any MIME cryptographic signatures
+found in the selected content (ie. "multipart/signed" parts). Status
+of the signature will be reported (currently only supported with
+--format=json), and the multipart/signed part will be replaced by the
+signed data.
+.RE
+
+.RS 4
+.TP 4
+.B \-\-decrypt
+
+Decrypt any MIME encrypted parts found in the selected content
+(ie. "multipart/encrypted" parts). Status of the decryption will be
+reported (currently only supported with --format=json) and the
+multipart/encrypted part will be replaced by the decrypted
+content.
+.RE
+
+A common use of
+.B notmuch show
+is to display a single thread of email messages. For this, use a
+search term of "thread:<thread-id>" as can be seen in the first
+column of output from the
+.B notmuch search
+command.
+
+See the
+.B "SEARCH SYNTAX"
+section below for details of the supported syntax for <search-terms>.
+.RE
+.RS 4
diff --git a/man/man1/notmuch-tag.1 b/man/man1/notmuch-tag.1
new file mode 100644
index 00000000..a0082f9b
--- /dev/null
+++ b/man/man1/notmuch-tag.1
@@ -0,0 +1,26 @@
+.TH NOTMUCH-TAG 1 2011-12-04 "Notmuch 0.10.2"
+.SH NAME
+notmuch-tag \- Add/remove tags for all messages matching the search terms.
+
+.SH SYNOPSIS
+.B notmuch tag
+.RI  "+<" tag> "|\-<" tag "> [...] [\-\-] <" search-term ">..."
+
+.SH DESCRIPTION
+
+Add/remove tags for all messages matching the search terms.
+
+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
+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
+.B "SEARCH SYNTAX"
+section below for details of the supported syntax for <search-terms>.
+.RE
diff --git a/man/man1/notmuch.1 b/man/man1/notmuch.1
new file mode 100644
index 00000000..74f892e8
--- /dev/null
+++ b/man/man1/notmuch.1
@@ -0,0 +1,136 @@
+.\" notmuch - Not much of an email program, (just index, search and tagging)
+.\"
+.\" Copyright © 2009 Carl Worth
+.\"
+.\" Notmuch is free software: you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation, either version 3 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" Notmuch is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program.  If not, see http://www.gnu.org/licenses/ .
+.\"
+.\" Author: Carl Worth <cworth@cworth.org>
+.TH NOTMUCH 1 2011-12-04 "Notmuch 0.10.2"
+.SH NAME
+notmuch \- thread-based email index, search, and tagging
+.SH SYNOPSIS
+.B notmuch
+.IR command " [" args " ...]"
+.SH DESCRIPTION
+Notmuch is a command-line based program for indexing, searching,
+reading, and tagging large collections of email messages.
+
+The quickest way to get started with Notmuch is to simply invoke the
+.B notmuch
+command with no arguments, which will interactively guide you through
+the process of indexing your mail.
+.SH NOTE
+While the command-line program
+.B notmuch
+provides powerful functionality, it does not provide the most
+convenient interface for that functionality. More sophisticated
+interfaces are expected to be built on top of either the command-line
+interface, or more likely, on top of the notmuch library
+interface. See http://notmuchmail.org for more about alternate
+interfaces to notmuch.
+.SH COMMANDS
+The
+.BR setup
+command is used to configure Notmuch for first use, (or to reconfigure
+it later).
+.RS 4
+.TP 4
+.B setup
+
+Interactively sets up notmuch for first use.
+
+The setup command will prompt for your full name, your primary email
+address, any alternate email addresses you use, and the directory
+containing your email archives. Your answers will be written to a
+configuration file in ${NOTMUCH_CONFIG} (if set) or
+${HOME}/.notmuch-config . This configuration file will be created with
+descriptive comments, making it easy to edit by hand later to change the
+configuration. Or you can run
+.B "notmuch setup"
+again to change the configuration.
+
+The mail directory you specify can contain any number of
+sub-directories and should primarily contain only files with individual
+email messages (eg. maildir or mh archives are perfect). If there are
+other, non-email files (such as indexes maintained by other email
+programs) then notmuch will do its best to detect those and ignore
+them.
+
+Mail storage that uses mbox format, (where one mbox file contains many
+messages), will not work with notmuch. If that's how your mail is
+currently stored, it is recommended you first convert it to maildir
+format with a utility such as mb2md before running
+.B "notmuch setup" .
+
+Invoking
+.B notmuch
+with no command argument will run
+.B setup
+if the setup command has not previously been completed.
+.RE
+
+
+
+Several of the notmuch commands accept search terms with a common
+syntax. See the
+.B "SEARCH SYNTAX"
+section below for more details on the supported syntax.
+
+The
+.BR search ", " show " and " count
+commands are used to query the email database.
+
+
+The
+.B reply
+command is useful for preparing a template for an email reply.
+.RS 4
+
+The
+.B tag
+command is the only command available for manipulating database
+contents.
+
+
+The
+.BR dump " and " restore
+commands can be used to create a textual dump of email tags for backup
+purposes, and to restore from that dump.
+
+The
+.B config
+command can be used to get or set settings int the notmuch
+configuration file.
+
+.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
+in the Notmuch distribution).
+
+The notmuch website:
+.B http://notmuchmail.org
+.SH CONTACT
+Feel free to send questions, comments, or kudos to the notmuch mailing
+list <notmuch@notmuchmail.org> . Subscription is not required before
+posting, but is available from the notmuchmail.org website.
+
+Real-time interaction with the Notmuch community is available via IRC
+(server: irc.freenode.net, channel: #notmuch).
diff --git a/man/man5/notmuch-hooks.5 b/man/man5/notmuch-hooks.5
new file mode 100644
index 00000000..8b66425e
--- /dev/null
+++ b/man/man5/notmuch-hooks.5
@@ -0,0 +1,40 @@
+.TH NOTMUCH-HOOKS 5 2011-12-04 "Notmuch 0.10.2"
+
+.SH NAME
+notmuch-hooks \- hooks for notmuch
+
+.SH SYNOPSIS
+ $DATABASEDIR/.notmuch/hooks/*
+
+.SH DESCRIPTION
+Hooks are scripts (or arbitrary executables or symlinks to such) that notmuch
+invokes before and after certain actions. These scripts reside in
+the .notmuch/hooks directory within the database directory and must have
+executable permissions.
+
+The currently available hooks are described below.
+.RS 4
+.TP 4
+.B pre\-new
+This hook is invoked by the
+.B new
+command before scanning or importing new messages into the database. If this
+hook exits with a non-zero status, notmuch will abort further processing of the
+.B new
+command.
+
+Typically this hook is used for fetching or delivering new mail to be imported
+into the database.
+.RE
+.RS 4
+.TP 4
+.B post\-new
+This hook is invoked by the
+.B new
+command after new messages have been imported into the database and initial tags
+have been applied. The hook will not be run if there have been any errors during
+the scan or import.
+
+Typically this hook is used to perform additional query\-based tagging on the
+imported messages.
+.RE
diff --git a/man/man7/notmuch-search-terms.7 b/man/man7/notmuch-search-terms.7
new file mode 100644
index 00000000..ba8b873e
--- /dev/null
+++ b/man/man7/notmuch-search-terms.7
@@ -0,0 +1,137 @@
+.TH NOTMUCH-SEARCH-TERMS 7 2011-12-04 "Notmuch 0.10.2"
+
+.SH NAME
+notmuch-search-terms \- Syntax for notmuch queries
+
+.SH SYNOPSIS
+
+.B notmuch count
+.RI  [ options... ]
+.RI  < search-term ">..."
+
+.B "notmuch dump"
+.RI "[ <" filename "> ] [--]"
+.RI "[ <" search-term ">...]"
+
+.B notmuch part
+.BI "\-\-part=" "<part-number>"
+.RI < search-term ">..."
+
+.B notmuch search
+.RI  [  options "...] <" search-term ">..."
+
+.B notmuch show
+.RI "[" options "...] <" search-term ">..."
+
+.B notmuch tag
+.RI  "+<" tag> "|\-<" tag "> [...] [\-\-] <" search-term ">..."
+
+
+.SH DESCRIPTION
+Several notmuch commands accept a common syntax for search terms.
+
+The search terms can consist of free-form text (and quoted phrases)
+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):
+
+	from:<name-or-address>
+
+	to:<name-or-address>
+
+	subject:<word-or-quoted-phrase>
+
+	attachment:<word>
+
+	tag:<tag> (or is:<tag>)
+
+	id:<message-id>
+
+	thread:<thread-id>
+
+	folder:<directory-path>
+
+The
+.B from:
+prefix is used to match the name or address of the sender of an email
+message.
+
+The
+.B to:
+prefix is used to match the names or addresses of any recipient of an
+email message, (whether To, Cc, or Bcc).
+
+Any term prefixed with
+.B subject:
+will match only text from the subject of an email. Searching for a
+phrase in the subject is supported by including quotation marks around
+the phrase, immediately following
+.BR subject: .
+
+The
+.B attachment:
+prefix can be used to search for specific filenames (or extensions) of
+attachments to email messages.
+
+For
+.BR tag: " and " is:
+valid tag values include
+.BR inbox " and " unread
+by default for new messages added by
+.B notmuch new
+as well as any other tag values added manually with
+.BR "notmuch tag" .
+
+For
+.BR id: ,
+message ID values are the literal contents of the Message\-ID: header
+of email messages, but without the '<', '>' delimiters.
+
+The
+.B thread:
+prefix can be used with the thread ID values that are generated
+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
+, etc.). Each term in the query will be implicitly connected by a
+logical AND if no explicit operator is provided, (except that terms
+with a common prefix will be implicitly combined with OR until we get
+Xapian defect #402 fixed).
+
+Parentheses can also be used to control the combination of the Boolean
+operators, but will have to be protected from interpretation by the
+shell, (such as by putting quotation marks around any parenthesized
+expression).
+
+Finally, results can be restricted to only messages within a
+particular time range, (based on the Date: header) with a syntax of:
+
+	<initial-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
+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 following syntax would
+specify a date range to return messages from 2009\-10\-01 until the
+current time:
+
+	$(date +%s \-d 2009\-10\-01)..$(date +%s)