doc: convert sphinx based docs

This is the output from sphinx-quickstart, massaged a bit, along with
our existing man pages converted to rst.

A skeleton notmuch-emacs manual is also included. It is not suitable
for end user use yet.

12 files changed, 1163 insertions, 0 deletions

diff --git a/doc/man1/notmuch-compact.rst b/doc/man1/notmuch-compact.rst
new file mode 100644
index 00000000..e0109dce
--- /dev/null
+++ b/doc/man1/notmuch-compact.rst
@@ -0,0 +1,52 @@
+===============
+notmuch-compact
+===============
+
+SYNOPSIS
+========
+
+**notmuch** **compact** [--quiet] [--backup=<*directory*>]
+
+DESCRIPTION
+===========
+
+The **compact** command can be used to compact the notmuch database.
+This can both reduce the space required by the database and improve
+lookup performance.
+
+The compacted database is built in a temporary directory and is later
+moved into the place of the origin database. The original uncompacted
+database is discarded, unless the ``--backup=``\ <directory> option is
+used.
+
+Note that the database write lock will be held during the compaction
+process (which may be quite long) to protect data integrity.
+
+Supported options for **compact** include
+
+    ``--backup=``\ <directory>
+        Save the current database to the given directory before
+        replacing it with the compacted database. The backup directory
+        must not exist and it must reside on the same mounted filesystem
+        as the current database.
+
+    ``--quiet``
+        Do not report database compaction progress to stdout.
+
+ENVIRONMENT
+===========
+
+The following environment variables can be used to control the behavior
+of notmuch.
+
+**NOTMUCH\_CONFIG**
+    Specifies the location of the notmuch configuration file. Notmuch
+    will use ${HOME}/.notmuch-config if this variable is not set.
+
+SEE ALSO
+========
+
+**notmuch(1)**, **notmuch-count(1)**, **notmuch-dump(1)**,
+**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
+**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
+**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst
new file mode 100644
index 00000000..3c9a5684
--- /dev/null
+++ b/doc/man1/notmuch-config.rst
@@ -0,0 +1,123 @@
+==============
+notmuch-config
+==============
+
+SYNOPSIS
+========
+
+**notmuch** **config** **get** <*section*>.<*item*>
+
+**notmuch** **config** **set** <*section*>.<*item*> [*value* ...]
+
+**notmuch** **config** **list**
+
+DESCRIPTION
+===========
+
+The **config** command can be used to get or set settings in the notmuch
+configuration file.
+
+    **get**
+        The value of the specified configuration item is printed to
+        stdout. If the item has multiple values (it is a list), each
+        value is separated by a newline character.
+
+    **set**
+        The specified configuration item is set to the given value. To
+        specify a multiple-value item (a list), 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.
+
+    **list**
+        Every configuration item is printed to stdout, each on a
+        separate line of the form:
+
+        *section*.\ *item*\ =\ *value*
+
+        No additional whitespace surrounds the dot or equals sign
+        characters. In a multiple-value item (a list), the values are
+        separated by semicolon characters.
+
+The available configuration items are described below.
+
+    **database.path**
+        The top-level directory where your mail currently exists and to
+        where mail will be delivered in the future. Files should be
+        individual email messages. Notmuch will store its database
+        within a sub-directory of the path configured here named
+        ``.notmuch``.
+
+    **user.name**
+        Your full name.
+
+    **user.primary\_email**
+        Your primary email address.
+
+    **user.other\_email**
+        A list of other email addresses at which you receive email.
+
+    **new.tags**
+        A list of tags that will be added to all messages incorporated
+        by **notmuch new**.
+
+    **new.ignore**
+        A list of file and directory names, without path, that will not
+        be searched for messages by **notmuch new**. All the files and
+        directories matching any of the names specified here will be
+        ignored, regardless of the location in the mail store directory
+        hierarchy.
+
+    **search.exclude\_tags**
+        A list of tags that will be excluded from search results by
+        default. Using an excluded tag in a query will override that
+        exclusion.
+
+    **maildir.synchronize\_flags**
+        If true, then the following maildir flags (in message filenames)
+        will be synchronized with the corresponding notmuch tags:
+
+        +--------+-----------------------------------------------+
+        | Flag   | Tag                                           |
+        +========+===============================================+
+        | D      | draft                                         |
+        +--------+-----------------------------------------------+
+        | F      | flagged                                       |
+        +--------+-----------------------------------------------+
+        | P      | passed                                        |
+        +--------+-----------------------------------------------+
+        | R      | replied                                       |
+        +--------+-----------------------------------------------+
+        | S      | unread (added when 'S' flag is not present)   |
+        +--------+-----------------------------------------------+
+
+        The **notmuch new** command will notice flag changes in
+        filenames and update tags, while the **notmuch tag** and
+        **notmuch restore** commands will notice tag changes and update
+        flags in filenames.
+
+        If there have been any changes in the maildir (new messages
+        added, old ones removed or renamed, maildir flags changed,
+        etc.), it is advisable to run **notmuch new** before **notmuch
+        tag** or **notmuch restore** commands to ensure the tag changes
+        are properly synchronized to the maildir flags, as the commands
+        expect the database and maildir to be in sync.
+
+ENVIRONMENT
+===========
+
+The following environment variables can be used to control the behavior
+of notmuch.
+
+**NOTMUCH\_CONFIG**
+    Specifies the location of the notmuch configuration file. Notmuch
+    will use ${HOME}/.notmuch-config if this variable is not set.
+
+SEE ALSO
+========
+
+**notmuch(1)**, **notmuch-count(1)**, **notmuch-dump(1)**,
+**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
+**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
+**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
diff --git a/doc/man1/notmuch-count.rst b/doc/man1/notmuch-count.rst
new file mode 100644
index 00000000..ca78c18b
--- /dev/null
+++ b/doc/man1/notmuch-count.rst
@@ -0,0 +1,60 @@
+=============
+notmuch-count
+=============
+
+SYNOPSIS
+========
+
+**notmuch** **count** [*option* ...] <*search-term*> ...
+
+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.
+
+See **notmuch-search-terms(7)** for details of the supported syntax for
+<search-terms>.
+
+Supported options for **count** include
+
+    ``--output=(messages|threads|files)``
+
+        **messages**
+            Output the number of matching messages. This is the default.
+
+        **threads**
+            Output the number of matching threads.
+
+        **files**
+            Output the number of files associated with matching
+            messages. This may be bigger than the number of matching
+            messages due to duplicates (i.e. multiple files having the
+            same message-id).
+
+    ``--exclude=(true|false)``
+        Specify whether to omit messages matching search.tag\_exclude
+        from the count (the default) or not.
+
+    ``--batch``
+        Read queries from a file (stdin by default), one per line, and
+        output the number of matching messages (or threads) to stdout,
+        one per line. On an empty input line the count of all messages
+        (or threads) in the database will be output. This option is not
+        compatible with specifying search terms on the command line.
+
+    ``--input=``\ <filename>
+        Read input from given file, instead of from stdin. Implies
+        ``--batch``.
+
+SEE ALSO
+========
+
+**notmuch(1)**, **notmuch-config(1)**, **notmuch-dump(1)**,
+**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
+**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
+**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
diff --git a/doc/man1/notmuch-dump.rst b/doc/man1/notmuch-dump.rst
new file mode 100644
index 00000000..17d1da5c
--- /dev/null
+++ b/doc/man1/notmuch-dump.rst
@@ -0,0 +1,72 @@
+============
+notmuch-dump
+============
+
+SYNOPSIS
+========
+
+**notmuch** **dump** [--format=(batch-tag|sup)] [--] [--output=<*file*>] [--] [<*search-term*> ...]
+
+DESCRIPTION
+===========
+
+Dump tags for messages matching the given search terms.
+
+Output is to the given filename, if any, or to stdout.
+
+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.)
+
+``--format=(sup|batch-tag)``
+    Notmuch restore supports two plain text dump formats, both with one
+    message-id per line, followed by a list of tags.
+
+    **batch-tag**
+        The default **batch-tag** dump format is intended to more robust
+        against malformed message-ids and tags containing whitespace or
+        non-\ **ascii(7)** characters. Each line has the form
+
+            +<*encoded-tag*\ > +<*encoded-tag*\ > ... --
+            id:<*quoted-message-id*\ >
+
+        Tags are hex-encoded by replacing every byte not matching the
+        regex **[A-Za-z0-9@=.,\_+-]** with **%nn** where nn is the two
+        digit hex encoding. The message ID is a valid Xapian query,
+        quoted using Xapian boolean term quoting rules: if the ID
+        contains whitespace or a close paren or starts with a double
+        quote, it must be enclosed in double quotes and double quotes
+        inside the ID must be doubled. The astute reader will notice
+        this is a special case of the batch input format for
+        **notmuch-tag(1)**; note that the single message-id query is
+        mandatory for **notmuch-restore(1)**.
+
+    **sup**
+        The **sup** 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 **notmuch
+        restore** command provides you a way to import all of your tags
+        (or labels as sup calls them). Each line has the following form
+
+            <*message-id*\ > **(** <*tag*\ > ... **)**
+
+        with zero or more tags are separated by spaces. Note that
+        (malformed) message-ids may contain arbitrary non-null
+        characters. Note also that tags with spaces will not be
+        correctly restored with this format.
+
+    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.
+
+    See **notmuch-search-terms(7)** for details of the supported syntax
+    for <search-terms>.
+
+SEE ALSO
+========
+
+**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
+**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
+**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
+**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
diff --git a/doc/man1/notmuch-insert.rst b/doc/man1/notmuch-insert.rst
new file mode 100644
index 00000000..2be1a7b8
--- /dev/null
+++ b/doc/man1/notmuch-insert.rst
@@ -0,0 +1,58 @@
+==============
+notmuch-insert
+==============
+
+SYNOPSIS
+========
+
+**notmuch** **insert** [option ...] [+<*tag*>|-<*tag*> ...]
+
+DESCRIPTION
+===========
+
+**notmuch insert** reads a message from standard input and delivers it
+into the maildir directory given by configuration option
+**database.path**, then incorporates the message into the notmuch
+database. It is an alternative to using a separate tool to deliver the
+message then running **notmuch new** afterwards.
+
+The new message will be tagged with the tags specified by the
+**new.tags** configuration option, then by operations specified on the
+command-line: tags prefixed by '+' are added while those prefixed by '-'
+are removed.
+
+If the new message is a duplicate of an existing message in the database
+(it has same Message-ID), it will be added to the maildir folder and
+notmuch database, but the tags will not be changed.
+
+Option arguments must appear before any tag operation arguments.
+Supported options for **insert** include
+
+    ``--folder=<``\ folder\ **>**
+        Deliver the message to the specified folder, relative to the
+        top-level directory given by the value of **database.path**. The
+        default is to deliver to the top-level directory.
+
+    ``--create-folder``
+        Try to create the folder named by the ``--folder`` option, if it
+        does not exist. Otherwise the folder must already exist for mail
+        delivery to succeed.
+
+EXIT STATUS
+===========
+
+This command returns exit status 0 if the message was successfully added
+to the mail directory, even if the message could not be indexed and
+added to the notmuch database. In the latter case, a warning will be
+printed to standard error but the message file will be left on disk.
+
+If the message could not be written to disk then a non-zero exit status
+is returned.
+
+SEE ALSO
+========
+
+**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
+**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-reply(1)**,
+**notmuch-restore(1)**, **notmuch-search(1)**,
+**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
diff --git a/doc/man1/notmuch-new.rst b/doc/man1/notmuch-new.rst
new file mode 100644
index 00000000..d11fceed
--- /dev/null
+++ b/doc/man1/notmuch-new.rst
@@ -0,0 +1,52 @@
+===========
+notmuch-new
+===========
+
+SYNOPSIS
+========
+
+**notmuch** **new** [--no-hooks]
+
+DESCRIPTION
+===========
+
+Find and import any new messages to the database.
+
+The **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 **inbox** and
+**unread** tags.
+
+You should run **notmuch new** once after first running **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 **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 ``notmuch`` with no command argument will run **new** if
+**notmuch setup** has previously been completed, but **notmuch new** has
+not previously been run.
+
+**notmuch new** updates tags according to maildir flag changes if the
+**maildir.synchronize\_flags** configuration option is enabled. See
+**notmuch-config(1)** for details.
+
+The **new** command supports hooks. See **notmuch-hooks(5)** for more
+details on hooks.
+
+Supported options for **new** include
+
+    ``--no-hooks``
+        Prevents hooks from being run.
+
+    ``--quiet``
+        Do not print progress or results.
+
+SEE ALSO
+========
+
+**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
+**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
+**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
+**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
diff --git a/doc/man1/notmuch-reply.rst b/doc/man1/notmuch-reply.rst
new file mode 100644
index 00000000..cfbd4ea8
--- /dev/null
+++ b/doc/man1/notmuch-reply.rst
@@ -0,0 +1,112 @@
+=============
+notmuch-reply
+=============
+
+SYNOPSIS
+========
+
+**notmuch** **reply** [option ...] <*search-term*> ...
+
+DESCRIPTION
+===========
+
+Constructs a reply template for a set of messages.
+
+To make replying to email easier, **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. Unless
+``--reply-to=sender`` is specified, values 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 **reply** include
+
+    ``--format=``\ (**default**\ \|\ **json**\ \|\ **sexp**\ \|\ **headers-only**)
+
+        **default**
+            Includes subject and quoted message body as an RFC 2822
+            message.
+
+        **json**
+            Produces JSON output containing headers for a reply message
+            and the contents of the original message. This output can be
+            used by a client to create a reply message intelligently.
+
+        **sexp**
+            Produces S-Expression output containing headers for a reply
+            message and the contents of the original message. This
+            output can be used by a client to create a reply message
+            intelligently.
+
+        **headers-only**
+            Only produces In-Reply-To, References, To, Cc, and Bcc
+            headers.
+
+    ``--format-version=N``
+        Use the specified structured output format version. This is
+        intended for programs that invoke **notmuch(1)** internally. If
+        omitted, the latest supported version will be used.
+
+    ``--reply-to=``\ (**all**\ \|\ **sender**)
+
+        **all** (default)
+            Replies to all addresses.
+
+        **sender**
+            Replies only to the sender. If replying to user's own
+            message (Reply-to: or From: header is one of the user's
+            configured email addresses), try To:, Cc:, and Bcc: headers
+            in this order, and copy values from the first that contains
+            something other than only the user's addresses.
+
+    ``--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
+        --format=sexp) and on successful decryption the
+        multipart/encrypted part will be replaced by the decrypted
+        content.
+
+        Decryption expects a functioning **gpg-agent(1)** to provide any
+        needed credentials. Without one, the decryption will fail.
+
+See **notmuch-search-terms(7)** for details of the supported syntax for
+<search-terms>.
+
+Note: It is most common to use **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 issues found in multiple patches. The
+default format supports replying to multiple messages at once, but the
+JSON and S-Expression formats do not.
+
+EXIT STATUS
+===========
+
+This command supports the following special exit status codes
+
+``20``
+    The requested format version is too old.
+
+``21``
+    The requested format version is too new.
+
+SEE ALSO
+========
+
+**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
+**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
+**notmuch-new(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
+**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
diff --git a/doc/man1/notmuch-restore.rst b/doc/man1/notmuch-restore.rst
new file mode 100644
index 00000000..d6cf19ab
--- /dev/null
+++ b/doc/man1/notmuch-restore.rst
@@ -0,0 +1,59 @@
+===============
+notmuch-restore
+===============
+
+SYNOPSIS
+========
+
+**notmuch** **restore** [--accumulate] [--format=(auto|batch-tag|sup)] [--input=<*filename*>]
+
+DESCRIPTION
+===========
+
+Restores the tags from the given file (see **notmuch dump**).
+
+The input is read from the given filename, if any, or from stdin.
+
+Supported options for **restore** include
+
+    ``--accumulate``
+        The union of the existing and new tags is applied, instead of
+        replacing each message's tags as they are read in from the dump
+        file.
+
+    ``--format=(sup|batch-tag|auto)``
+        Notmuch restore supports two plain text dump formats, with each
+        line specifying a message-id and a set of tags. For details of
+        the actual formats, see **notmuch-dump(1)**.
+
+        **sup**
+            The **sup** 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
+            **notmuch restore** command provides you a way to import all
+            of your tags (or labels as sup calls them).
+
+        **batch-tag**
+            The **batch-tag** dump format is intended to more robust
+            against malformed message-ids and tags containing whitespace
+            or non-\ **ascii(7)** characters. See **notmuch-dump(1)**
+            for details on this format.
+
+            **notmuch restore** updates the maildir flags according to
+            tag changes if the **maildir.synchronize\_flags**
+            configuration option is enabled. See **notmuch-config(1)**
+            for details.
+
+        **auto**
+            This option (the default) tries to guess the format from the
+            input. For correctly formed input in either supported
+            format, this heuristic, based the fact that batch-tag format
+            contains no parentheses, should be accurate.
+
+SEE ALSO
+========
+
+**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
+**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
+**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-search(1)**,
+**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
diff --git a/doc/man1/notmuch-search.rst b/doc/man1/notmuch-search.rst
new file mode 100644
index 00000000..7ac6c68e
--- /dev/null
+++ b/doc/man1/notmuch-search.rst
@@ -0,0 +1,146 @@
+==============
+notmuch-search
+==============
+
+SYNOPSIS
+========
+
+**notmuch** **search** [*option* ...] <*search-term*> ...
+
+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.
+
+See **notmuch-search-terms(7)** for details of the supported syntax for
+<search-terms>.
+
+Supported options for **search** include
+
+    ``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**)
+        Presents the results in either JSON, S-Expressions, newline
+        character separated plain-text (default), or null character
+        separated plain-text (compatible with **xargs(1)** -0 option
+        where available).
+
+    ``--format-version=N``
+        Use the specified structured output format version. This is
+        intended for programs that invoke **notmuch(1)** internally. If
+        omitted, the latest supported version will be used.
+
+    ``--output=(summary|threads|messages|files|tags)``
+
+        **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.
+
+        **threads**
+            Output the thread IDs of all threads with any message
+            matching the search terms, either one per line
+            (--format=text), separated by null characters
+            (--format=text0), as a JSON array (--format=json), or an
+            S-Expression list (--format=sexp).
+
+        **messages**
+            Output the message IDs of all messages matching the search
+            terms, either one per line (--format=text), separated by
+            null characters (--format=text0), as a JSON array
+            (--format=json), or as an S-Expression list (--format=sexp).
+
+        **files**
+            Output the filenames of all messages matching the search
+            terms, either one per line (--format=text), separated by
+            null characters (--format=text0), as a JSON array
+            (--format=json), or as an S-Expression list (--format=sexp).
+
+            Note that each message may have multiple filenames
+            associated with it. All of them are included in the output,
+            unless limited with the --duplicate=N option.
+
+        **tags**
+            Output all tags that appear on any message matching the
+            search terms, either one per line (--format=text), separated
+            by null characters (--format=text0), as a JSON array
+            (--format=json), or as an S-Expression list (--format=sexp).
+
+    ``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
+        This option can be used to present results in either
+        chronological order (**oldest-first**) or reverse chronological
+        order (**newest-first**).
+
+        Note: The thread order will be distinct between these two
+        options (beyond being simply reversed). When sorting by
+        **oldest-first** the threads will be sorted by the oldest
+        message in each thread, but when sorting by **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).
+
+    ``--offset=[-]N``
+        Skip displaying the first N results. With the leading '-', start
+        at the Nth result from the end.
+
+    ``--limit=N``
+        Limit the number of displayed results to N.
+
+    ``--exclude=(true|false|all|flag)``
+        A message is called "excluded" if it matches at least one tag in
+        search.tag\_exclude that does not appear explicitly in the
+        search terms. This option specifies whether to omit excluded
+        messages in the search process.
+
+        The default value, **true**, prevents excluded messages from
+        matching the search terms.
+
+        **all** additionally prevents excluded messages from appearing
+        in displayed results, in effect behaving as though the excluded
+        messages do not exist.
+
+        **false** allows excluded messages to match search terms and
+        appear in displayed results. Excluded messages are still marked
+        in the relevant outputs.
+
+        **flag** only has an effect when ``--output=summary``. The
+        output is almost identical to **false**, but the "match count"
+        is the number of matching non-excluded messages in the thread,
+        rather than the number of matching messages.
+
+    ``--duplicate=N``
+        Effective with ``--output=files``, output the Nth filename
+        associated with each message matching the query (N is 1-based).
+        If N is greater than the number of files associated with the
+        message, don't print anything.
+
+        Note that this option is orthogonal with the **folder:** search
+        prefix. The prefix matches messages based on filenames. This
+        option filters filenames of the matching messages.
+
+EXIT STATUS
+===========
+
+This command supports the following special exit status codes
+
+``20``
+    The requested format version is too old.
+
+``21``
+    The requested format version is too new.
+
+SEE ALSO
+========
+
+**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
+**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
+**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
+**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst
new file mode 100644
index 00000000..bad868be
--- /dev/null
+++ b/doc/man1/notmuch-show.rst
@@ -0,0 +1,179 @@
+============
+notmuch-show
+============
+
+SYNOPSIS
+========
+
+**notmuch** **show** [*option* ...] <*search-term*> ...
+
+DESCRIPTION
+===========
+
+Shows all messages matching the search terms.
+
+See **notmuch-search-terms(7)** for details of the supported syntax for
+<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 **show** include
+
+    ``--entire-thread=(true|false)``
+        If true, **notmuch show** outputs all messages in the thread of
+        any message matching the search terms; if false, it outputs only
+        the matching messages. For ``--format=json`` and
+        ``--format=sexp`` this defaults to true. For other formats, this
+        defaults to false.
+
+    ``--format=(text|json|sexp|mbox|raw)``
+
+        **text** (default for messages)
+            The default plain-text format has all text-content MIME
+            parts decoded. Various components in the output,
+            (**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.
+
+        **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. By default JSON
+            output includes all messages in a matching thread; that is,
+            by default,
+
+            ``--format=json`` sets ``--entire-thread`` The caller can
+            disable this behaviour by setting ``--entire-thread=false``
+
+        **sexp**
+            The output is formatted as an S-Expression (sexp). This
+            format is more robust than the text format for automated
+            processing. The nested structure of multipart MIME messages
+            is reflected in nested S-Expression output. By default,
+            S-Expression output includes all messages in a matching
+            thread; that is, by default,
+
+            ``--format=sexp`` sets ``--entire-thread`` The caller can
+            disable this behaviour by setting ``--entire-thread=false``
+
+        **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
+
+        **raw** (default for a single part, see --part)
+            For a message or an attached message part, 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. Note that
+            messages with a simple body still have two parts: part 0 is
+            the whole message and part 1 is the body.
+
+            For a multipart part, the part headers and body (including
+            all child parts) is output.
+
+            The raw format must only be used with search terms matching
+            single message.
+
+    ``--format-version=N``
+        Use the specified structured output format version. This is
+        intended for programs that invoke **notmuch(1)** internally. If
+        omitted, the latest supported version will be used.
+
+    ``--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', 'sexp' or 'text' output
+        formats.
+
+    ``--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 --format=sexp), and the
+        multipart/signed part will be replaced by the signed data.
+
+    ``--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
+        --format=sexp) and on successful decryption the
+        multipart/encrypted part will be replaced by the decrypted
+        content.
+
+        Decryption expects a functioning **gpg-agent(1)** to provide any
+        needed credentials. Without one, the decryption will fail.
+
+        Implies --verify.
+
+    ``--exclude=(true|false)``
+        Specify whether to omit threads only matching
+        search.tag\_exclude from the search results (the default) or
+        not. In either case the excluded message will be marked with the
+        exclude flag (except when output=mbox when there is nowhere to
+        put the flag).
+
+        If --entire-thread is specified then complete threads are
+        returned regardless (with the excluded flag being set when
+        appropriate) but threads that only match in an excluded message
+        are not returned when ``--exclude=true.``
+
+        The default is ``--exclude=true.``
+
+    ``--body=(true|false)``
+        If true (the default) **notmuch show** includes the bodies of
+        the messages in the output; if false, bodies are omitted.
+        ``--body=false`` is only implemented for the json and sexp
+        formats and it is incompatible with ``--part > 0.``
+
+        This is useful if the caller only needs the headers as body-less
+        output is much faster and substantially smaller.
+
+    ``--include-html``
+        Include "text/html" parts as part of the output (currently only
+        supported with --format=json and --format=sexp). By default,
+        unless ``--part=N`` is used to select a specific part or
+        ``--include-html`` is used to include all "text/html" parts, no
+        part with content type "text/html" is included in the output.
+
+A common use of **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 **notmuch search** command.
+
+EXIT STATUS
+===========
+
+This command supports the following special exit status codes
+
+``20``
+    The requested format version is too old.
+
+``21``
+    The requested format version is too new.
+
+SEE ALSO
+========
+
+**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
+**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
+**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
+**notmuch-search(1)**, **notmuch-search-terms(7)**, **notmuch-tag(1)**
diff --git a/doc/man1/notmuch-tag.rst b/doc/man1/notmuch-tag.rst
new file mode 100644
index 00000000..2e7e1d32
--- /dev/null
+++ b/doc/man1/notmuch-tag.rst
@@ -0,0 +1,107 @@
+===========
+notmuch-tag
+===========
+
+SYNOPSIS
+========
+
+**notmuch** **tag** [options ...] +<*tag*>|-<*tag*> [--] <*search-term*> ...
+
+**notmuch** **tag** **--batch** [--input=<*filename*>]
+
+DESCRIPTION
+===========
+
+Add/remove tags for all messages matching the search terms.
+
+See **notmuch-search-terms(7)** for details of the supported syntax for
+<*search-term*\ >.
+
+Tags prefixed by '+' are added while those prefixed by '-' are removed.
+For each message, tag changes are applied in the order they appear on
+the command line.
+
+The beginning of the 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.
+
+**notmuch tag** updates the maildir flags according to tag changes if
+the **maildir.synchronize\_flags** configuration option is enabled. See
+**notmuch-config(1)** for details.
+
+Supported options for **tag** include
+
+    ``--remove-all``
+        Remove all tags from each message matching the search terms
+        before applying the tag changes appearing on the command line.
+        This means setting the tags of each message to the tags to be
+        added. If there are no tags to be added, the messages will have
+        no tags.
+
+    ``--batch``
+        Read batch tagging operations from a file (stdin by default).
+        This is more efficient than repeated **notmuch tag**
+        invocations. See `TAG FILE FORMAT <#tag_file_format>`__ below
+        for the input format. This option is not compatible with
+        specifying tagging on the command line.
+
+    ``--input=``\ <filename>
+        Read input from given file, instead of from stdin. Implies
+        ``--batch``.
+
+TAG FILE FORMAT
+===============
+
+The input must consist of lines of the format:
+
++<*tag*\ >\|-<*tag*\ > [...] [--] <*query*\ >
+
+Each line is interpreted similarly to **notmuch tag** command line
+arguments. The delimiter is one or more spaces ' '. Any characters in
+<*tag*\ > **may** be hex-encoded with %NN where NN is the hexadecimal
+value of the character. To hex-encode a character with a multi-byte
+UTF-8 encoding, hex-encode each byte. Any spaces in <tag> **must** be
+hex-encoded as %20. Any characters that are not part of <*tag*\ > **must
+not** be hex-encoded.
+
+In the future tag:"tag with spaces" style quoting may be supported for
+<*tag*\ > as well; for this reason all double quote characters in
+<*tag*\ > **should** be hex-encoded.
+
+The <*query*\ > should be quoted using Xapian boolean term quoting
+rules: if a term contains whitespace or a close paren or starts with a
+double quote, it must be enclosed in double quotes (not including any
+prefix) and double quotes inside the term must be doubled (see below for
+examples).
+
+Leading and trailing space ' ' is ignored. Empty lines and lines
+beginning with '#' are ignored.
+
+EXAMPLE
+-------
+
+The following shows a valid input to batch tagging. Note that only the
+isolated '\*' acts as a wildcard. Also note the two different quotings
+of the tag **space in tags**
+
+::
+
+    +winner *
+    +foo::bar%25 -- (One and Two) or (One and tag:winner)
+    +found::it -- tag:foo::bar%
+    # ignore this line and the next
+
+    +space%20in%20tags -- Two
+    # add tag '(tags)', among other stunts.
+    +crazy{ +(tags) +&are +#possible\ -- tag:"space in tags"
+    +match*crazy -- tag:crazy{
+    +some_tag -- id:"this is ""nauty)"""
+
+SEE ALSO
+========
+
+**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
+**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
+**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
+**notmuch-search(1)**, **notmuch-search-terms(7)**, **notmuch-show(1)**,
diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst
new file mode 100644
index 00000000..97102943
--- /dev/null
+++ b/doc/man1/notmuch.rst
@@ -0,0 +1,143 @@
+=======
+notmuch
+=======
+
+SYNOPSIS
+========
+
+**notmuch** [option ...] **command** [arg ...]
+
+DESCRIPTION
+===========
+
+Notmuch is a command-line based program for indexing, searching,
+reading, and tagging large collections of email messages.
+
+This page describes how to get started using notmuch from the command
+line, and gives a brief overview of the commands available. For more
+information on e.g. **notmuch show** consult the **notmuch-show(1)** man
+page, also accessible via **notmuch help show**
+
+The quickest way to get started with Notmuch is to simply invoke the
+``notmuch`` command with no arguments, which will interactively guide
+you through the process of indexing your mail.
+
+NOTE
+====
+
+While the command-line program ``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. The emacs-based interface to
+notmuch (available under **emacs/** in the Notmuch source distribution)
+is probably the most widely used at this time.
+
+OPTIONS
+=======
+
+Supported global options for ``notmuch`` include
+
+    ``--help``
+        Print a synopsis of available commands and exit.
+
+    ``--version``
+        Print the installed version of notmuch, and exit.
+
+    ``--config=FILE``
+        Specify the configuration file to use. This overrides any
+        configuration file specified by ${NOTMUCH\_CONFIG}.
+
+COMMANDS
+========
+
+SETUP
+-----
+
+The **notmuch setup** command is used to configure Notmuch for first
+use, (or to reconfigure it later).
+
+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 **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 **notmuch setup .**
+
+Invoking ``notmuch`` with no command argument will run **setup** if the
+setup command has not previously been completed.
+
+OTHER COMMANDS
+--------------
+
+Several of the notmuch commands accept search terms with a common
+syntax. See **notmuch-search-terms**\ (7) for more details on the
+supported syntax.
+
+The **search**, **show** and **count** commands are used to query the
+email database.
+
+The **reply** command is useful for preparing a template for an email
+reply.
+
+The **tag** command is the only command available for manipulating
+database contents.
+
+The **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 **config** command can be used to get or set settings in the notmuch
+configuration file.
+
+ENVIRONMENT
+===========
+
+The following environment variables can be used to control the behavior
+of notmuch.
+
+**NOTMUCH\_CONFIG**
+    Specifies the location of the notmuch configuration file. Notmuch
+    will use ${HOME}/.notmuch-config if this variable is not set.
+
+**NOTMUCH\_TALLOC\_REPORT**
+    Location to write a talloc memory usage report. See
+    **talloc\_enable\_leak\_report\_full** in **talloc(3)** for more
+    information.
+
+**NOTMUCH\_DEBUG\_QUERY**
+    If set to a non-empty value, the notmuch library will print (to
+    stderr) Xapian queries it constructs.
+
+SEE ALSO
+========
+
+**notmuch-config(1)**, **notmuch-count(1)**, **notmuch-dump(1)**,
+**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
+**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
+**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
+
+The notmuch website: **http://notmuchmail.org**
+
+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).