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 107D6429E3F
\r
6 for <notmuch@notmuchmail.org>; Tue, 25 Feb 2014 03:53:50 -0800 (PST)
\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 OcmQLBrzxLpm for <notmuch@notmuchmail.org>;
\r
16 Tue, 25 Feb 2014 03:53:36 -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 9F996429E4D
\r
21 for <notmuch@notmuchmail.org>; Tue, 25 Feb 2014 03:53:34 -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 1WIGZj-0007xH-0i; Tue, 25 Feb 2014 07:53:27 -0400
\r
25 Received: (nullmailer pid 17599 invoked by uid 1000); Tue, 25 Feb 2014
\r
27 From: David Bremner <david@tethera.net>
\r
28 To: notmuch@notmuchmail.org
\r
29 Subject: [RFC PATCH v4 1/3] doc: start of sphinx based docs
\r
30 Date: Tue, 25 Feb 2014 07:52:59 -0400
\r
31 Message-Id: <1393329181-17404-2-git-send-email-david@tethera.net>
\r
32 X-Mailer: git-send-email 1.8.5.3
\r
33 In-Reply-To: <1393329181-17404-1-git-send-email-david@tethera.net>
\r
34 References: <1393329181-17404-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: Tue, 25 Feb 2014 11:53:50 -0000
\r
52 This is the output from sphinx-quickstart, massaged a bit, along with
\r
53 a man and texinfo pages all converted to rst.
\r
57 doc/Makefile.local | 28 +++++
\r
58 doc/conf.py | 166 +++++++++++++++++++++++++++
\r
59 doc/index.rst | 31 +++++
\r
60 doc/man1/notmuch-compact.rst | 52 +++++++++
\r
61 doc/man1/notmuch-config.rst | 123 ++++++++++++++++++++
\r
62 doc/man1/notmuch-count.rst | 60 ++++++++++
\r
63 doc/man1/notmuch-dump.rst | 72 ++++++++++++
\r
64 doc/man1/notmuch-insert.rst | 58 ++++++++++
\r
65 doc/man1/notmuch-new.rst | 52 +++++++++
\r
66 doc/man1/notmuch-reply.rst | 112 ++++++++++++++++++
\r
67 doc/man1/notmuch-restore.rst | 59 ++++++++++
\r
68 doc/man1/notmuch-search.rst | 146 ++++++++++++++++++++++++
\r
69 doc/man1/notmuch-show.rst | 181 +++++++++++++++++++++++++++++
\r
70 doc/man1/notmuch-tag.rst | 107 +++++++++++++++++
\r
71 doc/man1/notmuch.rst | 143 +++++++++++++++++++++++
\r
72 doc/man5/notmuch-hooks.rst | 44 +++++++
\r
73 doc/man7/notmuch-search-terms.rst | 234 ++++++++++++++++++++++++++++++++++++++
\r
74 doc/notmuch-emacs.rst | 192 +++++++++++++++++++++++++++++++
\r
75 20 files changed, 1866 insertions(+), 1 deletion(-)
\r
76 create mode 100644 doc/Makefile
\r
77 create mode 100644 doc/Makefile.local
\r
78 create mode 100644 doc/conf.py
\r
79 create mode 100644 doc/index.rst
\r
80 create mode 100644 doc/man1/notmuch-compact.rst
\r
81 create mode 100644 doc/man1/notmuch-config.rst
\r
82 create mode 100644 doc/man1/notmuch-count.rst
\r
83 create mode 100644 doc/man1/notmuch-dump.rst
\r
84 create mode 100644 doc/man1/notmuch-insert.rst
\r
85 create mode 100644 doc/man1/notmuch-new.rst
\r
86 create mode 100644 doc/man1/notmuch-reply.rst
\r
87 create mode 100644 doc/man1/notmuch-restore.rst
\r
88 create mode 100644 doc/man1/notmuch-search.rst
\r
89 create mode 100644 doc/man1/notmuch-show.rst
\r
90 create mode 100644 doc/man1/notmuch-tag.rst
\r
91 create mode 100644 doc/man1/notmuch.rst
\r
92 create mode 100644 doc/man5/notmuch-hooks.rst
\r
93 create mode 100644 doc/man7/notmuch-search-terms.rst
\r
94 create mode 100644 doc/notmuch-emacs.rst
\r
96 diff --git a/Makefile b/Makefile
\r
97 index 0428160..39f0e62 100644
\r
100 @@ -5,7 +5,7 @@ all:
\r
101 # List all subdirectories here. Each contains its own Makefile.local.
\r
102 # Use of '=', without '+=', seems to be required for out-of-tree
\r
104 -subdirs = compat completion emacs lib man parse-time-string performance-test util test
\r
105 +subdirs = compat completion doc emacs lib man parse-time-string performance-test util test
\r
107 # We make all targets depend on the Makefiles themselves.
\r
108 global_deps = Makefile Makefile.config Makefile.local \
\r
109 diff --git a/doc/Makefile b/doc/Makefile
\r
110 new file mode 100644
\r
111 index 0000000..fa25832
\r
116 + $(MAKE) -C .. all
\r
120 diff --git a/doc/Makefile.local b/doc/Makefile.local
\r
121 new file mode 100644
\r
122 index 0000000..d2a339b
\r
124 +++ b/doc/Makefile.local
\r
126 +# Makefile for Sphinx documentation
\r
131 +# You can set these variables from the command line.
\r
132 +SPHINXOPTS := -q -c $(dir)
\r
133 +SPHINXBUILD = sphinx-build
\r
134 +BUILDDIR := $(dir)/_build
\r
136 +# Internal variables.
\r
137 +ALLSPHINXOPTS := -d $(BUILDDIR)/doctrees $(SPHINXOPTS) $(dir)
\r
139 +.PHONY: help clean html man texinfo info
\r
142 + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
\r
145 + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
\r
148 + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
\r
151 + make -C $(BUILDDIR)/texinfo info
\r
153 +CLEAN := $(CLEAN) $(dir)/_build
\r
154 diff --git a/doc/conf.py b/doc/conf.py
\r
155 new file mode 100644
\r
156 index 0000000..d80b2af
\r
161 +# -*- coding: utf-8 -*-
\r
166 +# The suffix of source filenames.
\r
167 +source_suffix = '.rst'
\r
169 +# The master toctree document.
\r
170 +master_doc = 'index'
\r
172 +# General information about the project.
\r
173 +project = u'notmuch'
\r
174 +copyright = u'2014, Carl Worth and many others'
\r
176 +# The short X.Y version.
\r
178 +# The full version, including alpha/beta/rc tags.
\r
181 +# List of patterns, relative to source directory, that match files and
\r
182 +# directories to ignore when looking for source files.
\r
183 +exclude_patterns = ['_build']
\r
185 +# The name of the Pygments (syntax highlighting) style to use.
\r
186 +pygments_style = 'sphinx'
\r
188 +# -- Options for HTML output ----------------------------------------------
\r
190 +# The theme to use for HTML and HTML Help pages. See the documentation for
\r
191 +# a list of builtin themes.
\r
192 +html_theme = 'default'
\r
195 +# Add any paths that contain custom static files (such as style sheets) here,
\r
196 +# relative to this directory. They are copied after the builtin static files,
\r
197 +# so a file named "default.css" will overwrite the builtin "default.css".
\r
198 +html_static_path = ['_static']
\r
200 +# Output file base name for HTML help builder.
\r
201 +htmlhelp_basename = 'notmuchdoc'
\r
203 +# -- Options for manual page output ---------------------------------------
\r
205 +# One entry per manual page. List of tuples
\r
206 +# (source start file, name, description, authors, manual section).
\r
210 +('man1/notmuch','notmuch',
\r
211 + u'thread-based email index, search, and tagging',
\r
212 + [u'Carl Worth and many others'], 1),
\r
214 +('man1/notmuch-compact','notmuch-compact',
\r
215 + u'compact the notmuch database',
\r
216 + [u'Carl Worth and many others'], 1),
\r
218 +('man1/notmuch-config','notmuch-config',
\r
219 + u'access notmuch configuration file',
\r
220 + [u'Carl Worth and many others'], 1),
\r
222 +('man1/notmuch-count','notmuch-count',
\r
223 + u'count messages matching the given search terms',
\r
224 + [u'Carl Worth and many others'], 1),
\r
226 +('man1/notmuch-dump','notmuch-dump',
\r
227 + u'creates a plain-text dump of the tags of each message',
\r
228 + [u'Carl Worth and many others'], 1),
\r
230 +('man5/notmuch-hooks','notmuch-hooks',
\r
231 + u'hooks for notmuch',
\r
232 + [u'Carl Worth and many others'], 5),
\r
234 +('man1/notmuch-insert','notmuch-insert',
\r
235 + u'add a message to the maildir and notmuch database',
\r
236 + [u'Carl Worth and many others'], 1),
\r
238 +('man1/notmuch-new','notmuch-new',
\r
239 + u'incorporate new mail into the notmuch database',
\r
240 + [u'Carl Worth and many others'], 1),
\r
242 +('man1/notmuch-reply','notmuch-reply',
\r
243 + u'constructs a reply template for a set of messages',
\r
244 + [u'Carl Worth and many others'], 1),
\r
246 +('man1/notmuch-restore','notmuch-restore',
\r
247 + u'restores the tags from the given file (see notmuch dump)',
\r
248 + [u'Carl Worth and many others'], 1),
\r
250 +('man1/notmuch-search','notmuch-search',
\r
251 + u'search for messages matching the given search terms',
\r
252 + [u'Carl Worth and many others'], 1),
\r
254 +('man7/notmuch-search-terms','notmuch-search-terms',
\r
255 + u'syntax for notmuch queries',
\r
256 + [u'Carl Worth and many others'], 7),
\r
258 +('man1/notmuch-show','notmuch-show',
\r
259 + u'show messages matching the given search terms',
\r
260 + [u'Carl Worth and many others'], 1),
\r
262 +('man1/notmuch-tag','notmuch-tag',
\r
263 + u'add/remove tags for all messages matching the search terms',
\r
264 + [u'Carl Worth and many others'], 1),
\r
268 +# If true, show URL addresses after external links.
\r
269 +#man_show_urls = False
\r
271 +# -- Options for Texinfo output -------------------------------------------
\r
273 +# Grouping the document tree into Texinfo files. List of tuples
\r
274 +# (source start file, target name, title, author,
\r
275 +# dir menu entry, description, category)
\r
276 +# If true, do not generate a @detailmenu in the "Top" node's menu.
\r
277 +texinfo_no_detailmenu = True
\r
279 +texinfo_documents = [
\r
280 + ('notmuch-emacs', 'notmuch-emacs', u'notmuch Documentation',
\r
281 + u'Carl Worth and many others', 'notmuch-emacs',
\r
282 + 'emacs based front-end for notmuch', 'Miscellaneous'),
\r
283 +('man1/notmuch','notmuch',u'notmuch Documentation',
\r
284 + u'Carl Worth and many others', 'notmuch',
\r
285 + 'thread-based email index, search, and tagging','Miscellaneous'),
\r
286 +('man1/notmuch-compact','notmuch-compact',u'notmuch Documentation',
\r
287 + u'Carl Worth and many others', 'notmuch-compact',
\r
288 + 'compact the notmuch database','Miscellaneous'),
\r
289 +('man1/notmuch-config','notmuch-config',u'notmuch Documentation',
\r
290 + u'Carl Worth and many others', 'notmuch-config',
\r
291 + 'access notmuch configuration file','Miscellaneous'),
\r
292 +('man1/notmuch-count','notmuch-count',u'notmuch Documentation',
\r
293 + u'Carl Worth and many others', 'notmuch-count',
\r
294 + 'count messages matching the given search terms','Miscellaneous'),
\r
295 +('man1/notmuch-dump','notmuch-dump',u'notmuch Documentation',
\r
296 + u'Carl Worth and many others', 'notmuch-dump',
\r
297 + 'creates a plain-text dump of the tags of each message','Miscellaneous'),
\r
298 +('man5/notmuch-hooks','notmuch-hooks',u'notmuch Documentation',
\r
299 + u'Carl Worth and many others', 'notmuch-hooks',
\r
300 + 'hooks for notmuch','Miscellaneous'),
\r
301 +('man1/notmuch-insert','notmuch-insert',u'notmuch Documentation',
\r
302 + u'Carl Worth and many others', 'notmuch-insert',
\r
303 + 'add a message to the maildir and notmuch database','Miscellaneous'),
\r
304 +('man1/notmuch-new','notmuch-new',u'notmuch Documentation',
\r
305 + u'Carl Worth and many others', 'notmuch-new',
\r
306 + 'incorporate new mail into the notmuch database','Miscellaneous'),
\r
307 +('man1/notmuch-reply','notmuch-reply',u'notmuch Documentation',
\r
308 + u'Carl Worth and many others', 'notmuch-reply',
\r
309 + 'constructs a reply template for a set of messages','Miscellaneous'),
\r
310 +('man1/notmuch-restore','notmuch-restore',u'notmuch Documentation',
\r
311 + u'Carl Worth and many others', 'notmuch-restore',
\r
312 + 'restores the tags from the given file (see notmuch dump)','Miscellaneous'),
\r
313 +('man1/notmuch-search','notmuch-search',u'notmuch Documentation',
\r
314 + u'Carl Worth and many others', 'notmuch-search',
\r
315 + 'search for messages matching the given search terms','Miscellaneous'),
\r
316 +('man7/notmuch-search-terms','notmuch-search-terms',u'notmuch Documentation',
\r
317 + u'Carl Worth and many others', 'notmuch-search-terms',
\r
318 + 'syntax for notmuch queries','Miscellaneous'),
\r
319 +('man1/notmuch-show','notmuch-show',u'notmuch Documentation',
\r
320 + u'Carl Worth and many others', 'notmuch-show',
\r
321 + 'show messages matching the given search terms','Miscellaneous'),
\r
322 +('man1/notmuch-tag','notmuch-tag',u'notmuch Documentation',
\r
323 + u'Carl Worth and many others', 'notmuch-tag',
\r
324 + 'add/remove tags for all messages matching the search terms','Miscellaneous'),
\r
326 diff --git a/doc/index.rst b/doc/index.rst
\r
327 new file mode 100644
\r
328 index 0000000..deac9f4
\r
330 +++ b/doc/index.rst
\r
333 +Welcome to notmuch's documentation!
\r
334 +===================================
\r
342 + man1/notmuch-compact
\r
343 + man1/notmuch-config
\r
344 + man1/notmuch-count
\r
345 + man1/notmuch-dump
\r
346 + man5/notmuch-hooks
\r
347 + man1/notmuch-insert
\r
349 + man1/notmuch-reply
\r
350 + man1/notmuch-restore
\r
351 + man1/notmuch-search
\r
352 + man7/notmuch-search-terms
\r
353 + man1/notmuch-show
\r
357 +Indices and tables
\r
358 +==================
\r
363 diff --git a/doc/man1/notmuch-compact.rst b/doc/man1/notmuch-compact.rst
\r
364 new file mode 100644
\r
365 index 0000000..e0109dc
\r
367 +++ b/doc/man1/notmuch-compact.rst
\r
376 +**notmuch** **compact** [--quiet] [--backup=<*directory*>]
\r
381 +The **compact** command can be used to compact the notmuch database.
\r
382 +This can both reduce the space required by the database and improve
\r
383 +lookup performance.
\r
385 +The compacted database is built in a temporary directory and is later
\r
386 +moved into the place of the origin database. The original uncompacted
\r
387 +database is discarded, unless the ``--backup=``\ <directory> option is
\r
390 +Note that the database write lock will be held during the compaction
\r
391 +process (which may be quite long) to protect data integrity.
\r
393 +Supported options for **compact** include
\r
395 + ``--backup=``\ <directory>
\r
396 + Save the current database to the given directory before
\r
397 + replacing it with the compacted database. The backup directory
\r
398 + must not exist and it must reside on the same mounted filesystem
\r
399 + as the current database.
\r
402 + Do not report database compaction progress to stdout.
\r
407 +The following environment variables can be used to control the behavior
\r
410 +**NOTMUCH\_CONFIG**
\r
411 + Specifies the location of the notmuch configuration file. Notmuch
\r
412 + will use ${HOME}/.notmuch-config if this variable is not set.
\r
417 +**notmuch(1)**, **notmuch-count(1)**, **notmuch-dump(1)**,
\r
418 +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
419 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
420 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
421 diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst
\r
422 new file mode 100644
\r
423 index 0000000..3c9a568
\r
425 +++ b/doc/man1/notmuch-config.rst
\r
434 +**notmuch** **config** **get** <*section*>.<*item*>
\r
436 +**notmuch** **config** **set** <*section*>.<*item*> [*value* ...]
\r
438 +**notmuch** **config** **list**
\r
443 +The **config** command can be used to get or set settings in the notmuch
\r
444 +configuration file.
\r
447 + The value of the specified configuration item is printed to
\r
448 + stdout. If the item has multiple values (it is a list), each
\r
449 + value is separated by a newline character.
\r
452 + The specified configuration item is set to the given value. To
\r
453 + specify a multiple-value item (a list), provide each value as a
\r
454 + separate command-line argument.
\r
456 + If no values are provided, the specified configuration item will
\r
457 + be removed from the configuration file.
\r
460 + Every configuration item is printed to stdout, each on a
\r
461 + separate line of the form:
\r
463 + *section*.\ *item*\ =\ *value*
\r
465 + No additional whitespace surrounds the dot or equals sign
\r
466 + characters. In a multiple-value item (a list), the values are
\r
467 + separated by semicolon characters.
\r
469 +The available configuration items are described below.
\r
471 + **database.path**
\r
472 + The top-level directory where your mail currently exists and to
\r
473 + where mail will be delivered in the future. Files should be
\r
474 + individual email messages. Notmuch will store its database
\r
475 + within a sub-directory of the path configured here named
\r
481 + **user.primary\_email**
\r
482 + Your primary email address.
\r
484 + **user.other\_email**
\r
485 + A list of other email addresses at which you receive email.
\r
488 + A list of tags that will be added to all messages incorporated
\r
489 + by **notmuch new**.
\r
492 + A list of file and directory names, without path, that will not
\r
493 + be searched for messages by **notmuch new**. All the files and
\r
494 + directories matching any of the names specified here will be
\r
495 + ignored, regardless of the location in the mail store directory
\r
498 + **search.exclude\_tags**
\r
499 + A list of tags that will be excluded from search results by
\r
500 + default. Using an excluded tag in a query will override that
\r
503 + **maildir.synchronize\_flags**
\r
504 + If true, then the following maildir flags (in message filenames)
\r
505 + will be synchronized with the corresponding notmuch tags:
\r
507 + +--------+-----------------------------------------------+
\r
509 + +========+===============================================+
\r
511 + +--------+-----------------------------------------------+
\r
513 + +--------+-----------------------------------------------+
\r
515 + +--------+-----------------------------------------------+
\r
517 + +--------+-----------------------------------------------+
\r
518 + | S | unread (added when 'S' flag is not present) |
\r
519 + +--------+-----------------------------------------------+
\r
521 + The **notmuch new** command will notice flag changes in
\r
522 + filenames and update tags, while the **notmuch tag** and
\r
523 + **notmuch restore** commands will notice tag changes and update
\r
524 + flags in filenames.
\r
526 + If there have been any changes in the maildir (new messages
\r
527 + added, old ones removed or renamed, maildir flags changed,
\r
528 + etc.), it is advisable to run **notmuch new** before **notmuch
\r
529 + tag** or **notmuch restore** commands to ensure the tag changes
\r
530 + are properly synchronized to the maildir flags, as the commands
\r
531 + expect the database and maildir to be in sync.
\r
536 +The following environment variables can be used to control the behavior
\r
539 +**NOTMUCH\_CONFIG**
\r
540 + Specifies the location of the notmuch configuration file. Notmuch
\r
541 + will use ${HOME}/.notmuch-config if this variable is not set.
\r
546 +**notmuch(1)**, **notmuch-count(1)**, **notmuch-dump(1)**,
\r
547 +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
548 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
549 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
550 diff --git a/doc/man1/notmuch-count.rst b/doc/man1/notmuch-count.rst
\r
551 new file mode 100644
\r
552 index 0000000..ca78c18
\r
554 +++ b/doc/man1/notmuch-count.rst
\r
563 +**notmuch** **count** [*option* ...] <*search-term*> ...
\r
568 +Count messages matching the search terms.
\r
570 +The number of matching messages (or threads) is output to stdout.
\r
572 +With no search terms, a count of all messages (or threads) in the
\r
573 +database will be displayed.
\r
575 +See **notmuch-search-terms(7)** for details of the supported syntax for
\r
578 +Supported options for **count** include
\r
580 + ``--output=(messages|threads|files)``
\r
583 + Output the number of matching messages. This is the default.
\r
586 + Output the number of matching threads.
\r
589 + Output the number of files associated with matching
\r
590 + messages. This may be bigger than the number of matching
\r
591 + messages due to duplicates (i.e. multiple files having the
\r
592 + same message-id).
\r
594 + ``--exclude=(true|false)``
\r
595 + Specify whether to omit messages matching search.tag\_exclude
\r
596 + from the count (the default) or not.
\r
599 + Read queries from a file (stdin by default), one per line, and
\r
600 + output the number of matching messages (or threads) to stdout,
\r
601 + one per line. On an empty input line the count of all messages
\r
602 + (or threads) in the database will be output. This option is not
\r
603 + compatible with specifying search terms on the command line.
\r
605 + ``--input=``\ <filename>
\r
606 + Read input from given file, instead of from stdin. Implies
\r
612 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-dump(1)**,
\r
613 +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
614 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
615 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
616 diff --git a/doc/man1/notmuch-dump.rst b/doc/man1/notmuch-dump.rst
\r
617 new file mode 100644
\r
618 index 0000000..dd93e56
\r
620 +++ b/doc/man1/notmuch-dump.rst
\r
629 +**notmuch** **dump** **--format=(batch-tag|sup)** [--] [--output=<*file*>] [--] [<*search-term*> ...]
\r
634 +Dump tags for messages matching the given search terms.
\r
636 +Output is to the given filename, if any, or to stdout.
\r
638 +These tags are the only data in the notmuch database that can't be
\r
639 +recreated from the messages themselves. The output of notmuch dump is
\r
640 +therefore the only critical thing to backup (and much more friendly to
\r
641 +incremental backup than the native database files.)
\r
643 +``--format=(sup|batch-tag)``
\r
644 + Notmuch restore supports two plain text dump formats, both with one
\r
645 + message-id per line, followed by a list of tags.
\r
648 + The default **batch-tag** dump format is intended to more robust
\r
649 + against malformed message-ids and tags containing whitespace or
\r
650 + non-\ **ascii(7)** characters. Each line has the form
\r
652 + +<*encoded-tag*\ > +<*encoded-tag*\ > ... --
\r
653 + id:<*quoted-message-id*\ >
\r
655 + Tags are hex-encoded by replacing every byte not matching the
\r
656 + regex **[A-Za-z0-9@=.,\_+-]** with **%nn** where nn is the two
\r
657 + digit hex encoding. The message ID is a valid Xapian query,
\r
658 + quoted using Xapian boolean term quoting rules: if the ID
\r
659 + contains whitespace or a close paren or starts with a double
\r
660 + quote, it must be enclosed in double quotes and double quotes
\r
661 + inside the ID must be doubled. The astute reader will notice
\r
662 + this is a special case of the batch input format for
\r
663 + **notmuch-tag(1)**; note that the single message-id query is
\r
664 + mandatory for **notmuch-restore(1)**.
\r
667 + The **sup** dump file format is specifically chosen to be
\r
668 + compatible with the format of files produced by sup-dump. So if
\r
669 + you've previously been using sup for mail, then the **notmuch
\r
670 + restore** command provides you a way to import all of your tags
\r
671 + (or labels as sup calls them). Each line has the following form
\r
673 + <*message-id*\ > **(** <*tag*\ > ... **)**
\r
675 + with zero or more tags are separated by spaces. Note that
\r
676 + (malformed) message-ids may contain arbitrary non-null
\r
677 + characters. Note also that tags with spaces will not be
\r
678 + correctly restored with this format.
\r
680 + With no search terms, a dump of all messages in the database will be
\r
681 + generated. A "--" argument instructs notmuch that the remaining
\r
682 + arguments are search terms.
\r
684 + See **notmuch-search-terms(7)** for details of the supported syntax
\r
685 + for <search-terms>.
\r
690 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
691 +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
692 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
693 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
694 diff --git a/doc/man1/notmuch-insert.rst b/doc/man1/notmuch-insert.rst
\r
695 new file mode 100644
\r
696 index 0000000..2be1a7b
\r
698 +++ b/doc/man1/notmuch-insert.rst
\r
707 +**notmuch** **insert** [option ...] [+<*tag*>|-<*tag*> ...]
\r
712 +**notmuch insert** reads a message from standard input and delivers it
\r
713 +into the maildir directory given by configuration option
\r
714 +**database.path**, then incorporates the message into the notmuch
\r
715 +database. It is an alternative to using a separate tool to deliver the
\r
716 +message then running **notmuch new** afterwards.
\r
718 +The new message will be tagged with the tags specified by the
\r
719 +**new.tags** configuration option, then by operations specified on the
\r
720 +command-line: tags prefixed by '+' are added while those prefixed by '-'
\r
723 +If the new message is a duplicate of an existing message in the database
\r
724 +(it has same Message-ID), it will be added to the maildir folder and
\r
725 +notmuch database, but the tags will not be changed.
\r
727 +Option arguments must appear before any tag operation arguments.
\r
728 +Supported options for **insert** include
\r
730 + ``--folder=<``\ folder\ **>**
\r
731 + Deliver the message to the specified folder, relative to the
\r
732 + top-level directory given by the value of **database.path**. The
\r
733 + default is to deliver to the top-level directory.
\r
735 + ``--create-folder``
\r
736 + Try to create the folder named by the ``--folder`` option, if it
\r
737 + does not exist. Otherwise the folder must already exist for mail
\r
738 + delivery to succeed.
\r
743 +This command returns exit status 0 if the message was successfully added
\r
744 +to the mail directory, even if the message could not be indexed and
\r
745 +added to the notmuch database. In the latter case, a warning will be
\r
746 +printed to standard error but the message file will be left on disk.
\r
748 +If the message could not be written to disk then a non-zero exit status
\r
754 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
755 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-reply(1)**,
\r
756 +**notmuch-restore(1)**, **notmuch-search(1)**,
\r
757 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
758 diff --git a/doc/man1/notmuch-new.rst b/doc/man1/notmuch-new.rst
\r
759 new file mode 100644
\r
760 index 0000000..d11fcee
\r
762 +++ b/doc/man1/notmuch-new.rst
\r
771 +**notmuch** **new** [--no-hooks]
\r
776 +Find and import any new messages to the database.
\r
778 +The **new** command scans all sub-directories of the database,
\r
779 +performing full-text indexing on new messages that are found. Each new
\r
780 +message will automatically be tagged with both the **inbox** and
\r
783 +You should run **notmuch new** once after first running **notmuch
\r
784 +setup** to create the initial database. The first run may take a long
\r
785 +time if you have a significant amount of mail (several hundred thousand
\r
786 +messages or more). Subsequently, you should run **notmuch new** whenever
\r
787 +new mail is delivered and you wish to incorporate it into the database.
\r
788 +These subsequent runs will be much quicker than the initial run.
\r
790 +Invoking ``notmuch`` with no command argument will run **new** if
\r
791 +**notmuch setup** has previously been completed, but **notmuch new** has
\r
792 +not previously been run.
\r
794 +**notmuch new** updates tags according to maildir flag changes if the
\r
795 +**maildir.synchronize\_flags** configuration option is enabled. See
\r
796 +**notmuch-config(1)** for details.
\r
798 +The **new** command supports hooks. See **notmuch-hooks(5)** for more
\r
801 +Supported options for **new** include
\r
804 + Prevents hooks from being run.
\r
807 + Do not print progress or results.
\r
812 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
813 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
814 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
815 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
816 diff --git a/doc/man1/notmuch-reply.rst b/doc/man1/notmuch-reply.rst
\r
817 new file mode 100644
\r
818 index 0000000..cfbd4ea
\r
820 +++ b/doc/man1/notmuch-reply.rst
\r
829 +**notmuch** **reply** [option ...] <*search-term*> ...
\r
834 +Constructs a reply template for a set of messages.
\r
836 +To make replying to email easier, **notmuch reply** takes an existing
\r
837 +set of messages and constructs a suitable mail template. The Reply-to:
\r
838 +header (if any, otherwise From:) is used for the To: address. Unless
\r
839 +``--reply-to=sender`` is specified, values from the To: and Cc: headers
\r
840 +are copied, but not including any of the current user's email addresses
\r
841 +(as configured in primary\_mail or other\_email in the .notmuch-config
\r
842 +file) in the recipient list.
\r
844 +It also builds a suitable new subject, including Re: at the front (if
\r
845 +not already present), and adding the message IDs of the messages being
\r
846 +replied to to the References list and setting the In-Reply-To: field
\r
849 +Finally, the original contents of the emails are quoted by prefixing
\r
850 +each line with '> ' and included in the body.
\r
852 +The resulting message template is output to stdout.
\r
854 +Supported options for **reply** include
\r
856 + ``--format=``\ (**default**\ \|\ **json**\ \|\ **sexp**\ \|\ **headers-only**)
\r
859 + Includes subject and quoted message body as an RFC 2822
\r
863 + Produces JSON output containing headers for a reply message
\r
864 + and the contents of the original message. This output can be
\r
865 + used by a client to create a reply message intelligently.
\r
868 + Produces S-Expression output containing headers for a reply
\r
869 + message and the contents of the original message. This
\r
870 + output can be used by a client to create a reply message
\r
874 + Only produces In-Reply-To, References, To, Cc, and Bcc
\r
877 + ``--format-version=N``
\r
878 + Use the specified structured output format version. This is
\r
879 + intended for programs that invoke **notmuch(1)** internally. If
\r
880 + omitted, the latest supported version will be used.
\r
882 + ``--reply-to=``\ (**all**\ \|\ **sender**)
\r
884 + **all** (default)
\r
885 + Replies to all addresses.
\r
888 + Replies only to the sender. If replying to user's own
\r
889 + message (Reply-to: or From: header is one of the user's
\r
890 + configured email addresses), try To:, Cc:, and Bcc: headers
\r
891 + in this order, and copy values from the first that contains
\r
892 + something other than only the user's addresses.
\r
895 + Decrypt any MIME encrypted parts found in the selected content
\r
896 + (ie. "multipart/encrypted" parts). Status of the decryption will
\r
897 + be reported (currently only supported with --format=json and
\r
898 + --format=sexp) and on successful decryption the
\r
899 + multipart/encrypted part will be replaced by the decrypted
\r
902 + Decryption expects a functioning **gpg-agent(1)** to provide any
\r
903 + needed credentials. Without one, the decryption will fail.
\r
905 +See **notmuch-search-terms(7)** for details of the supported syntax for
\r
908 +Note: It is most common to use **notmuch reply** with a search string
\r
909 +matching a single message, (such as id:<message-id>), but it can be
\r
910 +useful to reply to several messages at once. For example, when a series
\r
911 +of patches are sent in a single thread, replying to the entire thread
\r
912 +allows for the reply to comment on issues found in multiple patches. The
\r
913 +default format supports replying to multiple messages at once, but the
\r
914 +JSON and S-Expression formats do not.
\r
919 +This command supports the following special exit status codes
\r
922 + The requested format version is too old.
\r
925 + The requested format version is too new.
\r
930 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
931 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
932 +**notmuch-new(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
933 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
934 diff --git a/doc/man1/notmuch-restore.rst b/doc/man1/notmuch-restore.rst
\r
935 new file mode 100644
\r
936 index 0000000..a199868
\r
938 +++ b/doc/man1/notmuch-restore.rst
\r
947 +**notmuch** **restore** [--accumulate] **--format=(auto|batch-tag|sup)** [--input=<*filename*>]
\r
952 +Restores the tags from the given file (see **notmuch dump**).
\r
954 +The input is read from the given filename, if any, or from stdin.
\r
956 +Supported options for **restore** include
\r
959 + The union of the existing and new tags is applied, instead of
\r
960 + replacing each message's tags as they are read in from the dump
\r
963 + ``--format=(sup|batch-tag|auto)``
\r
964 + Notmuch restore supports two plain text dump formats, with each
\r
965 + line specifying a message-id and a set of tags. For details of
\r
966 + the actual formats, see **notmuch-dump(1)**.
\r
969 + The **sup** dump file format is specifically chosen to be
\r
970 + compatible with the format of files produced by sup-dump. So
\r
971 + if you've previously been using sup for mail, then the
\r
972 + **notmuch restore** command provides you a way to import all
\r
973 + of your tags (or labels as sup calls them).
\r
976 + The **batch-tag** dump format is intended to more robust
\r
977 + against malformed message-ids and tags containing whitespace
\r
978 + or non-\ **ascii(7)** characters. See **notmuch-dump(1)**
\r
979 + for details on this format.
\r
981 + **notmuch restore** updates the maildir flags according to
\r
982 + tag changes if the **maildir.synchronize\_flags**
\r
983 + configuration option is enabled. See **notmuch-config(1)**
\r
987 + This option (the default) tries to guess the format from the
\r
988 + input. For correctly formed input in either supported
\r
989 + format, this heuristic, based the fact that batch-tag format
\r
990 + contains no parentheses, should be accurate.
\r
995 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
996 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
997 +**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-search(1)**,
\r
998 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
999 diff --git a/doc/man1/notmuch-search.rst b/doc/man1/notmuch-search.rst
\r
1000 new file mode 100644
\r
1001 index 0000000..7ac6c68
\r
1003 +++ b/doc/man1/notmuch-search.rst
\r
1012 +**notmuch** **search** [*option* ...] <*search-term*> ...
\r
1017 +Search for messages matching the given search terms, and display as
\r
1018 +results the threads containing the matched messages.
\r
1020 +The output consists of one line per thread, giving a thread ID, the date
\r
1021 +of the newest (or oldest, depending on the sort option) matched message
\r
1022 +in the thread, the number of matched messages and total messages in the
\r
1023 +thread, the names of all participants in the thread, and the subject of
\r
1024 +the newest (or oldest) message.
\r
1026 +See **notmuch-search-terms(7)** for details of the supported syntax for
\r
1029 +Supported options for **search** include
\r
1031 + ``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**)
\r
1032 + Presents the results in either JSON, S-Expressions, newline
\r
1033 + character separated plain-text (default), or null character
\r
1034 + separated plain-text (compatible with **xargs(1)** -0 option
\r
1035 + where available).
\r
1037 + ``--format-version=N``
\r
1038 + Use the specified structured output format version. This is
\r
1039 + intended for programs that invoke **notmuch(1)** internally. If
\r
1040 + omitted, the latest supported version will be used.
\r
1042 + ``--output=(summary|threads|messages|files|tags)``
\r
1045 + Output a summary of each thread with any message matching
\r
1046 + the search terms. The summary includes the thread ID, date,
\r
1047 + the number of messages in the thread (both the number
\r
1048 + matched and the total number), the authors of the thread and
\r
1052 + Output the thread IDs of all threads with any message
\r
1053 + matching the search terms, either one per line
\r
1054 + (--format=text), separated by null characters
\r
1055 + (--format=text0), as a JSON array (--format=json), or an
\r
1056 + S-Expression list (--format=sexp).
\r
1059 + Output the message IDs of all messages matching the search
\r
1060 + terms, either one per line (--format=text), separated by
\r
1061 + null characters (--format=text0), as a JSON array
\r
1062 + (--format=json), or as an S-Expression list (--format=sexp).
\r
1065 + Output the filenames of all messages matching the search
\r
1066 + terms, either one per line (--format=text), separated by
\r
1067 + null characters (--format=text0), as a JSON array
\r
1068 + (--format=json), or as an S-Expression list (--format=sexp).
\r
1070 + Note that each message may have multiple filenames
\r
1071 + associated with it. All of them are included in the output,
\r
1072 + unless limited with the --duplicate=N option.
\r
1075 + Output all tags that appear on any message matching the
\r
1076 + search terms, either one per line (--format=text), separated
\r
1077 + by null characters (--format=text0), as a JSON array
\r
1078 + (--format=json), or as an S-Expression list (--format=sexp).
\r
1080 + ``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
\r
1081 + This option can be used to present results in either
\r
1082 + chronological order (**oldest-first**) or reverse chronological
\r
1083 + order (**newest-first**).
\r
1085 + Note: The thread order will be distinct between these two
\r
1086 + options (beyond being simply reversed). When sorting by
\r
1087 + **oldest-first** the threads will be sorted by the oldest
\r
1088 + message in each thread, but when sorting by **newest-first** the
\r
1089 + threads will be sorted by the newest message in each thread.
\r
1091 + By default, results will be displayed in reverse chronological
\r
1092 + order, (that is, the newest results will be displayed first).
\r
1094 + ``--offset=[-]N``
\r
1095 + Skip displaying the first N results. With the leading '-', start
\r
1096 + at the Nth result from the end.
\r
1099 + Limit the number of displayed results to N.
\r
1101 + ``--exclude=(true|false|all|flag)``
\r
1102 + A message is called "excluded" if it matches at least one tag in
\r
1103 + search.tag\_exclude that does not appear explicitly in the
\r
1104 + search terms. This option specifies whether to omit excluded
\r
1105 + messages in the search process.
\r
1107 + The default value, **true**, prevents excluded messages from
\r
1108 + matching the search terms.
\r
1110 + **all** additionally prevents excluded messages from appearing
\r
1111 + in displayed results, in effect behaving as though the excluded
\r
1112 + messages do not exist.
\r
1114 + **false** allows excluded messages to match search terms and
\r
1115 + appear in displayed results. Excluded messages are still marked
\r
1116 + in the relevant outputs.
\r
1118 + **flag** only has an effect when ``--output=summary``. The
\r
1119 + output is almost identical to **false**, but the "match count"
\r
1120 + is the number of matching non-excluded messages in the thread,
\r
1121 + rather than the number of matching messages.
\r
1123 + ``--duplicate=N``
\r
1124 + Effective with ``--output=files``, output the Nth filename
\r
1125 + associated with each message matching the query (N is 1-based).
\r
1126 + If N is greater than the number of files associated with the
\r
1127 + message, don't print anything.
\r
1129 + Note that this option is orthogonal with the **folder:** search
\r
1130 + prefix. The prefix matches messages based on filenames. This
\r
1131 + option filters filenames of the matching messages.
\r
1136 +This command supports the following special exit status codes
\r
1139 + The requested format version is too old.
\r
1142 + The requested format version is too new.
\r
1147 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1148 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
1149 +**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
\r
1150 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1151 diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst
\r
1152 new file mode 100644
\r
1153 index 0000000..3fc3eca
\r
1155 +++ b/doc/man1/notmuch-show.rst
\r
1164 +**notmuch** **show** [*option* ...] <*search-term*> ...
\r
1169 +Shows all messages matching the search terms.
\r
1171 +See **notmuch-search-terms(7)** for details of the supported syntax for
\r
1174 +The messages will be grouped and sorted based on the threading (all
\r
1175 +replies to a particular message will appear immediately after that
\r
1176 +message in date order). The output is not indented by default, but depth
\r
1177 +tags are printed so that proper indentation can be performed by a
\r
1178 +post-processor (such as the emacs interface to notmuch).
\r
1180 +Supported options for **show** include
\r
1182 + ``--entire-thread=(true|false)``
\r
1183 + If true, **notmuch show** outputs all messages in the thread of
\r
1184 + any message matching the search terms; if false, it outputs only
\r
1185 + the matching messages. For ``--format=json`` and
\r
1186 + ``--format=sexp`` this defaults to true. For other formats, this
\r
1187 + defaults to false.
\r
1189 + ``--format=(text|json|sexp|mbox|raw)``
\r
1191 + **text** (default for messages)
\r
1192 + The default plain-text format has all text-content MIME
\r
1193 + parts decoded. Various components in the output,
\r
1194 + (**message**, **header**, **body**, **attachment**, and MIME
\r
1195 + **part**), will be delimited by easily-parsed markers. Each
\r
1196 + marker consists of a Control-L character (ASCII decimal 12),
\r
1197 + the name of the marker, and then either an opening or
\r
1198 + closing brace, ('{' or '}'), to either open or close the
\r
1199 + component. For a multipart MIME message, these parts will be
\r
1203 + The output is formatted with Javascript Object Notation
\r
1204 + (JSON). This format is more robust than the text format for
\r
1205 + automated processing. The nested structure of multipart MIME
\r
1206 + messages is reflected in nested JSON output. By default JSON
\r
1207 + output includes all messages in a matching thread; that is,
\r
1210 + ``--format=json`` sets ``--entire-thread`` The caller can
\r
1211 + disable this behaviour by setting ``--entire-thread=false``
\r
1214 + The output is formatted as an S-Expression (sexp). This
\r
1215 + format is more robust than the text format for automated
\r
1216 + processing. The nested structure of multipart MIME messages
\r
1217 + is reflected in nested S-Expression output. By default,
\r
1218 + S-Expression output includes all messages in a matching
\r
1219 + thread; that is, by default,
\r
1221 + ``--format=sexp`` sets ``--entire-thread`` The caller can
\r
1222 + disable this behaviour by setting ``--entire-thread=false``
\r
1225 + All matching messages are output in the traditional, Unix
\r
1226 + mbox format with each message being prefixed by a line
\r
1227 + beginning with "From " and a blank line separating each
\r
1228 + message. Lines in the message content beginning with "From "
\r
1229 + (preceded by zero or more '>' characters) have an additional
\r
1230 + '>' character added. This reversible escaping is termed
\r
1231 + "mboxrd" format and described in detail here:
\r
1237 + **raw** (default for a single part, see --part)
\r
1238 + For a message or an attached message part, the original, raw
\r
1239 + content of the email message is output. Consumers of this
\r
1240 + format should expect to implement MIME decoding and similar
\r
1243 + For a single part (--part) the raw part content is output
\r
1244 + after performing any necessary MIME decoding. Note that
\r
1245 + messages with a simple body still have two parts: part 0 is
\r
1246 + the whole message and part 1 is the body.
\r
1248 + For a multipart part, the part headers and body (including
\r
1249 + all child parts) is output.
\r
1251 + The raw format must only be used with search terms matching
\r
1254 + ``--format-version=N``
\r
1255 + Use the specified structured output format version. This is
\r
1256 + intended for programs that invoke **notmuch(1)** internally. If
\r
1257 + omitted, the latest supported version will be used.
\r
1260 + Output the single decoded MIME part N of a single message. The
\r
1261 + search terms must match only a single message. Message parts are
\r
1262 + numbered in a depth-first walk of the message MIME structure,
\r
1263 + and are identified in the 'json', 'sexp' or 'text' output
\r
1267 + Compute and report the validity of any MIME cryptographic
\r
1268 + signatures found in the selected content (ie. "multipart/signed"
\r
1269 + parts). Status of the signature will be reported (currently only
\r
1270 + supported with --format=json and --format=sexp), and the
\r
1271 + multipart/signed part will be replaced by the signed data.
\r
1274 + Decrypt any MIME encrypted parts found in the selected content
\r
1275 + (ie. "multipart/encrypted" parts). Status of the decryption will
\r
1276 + be reported (currently only supported with --format=json and
\r
1277 + --format=sexp) and on successful decryption the
\r
1278 + multipart/encrypted part will be replaced by the decrypted
\r
1281 + Decryption expects a functioning **gpg-agent(1)** to provide any
\r
1282 + needed credentials. Without one, the decryption will fail.
\r
1284 + Implies --verify.
\r
1286 + ``--exclude=(true|false)``
\r
1287 + Specify whether to omit threads only matching
\r
1288 + search.tag\_exclude from the search results (the default) or
\r
1289 + not. In either case the excluded message will be marked with the
\r
1290 + exclude flag (except when output=mbox when there is nowhere to
\r
1293 + If --entire-thread is specified then complete threads are
\r
1294 + returned regardless (with the excluded flag being set when
\r
1295 + appropriate) but threads that only match in an excluded message
\r
1296 + are not returned when ``--exclude=true.``
\r
1298 + The default is ``--exclude=true.``
\r
1300 + ``--body=(true|false)``
\r
1301 + If true (the default) **notmuch show** includes the bodies of
\r
1302 + the messages in the output; if false, bodies are omitted.
\r
1303 + ``--body=false`` is only implemented for the json and sexp
\r
1304 + formats and it is incompatible with ``--part > 0.``
\r
1306 + This is useful if the caller only needs the headers as body-less
\r
1307 + output is much faster and substantially smaller.
\r
1309 + ``--include-html``
\r
1310 + Include "text/html" parts as part of the output (currently only
\r
1311 + supported with --format=json and --format=sexp). By default,
\r
1312 + unless ``--part=N`` is used to select a specific part or
\r
1313 + ``--include-html`` is used to include all "text/html" parts, no
\r
1314 + part with content type "text/html" is included in the output.
\r
1316 +A common use of **notmuch show** is to display a single thread of email
\r
1317 +messages. For this, use a search term of "thread:<thread-id>" as can be
\r
1318 +seen in the first column of output from the **notmuch search** command.
\r
1323 +This command supports the following special exit status codes
\r
1326 + The requested format version is too old.
\r
1329 + The requested format version is too new.
\r
1334 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1335 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
1336 +**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
\r
1337 +**notmuch-search(1)**, **notmuch-search-terms(7)**, **notmuch-tag(1)**
\r
1338 diff --git a/doc/man1/notmuch-tag.rst b/doc/man1/notmuch-tag.rst
\r
1339 new file mode 100644
\r
1340 index 0000000..2e7e1d3
\r
1342 +++ b/doc/man1/notmuch-tag.rst
\r
1351 +**notmuch** **tag** [options ...] +<*tag*>|-<*tag*> [--] <*search-term*> ...
\r
1353 +**notmuch** **tag** **--batch** [--input=<*filename*>]
\r
1358 +Add/remove tags for all messages matching the search terms.
\r
1360 +See **notmuch-search-terms(7)** for details of the supported syntax for
\r
1361 +<*search-term*\ >.
\r
1363 +Tags prefixed by '+' are added while those prefixed by '-' are removed.
\r
1364 +For each message, tag changes are applied in the order they appear on
\r
1365 +the command line.
\r
1367 +The beginning of the search terms is recognized by the first argument
\r
1368 +that begins with neither '+' nor '-'. Support for an initial search term
\r
1369 +beginning with '+' or '-' is provided by allowing the user to specify a
\r
1370 +"--" argument to separate the tags from the search terms.
\r
1372 +**notmuch tag** updates the maildir flags according to tag changes if
\r
1373 +the **maildir.synchronize\_flags** configuration option is enabled. See
\r
1374 +**notmuch-config(1)** for details.
\r
1376 +Supported options for **tag** include
\r
1378 + ``--remove-all``
\r
1379 + Remove all tags from each message matching the search terms
\r
1380 + before applying the tag changes appearing on the command line.
\r
1381 + This means setting the tags of each message to the tags to be
\r
1382 + added. If there are no tags to be added, the messages will have
\r
1386 + Read batch tagging operations from a file (stdin by default).
\r
1387 + This is more efficient than repeated **notmuch tag**
\r
1388 + invocations. See `TAG FILE FORMAT <#tag_file_format>`__ below
\r
1389 + for the input format. This option is not compatible with
\r
1390 + specifying tagging on the command line.
\r
1392 + ``--input=``\ <filename>
\r
1393 + Read input from given file, instead of from stdin. Implies
\r
1399 +The input must consist of lines of the format:
\r
1401 ++<*tag*\ >\|-<*tag*\ > [...] [--] <*query*\ >
\r
1403 +Each line is interpreted similarly to **notmuch tag** command line
\r
1404 +arguments. The delimiter is one or more spaces ' '. Any characters in
\r
1405 +<*tag*\ > **may** be hex-encoded with %NN where NN is the hexadecimal
\r
1406 +value of the character. To hex-encode a character with a multi-byte
\r
1407 +UTF-8 encoding, hex-encode each byte. Any spaces in <tag> **must** be
\r
1408 +hex-encoded as %20. Any characters that are not part of <*tag*\ > **must
\r
1409 +not** be hex-encoded.
\r
1411 +In the future tag:"tag with spaces" style quoting may be supported for
\r
1412 +<*tag*\ > as well; for this reason all double quote characters in
\r
1413 +<*tag*\ > **should** be hex-encoded.
\r
1415 +The <*query*\ > should be quoted using Xapian boolean term quoting
\r
1416 +rules: if a term contains whitespace or a close paren or starts with a
\r
1417 +double quote, it must be enclosed in double quotes (not including any
\r
1418 +prefix) and double quotes inside the term must be doubled (see below for
\r
1421 +Leading and trailing space ' ' is ignored. Empty lines and lines
\r
1422 +beginning with '#' are ignored.
\r
1427 +The following shows a valid input to batch tagging. Note that only the
\r
1428 +isolated '\*' acts as a wildcard. Also note the two different quotings
\r
1429 +of the tag **space in tags**
\r
1434 + +foo::bar%25 -- (One and Two) or (One and tag:winner)
\r
1435 + +found::it -- tag:foo::bar%
\r
1436 + # ignore this line and the next
\r
1438 + +space%20in%20tags -- Two
\r
1439 + # add tag '(tags)', among other stunts.
\r
1440 + +crazy{ +(tags) +&are +#possible\ -- tag:"space in tags"
\r
1441 + +match*crazy -- tag:crazy{
\r
1442 + +some_tag -- id:"this is ""nauty)"""
\r
1447 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1448 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
1449 +**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
\r
1450 +**notmuch-search(1)**, **notmuch-search-terms(7)**, **notmuch-show(1)**,
\r
1451 diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst
\r
1452 new file mode 100644
\r
1453 index 0000000..343927f
\r
1455 +++ b/doc/man1/notmuch.rst
\r
1464 +**notmuch** [option ...] **command** [arg ...]
\r
1469 +Notmuch is a command-line based program for indexing, searching,
\r
1470 +reading, and tagging large collections of email messages.
\r
1472 +This page describes how to get started using notmuch from the command
\r
1473 +line, and gives a brief overview of the commands available. For more
\r
1474 +information on e.g. **notmuch show** consult the **notmuch-show(1)** man
\r
1475 +page, also accessible via **notmuch help show**
\r
1477 +The quickest way to get started with Notmuch is to simply invoke the
\r
1478 +``notmuch`` command with no arguments, which will interactively guide
\r
1479 +you through the process of indexing your mail.
\r
1484 +While the command-line program ``notmuch`` provides powerful
\r
1485 +functionality, it does not provide the most convenient interface for
\r
1486 +that functionality. More sophisticated interfaces are expected to be
\r
1487 +built on top of either the command-line interface, or more likely, on
\r
1488 +top of the notmuch library interface. See http://notmuchmail.org for
\r
1489 +more about alternate interfaces to notmuch. The emacs-based interface to
\r
1490 +notmuch (available under **emacs/** in the Notmuch source distribution)
\r
1491 +is probably the most widely used at this time.
\r
1496 +Supported global options for ``notmuch`` include
\r
1499 + Print a synopsis of available commands and exit.
\r
1502 + Print the installed version of notmuch, and exit.
\r
1504 + ``--config=FILE``
\r
1505 + Specify the configuration file to use. This overrides any
\r
1506 + configuration file specified by ${NOTMUCH\_CONFIG}.
\r
1514 +The **notmuch setup** command is used to configure Notmuch for first
\r
1515 +use, (or to reconfigure it later).
\r
1517 +The setup command will prompt for your full name, your primary email
\r
1518 +address, any alternate email addresses you use, and the directory
\r
1519 +containing your email archives. Your answers will be written to a
\r
1520 +configuration file in ${NOTMUCH\_CONFIG} (if set) or
\r
1521 +${HOME}/.notmuch-config . This configuration file will be created with
\r
1522 +descriptive comments, making it easy to edit by hand later to change the
\r
1523 +configuration. Or you can run **notmuch setup** again to change the
\r
1526 +The mail directory you specify can contain any number of sub-directories
\r
1527 +and should primarily contain only files with individual email messages
\r
1528 +(eg. maildir or mh archives are perfect). If there are other, non-email
\r
1529 +files (such as indexes maintained by other email programs) then notmuch
\r
1530 +will do its best to detect those and ignore them.
\r
1532 +Mail storage that uses mbox format, (where one mbox file contains many
\r
1533 +messages), will not work with notmuch. If that's how your mail is
\r
1534 +currently stored, it is recommended you first convert it to maildir
\r
1535 +format with a utility such as mb2md before running **notmuch setup .**
\r
1537 +Invoking ``notmuch`` with no command argument will run **setup** if the
\r
1538 +setup command has not previously been completed.
\r
1543 +Several of the notmuch commands accept search terms with a common
\r
1544 +syntax. See *notmuch-search-terms*\ (7) for more details on the
\r
1545 +supported syntax.
\r
1547 +The **search**, **show** and **count** commands are used to query the
\r
1550 +The **reply** command is useful for preparing a template for an email
\r
1553 +The **tag** command is the only command available for manipulating
\r
1554 +database contents.
\r
1556 +The **dump** and **restore** commands can be used to create a textual
\r
1557 +dump of email tags for backup purposes, and to restore from that dump.
\r
1559 +The **config** command can be used to get or set settings in the notmuch
\r
1560 +configuration file.
\r
1565 +The following environment variables can be used to control the behavior
\r
1568 +**NOTMUCH\_CONFIG**
\r
1569 + Specifies the location of the notmuch configuration file. Notmuch
\r
1570 + will use ${HOME}/.notmuch-config if this variable is not set.
\r
1572 +**NOTMUCH\_TALLOC\_REPORT**
\r
1573 + Location to write a talloc memory usage report. See
\r
1574 + **talloc\_enable\_leak\_report\_full** in **talloc(3)** for more
\r
1577 +**NOTMUCH\_DEBUG\_QUERY**
\r
1578 + If set to a non-empty value, the notmuch library will print (to
\r
1579 + stderr) Xapian queries it constructs.
\r
1584 +**notmuch-config(1)**, **notmuch-count(1)**, **notmuch-dump(1)**,
\r
1585 +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
1586 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
1587 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1589 +The notmuch website: **http://notmuchmail.org**
\r
1594 +Feel free to send questions, comments, or kudos to the notmuch mailing
\r
1595 +list <notmuch@notmuchmail.org> . Subscription is not required before
\r
1596 +posting, but is available from the notmuchmail.org website.
\r
1598 +Real-time interaction with the Notmuch community is available via IRC
\r
1599 +(server: irc.freenode.net, channel: #notmuch).
\r
1600 diff --git a/doc/man5/notmuch-hooks.rst b/doc/man5/notmuch-hooks.rst
\r
1601 new file mode 100644
\r
1602 index 0000000..493abf2
\r
1604 +++ b/doc/man5/notmuch-hooks.rst
\r
1613 + $DATABASEDIR/.notmuch/hooks/*
\r
1618 +Hooks are scripts (or arbitrary executables or symlinks to such) that
\r
1619 +notmuch invokes before and after certain actions. These scripts reside
\r
1620 +in the .notmuch/hooks directory within the database directory and must
\r
1621 +have executable permissions.
\r
1623 +The currently available hooks are described below.
\r
1626 + This hook is invoked by the **new** command before scanning or
\r
1627 + importing new messages into the database. If this hook exits
\r
1628 + with a non-zero status, notmuch will abort further processing of
\r
1629 + the **new** command.
\r
1631 + Typically this hook is used for fetching or delivering new mail
\r
1632 + to be imported into the database.
\r
1635 + This hook is invoked by the **new** command after new messages
\r
1636 + have been imported into the database and initial tags have been
\r
1637 + applied. The hook will not be run if there have been any errors
\r
1638 + during the scan or import.
\r
1640 + Typically this hook is used to perform additional query-based
\r
1641 + tagging on the imported messages.
\r
1646 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1647 +**notmuch-dump(1)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
1648 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
1649 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1650 diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst
\r
1651 new file mode 100644
\r
1652 index 0000000..99148b2
\r
1654 +++ b/doc/man7/notmuch-search-terms.rst
\r
1656 +====================
\r
1657 +notmuch-search-terms
\r
1658 +====================
\r
1663 +**notmuch** **count** [option ...] <*search-term*> ...
\r
1665 +**notmuch** **dump** **--format=(batch-tag|sup)** [--] [--output=<*file*>] [--] [<*search-term*> ...]
\r
1667 +**notmuch** **search** [option ...] <*search-term*> ...
\r
1669 +**notmuch** **show** [option ...] <*search-term*> ...
\r
1671 +**notmuch** **tag** +<*tag*> ... -<*tag*> [--] <*search-term*> ...
\r
1676 +Several notmuch commands accept a common syntax for search terms.
\r
1678 +The search terms can consist of free-form text (and quoted phrases)
\r
1679 +which will match all messages that contain all of the given
\r
1680 +terms/phrases in the body, the subject, or any of the sender or
\r
1681 +recipient headers.
\r
1683 +As a special case, a search string consisting of exactly a single
\r
1684 +asterisk ("\*") will match all messages.
\r
1686 +In addition to free text, the following prefixes can be used to force
\r
1687 +terms to match against specific portions of an email, (where <brackets>
\r
1688 +indicate user-supplied values):
\r
1690 +- from:<name-or-address>
\r
1692 +- to:<name-or-address>
\r
1694 +- subject:<word-or-quoted-phrase>
\r
1696 +- attachment:<word>
\r
1698 +- tag:<tag> (or is:<tag>)
\r
1700 +- id:<message-id>
\r
1702 +- thread:<thread-id>
\r
1704 +- folder:<directory-path>
\r
1706 +- date:<since>..<until>
\r
1708 +The **from:** prefix is used to match the name or address of the sender
\r
1709 +of an email message.
\r
1711 +The **to:** prefix is used to match the names or addresses of any
\r
1712 +recipient of an email message, (whether To, Cc, or Bcc).
\r
1714 +Any term prefixed with **subject:** will match only text from the
\r
1715 +subject of an email. Searching for a phrase in the subject is supported
\r
1716 +by including quotation marks around the phrase, immediately following
\r
1719 +The **attachment:** prefix can be used to search for specific filenames
\r
1720 +(or extensions) of attachments to email messages.
\r
1722 +For **tag:** and **is:** valid tag values include **inbox** and
\r
1723 +**unread** by default for new messages added by **notmuch new** as well
\r
1724 +as any other tag values added manually with **notmuch tag**.
\r
1726 +For **id:**, message ID values are the literal contents of the
\r
1727 +Message-ID: header of email messages, but without the '<', '>'
\r
1730 +The **thread:** prefix can be used with the thread ID values that are
\r
1731 +generated internally by notmuch (and do not appear in email messages).
\r
1732 +These thread ID values can be seen in the first column of output from
\r
1733 +**notmuch search**
\r
1735 +The **folder:** prefix can be used to search for email message files
\r
1736 +that are contained within particular directories within the mail store.
\r
1737 +If the same email message has multiple message files associated with it,
\r
1738 +it's sufficient for a match that at least one of the files is contained
\r
1739 +within a matching directory. Only the directory components below the
\r
1740 +top-level mail database path are available to be searched.
\r
1742 +The **date:** prefix can be used to restrict the results to only
\r
1743 +messages within a particular time range (based on the Date: header) with
\r
1744 +a range syntax of:
\r
1746 +date:<since>..<until>
\r
1748 +See **DATE AND TIME SEARCH** below for details on the range expression,
\r
1749 +and supported syntax for <since> and <until> date and time expressions.
\r
1751 +The time range can also be specified using timestamps with a syntax of:
\r
1753 +<initial-timestamp>..<final-timestamp>
\r
1755 +Each timestamp is a number representing the number of seconds since
\r
1756 +1970-01-01 00:00:00 UTC.
\r
1758 +In addition to individual terms, multiple terms can be combined with
\r
1759 +Boolean operators ( **and**, **or**, **not** , etc.). Each term in the
\r
1760 +query will be implicitly connected by a logical AND if no explicit
\r
1761 +operator is provided, (except that terms with a common prefix will be
\r
1762 +implicitly combined with OR until we get Xapian defect #402 fixed).
\r
1764 +Parentheses can also be used to control the combination of the Boolean
\r
1765 +operators, but will have to be protected from interpretation by the
\r
1766 +shell, (such as by putting quotation marks around any parenthesized
\r
1769 +DATE AND TIME SEARCH
\r
1770 +====================
\r
1772 +notmuch understands a variety of standard and natural ways of expressing
\r
1773 +dates and times, both in absolute terms ("2012-10-24") and in relative
\r
1774 +terms ("yesterday"). Any number of relative terms can be combined ("1
\r
1775 +hour 25 minutes") and an absolute date/time can be combined with
\r
1776 +relative terms to further adjust it. A non-exhaustive description of the
\r
1777 +syntax supported for absolute and relative terms is given below.
\r
1779 +The range expression
\r
1780 +--------------------
\r
1782 +**date:<since>..<until>**
\r
1784 +The above expression restricts the results to only messages from <since>
\r
1785 +to <until>, based on the Date: header.
\r
1787 +<since> and <until> can describe imprecise times, such as "yesterday".
\r
1788 +In this case, <since> is taken as the earliest time it could describe
\r
1789 +(the beginning of yesterday) and <until> is taken as the latest time it
\r
1790 +could describe (the end of yesterday). Similarly, date:january..february
\r
1791 +matches from the beginning of January to the end of February.
\r
1793 +Currently, we do not support spaces in range expressions. You can
\r
1794 +replace the spaces with '\_', or (in most cases) '-', or (in some cases)
\r
1795 +leave the spaces out altogether. Examples in this man page use spaces
\r
1798 +Open-ended ranges are supported (since Xapian 1.2.1), i.e. it's possible
\r
1799 +to specify date:..<until> or date:<since>.. to not limit the start or
\r
1800 +end time, respectively. Pre-1.2.1 Xapian does not report an error on
\r
1801 +open ended ranges, but it does not work as expected either.
\r
1803 +Entering date:expr without ".." (for example date:yesterday) won't work,
\r
1804 +as it's not interpreted as a range expression at all. You can achieve
\r
1805 +the expected result by duplicating the expr both sides of ".." (for
\r
1806 +example date:yesterday..yesterday).
\r
1808 +Relative date and time
\r
1809 +----------------------
\r
1812 +(years\|months\|weeks\|days\|hours\|hrs\|minutes\|mins\|seconds\|secs)
\r
1815 +All refer to past, can be repeated and will be accumulated.
\r
1817 +Units can be abbreviated to any length, with the otherwise ambiguous
\r
1818 +single m being m for minutes and M for months.
\r
1820 +Number can also be written out one, two, ..., ten, dozen, hundred.
\r
1821 +Additionally, the unit may be preceded by "last" or "this" (e.g., "last
\r
1822 +week" or "this month").
\r
1824 +When combined with absolute date and time, the relative date and time
\r
1825 +specification will be relative from the specified absolute date and
\r
1828 +Examples: 5M2d, two weeks
\r
1830 +Supported absolute time formats
\r
1831 +-------------------------------
\r
1833 +- H[H]:MM[:SS] [(am\|a.m.\|pm\|p.m.)]
\r
1835 +- H[H] (am\|a.m.\|pm\|p.m.)
\r
1845 +- Examples: 17:05, 5pm
\r
1847 +Supported absolute date formats
\r
1848 +-------------------------------
\r
1856 +- M[M]/D[D][/[YY]YY]
\r
1860 +- D[D].M[M][.[YY]YY]
\r
1862 +- D[D][(st\|nd\|rd\|th)] Mon[thname] [YYYY]
\r
1864 +- Mon[thname] D[D][(st\|nd\|rd\|th)] [YYYY]
\r
1868 +Month names can be abbreviated at three or more characters.
\r
1870 +Weekday names can be abbreviated at three or more characters.
\r
1872 +Examples: 2012-07-31, 31-07-2012, 7/31/2012, August 3
\r
1881 +Some time zone codes, e.g. UTC, EET.
\r
1886 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1887 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
1888 +**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
\r
1889 +**notmuch-search(1)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1890 diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
\r
1891 new file mode 100644
\r
1892 index 0000000..28301b3
\r
1894 +++ b/doc/notmuch-emacs.rst
\r
1900 +About this Manual
\r
1901 +=================
\r
1903 +This manual covers only the emacs interface to notmuch. For information
\r
1904 +on the command line interface, see See section “Description” in Notmuch
\r
1905 +Manual Pager. To save typing, we will sometimes use *notmuch* in this
\r
1906 +manual to refer to the Emacs interface to notmuch. If the distinction
\r
1907 +should every be important, we’ll refer to the Emacs inteface as
\r
1910 +Notmuch-emacs is highly customizable via the the Emacs customization
\r
1911 +framework (or just by setting the appropriate variables). We try to
\r
1912 +point out relevant variables in this manual, but in order to avoid
\r
1913 +duplication of information, but you can usually find the most detailed
\r
1914 +description in the varables docstring.
\r
1920 + single: notmuch-hello
\r
1923 +``notmuch-hello`` is the main entry point for notmuch. You can start it
\r
1924 +with ``M-x notmuch`` or ``M-x notmuch-hello``. The startup screen looks
\r
1925 +something like the following. There are some hints at the bottom of the
\r
1926 +screen. There are three main parts to the notmuch-hello screen,
\r
1927 +discussed below. The **bold** text indicates buttons you can click with
\r
1928 +a mouse or by positioning the cursor and pressing ``<return>``
\r
1930 +| Welcome to **notmuch** You have 52 messages.
\r
1932 +| Saved searches: **[edit]**
\r
1934 +| 52 **inbox** 52 **unread**
\r
1936 +| Search: ____________________________________
\r
1938 +| All tags: **[show]**
\r
1940 +| Type a search query and hit RET to view matching threads.
\r
1941 +| Edit saved searches with the ``edit`` button.
\r
1942 +| Hit RET or click on a saved search or tag name to view matching threads.
\r
1943 +| ``=`` to refresh this screen. ``s`` to search messages. ``q`` to quit.
\r
1944 +| **Customize** this page.
\r
1946 +You can change the overall appearence of the notmuch-hello screen by
\r
1947 +customizing the variable :index:`notmuch-hello-sections`.
\r
1951 +notmuch-hello key bindings
\r
1952 +--------------------------
\r
1955 + Move to the next widget (button or text entry field)
\r
1958 + Move to the previous widget.
\r
1961 + Activate the current widget.
\r
1964 + Refresh the buffer; mainly update the counts of messages for various
\r
1968 + Import mail, See :ref:`importing`
\r
1971 + Compose a message
\r
1974 + Search the notmuch database using :ref:`notmuch-search`
\r
1977 + Print notmuch version
\r
1982 +.. _saved-searches:
\r
1987 +Notmuch replaces the static assignment of messages with the more dynamic
\r
1988 +notion of searching. Notmuch-hello presents the user with a customizable
\r
1989 +set of saved searchs. The initial defaults are ``tag:inbox`` and
\r
1990 +``tag:unread``, but you can customize the following variables
\r
1992 +:index:`notmuch-saved-searches`
\r
1993 + A list of cons pairs, the first being the name to display, the
\r
1994 + second being a query string for notmuch. See section “Description”
\r
1995 + in Notmuch Query Syntax.
\r
1997 +:index:`notmuch-saved-searches-sort-function`
\r
1998 + This variable controls how saved searches should be sorted. A value
\r
1999 + of ``nil`` displays the saved searches in the order they are stored
\r
2000 + in ‘notmuch-saved-searches’.
\r
2002 +:index:`notmuch-column-control`
\r
2003 + Controls the number of columns for displaying saved-searches/tags
\r
2008 +The search box lets the user enter an notmuch query. See section
\r
2009 +“Description” in Notmuch Query Syntax, for more info on notmuch query
\r
2010 +syntax. A history of recent searches is also displayed by default. The
\r
2011 +latter is controlled by the variable :index:`notmuch-hello-recent-searches-max`.
\r
2016 +One special kind of saved search provided by default is for each
\r
2017 +individual tag defined in the database. This can be controlled via the
\r
2018 +following variables.
\r
2020 +:index:`notmuch-hello-tag-list-make-query`
\r
2021 + Control how to construct a search (“virtual folder”) from a given
\r
2024 +:index:`notmuch-hello-hide-tags`
\r
2025 + Which tags not to display at all.
\r
2027 +:index:`notmuch-column-control`
\r
2028 + Controls the number of columns for displaying saved-searches/tags
\r
2030 +.. _notmuch-search:
\r
2035 +``notmuch-search-mode`` is used to display the results from executing
\r
2036 +a query via ``notmuch-search``. The syntax for these queries is the
\r
2037 +the same as :ref:`saved-searches`. For details of this syntax see
\r
2038 +info:notmuch-search-terms
\r
2040 +By default the output approximates that of the command line See section
\r
2041 +“Description” in notmuch search command.
\r
2043 +The main purpose of the ``notmuch-search-mode`` buffer is to act as a
\r
2044 +menu of results that the user can explore further by pressing
\r
2045 +``<return>`` on the appropriate line.
\r
2048 + Move to next line
\r
2051 + Move to previous line
\r
2054 + Open thread on current line in :ref:`notmuch-show` mode
\r
2057 + Display full set of key bindings
\r
2059 +The presentation of results can be controlled by the following
\r
2062 +:index:`notmuch-search-result-format`
\r
2063 + Control how each thread of messages is presented in the
\r
2064 + ``notmuch-show-mode`` buffer
\r
2066 +:index:`notmuch-search-oldest-first`
\r
2067 + Display the oldest threads at the top of the buffer
\r
2069 +.. _notmuch-show:
\r
2085 +:index:`notmuch-poll`
\r
2087 +:index:`notmuch-poll-script`
\r