[RFC Patch v3 1/3] doc: start of sphinx based docs
David Bremner
david at tethera.net
Sat Feb 22 16:16:13 PST 2014
This is the output from sphinx-quickstart, massaged a bit, along with
a man and texinfo pages all converted to rst.
---
Makefile | 2 +-
doc/Makefile | 5 +
doc/Makefile.local | 28 +++++
doc/conf.py | 166 ++++++++++++++++++++++++++++
doc/index.rst | 31 ++++++
doc/man1/notmuch-compact.rst | 52 +++++++++
doc/man1/notmuch-config.rst | 111 +++++++++++++++++++
doc/man1/notmuch-count.rst | 60 ++++++++++
doc/man1/notmuch-dump.rst | 72 ++++++++++++
doc/man1/notmuch-insert.rst | 57 ++++++++++
doc/man1/notmuch-new.rst | 51 +++++++++
doc/man1/notmuch-reply.rst | 112 +++++++++++++++++++
doc/man1/notmuch-restore.rst | 58 ++++++++++
doc/man1/notmuch-search.rst | 146 +++++++++++++++++++++++++
doc/man1/notmuch-show.rst | 180 ++++++++++++++++++++++++++++++
doc/man1/notmuch-tag.rst | 105 ++++++++++++++++++
doc/man1/notmuch.rst | 143 ++++++++++++++++++++++++
doc/man5/notmuch-hooks.rst | 42 +++++++
doc/man7/notmuch-search-terms.rst | 225 ++++++++++++++++++++++++++++++++++++++
doc/notmuch-emacs.rst | 192 ++++++++++++++++++++++++++++++++
20 files changed, 1837 insertions(+), 1 deletion(-)
create mode 100644 doc/Makefile
create mode 100644 doc/Makefile.local
create mode 100644 doc/conf.py
create mode 100644 doc/index.rst
create mode 100644 doc/man1/notmuch-compact.rst
create mode 100644 doc/man1/notmuch-config.rst
create mode 100644 doc/man1/notmuch-count.rst
create mode 100644 doc/man1/notmuch-dump.rst
create mode 100644 doc/man1/notmuch-insert.rst
create mode 100644 doc/man1/notmuch-new.rst
create mode 100644 doc/man1/notmuch-reply.rst
create mode 100644 doc/man1/notmuch-restore.rst
create mode 100644 doc/man1/notmuch-search.rst
create mode 100644 doc/man1/notmuch-show.rst
create mode 100644 doc/man1/notmuch-tag.rst
create mode 100644 doc/man1/notmuch.rst
create mode 100644 doc/man5/notmuch-hooks.rst
create mode 100644 doc/man7/notmuch-search-terms.rst
create mode 100644 doc/notmuch-emacs.rst
diff --git a/Makefile b/Makefile
index 0428160..39f0e62 100644
--- a/Makefile
+++ b/Makefile
@@ -5,7 +5,7 @@ all:
# List all subdirectories here. Each contains its own Makefile.local.
# Use of '=', without '+=', seems to be required for out-of-tree
# builds to work.
-subdirs = compat completion emacs lib man parse-time-string performance-test util test
+subdirs = compat completion doc emacs lib man parse-time-string performance-test util test
# We make all targets depend on the Makefiles themselves.
global_deps = Makefile Makefile.config Makefile.local \
diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..fa25832
--- /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 0000000..d2a339b
--- /dev/null
+++ b/doc/Makefile.local
@@ -0,0 +1,28 @@
+# Makefile for Sphinx documentation
+#
+
+dir := doc
+
+# You can set these variables from the command line.
+SPHINXOPTS := -q -c $(dir)
+SPHINXBUILD = sphinx-build
+BUILDDIR := $(dir)/_build
+
+# Internal variables.
+ALLSPHINXOPTS := -d $(BUILDDIR)/doctrees $(SPHINXOPTS) $(dir)
+
+.PHONY: help clean html man texinfo info
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+
+texinfo:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+
+info: texinfo
+ make -C $(BUILDDIR)/texinfo info
+
+CLEAN := $(CLEAN) $(dir)/_build
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 0000000..d80b2af
--- /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']
+
+# 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 0000000..deac9f4
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,31 @@
+
+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
+ notmuch-emacs
+
+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 0000000..aeabd16
--- /dev/null
+++ b/doc/man1/notmuch-compact.rst
@@ -0,0 +1,52 @@
+===============
+notmuch-compact
+===============
+
+SYNOPSIS
+========
+
+**notmuch** **compact** [--quiet] [--backup=]
+
+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 0000000..50c9e7e
--- /dev/null
+++ b/doc/man1/notmuch-config.rst
@@ -0,0 +1,111 @@
+==============
+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 0000000..9165207
--- /dev/null
+++ b/doc/man1/notmuch-count.rst
@@ -0,0 +1,60 @@
+=============
+notmuch-count
+=============
+
+SYNOPSIS
+========
+
+**notmuch** **count** [options ...] **<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 0000000..018faf1
--- /dev/null
+++ b/doc/man1/notmuch-dump.rst
@@ -0,0 +1,72 @@
+============
+notmuch-dump
+============
+
+SYNOPSIS
+========
+
+**notmuch** **dump** **--format=** **batch-tag)** [--] [--output=] [--] [<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 0000000..18591b3
--- /dev/null
+++ b/doc/man1/notmuch-insert.rst
@@ -0,0 +1,57 @@
+==============
+notmuch-insert
+==============
+
+SYNOPSIS
+========
+
+**notmuch** **insert** [options] **+<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 0000000..949af4d
--- /dev/null
+++ b/doc/man1/notmuch-new.rst
@@ -0,0 +1,51 @@
+===========
+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 0000000..7575071
--- /dev/null
+++ b/doc/man1/notmuch-reply.rst
@@ -0,0 +1,112 @@
+=============
+notmuch-reply
+=============
+
+SYNOPSIS
+========
+
+**notmuch** **reply** [options ...] **<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 0000000..ec1cb6c
--- /dev/null
+++ b/doc/man1/notmuch-restore.rst
@@ -0,0 +1,58 @@
+===============
+notmuch-restore
+===============
+
+SYNOPSIS
+========
+
+**notmuch** **restore** [--accumulate] **--format=** **batch-tag** **sup)** [--input=]
+
+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 0000000..8ac580e
--- /dev/null
+++ b/doc/man1/notmuch-search.rst
@@ -0,0 +1,146 @@
+==============
+notmuch-search
+==============
+
+SYNOPSIS
+========
+
+**notmuch** **search** [options ...] **<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 0000000..5d9837c
--- /dev/null
+++ b/doc/man1/notmuch-show.rst
@@ -0,0 +1,180 @@
+============
+notmuch-show
+============
+
+SYNOPSIS
+========
+
+**notmuch** **show** [options ...] **<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:
+
+ ::
+
+
+
+ *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 0000000..548c7aa
--- /dev/null
+++ b/doc/man1/notmuch-tag.rst
@@ -0,0 +1,105 @@
+===========
+notmuch-tag
+===========
+
+SYNOPSIS
+========
+
+**notmuch** **tag** [options ...] **+<tag>** **-<tag>** [--] **<search-term>** **.[..]** **notmuch** **tag** **--batch** [--input=]
+
+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 0000000..ac728af
--- /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 at 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 0000000..5a055eb
--- /dev/null
+++ b/doc/man5/notmuch-hooks.rst
@@ -0,0 +1,42 @@
+=============
+notmuch-hooks
+=============
+
+SYNOPSIS
+========
+
+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 0000000..37095d7
--- /dev/null
+++ b/doc/man7/notmuch-search-terms.rst
@@ -0,0 +1,225 @@
+====================
+notmuch-search-terms
+====================
+
+SYNOPSIS
+========
+
+**notmuch** **count** [options ...] **<search-term> ...**
+
+**notmuch** **dump** [<filename>] [--] [<search-term> ...]
+
+**notmuch** **search** [options ...] **<search-term> ...**
+
+**notmuch** **show** [options ...] **<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 0000000..28301b3
--- /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`
--
1.8.5.3
More information about the notmuch
mailing list