[RFC Patch] start of sphinx based docs

* [RFC Patch] start of sphinx based docs
@ 2014-01-18 16:00 David Bremner
  2014-01-19 13:48 ` Tomi Ollila
  0 siblings, 1 reply; 39+ messages in thread
From: David Bremner @ 2014-01-18 16:00 UTC (permalink / raw)
  To: notmuch

---

here is quick and dirty start a sphinx based docs.
This has the advantage that everything is in rst, no mixed formats.

things you might try, after installing sphinx (only tested with 1.2)

% make -C doc man

% make -C doc info

% man -l doc/_build/man/notmuch-search.1

% info -f doc/_build/texinfo/notmuch-emacs.info

 doc/Makefile                 | 177 ++++++++++++++++++++++++++++
 doc/conf.py                  | 272 +++++++++++++++++++++++++++++++++++++++++++
 doc/index.rst                |  24 ++++
 doc/notmuch-emacs.rst        | 188 ++++++++++++++++++++++++++++++
 doc/notmuch-search-terms.rst | 255 ++++++++++++++++++++++++++++++++++++++++
 doc/notmuch-search.rst       | 203 ++++++++++++++++++++++++++++++++
 doc/notmuch.rst              | 173 +++++++++++++++++++++++++++
 7 files changed, 1292 insertions(+)
 create mode 100644 doc/Makefile
 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/doc/Makefile b/doc/Makefile
new file mode 100644
index 0000000..906268c
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,177 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/notmuch.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/notmuch.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/notmuch"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/notmuch"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 0000000..d9f7b22
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,272 @@
+# -*- coding: utf-8 -*-
+#
+# notmuch documentation build configuration file, created by
+# sphinx-quickstart on Fri Jan 17 22:34:14 2014.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# 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 encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'notmuch'
+copyright = u'2014, Carl Worth and many others'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.17'
+# The full version, including alpha/beta/rc tags.
+release = '0.17'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+
+# -- 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'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# 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']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'notmuchdoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+  ('index', 'notmuch.tex', u'notmuch Documentation',
+   u'Carl Worth and many others', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- 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'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# 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

^ permalink raw reply related	[flat|nested] 39+ messages in thread