27/9b185d808c67ed7cec556ada39023a168c0b7a

   1 Return-Path: <bremner@tethera.net>\r
   2 X-Original-To: notmuch@notmuchmail.org\r
   3 Delivered-To: notmuch@notmuchmail.org\r
   4 Received: from localhost (localhost [127.0.0.1])\r
   5         by olra.theworths.org (Postfix) with ESMTP id 3CDB6431FC2\r
   6         for <notmuch@notmuchmail.org>; Tue, 28 Jan 2014 08:13:11 -0800 (PST)\r
   7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
   8 X-Spam-Flag: NO\r
   9 X-Spam-Score: 0\r
  10 X-Spam-Level: \r
  11 X-Spam-Status: No, score=0 tagged_above=-999 required=5 tests=[none]\r
  12         autolearn=disabled\r
  13 Received: from olra.theworths.org ([127.0.0.1])\r
  14         by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
  15         with ESMTP id E3+TXQpA2J9q for <notmuch@notmuchmail.org>;\r
  16         Tue, 28 Jan 2014 08:13:06 -0800 (PST)\r
  17 Received: from yantan.tethera.net (yantan.tethera.net [199.188.72.155])\r
  18         (using TLSv1 with cipher DHE-RSA-AES128-SHA (128/128 bits))\r
  19         (No client certificate requested)\r
  20         by olra.theworths.org (Postfix) with ESMTPS id 3E400431FBF\r
  21         for <notmuch@notmuchmail.org>; Tue, 28 Jan 2014 08:13:06 -0800 (PST)\r
  22 Received: from remotemail by yantan.tethera.net with local (Exim 4.80)\r
  23         (envelope-from <bremner@tethera.net>)\r
  24         id 1W8BHY-000369-Fh; Tue, 28 Jan 2014 12:13:00 -0400\r
  25 Received: (nullmailer pid 15962 invoked by uid 1000); Tue, 28 Jan 2014\r
  26         16:12:53 -0000\r
  27 From: David Bremner <david@tethera.net>\r
  28 To: notmuch@notmuchmail.org\r
  29 Subject: [RFC Patch v2 1/2] doc: start of sphinx based docs\r
  30 Date: Tue, 28 Jan 2014 12:12:37 -0400\r
  31 Message-Id: <1390925558-15873-2-git-send-email-david@tethera.net>\r
  32 X-Mailer: git-send-email 1.8.5.2\r
  33 In-Reply-To: <1390925558-15873-1-git-send-email-david@tethera.net>\r
  34 References: <87vbxfkdex.fsf@zancas.localnet>\r
  35         <1390925558-15873-1-git-send-email-david@tethera.net>\r
  36 MIME-Version: 1.0\r
  37 Content-Type: text/plain; charset=UTF-8\r
  38 Content-Transfer-Encoding: 8bit\r
  39 X-BeenThere: notmuch@notmuchmail.org\r
  40 X-Mailman-Version: 2.1.13\r
  41 Precedence: list\r
  42 List-Id: "Use and development of the notmuch mail system."\r
  43         <notmuch.notmuchmail.org>\r
  44 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  45         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  46 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  47 List-Post: <mailto:notmuch@notmuchmail.org>\r
  48 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  49 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  50         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  51 X-List-Received-Date: Tue, 28 Jan 2014 16:13:11 -0000\r
  52 \r
  53 This is the output from sphinx-quickstart, massaged a bit, along with\r
  54 a few sample docs converted to rst.\r
  55 ---\r
  56  Makefile                     |   2 +-\r
  57  doc/Makefile                 |   5 +\r
  58  doc/Makefile.local           |  28 +++++\r
  59  doc/conf.py                  |  91 +++++++++++++++\r
  60  doc/index.rst                |  24 ++++\r
  61  doc/notmuch-emacs.rst        | 188 +++++++++++++++++++++++++++++++\r
  62  doc/notmuch-search-terms.rst | 255 +++++++++++++++++++++++++++++++++++++++++++\r
  63  doc/notmuch-search.rst       | 203 ++++++++++++++++++++++++++++++++++\r
  64  doc/notmuch.rst              | 173 +++++++++++++++++++++++++++++\r
  65  9 files changed, 968 insertions(+), 1 deletion(-)\r
  66  create mode 100644 doc/Makefile\r
  67  create mode 100644 doc/Makefile.local\r
  68  create mode 100644 doc/conf.py\r
  69  create mode 100644 doc/index.rst\r
  70  create mode 100644 doc/notmuch-emacs.rst\r
  71  create mode 100644 doc/notmuch-search-terms.rst\r
  72  create mode 100644 doc/notmuch-search.rst\r
  73  create mode 100644 doc/notmuch.rst\r
  74 \r
  75 diff --git a/Makefile b/Makefile\r
  76 index 0428160..39f0e62 100644\r
  77 --- a/Makefile\r
  78 +++ b/Makefile\r
  79 @@ -5,7 +5,7 @@ all:\r
  80  # List all subdirectories here. Each contains its own Makefile.local.\r
  81  # Use of '=', without '+=', seems to be required for out-of-tree\r
  82  # builds to work.\r
  83 -subdirs = compat completion emacs lib man parse-time-string performance-test util test\r
  84 +subdirs = compat completion doc emacs lib man parse-time-string performance-test util test\r
  85  \r
  86  # We make all targets depend on the Makefiles themselves.\r
  87  global_deps = Makefile Makefile.config Makefile.local \\r
  88 diff --git a/doc/Makefile b/doc/Makefile\r
  89 new file mode 100644\r
  90 index 0000000..fa25832\r
  91 --- /dev/null\r
  92 +++ b/doc/Makefile\r
  93 @@ -0,0 +1,5 @@\r
  94 +all:\r
  95 +       $(MAKE) -C .. all\r
  96 +\r
  97 +.DEFAULT:\r
  98 +       $(MAKE) -C .. $@\r
  99 diff --git a/doc/Makefile.local b/doc/Makefile.local\r
 100 new file mode 100644\r
 101 index 0000000..d2a339b\r
 102 --- /dev/null\r
 103 +++ b/doc/Makefile.local\r
 104 @@ -0,0 +1,28 @@\r
 105 +# Makefile for Sphinx documentation\r
 106 +#\r
 107 +\r
 108 +dir := doc\r
 109 +\r
 110 +# You can set these variables from the command line.\r
 111 +SPHINXOPTS    := -q -c $(dir)\r
 112 +SPHINXBUILD   = sphinx-build\r
 113 +BUILDDIR      := $(dir)/_build\r
 114 +\r
 115 +# Internal variables.\r
 116 +ALLSPHINXOPTS   := -d $(BUILDDIR)/doctrees $(SPHINXOPTS) $(dir)\r
 117 +\r
 118 +.PHONY: help clean html man texinfo info\r
 119 +\r
 120 +html:\r
 121 +       $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html\r
 122 +\r
 123 +man:\r
 124 +       $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man\r
 125 +\r
 126 +texinfo:\r
 127 +       $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo\r
 128 +\r
 129 +info: texinfo\r
 130 +       make -C $(BUILDDIR)/texinfo info\r
 131 +\r
 132 +CLEAN := $(CLEAN) $(dir)/_build\r
 133 diff --git a/doc/conf.py b/doc/conf.py\r
 134 new file mode 100644\r
 135 index 0000000..9170920\r
 136 --- /dev/null\r
 137 +++ b/doc/conf.py\r
 138 @@ -0,0 +1,91 @@\r
 139 +# -*- coding: utf-8 -*-\r
 140 +\r
 141 +import sys\r
 142 +import os\r
 143 +\r
 144 +# -- General configuration ------------------------------------------------\r
 145 +#\r
 146 +# Add any Sphinx extension module names here, as strings. They can be\r
 147 +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom\r
 148 +# ones.\r
 149 +extensions = []\r
 150 +\r
 151 +# Add any paths that contain templates here, relative to this directory.\r
 152 +templates_path = ['_templates']\r
 153 +\r
 154 +# The suffix of source filenames.\r
 155 +source_suffix = '.rst'\r
 156 +\r
 157 +# The master toctree document.\r
 158 +master_doc = 'index'\r
 159 +\r
 160 +# General information about the project.\r
 161 +project = u'notmuch'\r
 162 +copyright = u'2014, Carl Worth and many others'\r
 163 +\r
 164 +# The short X.Y version.\r
 165 +version = '0.17'\r
 166 +# The full version, including alpha/beta/rc tags.\r
 167 +release = '0.17'\r
 168 +\r
 169 +# List of patterns, relative to source directory, that match files and\r
 170 +# directories to ignore when looking for source files.\r
 171 +exclude_patterns = ['_build']\r
 172 +\r
 173 +# The name of the Pygments (syntax highlighting) style to use.\r
 174 +pygments_style = 'sphinx'\r
 175 +\r
 176 +# -- Options for HTML output ----------------------------------------------\r
 177 +\r
 178 +# The theme to use for HTML and HTML Help pages.  See the documentation for\r
 179 +# a list of builtin themes.\r
 180 +html_theme = 'default'\r
 181 +\r
 182 +\r
 183 +# Add any paths that contain custom static files (such as style sheets) here,\r
 184 +# relative to this directory. They are copied after the builtin static files,\r
 185 +# so a file named "default.css" will overwrite the builtin "default.css".\r
 186 +html_static_path = ['_static']\r
 187 +\r
 188 +# Output file base name for HTML help builder.\r
 189 +htmlhelp_basename = 'notmuchdoc'\r
 190 +\r
 191 +# -- Options for manual page output ---------------------------------------\r
 192 +\r
 193 +# One entry per manual page. List of tuples\r
 194 +# (source start file, name, description, authors, manual section).\r
 195 +man_pages = [\r
 196 +    ('notmuch', 'notmuch', u'thread-based email index, search, and tagging',\r
 197 +     [u'Carl Worth and many others'], 1),\r
 198 +    ('notmuch-search', 'notmuch-search', u'search the notmuch mail index',\r
 199 +     [u'Carl Worth and many others'], 1),\r
 200 +    ('notmuch-search-terms', 'notmuch-search-terms', u'query format for notmuch',\r
 201 +     [u'Carl Worth and many others'], 7),\r
 202 +\r
 203 +]\r
 204 +\r
 205 +# If true, show URL addresses after external links.\r
 206 +#man_show_urls = False\r
 207 +\r
 208 +# -- Options for Texinfo output -------------------------------------------\r
 209 +\r
 210 +# Grouping the document tree into Texinfo files. List of tuples\r
 211 +# (source start file, target name, title, author,\r
 212 +#  dir menu entry, description, category)\r
 213 +texinfo_documents = [\r
 214 +  ('notmuch', 'notmuch', u'notmuch Documentation',\r
 215 +   u'Carl Worth and many others', 'notmuch', 'thread-based email index, search and tagging',\r
 216 +   'Miscellaneous'),\r
 217 +  ('notmuch-emacs', 'notmuch-emacs', u'notmuch Documentation',\r
 218 +   u'Carl Worth and many others', 'notmuch-emacs', 'emacs based front-end for notmuch',\r
 219 +   'Miscellaneous'),\r
 220 +  ('notmuch-search', 'notmuch-search', u'notmuch Documentation',\r
 221 +   u'Carl Worth and many others', 'notmuch-search', 'search the notmuch mail index.',\r
 222 +   'Miscellaneous'),\r
 223 +  ('notmuch-search-terms', 'notmuch-search-terms', u'notmuch Documentation',\r
 224 +   u'Carl Worth and many others', 'notmuch-search-terms', 'query syntax for notmuch.',\r
 225 +   'Miscellaneous'),\r
 226 +]\r
 227 +\r
 228 +# If true, do not generate a @detailmenu in the "Top" node's menu.\r
 229 +texinfo_no_detailmenu = True\r
 230 diff --git a/doc/index.rst b/doc/index.rst\r
 231 new file mode 100644\r
 232 index 0000000..c05c855\r
 233 --- /dev/null\r
 234 +++ b/doc/index.rst\r
 235 @@ -0,0 +1,24 @@\r
 236 +.. notmuch documentation master file, created by\r
 237 +   sphinx-quickstart on Fri Jan 17 22:34:14 2014.\r
 238 +   You can adapt this file completely to your liking, but it should at least\r
 239 +   contain the root `toctree` directive.\r
 240 +\r
 241 +Welcome to notmuch's documentation!\r
 242 +===================================\r
 243 +\r
 244 +Contents:\r
 245 +\r
 246 +.. toctree::\r
 247 +   :maxdepth: 2\r
 248 +\r
 249 +   notmuch\r
 250 +   notmuch-emacs\r
 251 +   notmuch-search\r
 252 +   notmuch-search-terms\r
 253 +\r
 254 +Indices and tables\r
 255 +==================\r
 256 +\r
 257 +* :ref:`genindex`\r
 258 +* :ref:`modindex`\r
 259 +* :ref:`search`\r
 260 diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst\r
 261 new file mode 100644\r
 262 index 0000000..283bf69\r
 263 --- /dev/null\r
 264 +++ b/doc/notmuch-emacs.rst\r
 265 @@ -0,0 +1,188 @@\r
 266 +About this Manual\r
 267 +=================\r
 268 +\r
 269 +This manual covers only the emacs interface to notmuch. For information\r
 270 +on the command line interface, see See section “Description” in Notmuch\r
 271 +Manual Pager. To save typing, we will sometimes use *notmuch* in this\r
 272 +manual to refer to the Emacs interface to notmuch. If the distinction\r
 273 +should every be important, we’ll refer to the Emacs inteface as\r
 274 +*notmuch-emacs*.\r
 275 +\r
 276 +Notmuch-emacs is highly customizable via the the Emacs customization\r
 277 +framework (or just by setting the appropriate variables). We try to\r
 278 +point out relevant variables in this manual, but in order to avoid\r
 279 +duplication of information, but you can usually find the most detailed\r
 280 +description in the varables docstring.\r
 281 +\r
 282 +notmuch-hello\r
 283 +=============\r
 284 +\r
 285 +.. index::\r
 286 +   single: notmuch-hello\r
 287 +   single: notmuch\r
 288 +\r
 289 +``notmuch-hello`` is the main entry point for notmuch. You can start it\r
 290 +with ``M-x notmuch`` or ``M-x notmuch-hello``. The startup screen looks\r
 291 +something like the following. There are some hints at the bottom of the\r
 292 +screen. There are three main parts to the notmuch-hello screen,\r
 293 +discussed below. The **bold** text indicates buttons you can click with\r
 294 +a mouse or by positioning the cursor and pressing ``<return>``\r
 295 +\r
 296 +|   Welcome to **notmuch** You have 52 messages.\r
 297 +|\r
 298 +| Saved searches: **[edit]**\r
 299 +|\r
 300 +|        52 **inbox**           52 **unread**\r
 301 +|\r
 302 +| Search: ____________________________________\r
 303 +|\r
 304 +| All tags: **[show]**\r
 305 +|\r
 306 +|       Type a search query and hit RET to view matching threads.\r
 307 +|              Edit saved searches with the ``edit`` button.\r
 308 +| Hit RET or click on a saved search or tag name to view matching threads.\r
 309 +|     ``=`` to refresh this screen. ``s`` to search messages. ``q`` to quit.\r
 310 +|                  **Customize** this page.\r
 311 +\r
 312 +You can change the overall appearence of the notmuch-hello screen by\r
 313 +customizing the variable :index:`notmuch-hello-sections`.\r
 314 +\r
 315 +\r
 316 +\r
 317 +notmuch-hello key bindings\r
 318 +--------------------------\r
 319 +\r
 320 +``<tab>``\r
 321 +    Move to the next widget (button or text entry field)\r
 322 +\r
 323 +``<backtab>``\r
 324 +    Move to the previous widget.\r
 325 +\r
 326 +``<return>``\r
 327 +    Activate the current widget.\r
 328 +\r
 329 +``=``\r
 330 +    Refresh the buffer; mainly update the counts of messages for various\r
 331 +    saved searches.\r
 332 +\r
 333 +``G``\r
 334 +    Import mail, See :ref:`importing`\r
 335 +\r
 336 +``m``\r
 337 +    Compose a message\r
 338 +\r
 339 +``s``\r
 340 +    Search the notmuch database using :ref:`notmuch-search`\r
 341 +\r
 342 +``v``\r
 343 +    Print notmuch version\r
 344 +\r
 345 +``q``\r
 346 +    Quit\r
 347 +\r
 348 +.. _saved-searches:\r
 349 +\r
 350 +Saved Searches\r
 351 +--------------\r
 352 +\r
 353 +Notmuch replaces the static assignment of messages with the more dynamic\r
 354 +notion of searching. Notmuch-hello presents the user with a customizable\r
 355 +set of saved searchs. The initial defaults are ``tag:inbox`` and\r
 356 +``tag:unread``, but you can customize the following variables\r
 357 +\r
 358 +:index:`notmuch-saved-searches`\r
 359 +    A list of cons pairs, the first being the name to display, the\r
 360 +    second being a query string for notmuch. See section “Description”\r
 361 +    in Notmuch Query Syntax.\r
 362 +\r
 363 +:index:`notmuch-saved-searches-sort-function`\r
 364 +    This variable controls how saved searches should be sorted. A value\r
 365 +    of ``nil`` displays the saved searches in the order they are stored\r
 366 +    in ‘notmuch-saved-searches’.\r
 367 +\r
 368 +:index:`notmuch-column-control`\r
 369 +    Controls the number of columns for displaying saved-searches/tags\r
 370 +\r
 371 +Search Box\r
 372 +----------\r
 373 +\r
 374 +The search box lets the user enter an notmuch query. See section\r
 375 +“Description” in Notmuch Query Syntax, for more info on notmuch query\r
 376 +syntax. A history of recent searches is also displayed by default. The\r
 377 +latter is controlled by the variable :index:`notmuch-hello-recent-searches-max`.\r
 378 +\r
 379 +Known Tags\r
 380 +----------\r
 381 +\r
 382 +One special kind of saved search provided by default is for each\r
 383 +individual tag defined in the database. This can be controlled via the\r
 384 +following variables.\r
 385 +\r
 386 +:index:`notmuch-hello-tag-list-make-query`\r
 387 +    Control how to construct a search (“virtual folder”) from a given\r
 388 +    tag.\r
 389 +\r
 390 +:index:`notmuch-hello-hide-tags`\r
 391 +    Which tags not to display at all.\r
 392 +\r
 393 +:index:`notmuch-column-control`\r
 394 +    Controls the number of columns for displaying saved-searches/tags\r
 395 +\r
 396 +.. _notmuch-search:\r
 397 +\r
 398 +notmuch-search\r
 399 +==============\r
 400 +\r
 401 +``notmuch-search-mode`` is used to display the results from executing\r
 402 +a query via ``notmuch-search``. The syntax for these queries is the\r
 403 +the same as :ref:`saved-searches`. For details of this syntax see\r
 404 +info:notmuch-search-terms\r
 405 +\r
 406 +By default the output approximates that of the command line See section\r
 407 +“Description” in notmuch search command.\r
 408 +\r
 409 +The main purpose of the ``notmuch-search-mode`` buffer is to act as a\r
 410 +menu of results that the user can explore further by pressing\r
 411 +``<return>`` on the appropriate line.\r
 412 +\r
 413 +``n,C-n,<down>``\r
 414 +    Move to next line\r
 415 +\r
 416 +``p,C-p,<up>``\r
 417 +    Move to previous line\r
 418 +\r
 419 +``<return>``\r
 420 +    Open thread on current line in :ref:`notmuch-show` mode\r
 421 +\r
 422 +``?``\r
 423 +    Display full set of key bindings\r
 424 +\r
 425 +The presentation of results can be controlled by the following\r
 426 +variables.\r
 427 +\r
 428 +:index:`notmuch-search-result-format`\r
 429 +    Control how each thread of messages is presented in the\r
 430 +    ``notmuch-show-mode`` buffer\r
 431 +\r
 432 +:index:`notmuch-search-oldest-first`\r
 433 +    Display the oldest threads at the top of the buffer\r
 434 +\r
 435 +.. _notmuch-show:\r
 436 +\r
 437 +notmuch-show\r
 438 +============\r
 439 +\r
 440 +notmuch-tree\r
 441 +============\r
 442 +\r
 443 +Configuration\r
 444 +=============\r
 445 +\r
 446 +.. _importing:\r
 447 +\r
 448 +Importing Mail\r
 449 +--------------\r
 450 +\r
 451 +:index:`notmuch-poll`\r
 452 +\r
 453 +:index:`notmuch-poll-script`\r
 454 diff --git a/doc/notmuch-search-terms.rst b/doc/notmuch-search-terms.rst\r
 455 new file mode 100644\r
 456 index 0000000..7885c6a\r
 457 --- /dev/null\r
 458 +++ b/doc/notmuch-search-terms.rst\r
 459 @@ -0,0 +1,255 @@\r
 460 +====================\r
 461 +notmuch-search-terms\r
 462 +====================\r
 463 +\r
 464 +********\r
 465 +Synopsis\r
 466 +********\r
 467 +\r
 468 +\r
 469 +\ **notmuch**\  \ **count**\  [\ *options...*\ ] <\ *search-term*\ >...\r
 470 +\r
 471 +\ **notmuch**\  \ **dump**\  [ <\ *filename*\ > ] [--] [ <\ *search-term*\ >...]\r
 472 +\r
 473 +\ **notmuch**\  \ **search**\  [\ *options*\ ...] <\ *search-term*\ >...\r
 474 +\r
 475 +\ **notmuch**\  \ **show**\  [\ *options*\ ...] <\ *search-term*\ >...\r
 476 +\r
 477 +\ **notmuch**\  \ **tag**\  +<\ *tag*\ >|-<\ *tag*\ > [...] [--] <\ *search-term*\ >...\r
 478 +\r
 479 +\r
 480 +***********\r
 481 +Description\r
 482 +***********\r
 483 +\r
 484 +\r
 485 +Several notmuch commands accept a common syntax for search terms.\r
 486 +\r
 487 +The search terms can consist of free-form text (and quoted phrases)\r
 488 +which will match all messages that contain all of the given\r
 489 +terms/phrases in the body, the subject, or any of the sender or\r
 490 +recipient headers.\r
 491 +\r
 492 +As a special case, a search string consisting of exactly a single\r
 493 +asterisk ("\*") will match all messages.\r
 494 +\r
 495 +In addition to free text, the following prefixes can be used to force\r
 496 +terms to match against specific portions of an email, (where <brackets>\r
 497 +indicate user-supplied values):\r
 498 +\r
 499 +from:<name-or-address>\r
 500 +\r
 501 +to:<name-or-address>\r
 502 +\r
 503 +subject:<word-or-quoted-phrase>\r
 504 +\r
 505 +attachment:<word>\r
 506 +\r
 507 +tag:<tag> (or is:<tag>)\r
 508 +\r
 509 +id:<message-id>\r
 510 +\r
 511 +thread:<thread-id>\r
 512 +\r
 513 +folder:<directory-path>\r
 514 +\r
 515 +date:<since>..<until>\r
 516 +\r
 517 +The \ **from:**\  prefix is used to match the name or address of the sender of\r
 518 +an email message.\r
 519 +\r
 520 +The \ **to:**\  prefix is used to match the names or addresses of any recipient\r
 521 +of an email message, (whether To, Cc, or Bcc).\r
 522 +\r
 523 +Any term prefixed with \ **subject:**\  will match only text from the subject\r
 524 +of an email. Searching for a phrase in the subject is supported by\r
 525 +including quotation marks around the phrase, immediately following\r
 526 +\ **subject:**\ .\r
 527 +\r
 528 +The \ **attachment:**\  prefix can be used to search for specific filenames (or\r
 529 +extensions) of attachments to email messages.\r
 530 +\r
 531 +For \ **tag:**\  and \ **is:**\  valid tag values include \ **inbox**\  and \ **unread**\  by default\r
 532 +for new messages added by \ **notmuch**\  \ **new**\  as well as any other tag values\r
 533 +added manually with \ **notmuch**\  \ **tag**\ .\r
 534 +\r
 535 +For \ **id:**\ , message ID values are the literal contents of the Message-ID:\r
 536 +header of email messages, but without the \`<', \`>' delimiters.\r
 537 +\r
 538 +The \ **thread:**\  prefix can be used with the thread ID values that are\r
 539 +generated internally by notmuch (and do not appear in email messages).\r
 540 +These thread ID values can be seen in the first column of output from\r
 541 +\ **notmuch**\  \ **search**\\r
 542 +\r
 543 +The \ **folder:**\  prefix can be used to search for email message files that\r
 544 +are contained within particular directories within the mail store. If\r
 545 +the same email message has multiple message files associated with it,\r
 546 +it's sufficient for a match that at least one of the files is contained\r
 547 +within a matching directory. Only the directory components below the\r
 548 +top-level mail database path are available to be searched.\r
 549 +\r
 550 +The \ **date:**\  prefix can be used to restrict the results to only messages\r
 551 +within a particular time range (based on the Date: header) with a range\r
 552 +syntax of:\r
 553 +\r
 554 +date:<since>..<until>\r
 555 +\r
 556 +See \ **DATE**\  \ **AND**\  \ **TIME**\  \ **SEARCH**\  below for details on the range expression, and\r
 557 +supported syntax for <since> and <until> date and time expressions.\r
 558 +\r
 559 +The time range can also be specified using timestamps with a syntax of:\r
 560 +\r
 561 +<initial-timestamp>..<final-timestamp>\r
 562 +\r
 563 +Each timestamp is a number representing the number of seconds since\r
 564 +1970-01-01 00:00:00 UTC.\r
 565 +\r
 566 +In addition to individual terms, multiple terms can be combined with\r
 567 +Boolean operators ( \ **and**\ , \ **or**\ , \ **not**\  , etc.). Each term in the query will\r
 568 +be implicitly connected by a logical AND if no explicit operator is\r
 569 +provided, (except that terms with a common prefix will be implicitly\r
 570 +combined with OR until we get Xapian defect #402 fixed).\r
 571 +\r
 572 +Parentheses can also be used to control the combination of the Boolean\r
 573 +operators, but will have to be protected from interpretation by the\r
 574 +shell, (such as by putting quotation marks around any parenthesized\r
 575 +expression).\r
 576 +\r
 577 +\r
 578 +********************\r
 579 +Date and Time Search\r
 580 +********************\r
 581 +\r
 582 +\r
 583 +notmuch understands a variety of standard and natural ways of\r
 584 +expressing dates and times, both in absolute terms ("2012-10-24") and\r
 585 +in relative terms ("yesterday"). Any number of relative terms can be\r
 586 +combined ("1 hour 25 minutes") and an absolute date/time can be\r
 587 +combined with relative terms to further adjust it. A non-exhaustive\r
 588 +description of the syntax supported for absolute and relative terms is\r
 589 +given below.\r
 590 +\r
 591 +\ **The**\  \ **range**\  \ **expression**\\r
 592 +\r
 593 +date:<since>..<until>\r
 594 +\r
 595 +The above expression restricts the results to only messages\r
 596 +from <since> to <until>, based on the Date: header.\r
 597 +\r
 598 +<since> and <until> can describe imprecise times, such as\r
 599 +"yesterday". In this case, <since> is taken as the earliest\r
 600 +time it could describe (the beginning of yesterday) and <until>\r
 601 +is taken as the latest time it could describe (the end of\r
 602 +yesterday). Similarly, date:january..february matches from the\r
 603 +beginning of January to the end of February.\r
 604 +\r
 605 +Currently, we do not support spaces in range expressions. You\r
 606 +can replace the spaces with \`_', or (in most cases) \`-', or (in\r
 607 +some cases) leave the spaces out altogether. Examples in this\r
 608 +man page use spaces for clarity.\r
 609 +\r
 610 +Open-ended ranges are supported (since Xapian 1.2.1), i.e. it's\r
 611 +possible to specify date:..<until> or date:<since>.. to not\r
 612 +limit the start or end time, respectively. Pre-1.2.1 Xapian\r
 613 +does not report an error on open ended ranges, but it does not\r
 614 +work as expected either.\r
 615 +\r
 616 +Entering date:expr without ".." (for example date:yesterday)\r
 617 +won't work, as it's not interpreted as a range expression at\r
 618 +all. You can achieve the expected result by duplicating the\r
 619 +expr both sides of ".." (for example\r
 620 +date:yesterday..yesterday).\r
 621 +\r
 622 +\ **Relative**\  \ **date**\  \ **and**\  \ **time**\\r
 623 +[N|number]\r
 624 +(years|months|weeks|days|hours|hrs|minutes|mins|seconds|secs)\r
 625 +[...]\r
 626 +\r
 627 +All refer to past, can be repeated and will be accumulated.\r
 628 +\r
 629 +Units can be abbreviated to any length, with the otherwise\r
 630 +ambiguous single m being m for minutes and M for months.\r
 631 +\r
 632 +Number can also be written out one, two, ..., ten, dozen,\r
 633 +hundred. Additionally, the unit may be preceded by "last" or\r
 634 +"this" (e.g., "last week" or "this month").\r
 635 +\r
 636 +When combined with absolute date and time, the relative date\r
 637 +and time specification will be relative from the specified\r
 638 +absolute date and time.\r
 639 +\r
 640 +Examples: 5M2d, two weeks\r
 641 +\r
 642 +\ **Supported**\  \ **absolute**\  \ **time**\  \ **formats**\\r
 643 +H[H]:MM[:SS] [(am|a.m.|pm|p.m.)]\r
 644 +\r
 645 +H[H] (am|a.m.|pm|p.m.)\r
 646 +\r
 647 +\r
 648 +HHMMSS\r
 649 +\r
 650 +\r
 651 +\r
 652 +now\r
 653 +\r
 654 +noon\r
 655 +\r
 656 +midnight\r
 657 +\r
 658 +Examples: 17:05, 5pm\r
 659 +\r
 660 +\ **Supported**\  \ **absolute**\  \ **date**\  \ **formats**\\r
 661 +YYYY-MM[-DD]\r
 662 +\r
 663 +\r
 664 +DD-MM[-[YY]YY]\r
 665 +\r
 666 +\r
 667 +\r
 668 +MM-YYYY\r
 669 +\r
 670 +\r
 671 +\r
 672 +M[M]/D[D][/[YY]YY]\r
 673 +\r
 674 +\r
 675 +\r
 676 +M[M]/YYYY\r
 677 +\r
 678 +\r
 679 +\r
 680 +D[D].M[M][.[YY]YY]\r
 681 +\r
 682 +\r
 683 +\r
 684 +D[D][(st|nd|rd|th)] Mon[thname] [YYYY]\r
 685 +\r
 686 +Mon[thname] D[D][(st|nd|rd|th)] [YYYY]\r
 687 +\r
 688 +Wee[kday]\r
 689 +\r
 690 +Month names can be abbreviated at three or more characters.\r
 691 +\r
 692 +Weekday names can be abbreviated at three or more characters.\r
 693 +\r
 694 +Examples: 2012-07-31, 31-07-2012, 7/31/2012, August 3\r
 695 +\r
 696 +\ **Time**\  \ **zones**\\r
 697 +(+|-)HH:MM\r
 698 +\r
 699 +\r
 700 +(+|-)HH[MM]\r
 701 +\r
 702 +\r
 703 +\r
 704 +Some time zone codes, e.g. UTC, EET.\r
 705 +\r
 706 +\r
 707 +********\r
 708 +See Also\r
 709 +********\r
 710 +\r
 711 +\r
 712 +notmuch(1), notmuch-config(1), notmuch-count(1), notmuch-dump(1),\r
 713 +notmuch-hooks(5), notmuch-insert(1), notmuch-new(1), notmuch-reply(1),\r
 714 +notmuch-restore(1), notmuch-search(1), notmuch-show(1), notmuch-tag(1)\r
 715 diff --git a/doc/notmuch-search.rst b/doc/notmuch-search.rst\r
 716 new file mode 100644\r
 717 index 0000000..deb7e8b\r
 718 --- /dev/null\r
 719 +++ b/doc/notmuch-search.rst\r
 720 @@ -0,0 +1,203 @@\r
 721 +==============\r
 722 +notmuch-search\r
 723 +==============\r
 724 +\r
 725 +\r
 726 +********\r
 727 +Synopsis\r
 728 +********\r
 729 +\r
 730 +\r
 731 +\ **notmuch**\  \ **search**\  [\ *options*\ ...] <\ *search-term*\ >...\r
 732 +\r
 733 +\r
 734 +***********\r
 735 +Description\r
 736 +***********\r
 737 +\r
 738 +\r
 739 +Search for messages matching the given search terms, and display as\r
 740 +results the threads containing the matched messages.\r
 741 +\r
 742 +The output consists of one line per thread, giving a thread ID, the\r
 743 +date of the newest (or oldest, depending on the sort option) matched\r
 744 +message in the thread, the number of matched messages and total\r
 745 +messages in the thread, the names of all participants in the thread,\r
 746 +and the subject of the newest (or oldest) message.\r
 747 +\r
 748 +See notmuch-search-terms(7) for details of the supported syntax for\r
 749 +<search-terms>.\r
 750 +\r
 751 +Supported options for \ **search**\  include\r
 752 +\r
 753 +\r
 754 +  **--format=** ( **json** | **sexp** | **text** |  **text0** )\r
 755 +\r
 756 +\r
 757 +\r
 758 +Presents the results in either JSON, S-Expressions, newline\r
 759 +character separated plain-text (default), or null character\r
 760 +separated plain-text (compatible with xargs(1) -0 option where\r
 761 +available).\r
 762 +\r
 763 +\r
 764 +\ **--format-version=N**\\r
 765 +\r
 766 +\r
 767 +\r
 768 +Use the specified structured output format version. This is\r
 769 +intended for programs that invoke notmuch(1) internally. If\r
 770 +omitted, the latest supported version will be used.\r
 771 +\r
 772 +\r
 773 +\ **--output=(summary|threads|messages|files|tags)**\\r
 774 +\r
 775 +\r
 776 +\r
 777 +\ **summary**\\r
 778 +\r
 779 +Output a summary of each thread with any message matching\r
 780 +the search terms. The summary includes the thread ID, date,\r
 781 +the number of messages in the thread (both the number\r
 782 +matched and the total number), the authors of the thread\r
 783 +and the subject.\r
 784 +\r
 785 +\ **threads**\\r
 786 +\r
 787 +Output the thread IDs of all threads with any message\r
 788 +matching the search terms, either one per line\r
 789 +(--format=text), separated by null characters\r
 790 +(--format=text0), as a JSON array (--format=json), or an S-\r
 791 +Expression list (--format=sexp).\r
 792 +\r
 793 +\ **messages**\\r
 794 +\r
 795 +Output the message IDs of all messages matching the search\r
 796 +terms, either one per line (--format=text), separated by\r
 797 +null characters (--format=text0), as a JSON array\r
 798 +(--format=json), or as an S-Expression list\r
 799 +(--format=sexp).\r
 800 +\r
 801 +\ **files**\\r
 802 +\r
 803 +Output the filenames of all messages matching the search\r
 804 +terms, either one per line (--format=text), separated by\r
 805 +null characters (--format=text0), as a JSON array\r
 806 +(--format=json), or as an S-Expression list\r
 807 +(--format=sexp).\r
 808 +\r
 809 +Note that each message may have multiple filenames\r
 810 +associated with it. All of them are included in the\r
 811 +output, unless limited with the --duplicate=N option.\r
 812 +\r
 813 +\ **tags**\\r
 814 +\r
 815 +Output all tags that appear on any message matching the\r
 816 +search terms, either one per line (--format=text),\r
 817 +separated by null characters (--format=text0), as a JSON\r
 818 +array (--format=json), or as an S-Expression list\r
 819 +(--format=sexp).\r
 820 +\r
 821 +\r
 822 +\ **--sort=** (\ **newest-first** | **oldest-first** )\r
 823 +\r
 824 +\r
 825 +\r
 826 +This option can be used to present results in either\r
 827 +chronological order (\ **oldest-first**\ ) or reverse chronological\r
 828 +order (\ **newest-first**\ ).\r
 829 +\r
 830 +Note: The thread order will be distinct between these two\r
 831 +options (beyond being simply reversed). When sorting by\r
 832 +\ **oldest-first**\  the threads will be sorted by the oldest message\r
 833 +in each thread, but when sorting by \ **newest-first**\  the threads\r
 834 +will be sorted by the newest message in each thread.\r
 835 +\r
 836 +By default, results will be displayed in reverse chronological\r
 837 +order, (that is, the newest results will be displayed first).\r
 838 +\r
 839 +\r
 840 +\ **--offset=[-]N**\\r
 841 +\r
 842 +\r
 843 +\r
 844 +Skip displaying the first N results. With the leading \`-',\r
 845 +start at the Nth result from the end.\r
 846 +\r
 847 +\r
 848 +\ **--limit=N**\\r
 849 +\r
 850 +\r
 851 +\r
 852 +Limit the number of displayed results to N.\r
 853 +\r
 854 +\r
 855 +\ **--exclude=(true|false|all|flag)**\\r
 856 +\r
 857 +\r
 858 +\r
 859 +A message is called "excluded" if it matches at least one tag\r
 860 +in search.tag_exclude that does not appear explicitly in the\r
 861 +search terms. This option specifies whether to omit excluded\r
 862 +messages in the search process.\r
 863 +\r
 864 +The default value, \ **true**\ , prevents excluded messages from\r
 865 +matching the search terms.\r
 866 +\r
 867 +\ **all**\  additionally prevents excluded messages from appearing in\r
 868 +displayed results, in effect behaving as though the excluded\r
 869 +messages do not exist.\r
 870 +\r
 871 +\ **false**\  allows excluded messages to match search terms and appear\r
 872 +in displayed results. Excluded messages are still marked in the\r
 873 +relevant outputs.\r
 874 +\r
 875 +\ **flag**\  only has an effect when \ **--output=summary**\ . The output is\r
 876 +almost identical to \ **false**\ , but the "match count" is the number\r
 877 +of matching non-excluded messages in the thread, rather than\r
 878 +the number of matching messages.\r
 879 +\r
 880 +\r
 881 +\ **--duplicate=N**\\r
 882 +\r
 883 +\r
 884 +\r
 885 +Effective with \ **--output=files**\ , output the Nth filename\r
 886 +associated with each message matching the query (N is 1-based).\r
 887 +If N is greater than the number of files associated with the\r
 888 +message, don't print anything.\r
 889 +\r
 890 +Note that this option is orthogonal with the \ **folder:**\  search\r
 891 +prefix. The prefix matches messages based on filenames. This\r
 892 +option filters filenames of the matching messages.\r
 893 +\r
 894 +\r
 895 +***********\r
 896 +Exit Status\r
 897 +***********\r
 898 +\r
 899 +\r
 900 +This command supports the following special exit status codes\r
 901 +\r
 902 +\r
 903 +\ **20**\\r
 904 +\r
 905 +   The requested format version is too old.\r
 906 +\r
 907 +\r
 908 +\ **21**\\r
 909 +\r
 910 +   The requested format version is too new.\r
 911 +\r
 912 +\r
 913 +\r
 914 +\r
 915 +\r
 916 +********\r
 917 +See Also\r
 918 +********\r
 919 +\r
 920 +\r
 921 +notmuch(1), notmuch-config(1), notmuch-count(1), notmuch-dump(1),\r
 922 +notmuch-hooks(5), notmuch-insert(1), notmuch-new(1), notmuch-reply(1),\r
 923 +notmuch-restore(1), notmuch-search-terms(7), notmuch-show(1), notmuchtag(1)\r
 924 diff --git a/doc/notmuch.rst b/doc/notmuch.rst\r
 925 new file mode 100644\r
 926 index 0000000..9d9a35c\r
 927 --- /dev/null\r
 928 +++ b/doc/notmuch.rst\r
 929 @@ -0,0 +1,173 @@\r
 930 +========\r
 931 +notmuch\r
 932 +========\r
 933 +\r
 934 +Synopsis\r
 935 +========\r
 936 +\r
 937 +\r
 938 +\ **notmuch**\  [\ *option*\  ...] \ *command*\  [\ *arg*\  ...]\r
 939 +\r
 940 +\r
 941 +Description\r
 942 +===========\r
 943 +\r
 944 +\r
 945 +Notmuch is a command-line based program for indexing, searching,\r
 946 +reading, and tagging large collections of email messages.\r
 947 +\r
 948 +This page describes how to get started using notmuch from the command\r
 949 +line, and gives a brief overview of the commands available. For more\r
 950 +information on e.g. \ **notmuch**\  \ **show**\  consult the notmuch-show(1) man page,\r
 951 +also accessible via \ **notmuch**\  \ **help**\  \ **show**\\r
 952 +\r
 953 +The quickest way to get started with Notmuch is to simply invoke the\r
 954 +\ **notmuch**\  command with no arguments, which will interactively guide you\r
 955 +through the process of indexing your mail.\r
 956 +\r
 957 +Note\r
 958 +====\r
 959 +\r
 960 +\r
 961 +While the command-line program \ **notmuch**\  provides powerful functionality,\r
 962 +it does not provide the most convenient interface for that\r
 963 +functionality. More sophisticated interfaces are expected to be built\r
 964 +on top of either the command-line interface, or more likely, on top of\r
 965 +the notmuch library interface. See http://notmuchmail.org for more\r
 966 +about alternate interfaces to notmuch. The emacs-based interface to\r
 967 +notmuch (available under \ **emacs/**\  in the Notmuch source distribution) is\r
 968 +probably the most widely used at this time.\r
 969 +\r
 970 +Options\r
 971 +========\r
 972 +\r
 973 +\r
 974 +Supported global options for \ **notmuch**\  include\r
 975 +\r
 976 +\r
 977 +\ **--help**\\r
 978 +\r
 979 +\r
 980 +\r
 981 +Print a synopsis of available commands and exit.\r
 982 +\r
 983 +\r
 984 +\ **--version**\\r
 985 +\r
 986 +\r
 987 +\r
 988 +Print the installed version of notmuch, and exit.\r
 989 +\r
 990 +\r
 991 +\ **--config=FILE**\\r
 992 +\r
 993 +\r
 994 +\r
 995 +Specify the configuration file to use. This overrides any\r
 996 +configuration file specified by ${NOTMUCH_CONFIG}.\r
 997 +\r
 998 +Commands\r
 999 +========\r
1000 +\r
1001 +\r
1002 +\ **SETUP**\\r
1003 +The \ **notmuch**\  \ **setup**\  command is used to configure Notmuch for first use,\r
1004 +(or to reconfigure it later).\r
1005 +\r
1006 +The setup command will prompt for your full name, your primary email\r
1007 +address, any alternate email addresses you use, and the directory\r
1008 +containing your email archives. Your answers will be written to a\r
1009 +configuration file in ${NOTMUCH_CONFIG} (if set) or ${HOME}/.notmuch-\r
1010 +config . This configuration file will be created with descriptive\r
1011 +comments, making it easy to edit by hand later to change the\r
1012 +configuration. Or you can run \ **notmuch**\  \ **setup**\  again to change the\r
1013 +configuration.\r
1014 +\r
1015 +The mail directory you specify can contain any number of sub-\r
1016 +directories and should primarily contain only files with individual\r
1017 +email messages (eg. maildir or mh archives are perfect). If there are\r
1018 +other, non-email files (such as indexes maintained by other email\r
1019 +programs) then notmuch will do its best to detect those and ignore\r
1020 +them.\r
1021 +\r
1022 +Mail storage that uses mbox format, (where one mbox file contains many\r
1023 +messages), will not work with notmuch. If that's how your mail is\r
1024 +currently stored, it is recommended you first convert it to maildir\r
1025 +format with a utility such as mb2md before running \ **notmuch**\  \ **setup**\  \ **.**\\r
1026 +\r
1027 +Invoking \ **notmuch**\  with no command argument will run \ **setup**\  if the setup\r
1028 +command has not previously been completed.\r
1029 +\r
1030 +\ **OTHER**\  \ **COMMANDS**\\r
1031 +Several of the notmuch commands accept search terms with a common\r
1032 +syntax. See notmuch-search-terms(7) for more details on the supported\r
1033 +syntax.\r
1034 +\r
1035 +The \ **search**\ , \ **show**\  and \ **count**\  commands are used to query the email\r
1036 +database.\r
1037 +\r
1038 +The \ **reply**\  command is useful for preparing a template for an email\r
1039 +reply.\r
1040 +\r
1041 +The \ **tag**\  command is the only command available for manipulating database\r
1042 +contents.\r
1043 +\r
1044 +The \ **dump**\  and \ **restore**\  commands can be used to create a textual dump of\r
1045 +email tags for backup purposes, and to restore from that dump.\r
1046 +\r
1047 +The \ **config**\  command can be used to get or set settings int the notmuch\r
1048 +configuration file.\r
1049 +\r
1050 +\r
1051 +Environment\r
1052 +===========\r
1053 +\r
1054 +\r
1055 +The following environment variables can be used to control the behavior\r
1056 +of notmuch.\r
1057 +\r
1058 +\r
1059 +\ **NOTMUCH_CONFIG**\\r
1060 +\r
1061 + Specifies the location of the notmuch configuration file.\r
1062 + Notmuch will use ${HOME}/.notmuch-config if this variable is not\r
1063 + set.\r
1064 +\r
1065 +\r
1066 +\r
1067 +\ **NOTMUCH_TALLOC_REPORT**\\r
1068 +\r
1069 + Location to write a talloc memory usage report. See\r
1070 + \ **talloc_enable_leak_report_full**\  in talloc(3) for more\r
1071 + information.\r
1072 +\r
1073 +\r
1074 +\r
1075 +\ **NOTMUCH_DEBUG_QUERY**\\r
1076 +\r
1077 + If set to a non-empty value, the notmuch library will print (to\r
1078 + stderr) Xapian queries it constructs.\r
1079 +\r
1080 +\r
1081 +See Also\r
1082 +========\r
1083 +\r
1084 +\r
1085 +notmuch-config(1), notmuch-count(1), notmuch-dump(1), notmuch-hooks(5),\r
1086 +notmuch-insert(1), notmuch-new(1), notmuch-reply(1), notmuch-restore(1),\r
1087 +notmuch-search(1), notmuch-search-terms(7), notmuch-show(1),\r
1088 +notmuch-tag(1)\r
1089 +\r
1090 +The notmuch website: \ **http://notmuchmail.org**\\r
1091 +\r
1092 +\r
1093 +Contact\r
1094 +========\r
1095 +\r
1096 +\r
1097 +Feel free to send questions, comments, or kudos to the notmuch mailing\r
1098 +list <notmuch@notmuchmail.org> . Subscription is not required before\r
1099 +posting, but is available from the notmuchmail.org website.\r
1100 +\r
1101 +Real-time interaction with the Notmuch community is available via IRC\r
1102 +(server: irc.freenode.net, channel: #notmuch).\r
1103 -- \r
1104 1.8.5.2\r
1105 \r