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.

21 files changed, 1887 insertions, 0 deletions

diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 00000000..a60fb31e
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1,2 @@
+docdeps.mk
+_build
diff --git a/doc/INSTALL b/doc/INSTALL
new file mode 100644
index 00000000..e37c2b9b
--- /dev/null
+++ b/doc/INSTALL
@@ -0,0 +1,24 @@
+This file contains some more detailed information about building and
+installing the documentation.
+
+Building with sphinx.
+---------------------
+
+- You need sphinx at least version 1.0.
+
+- You can build build and install man pages with 'make install-man'
+
+- You can build man, info, html, and pdf versions of the docs
+  (currently only the man pages) with
+
+     'make install-{man|info|html|pdf}'
+
+Building the man pages
+----------------------
+
+- You can build the man pages with rst2man (from python-docutils) with
+  'make rst2man'.
+
+- Currently there is no support to automagically install the resulting
+  nroff files, but it should work to modify the target install-man
+  in doc/Makefile.local.
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 00000000..fa25832e
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,5 @@
+all:
+	$(MAKE) -C .. all
+
+.DEFAULT:
+	$(MAKE) -C .. $@
diff --git a/doc/Makefile.local b/doc/Makefile.local
new file mode 100644
index 00000000..ec230125
--- /dev/null
+++ b/doc/Makefile.local
@@ -0,0 +1,27 @@
+# -*- makefile -*-
+
+dir := doc
+
+# You can set these variables from the command line.
+SPHINXOPTS    := -q -c $(dir)
+SPHINXBUILD   = sphinx-build
+DOCBUILDDIR      := $(dir)/_build
+
+# Internal variables.
+ALLSPHINXOPTS   := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(dir)
+
+.PHONY: sphinx-html sphinx-man sphinx-texinfo sphinx-info
+
+sphinx-html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DOCBUILDDIR)/html
+
+sphinx-man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(DOCBUILDDIR)/man
+
+sphinx-texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(DOCBUILDDIR)/texinfo
+
+sphinx-info: sphinx-texinfo
+	make -C $(DOCBUILDDIR)/texinfo info
+
+CLEAN := $(CLEAN) $(DOCBUILDDIR)
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 00000000..6c2806d7
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,166 @@
+
+# -*- coding: utf-8 -*-
+
+import sys
+import os
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'notmuch'
+copyright = u'2014, Carl Worth and many others'
+
+# The short X.Y version.
+version = '0.17'
+# The full version, including alpha/beta/rc tags.
+release = '0.17'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build', 'notmuch-emacs.rst']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'notmuchdoc'
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+
+man_pages = [
+
+('man1/notmuch','notmuch',
+        u'thread-based email index, search, and tagging',
+        [u'Carl Worth and many others'], 1),
+
+('man1/notmuch-compact','notmuch-compact',
+        u'compact the notmuch database',
+        [u'Carl Worth and many others'], 1),
+
+('man1/notmuch-config','notmuch-config',
+        u'access notmuch configuration file',
+        [u'Carl Worth and many others'], 1),
+
+('man1/notmuch-count','notmuch-count',
+        u'count messages matching the given search terms',
+        [u'Carl Worth and many others'], 1),
+
+('man1/notmuch-dump','notmuch-dump',
+        u'creates a plain-text dump of the tags of each message',
+        [u'Carl Worth and many others'], 1),
+
+('man5/notmuch-hooks','notmuch-hooks',
+        u'hooks for notmuch',
+        [u'Carl Worth and many others'], 5),
+
+('man1/notmuch-insert','notmuch-insert',
+        u'add a message to the maildir and notmuch database',
+        [u'Carl Worth and many others'], 1),
+
+('man1/notmuch-new','notmuch-new',
+        u'incorporate new mail into the notmuch database',
+        [u'Carl Worth and many others'], 1),
+
+('man1/notmuch-reply','notmuch-reply',
+        u'constructs a reply template for a set of messages',
+        [u'Carl Worth and many others'], 1),
+
+('man1/notmuch-restore','notmuch-restore',
+        u'restores the tags from the given file (see notmuch dump)',
+        [u'Carl Worth and many others'], 1),
+
+('man1/notmuch-search','notmuch-search',
+        u'search for messages matching the given search terms',
+        [u'Carl Worth and many others'], 1),
+
+('man7/notmuch-search-terms','notmuch-search-terms',
+        u'syntax for notmuch queries',
+        [u'Carl Worth and many others'], 7),
+
+('man1/notmuch-show','notmuch-show',
+        u'show messages matching the given search terms',
+        [u'Carl Worth and many others'], 1),
+
+('man1/notmuch-tag','notmuch-tag',
+        u'add/remove tags for all messages matching the search terms',
+        [u'Carl Worth and many others'], 1),
+
+
+]
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+texinfo_no_detailmenu = True
+
+texinfo_documents = [
+ ('notmuch-emacs', 'notmuch-emacs', u'notmuch Documentation',
+   u'Carl Worth and many others', 'notmuch-emacs',
+   'emacs based front-end for notmuch', 'Miscellaneous'),
+('man1/notmuch','notmuch',u'notmuch Documentation',
+      u'Carl Worth and many others', 'notmuch',
+      'thread-based email index, search, and tagging','Miscellaneous'),
+('man1/notmuch-compact','notmuch-compact',u'notmuch Documentation',
+      u'Carl Worth and many others', 'notmuch-compact',
+      'compact the notmuch database','Miscellaneous'),
+('man1/notmuch-config','notmuch-config',u'notmuch Documentation',
+      u'Carl Worth and many others', 'notmuch-config',
+      'access notmuch configuration file','Miscellaneous'),
+('man1/notmuch-count','notmuch-count',u'notmuch Documentation',
+      u'Carl Worth and many others', 'notmuch-count',
+      'count messages matching the given search terms','Miscellaneous'),
+('man1/notmuch-dump','notmuch-dump',u'notmuch Documentation',
+      u'Carl Worth and many others', 'notmuch-dump',
+      'creates a plain-text dump of the tags of each message','Miscellaneous'),
+('man5/notmuch-hooks','notmuch-hooks',u'notmuch Documentation',
+      u'Carl Worth and many others', 'notmuch-hooks',
+      'hooks for notmuch','Miscellaneous'),
+('man1/notmuch-insert','notmuch-insert',u'notmuch Documentation',
+      u'Carl Worth and many others', 'notmuch-insert',
+      'add a message to the maildir and notmuch database','Miscellaneous'),
+('man1/notmuch-new','notmuch-new',u'notmuch Documentation',
+      u'Carl Worth and many others', 'notmuch-new',
+      'incorporate new mail into the notmuch database','Miscellaneous'),
+('man1/notmuch-reply','notmuch-reply',u'notmuch Documentation',
+      u'Carl Worth and many others', 'notmuch-reply',
+      'constructs a reply template for a set of messages','Miscellaneous'),
+('man1/notmuch-restore','notmuch-restore',u'notmuch Documentation',
+      u'Carl Worth and many others', 'notmuch-restore',
+      'restores the tags from the given file (see notmuch dump)','Miscellaneous'),
+('man1/notmuch-search','notmuch-search',u'notmuch Documentation',
+      u'Carl Worth and many others', 'notmuch-search',
+      'search for messages matching the given search terms','Miscellaneous'),
+('man7/notmuch-search-terms','notmuch-search-terms',u'notmuch Documentation',
+      u'Carl Worth and many others', 'notmuch-search-terms',
+      'syntax for notmuch queries','Miscellaneous'),
+('man1/notmuch-show','notmuch-show',u'notmuch Documentation',
+      u'Carl Worth and many others', 'notmuch-show',
+      'show messages matching the given search terms','Miscellaneous'),
+('man1/notmuch-tag','notmuch-tag',u'notmuch Documentation',
+      u'Carl Worth and many others', 'notmuch-tag',
+      'add/remove tags for all messages matching the search terms','Miscellaneous'),
+]
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 00000000..b33aa9fb
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,30 @@
+
+Welcome to notmuch's documentation!
+===================================
+
+Contents:
+
+.. toctree::
+   :titlesonly:
+
+   man1/notmuch
+   man1/notmuch-compact
+   man1/notmuch-config
+   man1/notmuch-count
+   man1/notmuch-dump
+   man5/notmuch-hooks
+   man1/notmuch-insert
+   man1/notmuch-new
+   man1/notmuch-reply
+   man1/notmuch-restore
+   man1/notmuch-search
+   man7/notmuch-search-terms
+   man1/notmuch-show
+   man1/notmuch-tag
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
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).
diff --git a/doc/man5/notmuch-hooks.rst b/doc/man5/notmuch-hooks.rst
new file mode 100644
index 00000000..493abf20
--- /dev/null
+++ b/doc/man5/notmuch-hooks.rst
@@ -0,0 +1,44 @@
+=============
+notmuch-hooks
+=============
+
+SYNOPSIS
+========
+
+	$DATABASEDIR/.notmuch/hooks/*
+
+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.
+
+    **pre-new**
+        This hook is invoked by the **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 **new** command.
+
+        Typically this hook is used for fetching or delivering new mail
+        to be imported into the database.
+
+    **post-new**
+        This hook is invoked by the **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.
+
+SEE ALSO
+========
+
+**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
+**notmuch-dump(1)**, **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/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst
new file mode 100644
index 00000000..20bc6f1e
--- /dev/null
+++ b/doc/man7/notmuch-search-terms.rst
@@ -0,0 +1,234 @@
+====================
+notmuch-search-terms
+====================
+
+SYNOPSIS
+========
+
+**notmuch** **count** [option ...] <*search-term*> ...
+
+**notmuch** **dump** [--format=(batch-tag|sup)] [--] [--output=<*file*>] [--] [<*search-term*> ...]
+
+**notmuch** **search** [option ...] <*search-term*> ...
+
+**notmuch** **show** [option ...] <*search-term*> ...
+
+**notmuch** **tag** +<*tag*> ... -<*tag*> [--] <*search-term*> ...
+
+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>
+
+-  date:<since>..<until>
+
+The **from:** prefix is used to match the name or address of the sender
+of an email message.
+
+The **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 **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
+**subject:**.
+
+The **attachment:** prefix can be used to search for specific filenames
+(or extensions) of attachments to email messages.
+
+For **tag:** and **is:** valid tag values include **inbox** and
+**unread** by default for new messages added by **notmuch new** as well
+as any other tag values added manually with **notmuch tag**.
+
+For **id:**, message ID values are the literal contents of the
+Message-ID: header of email messages, but without the '<', '>'
+delimiters.
+
+The **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
+**notmuch search**
+
+The **folder:** prefix can be used to search for email message files
+that are contained within particular directories within the mail store.
+If the same email message has multiple message files associated with it,
+it's sufficient for a match that at least one of the files is contained
+within a matching directory. Only the directory components below the
+top-level mail database path are available to be searched.
+
+The **date:** prefix can be used to restrict the results to only
+messages within a particular time range (based on the Date: header) with
+a range syntax of:
+
+date:<since>..<until>
+
+See **DATE AND TIME SEARCH** below for details on the range expression,
+and supported syntax for <since> and <until> date and time expressions.
+
+The time range can also be specified using timestamps 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.
+
+In addition to individual terms, multiple terms can be combined with
+Boolean operators ( **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).
+
+DATE AND TIME SEARCH
+====================
+
+notmuch understands a variety of standard and natural ways of expressing
+dates and times, both in absolute terms ("2012-10-24") and in relative
+terms ("yesterday"). Any number of relative terms can be combined ("1
+hour 25 minutes") and an absolute date/time can be combined with
+relative terms to further adjust it. A non-exhaustive description of the
+syntax supported for absolute and relative terms is given below.
+
+The range expression
+--------------------
+
+date:<since>..<until>
+
+The above expression restricts the results to only messages from <since>
+to <until>, based on the Date: header.
+
+<since> and <until> can describe imprecise times, such as "yesterday".
+In this case, <since> is taken as the earliest time it could describe
+(the beginning of yesterday) and <until> is taken as the latest time it
+could describe (the end of yesterday). Similarly, date:january..february
+matches from the beginning of January to the end of February.
+
+Currently, we do not support spaces in range expressions. You can
+replace the spaces with '\_', or (in most cases) '-', or (in some cases)
+leave the spaces out altogether. Examples in this man page use spaces
+for clarity.
+
+Open-ended ranges are supported (since Xapian 1.2.1), i.e. it's possible
+to specify date:..<until> or date:<since>.. to not limit the start or
+end time, respectively. Pre-1.2.1 Xapian does not report an error on
+open ended ranges, but it does not work as expected either.
+
+Entering date:expr without ".." (for example date:yesterday) won't work,
+as it's not interpreted as a range expression at all. You can achieve
+the expected result by duplicating the expr both sides of ".." (for
+example date:yesterday..yesterday).
+
+Relative date and time
+----------------------
+
+[N\|number]
+(years\|months\|weeks\|days\|hours\|hrs\|minutes\|mins\|seconds\|secs)
+[...]
+
+All refer to past, can be repeated and will be accumulated.
+
+Units can be abbreviated to any length, with the otherwise ambiguous
+single m being m for minutes and M for months.
+
+Number can also be written out one, two, ..., ten, dozen, hundred.
+Additionally, the unit may be preceded by "last" or "this" (e.g., "last
+week" or "this month").
+
+When combined with absolute date and time, the relative date and time
+specification will be relative from the specified absolute date and
+time.
+
+Examples: 5M2d, two weeks
+
+Supported absolute time formats
+-------------------------------
+
+-  H[H]:MM[:SS] [(am\|a.m.\|pm\|p.m.)]
+
+-  H[H] (am\|a.m.\|pm\|p.m.)
+
+-  HHMMSS
+
+-  now
+
+-  noon
+
+-  midnight
+
+-  Examples: 17:05, 5pm
+
+Supported absolute date formats
+-------------------------------
+
+-  YYYY-MM[-DD]
+
+-  DD-MM[-[YY]YY]
+
+-  MM-YYYY
+
+-  M[M]/D[D][/[YY]YY]
+
+-  M[M]/YYYY
+
+-  D[D].M[M][.[YY]YY]
+
+-  D[D][(st\|nd\|rd\|th)] Mon[thname] [YYYY]
+
+-  Mon[thname] D[D][(st\|nd\|rd\|th)] [YYYY]
+
+-  Wee[kday]
+
+Month names can be abbreviated at three or more characters.
+
+Weekday names can be abbreviated at three or more characters.
+
+Examples: 2012-07-31, 31-07-2012, 7/31/2012, August 3
+
+Time zones
+----------
+
+-  (+\|-)HH:MM
+
+-  (+\|-)HH[MM]
+
+Some time zone codes, e.g. UTC, EET.
+
+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-show(1)**, **notmuch-tag(1)**
diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
new file mode 100644
index 00000000..28301b3c
--- /dev/null
+++ b/doc/notmuch-emacs.rst
@@ -0,0 +1,192 @@
+=============
+notmuch-emacs
+=============
+
+About this Manual
+=================
+
+This manual covers only the emacs interface to notmuch. For information
+on the command line interface, see See section “Description” in Notmuch
+Manual Pager. To save typing, we will sometimes use *notmuch* in this
+manual to refer to the Emacs interface to notmuch. If the distinction
+should every be important, we’ll refer to the Emacs inteface as
+*notmuch-emacs*.
+
+Notmuch-emacs is highly customizable via the the Emacs customization
+framework (or just by setting the appropriate variables). We try to
+point out relevant variables in this manual, but in order to avoid
+duplication of information, but you can usually find the most detailed
+description in the varables docstring.
+
+notmuch-hello
+=============
+
+.. index::
+   single: notmuch-hello
+   single: notmuch
+
+``notmuch-hello`` is the main entry point for notmuch. You can start it
+with ``M-x notmuch`` or ``M-x notmuch-hello``. The startup screen looks
+something like the following. There are some hints at the bottom of the
+screen. There are three main parts to the notmuch-hello screen,
+discussed below. The **bold** text indicates buttons you can click with
+a mouse or by positioning the cursor and pressing ``<return>``
+
+|   Welcome to **notmuch** You have 52 messages.
+|
+| Saved searches: **[edit]**
+|
+|	  52 **inbox**           52 **unread**
+|
+| Search: ____________________________________
+|
+| All tags: **[show]**
+|
+|	 Type a search query and hit RET to view matching threads.
+|		Edit saved searches with the ``edit`` button.
+| Hit RET or click on a saved search or tag name to view matching threads.
+|     ``=`` to refresh this screen. ``s`` to search messages. ``q`` to quit.
+|		    **Customize** this page.
+
+You can change the overall appearence of the notmuch-hello screen by
+customizing the variable :index:`notmuch-hello-sections`.
+
+
+
+notmuch-hello key bindings
+--------------------------
+
+``<tab>``
+    Move to the next widget (button or text entry field)
+
+``<backtab>``
+    Move to the previous widget.
+
+``<return>``
+    Activate the current widget.
+
+``=``
+    Refresh the buffer; mainly update the counts of messages for various
+    saved searches.
+
+``G``
+    Import mail, See :ref:`importing`
+
+``m``
+    Compose a message
+
+``s``
+    Search the notmuch database using :ref:`notmuch-search`
+
+``v``
+    Print notmuch version
+
+``q``
+    Quit
+
+.. _saved-searches:
+
+Saved Searches
+--------------
+
+Notmuch replaces the static assignment of messages with the more dynamic
+notion of searching. Notmuch-hello presents the user with a customizable
+set of saved searchs. The initial defaults are ``tag:inbox`` and
+``tag:unread``, but you can customize the following variables
+
+:index:`notmuch-saved-searches`
+    A list of cons pairs, the first being the name to display, the
+    second being a query string for notmuch. See section “Description”
+    in Notmuch Query Syntax.
+
+:index:`notmuch-saved-searches-sort-function`
+    This variable controls how saved searches should be sorted. A value
+    of ``nil`` displays the saved searches in the order they are stored
+    in ‘notmuch-saved-searches’.
+
+:index:`notmuch-column-control`
+    Controls the number of columns for displaying saved-searches/tags
+
+Search Box
+----------
+
+The search box lets the user enter an notmuch query. See section
+“Description” in Notmuch Query Syntax, for more info on notmuch query
+syntax. A history of recent searches is also displayed by default. The
+latter is controlled by the variable :index:`notmuch-hello-recent-searches-max`.
+
+Known Tags
+----------
+
+One special kind of saved search provided by default is for each
+individual tag defined in the database. This can be controlled via the
+following variables.
+
+:index:`notmuch-hello-tag-list-make-query`
+    Control how to construct a search (“virtual folder”) from a given
+    tag.
+
+:index:`notmuch-hello-hide-tags`
+    Which tags not to display at all.
+
+:index:`notmuch-column-control`
+    Controls the number of columns for displaying saved-searches/tags
+
+.. _notmuch-search:
+
+notmuch-search
+==============
+
+``notmuch-search-mode`` is used to display the results from executing
+a query via ``notmuch-search``. The syntax for these queries is the
+the same as :ref:`saved-searches`. For details of this syntax see
+info:notmuch-search-terms
+
+By default the output approximates that of the command line See section
+“Description” in notmuch search command.
+
+The main purpose of the ``notmuch-search-mode`` buffer is to act as a
+menu of results that the user can explore further by pressing
+``<return>`` on the appropriate line.
+
+``n,C-n,<down>``
+    Move to next line
+
+``p,C-p,<up>``
+    Move to previous line
+
+``<return>``
+    Open thread on current line in :ref:`notmuch-show` mode
+
+``?``
+    Display full set of key bindings
+
+The presentation of results can be controlled by the following
+variables.
+
+:index:`notmuch-search-result-format`
+    Control how each thread of messages is presented in the
+    ``notmuch-show-mode`` buffer
+
+:index:`notmuch-search-oldest-first`
+    Display the oldest threads at the top of the buffer
+
+.. _notmuch-show:
+
+notmuch-show
+============
+
+notmuch-tree
+============
+
+Configuration
+=============
+
+.. _importing:
+
+Importing Mail
+--------------
+
+:index:`notmuch-poll`
+
+:index:`notmuch-poll-script`