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 462AE431FBF
\r
6 for <notmuch@notmuchmail.org>; Sun, 9 Mar 2014 05:57:31 -0700 (PDT)
\r
7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org
\r
11 X-Spam-Status: No, score=0.001 tagged_above=-999 required=5
\r
12 tests=[WEIRD_QUOTING=0.001] 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 OJ7DrwVg5KEe for <notmuch@notmuchmail.org>;
\r
16 Sun, 9 Mar 2014 05:57:18 -0700 (PDT)
\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 5F3CC431FBD
\r
21 for <notmuch@notmuchmail.org>; Sun, 9 Mar 2014 05:57:18 -0700 (PDT)
\r
22 Received: from remotemail by yantan.tethera.net with local (Exim 4.80)
\r
23 (envelope-from <bremner@tethera.net>)
\r
24 id 1WMdI3-0003qE-VW; Sun, 09 Mar 2014 09:57:15 -0300
\r
25 Received: (nullmailer pid 8481 invoked by uid 1000); Sun, 09 Mar 2014
\r
27 From: David Bremner <david@tethera.net>
\r
28 To: notmuch@notmuchmail.org
\r
29 Subject: [Patch v3 1/4] doc: convert sphinx based docs
\r
30 Date: Sun, 9 Mar 2014 09:56:57 -0300
\r
31 Message-Id: <1394369820-8319-2-git-send-email-david@tethera.net>
\r
32 X-Mailer: git-send-email 1.8.5.3
\r
33 In-Reply-To: <1394369820-8319-1-git-send-email-david@tethera.net>
\r
34 References: <1394369820-8319-1-git-send-email-david@tethera.net>
\r
36 Content-Type: text/plain; charset=UTF-8
\r
37 Content-Transfer-Encoding: 8bit
\r
38 X-BeenThere: notmuch@notmuchmail.org
\r
39 X-Mailman-Version: 2.1.13
\r
41 List-Id: "Use and development of the notmuch mail system."
\r
42 <notmuch.notmuchmail.org>
\r
43 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,
\r
44 <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>
\r
45 List-Archive: <http://notmuchmail.org/pipermail/notmuch>
\r
46 List-Post: <mailto:notmuch@notmuchmail.org>
\r
47 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>
\r
48 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,
\r
49 <mailto:notmuch-request@notmuchmail.org?subject=subscribe>
\r
50 X-List-Received-Date: Sun, 09 Mar 2014 12:57:31 -0000
\r
52 This is the output from sphinx-quickstart, massaged a bit, along with
\r
53 our existing man pages converted to rst.
\r
55 A skeleton notmuch-emacs manual is also included. It is not suitable
\r
56 for end user use yet.
\r
60 debian/control | 1 +
\r
61 doc/.gitignore | 2 +
\r
62 doc/INSTALL | 24 ++++
\r
64 doc/Makefile.local | 27 +++++
\r
65 doc/conf.py | 166 +++++++++++++++++++++++++++
\r
66 doc/index.rst | 30 +++++
\r
67 doc/man1/notmuch-compact.rst | 52 +++++++++
\r
68 doc/man1/notmuch-config.rst | 123 ++++++++++++++++++++
\r
69 doc/man1/notmuch-count.rst | 60 ++++++++++
\r
70 doc/man1/notmuch-dump.rst | 72 ++++++++++++
\r
71 doc/man1/notmuch-insert.rst | 58 ++++++++++
\r
72 doc/man1/notmuch-new.rst | 52 +++++++++
\r
73 doc/man1/notmuch-reply.rst | 112 ++++++++++++++++++
\r
74 doc/man1/notmuch-restore.rst | 59 ++++++++++
\r
75 doc/man1/notmuch-search.rst | 146 ++++++++++++++++++++++++
\r
76 doc/man1/notmuch-show.rst | 179 +++++++++++++++++++++++++++++
\r
77 doc/man1/notmuch-tag.rst | 107 +++++++++++++++++
\r
78 doc/man1/notmuch.rst | 143 +++++++++++++++++++++++
\r
79 doc/man5/notmuch-hooks.rst | 44 +++++++
\r
80 doc/man7/notmuch-search-terms.rst | 234 ++++++++++++++++++++++++++++++++++++++
\r
81 doc/notmuch-emacs.rst | 192 +++++++++++++++++++++++++++++++
\r
82 24 files changed, 1905 insertions(+), 3 deletions(-)
\r
83 create mode 100644 doc/.gitignore
\r
84 create mode 100644 doc/INSTALL
\r
85 create mode 100644 doc/Makefile
\r
86 create mode 100644 doc/Makefile.local
\r
87 create mode 100644 doc/conf.py
\r
88 create mode 100644 doc/index.rst
\r
89 create mode 100644 doc/man1/notmuch-compact.rst
\r
90 create mode 100644 doc/man1/notmuch-config.rst
\r
91 create mode 100644 doc/man1/notmuch-count.rst
\r
92 create mode 100644 doc/man1/notmuch-dump.rst
\r
93 create mode 100644 doc/man1/notmuch-insert.rst
\r
94 create mode 100644 doc/man1/notmuch-new.rst
\r
95 create mode 100644 doc/man1/notmuch-reply.rst
\r
96 create mode 100644 doc/man1/notmuch-restore.rst
\r
97 create mode 100644 doc/man1/notmuch-search.rst
\r
98 create mode 100644 doc/man1/notmuch-show.rst
\r
99 create mode 100644 doc/man1/notmuch-tag.rst
\r
100 create mode 100644 doc/man1/notmuch.rst
\r
101 create mode 100644 doc/man5/notmuch-hooks.rst
\r
102 create mode 100644 doc/man7/notmuch-search-terms.rst
\r
103 create mode 100644 doc/notmuch-emacs.rst
\r
105 diff --git a/INSTALL b/INSTALL
\r
106 index fce9352..690b0ef 100644
\r
109 @@ -60,16 +60,30 @@ Talloc which are each described below:
\r
111 Talloc is available from http://talloc.samba.org/
\r
113 +Building Documentation
\r
114 +----------------------
\r
116 +By default the documentation for notmuch is built using sphinx.
\r
118 +Sphinx is available from www.sphinx-doc.org.
\r
120 +If you prefer, you can build the man pages using rst2man, from the
\r
121 +python docutils package. See doc/INSTALL for details.
\r
124 +Installing Dependencies from Packages
\r
125 +-------------------------------------
\r
127 On a modern, package-based operating system you can install all of the
\r
128 dependencies with a simple simple command line. For example:
\r
130 For Debian and similar:
\r
132 - sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev
\r
133 + sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev python-sphinx
\r
135 For Fedora and similar:
\r
137 - sudo yum install xapian-core-devel gmime-devel libtalloc-devel
\r
138 + sudo yum install xapian-core-devel gmime-devel libtalloc-devel python-sphinx
\r
140 On other systems, a similar command can be used, but the details of
\r
141 the package names may be different.
\r
142 diff --git a/Makefile b/Makefile
\r
143 index 0428160..39f0e62 100644
\r
146 @@ -5,7 +5,7 @@ all:
\r
147 # List all subdirectories here. Each contains its own Makefile.local.
\r
148 # Use of '=', without '+=', seems to be required for out-of-tree
\r
150 -subdirs = compat completion emacs lib man parse-time-string performance-test util test
\r
151 +subdirs = compat completion doc emacs lib man parse-time-string performance-test util test
\r
153 # We make all targets depend on the Makefiles themselves.
\r
154 global_deps = Makefile Makefile.config Makefile.local \
\r
155 diff --git a/debian/control b/debian/control
\r
156 index c5475c4..8d8e938 100644
\r
157 --- a/debian/control
\r
158 +++ b/debian/control
\r
159 @@ -15,6 +15,7 @@ Build-Depends:
\r
161 python-all (>= 2.6.6-3~),
\r
162 python3-all (>= 3.1.2-7~),
\r
163 + python-sphinx (>= 1.0),
\r
164 ruby, ruby-dev (>>1:1.9.3~),
\r
165 emacs23-nox | emacs23 (>=23~) | emacs23-lucid (>=23~) |
\r
166 emacs24-nox | emacs24 (>=24~) | emacs24-lucid (>=24~),
\r
167 diff --git a/doc/.gitignore b/doc/.gitignore
\r
168 new file mode 100644
\r
169 index 0000000..a60fb31
\r
171 +++ b/doc/.gitignore
\r
175 diff --git a/doc/INSTALL b/doc/INSTALL
\r
176 new file mode 100644
\r
177 index 0000000..e37c2b9
\r
181 +This file contains some more detailed information about building and
\r
182 +installing the documentation.
\r
184 +Building with sphinx.
\r
185 +---------------------
\r
187 +- You need sphinx at least version 1.0.
\r
189 +- You can build build and install man pages with 'make install-man'
\r
191 +- You can build man, info, html, and pdf versions of the docs
\r
192 + (currently only the man pages) with
\r
194 + 'make install-{man|info|html|pdf}'
\r
196 +Building the man pages
\r
197 +----------------------
\r
199 +- You can build the man pages with rst2man (from python-docutils) with
\r
202 +- Currently there is no support to automagically install the resulting
\r
203 + nroff files, but it should work to modify the target install-man
\r
204 + in doc/Makefile.local.
\r
205 diff --git a/doc/Makefile b/doc/Makefile
\r
206 new file mode 100644
\r
207 index 0000000..fa25832
\r
212 + $(MAKE) -C .. all
\r
216 diff --git a/doc/Makefile.local b/doc/Makefile.local
\r
217 new file mode 100644
\r
218 index 0000000..ec23012
\r
220 +++ b/doc/Makefile.local
\r
222 +# -*- makefile -*-
\r
226 +# You can set these variables from the command line.
\r
227 +SPHINXOPTS := -q -c $(dir)
\r
228 +SPHINXBUILD = sphinx-build
\r
229 +DOCBUILDDIR := $(dir)/_build
\r
231 +# Internal variables.
\r
232 +ALLSPHINXOPTS := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(dir)
\r
234 +.PHONY: sphinx-html sphinx-man sphinx-texinfo sphinx-info
\r
237 + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DOCBUILDDIR)/html
\r
240 + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(DOCBUILDDIR)/man
\r
243 + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(DOCBUILDDIR)/texinfo
\r
245 +sphinx-info: sphinx-texinfo
\r
246 + make -C $(DOCBUILDDIR)/texinfo info
\r
248 +CLEAN := $(CLEAN) $(DOCBUILDDIR)
\r
249 diff --git a/doc/conf.py b/doc/conf.py
\r
250 new file mode 100644
\r
251 index 0000000..6c2806d
\r
256 +# -*- coding: utf-8 -*-
\r
261 +# The suffix of source filenames.
\r
262 +source_suffix = '.rst'
\r
264 +# The master toctree document.
\r
265 +master_doc = 'index'
\r
267 +# General information about the project.
\r
268 +project = u'notmuch'
\r
269 +copyright = u'2014, Carl Worth and many others'
\r
271 +# The short X.Y version.
\r
273 +# The full version, including alpha/beta/rc tags.
\r
276 +# List of patterns, relative to source directory, that match files and
\r
277 +# directories to ignore when looking for source files.
\r
278 +exclude_patterns = ['_build', 'notmuch-emacs.rst']
\r
280 +# The name of the Pygments (syntax highlighting) style to use.
\r
281 +pygments_style = 'sphinx'
\r
283 +# -- Options for HTML output ----------------------------------------------
\r
285 +# The theme to use for HTML and HTML Help pages. See the documentation for
\r
286 +# a list of builtin themes.
\r
287 +html_theme = 'default'
\r
290 +# Add any paths that contain custom static files (such as style sheets) here,
\r
291 +# relative to this directory. They are copied after the builtin static files,
\r
292 +# so a file named "default.css" will overwrite the builtin "default.css".
\r
293 +html_static_path = ['_static']
\r
295 +# Output file base name for HTML help builder.
\r
296 +htmlhelp_basename = 'notmuchdoc'
\r
298 +# -- Options for manual page output ---------------------------------------
\r
300 +# One entry per manual page. List of tuples
\r
301 +# (source start file, name, description, authors, manual section).
\r
305 +('man1/notmuch','notmuch',
\r
306 + u'thread-based email index, search, and tagging',
\r
307 + [u'Carl Worth and many others'], 1),
\r
309 +('man1/notmuch-compact','notmuch-compact',
\r
310 + u'compact the notmuch database',
\r
311 + [u'Carl Worth and many others'], 1),
\r
313 +('man1/notmuch-config','notmuch-config',
\r
314 + u'access notmuch configuration file',
\r
315 + [u'Carl Worth and many others'], 1),
\r
317 +('man1/notmuch-count','notmuch-count',
\r
318 + u'count messages matching the given search terms',
\r
319 + [u'Carl Worth and many others'], 1),
\r
321 +('man1/notmuch-dump','notmuch-dump',
\r
322 + u'creates a plain-text dump of the tags of each message',
\r
323 + [u'Carl Worth and many others'], 1),
\r
325 +('man5/notmuch-hooks','notmuch-hooks',
\r
326 + u'hooks for notmuch',
\r
327 + [u'Carl Worth and many others'], 5),
\r
329 +('man1/notmuch-insert','notmuch-insert',
\r
330 + u'add a message to the maildir and notmuch database',
\r
331 + [u'Carl Worth and many others'], 1),
\r
333 +('man1/notmuch-new','notmuch-new',
\r
334 + u'incorporate new mail into the notmuch database',
\r
335 + [u'Carl Worth and many others'], 1),
\r
337 +('man1/notmuch-reply','notmuch-reply',
\r
338 + u'constructs a reply template for a set of messages',
\r
339 + [u'Carl Worth and many others'], 1),
\r
341 +('man1/notmuch-restore','notmuch-restore',
\r
342 + u'restores the tags from the given file (see notmuch dump)',
\r
343 + [u'Carl Worth and many others'], 1),
\r
345 +('man1/notmuch-search','notmuch-search',
\r
346 + u'search for messages matching the given search terms',
\r
347 + [u'Carl Worth and many others'], 1),
\r
349 +('man7/notmuch-search-terms','notmuch-search-terms',
\r
350 + u'syntax for notmuch queries',
\r
351 + [u'Carl Worth and many others'], 7),
\r
353 +('man1/notmuch-show','notmuch-show',
\r
354 + u'show messages matching the given search terms',
\r
355 + [u'Carl Worth and many others'], 1),
\r
357 +('man1/notmuch-tag','notmuch-tag',
\r
358 + u'add/remove tags for all messages matching the search terms',
\r
359 + [u'Carl Worth and many others'], 1),
\r
363 +# If true, show URL addresses after external links.
\r
364 +#man_show_urls = False
\r
366 +# -- Options for Texinfo output -------------------------------------------
\r
368 +# Grouping the document tree into Texinfo files. List of tuples
\r
369 +# (source start file, target name, title, author,
\r
370 +# dir menu entry, description, category)
\r
371 +# If true, do not generate a @detailmenu in the "Top" node's menu.
\r
372 +texinfo_no_detailmenu = True
\r
374 +texinfo_documents = [
\r
375 + ('notmuch-emacs', 'notmuch-emacs', u'notmuch Documentation',
\r
376 + u'Carl Worth and many others', 'notmuch-emacs',
\r
377 + 'emacs based front-end for notmuch', 'Miscellaneous'),
\r
378 +('man1/notmuch','notmuch',u'notmuch Documentation',
\r
379 + u'Carl Worth and many others', 'notmuch',
\r
380 + 'thread-based email index, search, and tagging','Miscellaneous'),
\r
381 +('man1/notmuch-compact','notmuch-compact',u'notmuch Documentation',
\r
382 + u'Carl Worth and many others', 'notmuch-compact',
\r
383 + 'compact the notmuch database','Miscellaneous'),
\r
384 +('man1/notmuch-config','notmuch-config',u'notmuch Documentation',
\r
385 + u'Carl Worth and many others', 'notmuch-config',
\r
386 + 'access notmuch configuration file','Miscellaneous'),
\r
387 +('man1/notmuch-count','notmuch-count',u'notmuch Documentation',
\r
388 + u'Carl Worth and many others', 'notmuch-count',
\r
389 + 'count messages matching the given search terms','Miscellaneous'),
\r
390 +('man1/notmuch-dump','notmuch-dump',u'notmuch Documentation',
\r
391 + u'Carl Worth and many others', 'notmuch-dump',
\r
392 + 'creates a plain-text dump of the tags of each message','Miscellaneous'),
\r
393 +('man5/notmuch-hooks','notmuch-hooks',u'notmuch Documentation',
\r
394 + u'Carl Worth and many others', 'notmuch-hooks',
\r
395 + 'hooks for notmuch','Miscellaneous'),
\r
396 +('man1/notmuch-insert','notmuch-insert',u'notmuch Documentation',
\r
397 + u'Carl Worth and many others', 'notmuch-insert',
\r
398 + 'add a message to the maildir and notmuch database','Miscellaneous'),
\r
399 +('man1/notmuch-new','notmuch-new',u'notmuch Documentation',
\r
400 + u'Carl Worth and many others', 'notmuch-new',
\r
401 + 'incorporate new mail into the notmuch database','Miscellaneous'),
\r
402 +('man1/notmuch-reply','notmuch-reply',u'notmuch Documentation',
\r
403 + u'Carl Worth and many others', 'notmuch-reply',
\r
404 + 'constructs a reply template for a set of messages','Miscellaneous'),
\r
405 +('man1/notmuch-restore','notmuch-restore',u'notmuch Documentation',
\r
406 + u'Carl Worth and many others', 'notmuch-restore',
\r
407 + 'restores the tags from the given file (see notmuch dump)','Miscellaneous'),
\r
408 +('man1/notmuch-search','notmuch-search',u'notmuch Documentation',
\r
409 + u'Carl Worth and many others', 'notmuch-search',
\r
410 + 'search for messages matching the given search terms','Miscellaneous'),
\r
411 +('man7/notmuch-search-terms','notmuch-search-terms',u'notmuch Documentation',
\r
412 + u'Carl Worth and many others', 'notmuch-search-terms',
\r
413 + 'syntax for notmuch queries','Miscellaneous'),
\r
414 +('man1/notmuch-show','notmuch-show',u'notmuch Documentation',
\r
415 + u'Carl Worth and many others', 'notmuch-show',
\r
416 + 'show messages matching the given search terms','Miscellaneous'),
\r
417 +('man1/notmuch-tag','notmuch-tag',u'notmuch Documentation',
\r
418 + u'Carl Worth and many others', 'notmuch-tag',
\r
419 + 'add/remove tags for all messages matching the search terms','Miscellaneous'),
\r
421 diff --git a/doc/index.rst b/doc/index.rst
\r
422 new file mode 100644
\r
423 index 0000000..b33aa9f
\r
425 +++ b/doc/index.rst
\r
428 +Welcome to notmuch's documentation!
\r
429 +===================================
\r
437 + man1/notmuch-compact
\r
438 + man1/notmuch-config
\r
439 + man1/notmuch-count
\r
440 + man1/notmuch-dump
\r
441 + man5/notmuch-hooks
\r
442 + man1/notmuch-insert
\r
444 + man1/notmuch-reply
\r
445 + man1/notmuch-restore
\r
446 + man1/notmuch-search
\r
447 + man7/notmuch-search-terms
\r
448 + man1/notmuch-show
\r
451 +Indices and tables
\r
452 +==================
\r
457 diff --git a/doc/man1/notmuch-compact.rst b/doc/man1/notmuch-compact.rst
\r
458 new file mode 100644
\r
459 index 0000000..e0109dc
\r
461 +++ b/doc/man1/notmuch-compact.rst
\r
470 +**notmuch** **compact** [--quiet] [--backup=<*directory*>]
\r
475 +The **compact** command can be used to compact the notmuch database.
\r
476 +This can both reduce the space required by the database and improve
\r
477 +lookup performance.
\r
479 +The compacted database is built in a temporary directory and is later
\r
480 +moved into the place of the origin database. The original uncompacted
\r
481 +database is discarded, unless the ``--backup=``\ <directory> option is
\r
484 +Note that the database write lock will be held during the compaction
\r
485 +process (which may be quite long) to protect data integrity.
\r
487 +Supported options for **compact** include
\r
489 + ``--backup=``\ <directory>
\r
490 + Save the current database to the given directory before
\r
491 + replacing it with the compacted database. The backup directory
\r
492 + must not exist and it must reside on the same mounted filesystem
\r
493 + as the current database.
\r
496 + Do not report database compaction progress to stdout.
\r
501 +The following environment variables can be used to control the behavior
\r
504 +**NOTMUCH\_CONFIG**
\r
505 + Specifies the location of the notmuch configuration file. Notmuch
\r
506 + will use ${HOME}/.notmuch-config if this variable is not set.
\r
511 +**notmuch(1)**, **notmuch-count(1)**, **notmuch-dump(1)**,
\r
512 +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
513 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
514 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
515 diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst
\r
516 new file mode 100644
\r
517 index 0000000..3c9a568
\r
519 +++ b/doc/man1/notmuch-config.rst
\r
528 +**notmuch** **config** **get** <*section*>.<*item*>
\r
530 +**notmuch** **config** **set** <*section*>.<*item*> [*value* ...]
\r
532 +**notmuch** **config** **list**
\r
537 +The **config** command can be used to get or set settings in the notmuch
\r
538 +configuration file.
\r
541 + The value of the specified configuration item is printed to
\r
542 + stdout. If the item has multiple values (it is a list), each
\r
543 + value is separated by a newline character.
\r
546 + The specified configuration item is set to the given value. To
\r
547 + specify a multiple-value item (a list), provide each value as a
\r
548 + separate command-line argument.
\r
550 + If no values are provided, the specified configuration item will
\r
551 + be removed from the configuration file.
\r
554 + Every configuration item is printed to stdout, each on a
\r
555 + separate line of the form:
\r
557 + *section*.\ *item*\ =\ *value*
\r
559 + No additional whitespace surrounds the dot or equals sign
\r
560 + characters. In a multiple-value item (a list), the values are
\r
561 + separated by semicolon characters.
\r
563 +The available configuration items are described below.
\r
565 + **database.path**
\r
566 + The top-level directory where your mail currently exists and to
\r
567 + where mail will be delivered in the future. Files should be
\r
568 + individual email messages. Notmuch will store its database
\r
569 + within a sub-directory of the path configured here named
\r
575 + **user.primary\_email**
\r
576 + Your primary email address.
\r
578 + **user.other\_email**
\r
579 + A list of other email addresses at which you receive email.
\r
582 + A list of tags that will be added to all messages incorporated
\r
583 + by **notmuch new**.
\r
586 + A list of file and directory names, without path, that will not
\r
587 + be searched for messages by **notmuch new**. All the files and
\r
588 + directories matching any of the names specified here will be
\r
589 + ignored, regardless of the location in the mail store directory
\r
592 + **search.exclude\_tags**
\r
593 + A list of tags that will be excluded from search results by
\r
594 + default. Using an excluded tag in a query will override that
\r
597 + **maildir.synchronize\_flags**
\r
598 + If true, then the following maildir flags (in message filenames)
\r
599 + will be synchronized with the corresponding notmuch tags:
\r
601 + +--------+-----------------------------------------------+
\r
603 + +========+===============================================+
\r
605 + +--------+-----------------------------------------------+
\r
607 + +--------+-----------------------------------------------+
\r
609 + +--------+-----------------------------------------------+
\r
611 + +--------+-----------------------------------------------+
\r
612 + | S | unread (added when 'S' flag is not present) |
\r
613 + +--------+-----------------------------------------------+
\r
615 + The **notmuch new** command will notice flag changes in
\r
616 + filenames and update tags, while the **notmuch tag** and
\r
617 + **notmuch restore** commands will notice tag changes and update
\r
618 + flags in filenames.
\r
620 + If there have been any changes in the maildir (new messages
\r
621 + added, old ones removed or renamed, maildir flags changed,
\r
622 + etc.), it is advisable to run **notmuch new** before **notmuch
\r
623 + tag** or **notmuch restore** commands to ensure the tag changes
\r
624 + are properly synchronized to the maildir flags, as the commands
\r
625 + expect the database and maildir to be in sync.
\r
630 +The following environment variables can be used to control the behavior
\r
633 +**NOTMUCH\_CONFIG**
\r
634 + Specifies the location of the notmuch configuration file. Notmuch
\r
635 + will use ${HOME}/.notmuch-config if this variable is not set.
\r
640 +**notmuch(1)**, **notmuch-count(1)**, **notmuch-dump(1)**,
\r
641 +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
642 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
643 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
644 diff --git a/doc/man1/notmuch-count.rst b/doc/man1/notmuch-count.rst
\r
645 new file mode 100644
\r
646 index 0000000..ca78c18
\r
648 +++ b/doc/man1/notmuch-count.rst
\r
657 +**notmuch** **count** [*option* ...] <*search-term*> ...
\r
662 +Count messages matching the search terms.
\r
664 +The number of matching messages (or threads) is output to stdout.
\r
666 +With no search terms, a count of all messages (or threads) in the
\r
667 +database will be displayed.
\r
669 +See **notmuch-search-terms(7)** for details of the supported syntax for
\r
672 +Supported options for **count** include
\r
674 + ``--output=(messages|threads|files)``
\r
677 + Output the number of matching messages. This is the default.
\r
680 + Output the number of matching threads.
\r
683 + Output the number of files associated with matching
\r
684 + messages. This may be bigger than the number of matching
\r
685 + messages due to duplicates (i.e. multiple files having the
\r
686 + same message-id).
\r
688 + ``--exclude=(true|false)``
\r
689 + Specify whether to omit messages matching search.tag\_exclude
\r
690 + from the count (the default) or not.
\r
693 + Read queries from a file (stdin by default), one per line, and
\r
694 + output the number of matching messages (or threads) to stdout,
\r
695 + one per line. On an empty input line the count of all messages
\r
696 + (or threads) in the database will be output. This option is not
\r
697 + compatible with specifying search terms on the command line.
\r
699 + ``--input=``\ <filename>
\r
700 + Read input from given file, instead of from stdin. Implies
\r
706 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-dump(1)**,
\r
707 +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
708 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
709 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
710 diff --git a/doc/man1/notmuch-dump.rst b/doc/man1/notmuch-dump.rst
\r
711 new file mode 100644
\r
712 index 0000000..17d1da5
\r
714 +++ b/doc/man1/notmuch-dump.rst
\r
723 +**notmuch** **dump** [--format=(batch-tag|sup)] [--] [--output=<*file*>] [--] [<*search-term*> ...]
\r
728 +Dump tags for messages matching the given search terms.
\r
730 +Output is to the given filename, if any, or to stdout.
\r
732 +These tags are the only data in the notmuch database that can't be
\r
733 +recreated from the messages themselves. The output of notmuch dump is
\r
734 +therefore the only critical thing to backup (and much more friendly to
\r
735 +incremental backup than the native database files.)
\r
737 +``--format=(sup|batch-tag)``
\r
738 + Notmuch restore supports two plain text dump formats, both with one
\r
739 + message-id per line, followed by a list of tags.
\r
742 + The default **batch-tag** dump format is intended to more robust
\r
743 + against malformed message-ids and tags containing whitespace or
\r
744 + non-\ **ascii(7)** characters. Each line has the form
\r
746 + +<*encoded-tag*\ > +<*encoded-tag*\ > ... --
\r
747 + id:<*quoted-message-id*\ >
\r
749 + Tags are hex-encoded by replacing every byte not matching the
\r
750 + regex **[A-Za-z0-9@=.,\_+-]** with **%nn** where nn is the two
\r
751 + digit hex encoding. The message ID is a valid Xapian query,
\r
752 + quoted using Xapian boolean term quoting rules: if the ID
\r
753 + contains whitespace or a close paren or starts with a double
\r
754 + quote, it must be enclosed in double quotes and double quotes
\r
755 + inside the ID must be doubled. The astute reader will notice
\r
756 + this is a special case of the batch input format for
\r
757 + **notmuch-tag(1)**; note that the single message-id query is
\r
758 + mandatory for **notmuch-restore(1)**.
\r
761 + The **sup** dump file format is specifically chosen to be
\r
762 + compatible with the format of files produced by sup-dump. So if
\r
763 + you've previously been using sup for mail, then the **notmuch
\r
764 + restore** command provides you a way to import all of your tags
\r
765 + (or labels as sup calls them). Each line has the following form
\r
767 + <*message-id*\ > **(** <*tag*\ > ... **)**
\r
769 + with zero or more tags are separated by spaces. Note that
\r
770 + (malformed) message-ids may contain arbitrary non-null
\r
771 + characters. Note also that tags with spaces will not be
\r
772 + correctly restored with this format.
\r
774 + With no search terms, a dump of all messages in the database will be
\r
775 + generated. A "--" argument instructs notmuch that the remaining
\r
776 + arguments are search terms.
\r
778 + See **notmuch-search-terms(7)** for details of the supported syntax
\r
779 + for <search-terms>.
\r
784 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
785 +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
786 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
787 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
788 diff --git a/doc/man1/notmuch-insert.rst b/doc/man1/notmuch-insert.rst
\r
789 new file mode 100644
\r
790 index 0000000..2be1a7b
\r
792 +++ b/doc/man1/notmuch-insert.rst
\r
801 +**notmuch** **insert** [option ...] [+<*tag*>|-<*tag*> ...]
\r
806 +**notmuch insert** reads a message from standard input and delivers it
\r
807 +into the maildir directory given by configuration option
\r
808 +**database.path**, then incorporates the message into the notmuch
\r
809 +database. It is an alternative to using a separate tool to deliver the
\r
810 +message then running **notmuch new** afterwards.
\r
812 +The new message will be tagged with the tags specified by the
\r
813 +**new.tags** configuration option, then by operations specified on the
\r
814 +command-line: tags prefixed by '+' are added while those prefixed by '-'
\r
817 +If the new message is a duplicate of an existing message in the database
\r
818 +(it has same Message-ID), it will be added to the maildir folder and
\r
819 +notmuch database, but the tags will not be changed.
\r
821 +Option arguments must appear before any tag operation arguments.
\r
822 +Supported options for **insert** include
\r
824 + ``--folder=<``\ folder\ **>**
\r
825 + Deliver the message to the specified folder, relative to the
\r
826 + top-level directory given by the value of **database.path**. The
\r
827 + default is to deliver to the top-level directory.
\r
829 + ``--create-folder``
\r
830 + Try to create the folder named by the ``--folder`` option, if it
\r
831 + does not exist. Otherwise the folder must already exist for mail
\r
832 + delivery to succeed.
\r
837 +This command returns exit status 0 if the message was successfully added
\r
838 +to the mail directory, even if the message could not be indexed and
\r
839 +added to the notmuch database. In the latter case, a warning will be
\r
840 +printed to standard error but the message file will be left on disk.
\r
842 +If the message could not be written to disk then a non-zero exit status
\r
848 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
849 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-reply(1)**,
\r
850 +**notmuch-restore(1)**, **notmuch-search(1)**,
\r
851 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
852 diff --git a/doc/man1/notmuch-new.rst b/doc/man1/notmuch-new.rst
\r
853 new file mode 100644
\r
854 index 0000000..d11fcee
\r
856 +++ b/doc/man1/notmuch-new.rst
\r
865 +**notmuch** **new** [--no-hooks]
\r
870 +Find and import any new messages to the database.
\r
872 +The **new** command scans all sub-directories of the database,
\r
873 +performing full-text indexing on new messages that are found. Each new
\r
874 +message will automatically be tagged with both the **inbox** and
\r
877 +You should run **notmuch new** once after first running **notmuch
\r
878 +setup** to create the initial database. The first run may take a long
\r
879 +time if you have a significant amount of mail (several hundred thousand
\r
880 +messages or more). Subsequently, you should run **notmuch new** whenever
\r
881 +new mail is delivered and you wish to incorporate it into the database.
\r
882 +These subsequent runs will be much quicker than the initial run.
\r
884 +Invoking ``notmuch`` with no command argument will run **new** if
\r
885 +**notmuch setup** has previously been completed, but **notmuch new** has
\r
886 +not previously been run.
\r
888 +**notmuch new** updates tags according to maildir flag changes if the
\r
889 +**maildir.synchronize\_flags** configuration option is enabled. See
\r
890 +**notmuch-config(1)** for details.
\r
892 +The **new** command supports hooks. See **notmuch-hooks(5)** for more
\r
895 +Supported options for **new** include
\r
898 + Prevents hooks from being run.
\r
901 + Do not print progress or results.
\r
906 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
907 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
908 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
909 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
910 diff --git a/doc/man1/notmuch-reply.rst b/doc/man1/notmuch-reply.rst
\r
911 new file mode 100644
\r
912 index 0000000..cfbd4ea
\r
914 +++ b/doc/man1/notmuch-reply.rst
\r
923 +**notmuch** **reply** [option ...] <*search-term*> ...
\r
928 +Constructs a reply template for a set of messages.
\r
930 +To make replying to email easier, **notmuch reply** takes an existing
\r
931 +set of messages and constructs a suitable mail template. The Reply-to:
\r
932 +header (if any, otherwise From:) is used for the To: address. Unless
\r
933 +``--reply-to=sender`` is specified, values from the To: and Cc: headers
\r
934 +are copied, but not including any of the current user's email addresses
\r
935 +(as configured in primary\_mail or other\_email in the .notmuch-config
\r
936 +file) in the recipient list.
\r
938 +It also builds a suitable new subject, including Re: at the front (if
\r
939 +not already present), and adding the message IDs of the messages being
\r
940 +replied to to the References list and setting the In-Reply-To: field
\r
943 +Finally, the original contents of the emails are quoted by prefixing
\r
944 +each line with '> ' and included in the body.
\r
946 +The resulting message template is output to stdout.
\r
948 +Supported options for **reply** include
\r
950 + ``--format=``\ (**default**\ \|\ **json**\ \|\ **sexp**\ \|\ **headers-only**)
\r
953 + Includes subject and quoted message body as an RFC 2822
\r
957 + Produces JSON output containing headers for a reply message
\r
958 + and the contents of the original message. This output can be
\r
959 + used by a client to create a reply message intelligently.
\r
962 + Produces S-Expression output containing headers for a reply
\r
963 + message and the contents of the original message. This
\r
964 + output can be used by a client to create a reply message
\r
968 + Only produces In-Reply-To, References, To, Cc, and Bcc
\r
971 + ``--format-version=N``
\r
972 + Use the specified structured output format version. This is
\r
973 + intended for programs that invoke **notmuch(1)** internally. If
\r
974 + omitted, the latest supported version will be used.
\r
976 + ``--reply-to=``\ (**all**\ \|\ **sender**)
\r
978 + **all** (default)
\r
979 + Replies to all addresses.
\r
982 + Replies only to the sender. If replying to user's own
\r
983 + message (Reply-to: or From: header is one of the user's
\r
984 + configured email addresses), try To:, Cc:, and Bcc: headers
\r
985 + in this order, and copy values from the first that contains
\r
986 + something other than only the user's addresses.
\r
989 + Decrypt any MIME encrypted parts found in the selected content
\r
990 + (ie. "multipart/encrypted" parts). Status of the decryption will
\r
991 + be reported (currently only supported with --format=json and
\r
992 + --format=sexp) and on successful decryption the
\r
993 + multipart/encrypted part will be replaced by the decrypted
\r
996 + Decryption expects a functioning **gpg-agent(1)** to provide any
\r
997 + needed credentials. Without one, the decryption will fail.
\r
999 +See **notmuch-search-terms(7)** for details of the supported syntax for
\r
1002 +Note: It is most common to use **notmuch reply** with a search string
\r
1003 +matching a single message, (such as id:<message-id>), but it can be
\r
1004 +useful to reply to several messages at once. For example, when a series
\r
1005 +of patches are sent in a single thread, replying to the entire thread
\r
1006 +allows for the reply to comment on issues found in multiple patches. The
\r
1007 +default format supports replying to multiple messages at once, but the
\r
1008 +JSON and S-Expression formats do not.
\r
1013 +This command supports the following special exit status codes
\r
1016 + The requested format version is too old.
\r
1019 + The requested format version is too new.
\r
1024 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1025 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
1026 +**notmuch-new(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
1027 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1028 diff --git a/doc/man1/notmuch-restore.rst b/doc/man1/notmuch-restore.rst
\r
1029 new file mode 100644
\r
1030 index 0000000..d6cf19a
\r
1032 +++ b/doc/man1/notmuch-restore.rst
\r
1041 +**notmuch** **restore** [--accumulate] [--format=(auto|batch-tag|sup)] [--input=<*filename*>]
\r
1046 +Restores the tags from the given file (see **notmuch dump**).
\r
1048 +The input is read from the given filename, if any, or from stdin.
\r
1050 +Supported options for **restore** include
\r
1052 + ``--accumulate``
\r
1053 + The union of the existing and new tags is applied, instead of
\r
1054 + replacing each message's tags as they are read in from the dump
\r
1057 + ``--format=(sup|batch-tag|auto)``
\r
1058 + Notmuch restore supports two plain text dump formats, with each
\r
1059 + line specifying a message-id and a set of tags. For details of
\r
1060 + the actual formats, see **notmuch-dump(1)**.
\r
1063 + The **sup** dump file format is specifically chosen to be
\r
1064 + compatible with the format of files produced by sup-dump. So
\r
1065 + if you've previously been using sup for mail, then the
\r
1066 + **notmuch restore** command provides you a way to import all
\r
1067 + of your tags (or labels as sup calls them).
\r
1070 + The **batch-tag** dump format is intended to more robust
\r
1071 + against malformed message-ids and tags containing whitespace
\r
1072 + or non-\ **ascii(7)** characters. See **notmuch-dump(1)**
\r
1073 + for details on this format.
\r
1075 + **notmuch restore** updates the maildir flags according to
\r
1076 + tag changes if the **maildir.synchronize\_flags**
\r
1077 + configuration option is enabled. See **notmuch-config(1)**
\r
1081 + This option (the default) tries to guess the format from the
\r
1082 + input. For correctly formed input in either supported
\r
1083 + format, this heuristic, based the fact that batch-tag format
\r
1084 + contains no parentheses, should be accurate.
\r
1089 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1090 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
1091 +**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-search(1)**,
\r
1092 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1093 diff --git a/doc/man1/notmuch-search.rst b/doc/man1/notmuch-search.rst
\r
1094 new file mode 100644
\r
1095 index 0000000..7ac6c68
\r
1097 +++ b/doc/man1/notmuch-search.rst
\r
1106 +**notmuch** **search** [*option* ...] <*search-term*> ...
\r
1111 +Search for messages matching the given search terms, and display as
\r
1112 +results the threads containing the matched messages.
\r
1114 +The output consists of one line per thread, giving a thread ID, the date
\r
1115 +of the newest (or oldest, depending on the sort option) matched message
\r
1116 +in the thread, the number of matched messages and total messages in the
\r
1117 +thread, the names of all participants in the thread, and the subject of
\r
1118 +the newest (or oldest) message.
\r
1120 +See **notmuch-search-terms(7)** for details of the supported syntax for
\r
1123 +Supported options for **search** include
\r
1125 + ``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**)
\r
1126 + Presents the results in either JSON, S-Expressions, newline
\r
1127 + character separated plain-text (default), or null character
\r
1128 + separated plain-text (compatible with **xargs(1)** -0 option
\r
1129 + where available).
\r
1131 + ``--format-version=N``
\r
1132 + Use the specified structured output format version. This is
\r
1133 + intended for programs that invoke **notmuch(1)** internally. If
\r
1134 + omitted, the latest supported version will be used.
\r
1136 + ``--output=(summary|threads|messages|files|tags)``
\r
1139 + Output a summary of each thread with any message matching
\r
1140 + the search terms. The summary includes the thread ID, date,
\r
1141 + the number of messages in the thread (both the number
\r
1142 + matched and the total number), the authors of the thread and
\r
1146 + Output the thread IDs of all threads with any message
\r
1147 + matching the search terms, either one per line
\r
1148 + (--format=text), separated by null characters
\r
1149 + (--format=text0), as a JSON array (--format=json), or an
\r
1150 + S-Expression list (--format=sexp).
\r
1153 + Output the message IDs of all messages matching the search
\r
1154 + terms, either one per line (--format=text), separated by
\r
1155 + null characters (--format=text0), as a JSON array
\r
1156 + (--format=json), or as an S-Expression list (--format=sexp).
\r
1159 + Output the filenames of all messages matching the search
\r
1160 + terms, either one per line (--format=text), separated by
\r
1161 + null characters (--format=text0), as a JSON array
\r
1162 + (--format=json), or as an S-Expression list (--format=sexp).
\r
1164 + Note that each message may have multiple filenames
\r
1165 + associated with it. All of them are included in the output,
\r
1166 + unless limited with the --duplicate=N option.
\r
1169 + Output all tags that appear on any message matching the
\r
1170 + search terms, either one per line (--format=text), separated
\r
1171 + by null characters (--format=text0), as a JSON array
\r
1172 + (--format=json), or as an S-Expression list (--format=sexp).
\r
1174 + ``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
\r
1175 + This option can be used to present results in either
\r
1176 + chronological order (**oldest-first**) or reverse chronological
\r
1177 + order (**newest-first**).
\r
1179 + Note: The thread order will be distinct between these two
\r
1180 + options (beyond being simply reversed). When sorting by
\r
1181 + **oldest-first** the threads will be sorted by the oldest
\r
1182 + message in each thread, but when sorting by **newest-first** the
\r
1183 + threads will be sorted by the newest message in each thread.
\r
1185 + By default, results will be displayed in reverse chronological
\r
1186 + order, (that is, the newest results will be displayed first).
\r
1188 + ``--offset=[-]N``
\r
1189 + Skip displaying the first N results. With the leading '-', start
\r
1190 + at the Nth result from the end.
\r
1193 + Limit the number of displayed results to N.
\r
1195 + ``--exclude=(true|false|all|flag)``
\r
1196 + A message is called "excluded" if it matches at least one tag in
\r
1197 + search.tag\_exclude that does not appear explicitly in the
\r
1198 + search terms. This option specifies whether to omit excluded
\r
1199 + messages in the search process.
\r
1201 + The default value, **true**, prevents excluded messages from
\r
1202 + matching the search terms.
\r
1204 + **all** additionally prevents excluded messages from appearing
\r
1205 + in displayed results, in effect behaving as though the excluded
\r
1206 + messages do not exist.
\r
1208 + **false** allows excluded messages to match search terms and
\r
1209 + appear in displayed results. Excluded messages are still marked
\r
1210 + in the relevant outputs.
\r
1212 + **flag** only has an effect when ``--output=summary``. The
\r
1213 + output is almost identical to **false**, but the "match count"
\r
1214 + is the number of matching non-excluded messages in the thread,
\r
1215 + rather than the number of matching messages.
\r
1217 + ``--duplicate=N``
\r
1218 + Effective with ``--output=files``, output the Nth filename
\r
1219 + associated with each message matching the query (N is 1-based).
\r
1220 + If N is greater than the number of files associated with the
\r
1221 + message, don't print anything.
\r
1223 + Note that this option is orthogonal with the **folder:** search
\r
1224 + prefix. The prefix matches messages based on filenames. This
\r
1225 + option filters filenames of the matching messages.
\r
1230 +This command supports the following special exit status codes
\r
1233 + The requested format version is too old.
\r
1236 + The requested format version is too new.
\r
1241 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1242 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
1243 +**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
\r
1244 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1245 diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst
\r
1246 new file mode 100644
\r
1247 index 0000000..bad868b
\r
1249 +++ b/doc/man1/notmuch-show.rst
\r
1258 +**notmuch** **show** [*option* ...] <*search-term*> ...
\r
1263 +Shows all messages matching the search terms.
\r
1265 +See **notmuch-search-terms(7)** for details of the supported syntax for
\r
1268 +The messages will be grouped and sorted based on the threading (all
\r
1269 +replies to a particular message will appear immediately after that
\r
1270 +message in date order). The output is not indented by default, but depth
\r
1271 +tags are printed so that proper indentation can be performed by a
\r
1272 +post-processor (such as the emacs interface to notmuch).
\r
1274 +Supported options for **show** include
\r
1276 + ``--entire-thread=(true|false)``
\r
1277 + If true, **notmuch show** outputs all messages in the thread of
\r
1278 + any message matching the search terms; if false, it outputs only
\r
1279 + the matching messages. For ``--format=json`` and
\r
1280 + ``--format=sexp`` this defaults to true. For other formats, this
\r
1281 + defaults to false.
\r
1283 + ``--format=(text|json|sexp|mbox|raw)``
\r
1285 + **text** (default for messages)
\r
1286 + The default plain-text format has all text-content MIME
\r
1287 + parts decoded. Various components in the output,
\r
1288 + (**message**, **header**, **body**, **attachment**, and MIME
\r
1289 + **part**), will be delimited by easily-parsed markers. Each
\r
1290 + marker consists of a Control-L character (ASCII decimal 12),
\r
1291 + the name of the marker, and then either an opening or
\r
1292 + closing brace, ('{' or '}'), to either open or close the
\r
1293 + component. For a multipart MIME message, these parts will be
\r
1297 + The output is formatted with Javascript Object Notation
\r
1298 + (JSON). This format is more robust than the text format for
\r
1299 + automated processing. The nested structure of multipart MIME
\r
1300 + messages is reflected in nested JSON output. By default JSON
\r
1301 + output includes all messages in a matching thread; that is,
\r
1304 + ``--format=json`` sets ``--entire-thread`` The caller can
\r
1305 + disable this behaviour by setting ``--entire-thread=false``
\r
1308 + The output is formatted as an S-Expression (sexp). This
\r
1309 + format is more robust than the text format for automated
\r
1310 + processing. The nested structure of multipart MIME messages
\r
1311 + is reflected in nested S-Expression output. By default,
\r
1312 + S-Expression output includes all messages in a matching
\r
1313 + thread; that is, by default,
\r
1315 + ``--format=sexp`` sets ``--entire-thread`` The caller can
\r
1316 + disable this behaviour by setting ``--entire-thread=false``
\r
1319 + All matching messages are output in the traditional, Unix
\r
1320 + mbox format with each message being prefixed by a line
\r
1321 + beginning with "From " and a blank line separating each
\r
1322 + message. Lines in the message content beginning with "From "
\r
1323 + (preceded by zero or more '>' characters) have an additional
\r
1324 + '>' character added. This reversible escaping is termed
\r
1325 + "mboxrd" format and described in detail here:
\r
1327 + http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
\r
1329 + **raw** (default for a single part, see --part)
\r
1330 + For a message or an attached message part, the original, raw
\r
1331 + content of the email message is output. Consumers of this
\r
1332 + format should expect to implement MIME decoding and similar
\r
1335 + For a single part (--part) the raw part content is output
\r
1336 + after performing any necessary MIME decoding. Note that
\r
1337 + messages with a simple body still have two parts: part 0 is
\r
1338 + the whole message and part 1 is the body.
\r
1340 + For a multipart part, the part headers and body (including
\r
1341 + all child parts) is output.
\r
1343 + The raw format must only be used with search terms matching
\r
1346 + ``--format-version=N``
\r
1347 + Use the specified structured output format version. This is
\r
1348 + intended for programs that invoke **notmuch(1)** internally. If
\r
1349 + omitted, the latest supported version will be used.
\r
1352 + Output the single decoded MIME part N of a single message. The
\r
1353 + search terms must match only a single message. Message parts are
\r
1354 + numbered in a depth-first walk of the message MIME structure,
\r
1355 + and are identified in the 'json', 'sexp' or 'text' output
\r
1359 + Compute and report the validity of any MIME cryptographic
\r
1360 + signatures found in the selected content (ie. "multipart/signed"
\r
1361 + parts). Status of the signature will be reported (currently only
\r
1362 + supported with --format=json and --format=sexp), and the
\r
1363 + multipart/signed part will be replaced by the signed data.
\r
1366 + Decrypt any MIME encrypted parts found in the selected content
\r
1367 + (ie. "multipart/encrypted" parts). Status of the decryption will
\r
1368 + be reported (currently only supported with --format=json and
\r
1369 + --format=sexp) and on successful decryption the
\r
1370 + multipart/encrypted part will be replaced by the decrypted
\r
1373 + Decryption expects a functioning **gpg-agent(1)** to provide any
\r
1374 + needed credentials. Without one, the decryption will fail.
\r
1376 + Implies --verify.
\r
1378 + ``--exclude=(true|false)``
\r
1379 + Specify whether to omit threads only matching
\r
1380 + search.tag\_exclude from the search results (the default) or
\r
1381 + not. In either case the excluded message will be marked with the
\r
1382 + exclude flag (except when output=mbox when there is nowhere to
\r
1385 + If --entire-thread is specified then complete threads are
\r
1386 + returned regardless (with the excluded flag being set when
\r
1387 + appropriate) but threads that only match in an excluded message
\r
1388 + are not returned when ``--exclude=true.``
\r
1390 + The default is ``--exclude=true.``
\r
1392 + ``--body=(true|false)``
\r
1393 + If true (the default) **notmuch show** includes the bodies of
\r
1394 + the messages in the output; if false, bodies are omitted.
\r
1395 + ``--body=false`` is only implemented for the json and sexp
\r
1396 + formats and it is incompatible with ``--part > 0.``
\r
1398 + This is useful if the caller only needs the headers as body-less
\r
1399 + output is much faster and substantially smaller.
\r
1401 + ``--include-html``
\r
1402 + Include "text/html" parts as part of the output (currently only
\r
1403 + supported with --format=json and --format=sexp). By default,
\r
1404 + unless ``--part=N`` is used to select a specific part or
\r
1405 + ``--include-html`` is used to include all "text/html" parts, no
\r
1406 + part with content type "text/html" is included in the output.
\r
1408 +A common use of **notmuch show** is to display a single thread of email
\r
1409 +messages. For this, use a search term of "thread:<thread-id>" as can be
\r
1410 +seen in the first column of output from the **notmuch search** command.
\r
1415 +This command supports the following special exit status codes
\r
1418 + The requested format version is too old.
\r
1421 + The requested format version is too new.
\r
1426 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1427 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
1428 +**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
\r
1429 +**notmuch-search(1)**, **notmuch-search-terms(7)**, **notmuch-tag(1)**
\r
1430 diff --git a/doc/man1/notmuch-tag.rst b/doc/man1/notmuch-tag.rst
\r
1431 new file mode 100644
\r
1432 index 0000000..2e7e1d3
\r
1434 +++ b/doc/man1/notmuch-tag.rst
\r
1443 +**notmuch** **tag** [options ...] +<*tag*>|-<*tag*> [--] <*search-term*> ...
\r
1445 +**notmuch** **tag** **--batch** [--input=<*filename*>]
\r
1450 +Add/remove tags for all messages matching the search terms.
\r
1452 +See **notmuch-search-terms(7)** for details of the supported syntax for
\r
1453 +<*search-term*\ >.
\r
1455 +Tags prefixed by '+' are added while those prefixed by '-' are removed.
\r
1456 +For each message, tag changes are applied in the order they appear on
\r
1457 +the command line.
\r
1459 +The beginning of the search terms is recognized by the first argument
\r
1460 +that begins with neither '+' nor '-'. Support for an initial search term
\r
1461 +beginning with '+' or '-' is provided by allowing the user to specify a
\r
1462 +"--" argument to separate the tags from the search terms.
\r
1464 +**notmuch tag** updates the maildir flags according to tag changes if
\r
1465 +the **maildir.synchronize\_flags** configuration option is enabled. See
\r
1466 +**notmuch-config(1)** for details.
\r
1468 +Supported options for **tag** include
\r
1470 + ``--remove-all``
\r
1471 + Remove all tags from each message matching the search terms
\r
1472 + before applying the tag changes appearing on the command line.
\r
1473 + This means setting the tags of each message to the tags to be
\r
1474 + added. If there are no tags to be added, the messages will have
\r
1478 + Read batch tagging operations from a file (stdin by default).
\r
1479 + This is more efficient than repeated **notmuch tag**
\r
1480 + invocations. See `TAG FILE FORMAT <#tag_file_format>`__ below
\r
1481 + for the input format. This option is not compatible with
\r
1482 + specifying tagging on the command line.
\r
1484 + ``--input=``\ <filename>
\r
1485 + Read input from given file, instead of from stdin. Implies
\r
1491 +The input must consist of lines of the format:
\r
1493 ++<*tag*\ >\|-<*tag*\ > [...] [--] <*query*\ >
\r
1495 +Each line is interpreted similarly to **notmuch tag** command line
\r
1496 +arguments. The delimiter is one or more spaces ' '. Any characters in
\r
1497 +<*tag*\ > **may** be hex-encoded with %NN where NN is the hexadecimal
\r
1498 +value of the character. To hex-encode a character with a multi-byte
\r
1499 +UTF-8 encoding, hex-encode each byte. Any spaces in <tag> **must** be
\r
1500 +hex-encoded as %20. Any characters that are not part of <*tag*\ > **must
\r
1501 +not** be hex-encoded.
\r
1503 +In the future tag:"tag with spaces" style quoting may be supported for
\r
1504 +<*tag*\ > as well; for this reason all double quote characters in
\r
1505 +<*tag*\ > **should** be hex-encoded.
\r
1507 +The <*query*\ > should be quoted using Xapian boolean term quoting
\r
1508 +rules: if a term contains whitespace or a close paren or starts with a
\r
1509 +double quote, it must be enclosed in double quotes (not including any
\r
1510 +prefix) and double quotes inside the term must be doubled (see below for
\r
1513 +Leading and trailing space ' ' is ignored. Empty lines and lines
\r
1514 +beginning with '#' are ignored.
\r
1519 +The following shows a valid input to batch tagging. Note that only the
\r
1520 +isolated '\*' acts as a wildcard. Also note the two different quotings
\r
1521 +of the tag **space in tags**
\r
1526 + +foo::bar%25 -- (One and Two) or (One and tag:winner)
\r
1527 + +found::it -- tag:foo::bar%
\r
1528 + # ignore this line and the next
\r
1530 + +space%20in%20tags -- Two
\r
1531 + # add tag '(tags)', among other stunts.
\r
1532 + +crazy{ +(tags) +&are +#possible\ -- tag:"space in tags"
\r
1533 + +match*crazy -- tag:crazy{
\r
1534 + +some_tag -- id:"this is ""nauty)"""
\r
1539 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1540 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
1541 +**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
\r
1542 +**notmuch-search(1)**, **notmuch-search-terms(7)**, **notmuch-show(1)**,
\r
1543 diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst
\r
1544 new file mode 100644
\r
1545 index 0000000..9710294
\r
1547 +++ b/doc/man1/notmuch.rst
\r
1556 +**notmuch** [option ...] **command** [arg ...]
\r
1561 +Notmuch is a command-line based program for indexing, searching,
\r
1562 +reading, and tagging large collections of email messages.
\r
1564 +This page describes how to get started using notmuch from the command
\r
1565 +line, and gives a brief overview of the commands available. For more
\r
1566 +information on e.g. **notmuch show** consult the **notmuch-show(1)** man
\r
1567 +page, also accessible via **notmuch help show**
\r
1569 +The quickest way to get started with Notmuch is to simply invoke the
\r
1570 +``notmuch`` command with no arguments, which will interactively guide
\r
1571 +you through the process of indexing your mail.
\r
1576 +While the command-line program ``notmuch`` provides powerful
\r
1577 +functionality, it does not provide the most convenient interface for
\r
1578 +that functionality. More sophisticated interfaces are expected to be
\r
1579 +built on top of either the command-line interface, or more likely, on
\r
1580 +top of the notmuch library interface. See http://notmuchmail.org for
\r
1581 +more about alternate interfaces to notmuch. The emacs-based interface to
\r
1582 +notmuch (available under **emacs/** in the Notmuch source distribution)
\r
1583 +is probably the most widely used at this time.
\r
1588 +Supported global options for ``notmuch`` include
\r
1591 + Print a synopsis of available commands and exit.
\r
1594 + Print the installed version of notmuch, and exit.
\r
1596 + ``--config=FILE``
\r
1597 + Specify the configuration file to use. This overrides any
\r
1598 + configuration file specified by ${NOTMUCH\_CONFIG}.
\r
1606 +The **notmuch setup** command is used to configure Notmuch for first
\r
1607 +use, (or to reconfigure it later).
\r
1609 +The setup command will prompt for your full name, your primary email
\r
1610 +address, any alternate email addresses you use, and the directory
\r
1611 +containing your email archives. Your answers will be written to a
\r
1612 +configuration file in ${NOTMUCH\_CONFIG} (if set) or
\r
1613 +${HOME}/.notmuch-config . This configuration file will be created with
\r
1614 +descriptive comments, making it easy to edit by hand later to change the
\r
1615 +configuration. Or you can run **notmuch setup** again to change the
\r
1618 +The mail directory you specify can contain any number of sub-directories
\r
1619 +and should primarily contain only files with individual email messages
\r
1620 +(eg. maildir or mh archives are perfect). If there are other, non-email
\r
1621 +files (such as indexes maintained by other email programs) then notmuch
\r
1622 +will do its best to detect those and ignore them.
\r
1624 +Mail storage that uses mbox format, (where one mbox file contains many
\r
1625 +messages), will not work with notmuch. If that's how your mail is
\r
1626 +currently stored, it is recommended you first convert it to maildir
\r
1627 +format with a utility such as mb2md before running **notmuch setup .**
\r
1629 +Invoking ``notmuch`` with no command argument will run **setup** if the
\r
1630 +setup command has not previously been completed.
\r
1635 +Several of the notmuch commands accept search terms with a common
\r
1636 +syntax. See **notmuch-search-terms**\ (7) for more details on the
\r
1637 +supported syntax.
\r
1639 +The **search**, **show** and **count** commands are used to query the
\r
1642 +The **reply** command is useful for preparing a template for an email
\r
1645 +The **tag** command is the only command available for manipulating
\r
1646 +database contents.
\r
1648 +The **dump** and **restore** commands can be used to create a textual
\r
1649 +dump of email tags for backup purposes, and to restore from that dump.
\r
1651 +The **config** command can be used to get or set settings in the notmuch
\r
1652 +configuration file.
\r
1657 +The following environment variables can be used to control the behavior
\r
1660 +**NOTMUCH\_CONFIG**
\r
1661 + Specifies the location of the notmuch configuration file. Notmuch
\r
1662 + will use ${HOME}/.notmuch-config if this variable is not set.
\r
1664 +**NOTMUCH\_TALLOC\_REPORT**
\r
1665 + Location to write a talloc memory usage report. See
\r
1666 + **talloc\_enable\_leak\_report\_full** in **talloc(3)** for more
\r
1669 +**NOTMUCH\_DEBUG\_QUERY**
\r
1670 + If set to a non-empty value, the notmuch library will print (to
\r
1671 + stderr) Xapian queries it constructs.
\r
1676 +**notmuch-config(1)**, **notmuch-count(1)**, **notmuch-dump(1)**,
\r
1677 +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
1678 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
1679 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1681 +The notmuch website: **http://notmuchmail.org**
\r
1686 +Feel free to send questions, comments, or kudos to the notmuch mailing
\r
1687 +list <notmuch@notmuchmail.org> . Subscription is not required before
\r
1688 +posting, but is available from the notmuchmail.org website.
\r
1690 +Real-time interaction with the Notmuch community is available via IRC
\r
1691 +(server: irc.freenode.net, channel: #notmuch).
\r
1692 diff --git a/doc/man5/notmuch-hooks.rst b/doc/man5/notmuch-hooks.rst
\r
1693 new file mode 100644
\r
1694 index 0000000..493abf2
\r
1696 +++ b/doc/man5/notmuch-hooks.rst
\r
1705 + $DATABASEDIR/.notmuch/hooks/*
\r
1710 +Hooks are scripts (or arbitrary executables or symlinks to such) that
\r
1711 +notmuch invokes before and after certain actions. These scripts reside
\r
1712 +in the .notmuch/hooks directory within the database directory and must
\r
1713 +have executable permissions.
\r
1715 +The currently available hooks are described below.
\r
1718 + This hook is invoked by the **new** command before scanning or
\r
1719 + importing new messages into the database. If this hook exits
\r
1720 + with a non-zero status, notmuch will abort further processing of
\r
1721 + the **new** command.
\r
1723 + Typically this hook is used for fetching or delivering new mail
\r
1724 + to be imported into the database.
\r
1727 + This hook is invoked by the **new** command after new messages
\r
1728 + have been imported into the database and initial tags have been
\r
1729 + applied. The hook will not be run if there have been any errors
\r
1730 + during the scan or import.
\r
1732 + Typically this hook is used to perform additional query-based
\r
1733 + tagging on the imported messages.
\r
1738 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1739 +**notmuch-dump(1)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
1740 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
1741 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1742 diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst
\r
1743 new file mode 100644
\r
1744 index 0000000..20bc6f1
\r
1746 +++ b/doc/man7/notmuch-search-terms.rst
\r
1748 +====================
\r
1749 +notmuch-search-terms
\r
1750 +====================
\r
1755 +**notmuch** **count** [option ...] <*search-term*> ...
\r
1757 +**notmuch** **dump** [--format=(batch-tag|sup)] [--] [--output=<*file*>] [--] [<*search-term*> ...]
\r
1759 +**notmuch** **search** [option ...] <*search-term*> ...
\r
1761 +**notmuch** **show** [option ...] <*search-term*> ...
\r
1763 +**notmuch** **tag** +<*tag*> ... -<*tag*> [--] <*search-term*> ...
\r
1768 +Several notmuch commands accept a common syntax for search terms.
\r
1770 +The search terms can consist of free-form text (and quoted phrases)
\r
1771 +which will match all messages that contain all of the given
\r
1772 +terms/phrases in the body, the subject, or any of the sender or
\r
1773 +recipient headers.
\r
1775 +As a special case, a search string consisting of exactly a single
\r
1776 +asterisk ("\*") will match all messages.
\r
1778 +In addition to free text, the following prefixes can be used to force
\r
1779 +terms to match against specific portions of an email, (where <brackets>
\r
1780 +indicate user-supplied values):
\r
1782 +- from:<name-or-address>
\r
1784 +- to:<name-or-address>
\r
1786 +- subject:<word-or-quoted-phrase>
\r
1788 +- attachment:<word>
\r
1790 +- tag:<tag> (or is:<tag>)
\r
1792 +- id:<message-id>
\r
1794 +- thread:<thread-id>
\r
1796 +- folder:<directory-path>
\r
1798 +- date:<since>..<until>
\r
1800 +The **from:** prefix is used to match the name or address of the sender
\r
1801 +of an email message.
\r
1803 +The **to:** prefix is used to match the names or addresses of any
\r
1804 +recipient of an email message, (whether To, Cc, or Bcc).
\r
1806 +Any term prefixed with **subject:** will match only text from the
\r
1807 +subject of an email. Searching for a phrase in the subject is supported
\r
1808 +by including quotation marks around the phrase, immediately following
\r
1811 +The **attachment:** prefix can be used to search for specific filenames
\r
1812 +(or extensions) of attachments to email messages.
\r
1814 +For **tag:** and **is:** valid tag values include **inbox** and
\r
1815 +**unread** by default for new messages added by **notmuch new** as well
\r
1816 +as any other tag values added manually with **notmuch tag**.
\r
1818 +For **id:**, message ID values are the literal contents of the
\r
1819 +Message-ID: header of email messages, but without the '<', '>'
\r
1822 +The **thread:** prefix can be used with the thread ID values that are
\r
1823 +generated internally by notmuch (and do not appear in email messages).
\r
1824 +These thread ID values can be seen in the first column of output from
\r
1825 +**notmuch search**
\r
1827 +The **folder:** prefix can be used to search for email message files
\r
1828 +that are contained within particular directories within the mail store.
\r
1829 +If the same email message has multiple message files associated with it,
\r
1830 +it's sufficient for a match that at least one of the files is contained
\r
1831 +within a matching directory. Only the directory components below the
\r
1832 +top-level mail database path are available to be searched.
\r
1834 +The **date:** prefix can be used to restrict the results to only
\r
1835 +messages within a particular time range (based on the Date: header) with
\r
1836 +a range syntax of:
\r
1838 +date:<since>..<until>
\r
1840 +See **DATE AND TIME SEARCH** below for details on the range expression,
\r
1841 +and supported syntax for <since> and <until> date and time expressions.
\r
1843 +The time range can also be specified using timestamps with a syntax of:
\r
1845 +<initial-timestamp>..<final-timestamp>
\r
1847 +Each timestamp is a number representing the number of seconds since
\r
1848 +1970-01-01 00:00:00 UTC.
\r
1850 +In addition to individual terms, multiple terms can be combined with
\r
1851 +Boolean operators ( **and**, **or**, **not** , etc.). Each term in the
\r
1852 +query will be implicitly connected by a logical AND if no explicit
\r
1853 +operator is provided, (except that terms with a common prefix will be
\r
1854 +implicitly combined with OR until we get Xapian defect #402 fixed).
\r
1856 +Parentheses can also be used to control the combination of the Boolean
\r
1857 +operators, but will have to be protected from interpretation by the
\r
1858 +shell, (such as by putting quotation marks around any parenthesized
\r
1861 +DATE AND TIME SEARCH
\r
1862 +====================
\r
1864 +notmuch understands a variety of standard and natural ways of expressing
\r
1865 +dates and times, both in absolute terms ("2012-10-24") and in relative
\r
1866 +terms ("yesterday"). Any number of relative terms can be combined ("1
\r
1867 +hour 25 minutes") and an absolute date/time can be combined with
\r
1868 +relative terms to further adjust it. A non-exhaustive description of the
\r
1869 +syntax supported for absolute and relative terms is given below.
\r
1871 +The range expression
\r
1872 +--------------------
\r
1874 +date:<since>..<until>
\r
1876 +The above expression restricts the results to only messages from <since>
\r
1877 +to <until>, based on the Date: header.
\r
1879 +<since> and <until> can describe imprecise times, such as "yesterday".
\r
1880 +In this case, <since> is taken as the earliest time it could describe
\r
1881 +(the beginning of yesterday) and <until> is taken as the latest time it
\r
1882 +could describe (the end of yesterday). Similarly, date:january..february
\r
1883 +matches from the beginning of January to the end of February.
\r
1885 +Currently, we do not support spaces in range expressions. You can
\r
1886 +replace the spaces with '\_', or (in most cases) '-', or (in some cases)
\r
1887 +leave the spaces out altogether. Examples in this man page use spaces
\r
1890 +Open-ended ranges are supported (since Xapian 1.2.1), i.e. it's possible
\r
1891 +to specify date:..<until> or date:<since>.. to not limit the start or
\r
1892 +end time, respectively. Pre-1.2.1 Xapian does not report an error on
\r
1893 +open ended ranges, but it does not work as expected either.
\r
1895 +Entering date:expr without ".." (for example date:yesterday) won't work,
\r
1896 +as it's not interpreted as a range expression at all. You can achieve
\r
1897 +the expected result by duplicating the expr both sides of ".." (for
\r
1898 +example date:yesterday..yesterday).
\r
1900 +Relative date and time
\r
1901 +----------------------
\r
1904 +(years\|months\|weeks\|days\|hours\|hrs\|minutes\|mins\|seconds\|secs)
\r
1907 +All refer to past, can be repeated and will be accumulated.
\r
1909 +Units can be abbreviated to any length, with the otherwise ambiguous
\r
1910 +single m being m for minutes and M for months.
\r
1912 +Number can also be written out one, two, ..., ten, dozen, hundred.
\r
1913 +Additionally, the unit may be preceded by "last" or "this" (e.g., "last
\r
1914 +week" or "this month").
\r
1916 +When combined with absolute date and time, the relative date and time
\r
1917 +specification will be relative from the specified absolute date and
\r
1920 +Examples: 5M2d, two weeks
\r
1922 +Supported absolute time formats
\r
1923 +-------------------------------
\r
1925 +- H[H]:MM[:SS] [(am\|a.m.\|pm\|p.m.)]
\r
1927 +- H[H] (am\|a.m.\|pm\|p.m.)
\r
1937 +- Examples: 17:05, 5pm
\r
1939 +Supported absolute date formats
\r
1940 +-------------------------------
\r
1948 +- M[M]/D[D][/[YY]YY]
\r
1952 +- D[D].M[M][.[YY]YY]
\r
1954 +- D[D][(st\|nd\|rd\|th)] Mon[thname] [YYYY]
\r
1956 +- Mon[thname] D[D][(st\|nd\|rd\|th)] [YYYY]
\r
1960 +Month names can be abbreviated at three or more characters.
\r
1962 +Weekday names can be abbreviated at three or more characters.
\r
1964 +Examples: 2012-07-31, 31-07-2012, 7/31/2012, August 3
\r
1973 +Some time zone codes, e.g. UTC, EET.
\r
1978 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1979 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
1980 +**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
\r
1981 +**notmuch-search(1)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1982 diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
\r
1983 new file mode 100644
\r
1984 index 0000000..28301b3
\r
1986 +++ b/doc/notmuch-emacs.rst
\r
1992 +About this Manual
\r
1993 +=================
\r
1995 +This manual covers only the emacs interface to notmuch. For information
\r
1996 +on the command line interface, see See section “Description” in Notmuch
\r
1997 +Manual Pager. To save typing, we will sometimes use *notmuch* in this
\r
1998 +manual to refer to the Emacs interface to notmuch. If the distinction
\r
1999 +should every be important, we’ll refer to the Emacs inteface as
\r
2002 +Notmuch-emacs is highly customizable via the the Emacs customization
\r
2003 +framework (or just by setting the appropriate variables). We try to
\r
2004 +point out relevant variables in this manual, but in order to avoid
\r
2005 +duplication of information, but you can usually find the most detailed
\r
2006 +description in the varables docstring.
\r
2012 + single: notmuch-hello
\r
2015 +``notmuch-hello`` is the main entry point for notmuch. You can start it
\r
2016 +with ``M-x notmuch`` or ``M-x notmuch-hello``. The startup screen looks
\r
2017 +something like the following. There are some hints at the bottom of the
\r
2018 +screen. There are three main parts to the notmuch-hello screen,
\r
2019 +discussed below. The **bold** text indicates buttons you can click with
\r
2020 +a mouse or by positioning the cursor and pressing ``<return>``
\r
2022 +| Welcome to **notmuch** You have 52 messages.
\r
2024 +| Saved searches: **[edit]**
\r
2026 +| 52 **inbox** 52 **unread**
\r
2028 +| Search: ____________________________________
\r
2030 +| All tags: **[show]**
\r
2032 +| Type a search query and hit RET to view matching threads.
\r
2033 +| Edit saved searches with the ``edit`` button.
\r
2034 +| Hit RET or click on a saved search or tag name to view matching threads.
\r
2035 +| ``=`` to refresh this screen. ``s`` to search messages. ``q`` to quit.
\r
2036 +| **Customize** this page.
\r
2038 +You can change the overall appearence of the notmuch-hello screen by
\r
2039 +customizing the variable :index:`notmuch-hello-sections`.
\r
2043 +notmuch-hello key bindings
\r
2044 +--------------------------
\r
2047 + Move to the next widget (button or text entry field)
\r
2050 + Move to the previous widget.
\r
2053 + Activate the current widget.
\r
2056 + Refresh the buffer; mainly update the counts of messages for various
\r
2060 + Import mail, See :ref:`importing`
\r
2063 + Compose a message
\r
2066 + Search the notmuch database using :ref:`notmuch-search`
\r
2069 + Print notmuch version
\r
2074 +.. _saved-searches:
\r
2079 +Notmuch replaces the static assignment of messages with the more dynamic
\r
2080 +notion of searching. Notmuch-hello presents the user with a customizable
\r
2081 +set of saved searchs. The initial defaults are ``tag:inbox`` and
\r
2082 +``tag:unread``, but you can customize the following variables
\r
2084 +:index:`notmuch-saved-searches`
\r
2085 + A list of cons pairs, the first being the name to display, the
\r
2086 + second being a query string for notmuch. See section “Description”
\r
2087 + in Notmuch Query Syntax.
\r
2089 +:index:`notmuch-saved-searches-sort-function`
\r
2090 + This variable controls how saved searches should be sorted. A value
\r
2091 + of ``nil`` displays the saved searches in the order they are stored
\r
2092 + in ‘notmuch-saved-searches’.
\r
2094 +:index:`notmuch-column-control`
\r
2095 + Controls the number of columns for displaying saved-searches/tags
\r
2100 +The search box lets the user enter an notmuch query. See section
\r
2101 +“Description” in Notmuch Query Syntax, for more info on notmuch query
\r
2102 +syntax. A history of recent searches is also displayed by default. The
\r
2103 +latter is controlled by the variable :index:`notmuch-hello-recent-searches-max`.
\r
2108 +One special kind of saved search provided by default is for each
\r
2109 +individual tag defined in the database. This can be controlled via the
\r
2110 +following variables.
\r
2112 +:index:`notmuch-hello-tag-list-make-query`
\r
2113 + Control how to construct a search (“virtual folder”) from a given
\r
2116 +:index:`notmuch-hello-hide-tags`
\r
2117 + Which tags not to display at all.
\r
2119 +:index:`notmuch-column-control`
\r
2120 + Controls the number of columns for displaying saved-searches/tags
\r
2122 +.. _notmuch-search:
\r
2127 +``notmuch-search-mode`` is used to display the results from executing
\r
2128 +a query via ``notmuch-search``. The syntax for these queries is the
\r
2129 +the same as :ref:`saved-searches`. For details of this syntax see
\r
2130 +info:notmuch-search-terms
\r
2132 +By default the output approximates that of the command line See section
\r
2133 +“Description” in notmuch search command.
\r
2135 +The main purpose of the ``notmuch-search-mode`` buffer is to act as a
\r
2136 +menu of results that the user can explore further by pressing
\r
2137 +``<return>`` on the appropriate line.
\r
2140 + Move to next line
\r
2143 + Move to previous line
\r
2146 + Open thread on current line in :ref:`notmuch-show` mode
\r
2149 + Display full set of key bindings
\r
2151 +The presentation of results can be controlled by the following
\r
2154 +:index:`notmuch-search-result-format`
\r
2155 + Control how each thread of messages is presented in the
\r
2156 + ``notmuch-show-mode`` buffer
\r
2158 +:index:`notmuch-search-oldest-first`
\r
2159 + Display the oldest threads at the top of the buffer
\r
2161 +.. _notmuch-show:
\r
2177 +:index:`notmuch-poll`
\r
2179 +:index:`notmuch-poll-script`
\r
projects / notmuch-archives.git / blob