* [Patch v3 1/4] doc: convert sphinx based docs
2014-03-09 12:56 sphinx docs, v3 David Bremner
@ 2014-03-09 12:56 ` David Bremner
2014-03-09 12:56 ` [Patch v3 2/4] doc: add target rst2man to build man pages using rst2man David Bremner
` (3 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: David Bremner @ 2014-03-09 12:56 UTC (permalink / raw)
To: notmuch
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.
---
INSTALL | 18 ++-
Makefile | 2 +-
debian/control | 1 +
doc/.gitignore | 2 +
doc/INSTALL | 24 ++++
doc/Makefile | 5 +
doc/Makefile.local | 27 +++++
doc/conf.py | 166 +++++++++++++++++++++++++++
doc/index.rst | 30 +++++
doc/man1/notmuch-compact.rst | 52 +++++++++
doc/man1/notmuch-config.rst | 123 ++++++++++++++++++++
doc/man1/notmuch-count.rst | 60 ++++++++++
doc/man1/notmuch-dump.rst | 72 ++++++++++++
doc/man1/notmuch-insert.rst | 58 ++++++++++
doc/man1/notmuch-new.rst | 52 +++++++++
doc/man1/notmuch-reply.rst | 112 ++++++++++++++++++
doc/man1/notmuch-restore.rst | 59 ++++++++++
doc/man1/notmuch-search.rst | 146 ++++++++++++++++++++++++
doc/man1/notmuch-show.rst | 179 +++++++++++++++++++++++++++++
doc/man1/notmuch-tag.rst | 107 +++++++++++++++++
doc/man1/notmuch.rst | 143 +++++++++++++++++++++++
doc/man5/notmuch-hooks.rst | 44 +++++++
doc/man7/notmuch-search-terms.rst | 234 ++++++++++++++++++++++++++++++++++++++
doc/notmuch-emacs.rst | 192 +++++++++++++++++++++++++++++++
24 files changed, 1905 insertions(+), 3 deletions(-)
create mode 100644 doc/.gitignore
create mode 100644 doc/INSTALL
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/INSTALL b/INSTALL
index fce9352..690b0ef 100644
--- a/INSTALL
+++ b/INSTALL
@@ -60,16 +60,30 @@ Talloc which are each described below:
Talloc is available from http://talloc.samba.org/
+Building Documentation
+----------------------
+
+By default the documentation for notmuch is built using sphinx.
+
+Sphinx is available from www.sphinx-doc.org.
+
+If you prefer, you can build the man pages using rst2man, from the
+python docutils package. See doc/INSTALL for details.
+
+
+Installing Dependencies from Packages
+-------------------------------------
+
On a modern, package-based operating system you can install all of the
dependencies with a simple simple command line. For example:
For Debian and similar:
- sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev
+ sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev python-sphinx
For Fedora and similar:
- sudo yum install xapian-core-devel gmime-devel libtalloc-devel
+ sudo yum install xapian-core-devel gmime-devel libtalloc-devel python-sphinx
On other systems, a similar command can be used, but the details of
the package names may be different.
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/debian/control b/debian/control
index c5475c4..8d8e938 100644
--- a/debian/control
+++ b/debian/control
@@ -15,6 +15,7 @@ Build-Depends:
libz-dev,
python-all (>= 2.6.6-3~),
python3-all (>= 3.1.2-7~),
+ python-sphinx (>= 1.0),
ruby, ruby-dev (>>1:1.9.3~),
emacs23-nox | emacs23 (>=23~) | emacs23-lucid (>=23~) |
emacs24-nox | emacs24 (>=24~) | emacs24-lucid (>=24~),
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 0000000..a60fb31
--- /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 0000000..e37c2b9
--- /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 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..ec23012
--- /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 0000000..6c2806d
--- /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 0000000..b33aa9f
--- /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 0000000..e0109dc
--- /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 0000000..3c9a568
--- /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 0000000..ca78c18
--- /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 0000000..17d1da5
--- /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 0000000..2be1a7b
--- /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 0000000..d11fcee
--- /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 0000000..cfbd4ea
--- /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 0000000..d6cf19a
--- /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 0000000..7ac6c68
--- /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 0000000..bad868b
--- /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 0000000..2e7e1d3
--- /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 0000000..9710294
--- /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 0000000..493abf2
--- /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 0000000..20bc6f1
--- /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 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
^ permalink raw reply related [flat|nested] 6+ messages in thread