From: David Bremner <david@tethera.net>
To: notmuch@notmuchmail.org
Subject: [RFC Patch v2 1/2] doc: start of sphinx based docs
Date: Tue, 28 Jan 2014 12:12:37 -0400
Message-Id: <1390925558-15873-2-git-send-email-david@tethera.net>
In-Reply-To: <1390925558-15873-1-git-send-email-david@tethera.net>
References: <87vbxfkdex.fsf@zancas.localnet>
	<1390925558-15873-1-git-send-email-david@tethera.net>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Precedence: list

This is the output from sphinx-quickstart, massaged a bit, along with
a few sample docs converted to rst.
---
 Makefile                     |   2 +-
 doc/Makefile                 |   5 +
 doc/Makefile.local           |  28 +++++
 doc/conf.py                  |  91 +++++++++++++++
 doc/index.rst                |  24 ++++
 doc/notmuch-emacs.rst        | 188 +++++++++++++++++++++++++++++++
 doc/notmuch-search-terms.rst | 255 +++++++++++++++++++++++++++++++++++++++++++
 doc/notmuch-search.rst       | 203 ++++++++++++++++++++++++++++++++++
 doc/notmuch.rst              | 173 +++++++++++++++++++++++++++++
 9 files changed, 968 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/notmuch-emacs.rst
 create mode 100644 doc/notmuch-search-terms.rst
 create mode 100644 doc/notmuch-search.rst
 create mode 100644 doc/notmuch.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..9170920
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,91 @@
+# -*- coding: utf-8 -*-
+
+import sys
+import os
+
+# -- General configuration ------------------------------------------------
+#
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# 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 = [
+    ('notmuch', 'notmuch', u'thread-based email index, search, and tagging',
+     [u'Carl Worth and many others'], 1),
+    ('notmuch-search', 'notmuch-search', u'search the notmuch mail index',
+     [u'Carl Worth and many others'], 1),
+    ('notmuch-search-terms', 'notmuch-search-terms', u'query format for notmuch',
+     [u'Carl Worth and many others'], 7),
+
+]
+
+# 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)
+texinfo_documents = [
+  ('notmuch', 'notmuch', u'notmuch Documentation',
+   u'Carl Worth and many others', 'notmuch', 'thread-based email index, search and tagging',
+   'Miscellaneous'),
+  ('notmuch-emacs', 'notmuch-emacs', u'notmuch Documentation',
+   u'Carl Worth and many others', 'notmuch-emacs', 'emacs based front-end for notmuch',
+   'Miscellaneous'),
+  ('notmuch-search', 'notmuch-search', u'notmuch Documentation',
+   u'Carl Worth and many others', 'notmuch-search', 'search the notmuch mail index.',
+   'Miscellaneous'),
+  ('notmuch-search-terms', 'notmuch-search-terms', u'notmuch Documentation',
+   u'Carl Worth and many others', 'notmuch-search-terms', 'query syntax for notmuch.',
+   'Miscellaneous'),
+]
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+texinfo_no_detailmenu = True
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 0000000..c05c855
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,24 @@
+.. notmuch documentation master file, created by
+   sphinx-quickstart on Fri Jan 17 22:34:14 2014.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to notmuch's documentation!
+===================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   notmuch
+   notmuch-emacs
+   notmuch-search
+   notmuch-search-terms
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
new file mode 100644
index 0000000..283bf69
--- /dev/null
+++ b/doc/notmuch-emacs.rst
@@ -0,0 +1,188 @@
+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`
diff --git a/doc/notmuch-search-terms.rst b/doc/notmuch-search-terms.rst
new file mode 100644
index 0000000..7885c6a
--- /dev/null
+++ b/doc/notmuch-search-terms.rst
@@ -0,0 +1,255 @@
+====================
+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-search.rst b/doc/notmuch-search.rst
new file mode 100644
index 0000000..deb7e8b
--- /dev/null
+++ b/doc/notmuch-search.rst
@@ -0,0 +1,203 @@
+==============
+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), notmuchtag(1)
diff --git a/doc/notmuch.rst b/doc/notmuch.rst
new file mode 100644
index 0000000..9d9a35c
--- /dev/null
+++ b/doc/notmuch.rst
@@ -0,0 +1,173 @@
+========
+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 int 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).
-- 
1.8.5.2