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 CEC80431FBD
\r
6 for <notmuch@notmuchmail.org>; Wed, 5 Mar 2014 06:57:14 -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 dFHBGjjOfSwN for <notmuch@notmuchmail.org>;
\r
16 Wed, 5 Mar 2014 06:56:59 -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 00568431FAE
\r
21 for <notmuch@notmuchmail.org>; Wed, 5 Mar 2014 06:56:50 -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 1WLDFa-0004AL-Ju; Wed, 05 Mar 2014 10:56:50 -0400
\r
25 Received: (nullmailer pid 10379 invoked by uid 1000); Wed, 05 Mar 2014
\r
27 From: David Bremner <david@tethera.net>
\r
28 To: notmuch@notmuchmail.org
\r
29 Subject: [PATCH 1/4] doc: convert sphinx based docs
\r
30 Date: Wed, 5 Mar 2014 10:56:32 -0400
\r
31 Message-Id: <1394031395-8014-2-git-send-email-david@tethera.net>
\r
32 X-Mailer: git-send-email 1.8.5.3
\r
33 In-Reply-To: <1394031395-8014-1-git-send-email-david@tethera.net>
\r
34 References: <1394031395-8014-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: Wed, 05 Mar 2014 14:57:15 -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 doc/Makefile.local | 27 +++++
\r
61 doc/conf.py | 166 +++++++++++++++++++++++++++
\r
62 doc/index.rst | 30 +++++
\r
63 doc/man1/notmuch-compact.rst | 52 +++++++++
\r
64 doc/man1/notmuch-config.rst | 123 ++++++++++++++++++++
\r
65 doc/man1/notmuch-count.rst | 60 ++++++++++
\r
66 doc/man1/notmuch-dump.rst | 72 ++++++++++++
\r
67 doc/man1/notmuch-insert.rst | 58 ++++++++++
\r
68 doc/man1/notmuch-new.rst | 52 +++++++++
\r
69 doc/man1/notmuch-reply.rst | 112 ++++++++++++++++++
\r
70 doc/man1/notmuch-restore.rst | 59 ++++++++++
\r
71 doc/man1/notmuch-search.rst | 146 ++++++++++++++++++++++++
\r
72 doc/man1/notmuch-show.rst | 179 +++++++++++++++++++++++++++++
\r
73 doc/man1/notmuch-tag.rst | 107 +++++++++++++++++
\r
74 doc/man1/notmuch.rst | 143 +++++++++++++++++++++++
\r
75 doc/man5/notmuch-hooks.rst | 44 +++++++
\r
76 doc/man7/notmuch-search-terms.rst | 234 ++++++++++++++++++++++++++++++++++++++
\r
77 doc/notmuch-emacs.rst | 192 +++++++++++++++++++++++++++++++
\r
78 20 files changed, 1862 insertions(+), 1 deletion(-)
\r
79 create mode 100644 doc/Makefile
\r
80 create mode 100644 doc/Makefile.local
\r
81 create mode 100644 doc/conf.py
\r
82 create mode 100644 doc/index.rst
\r
83 create mode 100644 doc/man1/notmuch-compact.rst
\r
84 create mode 100644 doc/man1/notmuch-config.rst
\r
85 create mode 100644 doc/man1/notmuch-count.rst
\r
86 create mode 100644 doc/man1/notmuch-dump.rst
\r
87 create mode 100644 doc/man1/notmuch-insert.rst
\r
88 create mode 100644 doc/man1/notmuch-new.rst
\r
89 create mode 100644 doc/man1/notmuch-reply.rst
\r
90 create mode 100644 doc/man1/notmuch-restore.rst
\r
91 create mode 100644 doc/man1/notmuch-search.rst
\r
92 create mode 100644 doc/man1/notmuch-show.rst
\r
93 create mode 100644 doc/man1/notmuch-tag.rst
\r
94 create mode 100644 doc/man1/notmuch.rst
\r
95 create mode 100644 doc/man5/notmuch-hooks.rst
\r
96 create mode 100644 doc/man7/notmuch-search-terms.rst
\r
97 create mode 100644 doc/notmuch-emacs.rst
\r
99 diff --git a/Makefile b/Makefile
\r
100 index 0428160..39f0e62 100644
\r
103 @@ -5,7 +5,7 @@ all:
\r
104 # List all subdirectories here. Each contains its own Makefile.local.
\r
105 # Use of '=', without '+=', seems to be required for out-of-tree
\r
107 -subdirs = compat completion emacs lib man parse-time-string performance-test util test
\r
108 +subdirs = compat completion doc emacs lib man parse-time-string performance-test util test
\r
110 # We make all targets depend on the Makefiles themselves.
\r
111 global_deps = Makefile Makefile.config Makefile.local \
\r
112 diff --git a/doc/Makefile b/doc/Makefile
\r
113 new file mode 100644
\r
114 index 0000000..fa25832
\r
119 + $(MAKE) -C .. all
\r
123 diff --git a/doc/Makefile.local b/doc/Makefile.local
\r
124 new file mode 100644
\r
125 index 0000000..ec23012
\r
127 +++ b/doc/Makefile.local
\r
129 +# -*- makefile -*-
\r
133 +# You can set these variables from the command line.
\r
134 +SPHINXOPTS := -q -c $(dir)
\r
135 +SPHINXBUILD = sphinx-build
\r
136 +DOCBUILDDIR := $(dir)/_build
\r
138 +# Internal variables.
\r
139 +ALLSPHINXOPTS := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(dir)
\r
141 +.PHONY: sphinx-html sphinx-man sphinx-texinfo sphinx-info
\r
144 + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DOCBUILDDIR)/html
\r
147 + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(DOCBUILDDIR)/man
\r
150 + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(DOCBUILDDIR)/texinfo
\r
152 +sphinx-info: sphinx-texinfo
\r
153 + make -C $(DOCBUILDDIR)/texinfo info
\r
155 +CLEAN := $(CLEAN) $(DOCBUILDDIR)
\r
156 diff --git a/doc/conf.py b/doc/conf.py
\r
157 new file mode 100644
\r
158 index 0000000..6c2806d
\r
163 +# -*- coding: utf-8 -*-
\r
168 +# The suffix of source filenames.
\r
169 +source_suffix = '.rst'
\r
171 +# The master toctree document.
\r
172 +master_doc = 'index'
\r
174 +# General information about the project.
\r
175 +project = u'notmuch'
\r
176 +copyright = u'2014, Carl Worth and many others'
\r
178 +# The short X.Y version.
\r
180 +# The full version, including alpha/beta/rc tags.
\r
183 +# List of patterns, relative to source directory, that match files and
\r
184 +# directories to ignore when looking for source files.
\r
185 +exclude_patterns = ['_build', 'notmuch-emacs.rst']
\r
187 +# The name of the Pygments (syntax highlighting) style to use.
\r
188 +pygments_style = 'sphinx'
\r
190 +# -- Options for HTML output ----------------------------------------------
\r
192 +# The theme to use for HTML and HTML Help pages. See the documentation for
\r
193 +# a list of builtin themes.
\r
194 +html_theme = 'default'
\r
197 +# Add any paths that contain custom static files (such as style sheets) here,
\r
198 +# relative to this directory. They are copied after the builtin static files,
\r
199 +# so a file named "default.css" will overwrite the builtin "default.css".
\r
200 +html_static_path = ['_static']
\r
202 +# Output file base name for HTML help builder.
\r
203 +htmlhelp_basename = 'notmuchdoc'
\r
205 +# -- Options for manual page output ---------------------------------------
\r
207 +# One entry per manual page. List of tuples
\r
208 +# (source start file, name, description, authors, manual section).
\r
212 +('man1/notmuch','notmuch',
\r
213 + u'thread-based email index, search, and tagging',
\r
214 + [u'Carl Worth and many others'], 1),
\r
216 +('man1/notmuch-compact','notmuch-compact',
\r
217 + u'compact the notmuch database',
\r
218 + [u'Carl Worth and many others'], 1),
\r
220 +('man1/notmuch-config','notmuch-config',
\r
221 + u'access notmuch configuration file',
\r
222 + [u'Carl Worth and many others'], 1),
\r
224 +('man1/notmuch-count','notmuch-count',
\r
225 + u'count messages matching the given search terms',
\r
226 + [u'Carl Worth and many others'], 1),
\r
228 +('man1/notmuch-dump','notmuch-dump',
\r
229 + u'creates a plain-text dump of the tags of each message',
\r
230 + [u'Carl Worth and many others'], 1),
\r
232 +('man5/notmuch-hooks','notmuch-hooks',
\r
233 + u'hooks for notmuch',
\r
234 + [u'Carl Worth and many others'], 5),
\r
236 +('man1/notmuch-insert','notmuch-insert',
\r
237 + u'add a message to the maildir and notmuch database',
\r
238 + [u'Carl Worth and many others'], 1),
\r
240 +('man1/notmuch-new','notmuch-new',
\r
241 + u'incorporate new mail into the notmuch database',
\r
242 + [u'Carl Worth and many others'], 1),
\r
244 +('man1/notmuch-reply','notmuch-reply',
\r
245 + u'constructs a reply template for a set of messages',
\r
246 + [u'Carl Worth and many others'], 1),
\r
248 +('man1/notmuch-restore','notmuch-restore',
\r
249 + u'restores the tags from the given file (see notmuch dump)',
\r
250 + [u'Carl Worth and many others'], 1),
\r
252 +('man1/notmuch-search','notmuch-search',
\r
253 + u'search for messages matching the given search terms',
\r
254 + [u'Carl Worth and many others'], 1),
\r
256 +('man7/notmuch-search-terms','notmuch-search-terms',
\r
257 + u'syntax for notmuch queries',
\r
258 + [u'Carl Worth and many others'], 7),
\r
260 +('man1/notmuch-show','notmuch-show',
\r
261 + u'show messages matching the given search terms',
\r
262 + [u'Carl Worth and many others'], 1),
\r
264 +('man1/notmuch-tag','notmuch-tag',
\r
265 + u'add/remove tags for all messages matching the search terms',
\r
266 + [u'Carl Worth and many others'], 1),
\r
270 +# If true, show URL addresses after external links.
\r
271 +#man_show_urls = False
\r
273 +# -- Options for Texinfo output -------------------------------------------
\r
275 +# Grouping the document tree into Texinfo files. List of tuples
\r
276 +# (source start file, target name, title, author,
\r
277 +# dir menu entry, description, category)
\r
278 +# If true, do not generate a @detailmenu in the "Top" node's menu.
\r
279 +texinfo_no_detailmenu = True
\r
281 +texinfo_documents = [
\r
282 + ('notmuch-emacs', 'notmuch-emacs', u'notmuch Documentation',
\r
283 + u'Carl Worth and many others', 'notmuch-emacs',
\r
284 + 'emacs based front-end for notmuch', 'Miscellaneous'),
\r
285 +('man1/notmuch','notmuch',u'notmuch Documentation',
\r
286 + u'Carl Worth and many others', 'notmuch',
\r
287 + 'thread-based email index, search, and tagging','Miscellaneous'),
\r
288 +('man1/notmuch-compact','notmuch-compact',u'notmuch Documentation',
\r
289 + u'Carl Worth and many others', 'notmuch-compact',
\r
290 + 'compact the notmuch database','Miscellaneous'),
\r
291 +('man1/notmuch-config','notmuch-config',u'notmuch Documentation',
\r
292 + u'Carl Worth and many others', 'notmuch-config',
\r
293 + 'access notmuch configuration file','Miscellaneous'),
\r
294 +('man1/notmuch-count','notmuch-count',u'notmuch Documentation',
\r
295 + u'Carl Worth and many others', 'notmuch-count',
\r
296 + 'count messages matching the given search terms','Miscellaneous'),
\r
297 +('man1/notmuch-dump','notmuch-dump',u'notmuch Documentation',
\r
298 + u'Carl Worth and many others', 'notmuch-dump',
\r
299 + 'creates a plain-text dump of the tags of each message','Miscellaneous'),
\r
300 +('man5/notmuch-hooks','notmuch-hooks',u'notmuch Documentation',
\r
301 + u'Carl Worth and many others', 'notmuch-hooks',
\r
302 + 'hooks for notmuch','Miscellaneous'),
\r
303 +('man1/notmuch-insert','notmuch-insert',u'notmuch Documentation',
\r
304 + u'Carl Worth and many others', 'notmuch-insert',
\r
305 + 'add a message to the maildir and notmuch database','Miscellaneous'),
\r
306 +('man1/notmuch-new','notmuch-new',u'notmuch Documentation',
\r
307 + u'Carl Worth and many others', 'notmuch-new',
\r
308 + 'incorporate new mail into the notmuch database','Miscellaneous'),
\r
309 +('man1/notmuch-reply','notmuch-reply',u'notmuch Documentation',
\r
310 + u'Carl Worth and many others', 'notmuch-reply',
\r
311 + 'constructs a reply template for a set of messages','Miscellaneous'),
\r
312 +('man1/notmuch-restore','notmuch-restore',u'notmuch Documentation',
\r
313 + u'Carl Worth and many others', 'notmuch-restore',
\r
314 + 'restores the tags from the given file (see notmuch dump)','Miscellaneous'),
\r
315 +('man1/notmuch-search','notmuch-search',u'notmuch Documentation',
\r
316 + u'Carl Worth and many others', 'notmuch-search',
\r
317 + 'search for messages matching the given search terms','Miscellaneous'),
\r
318 +('man7/notmuch-search-terms','notmuch-search-terms',u'notmuch Documentation',
\r
319 + u'Carl Worth and many others', 'notmuch-search-terms',
\r
320 + 'syntax for notmuch queries','Miscellaneous'),
\r
321 +('man1/notmuch-show','notmuch-show',u'notmuch Documentation',
\r
322 + u'Carl Worth and many others', 'notmuch-show',
\r
323 + 'show messages matching the given search terms','Miscellaneous'),
\r
324 +('man1/notmuch-tag','notmuch-tag',u'notmuch Documentation',
\r
325 + u'Carl Worth and many others', 'notmuch-tag',
\r
326 + 'add/remove tags for all messages matching the search terms','Miscellaneous'),
\r
328 diff --git a/doc/index.rst b/doc/index.rst
\r
329 new file mode 100644
\r
330 index 0000000..b33aa9f
\r
332 +++ b/doc/index.rst
\r
335 +Welcome to notmuch's documentation!
\r
336 +===================================
\r
344 + man1/notmuch-compact
\r
345 + man1/notmuch-config
\r
346 + man1/notmuch-count
\r
347 + man1/notmuch-dump
\r
348 + man5/notmuch-hooks
\r
349 + man1/notmuch-insert
\r
351 + man1/notmuch-reply
\r
352 + man1/notmuch-restore
\r
353 + man1/notmuch-search
\r
354 + man7/notmuch-search-terms
\r
355 + man1/notmuch-show
\r
358 +Indices and tables
\r
359 +==================
\r
364 diff --git a/doc/man1/notmuch-compact.rst b/doc/man1/notmuch-compact.rst
\r
365 new file mode 100644
\r
366 index 0000000..e0109dc
\r
368 +++ b/doc/man1/notmuch-compact.rst
\r
377 +**notmuch** **compact** [--quiet] [--backup=<*directory*>]
\r
382 +The **compact** command can be used to compact the notmuch database.
\r
383 +This can both reduce the space required by the database and improve
\r
384 +lookup performance.
\r
386 +The compacted database is built in a temporary directory and is later
\r
387 +moved into the place of the origin database. The original uncompacted
\r
388 +database is discarded, unless the ``--backup=``\ <directory> option is
\r
391 +Note that the database write lock will be held during the compaction
\r
392 +process (which may be quite long) to protect data integrity.
\r
394 +Supported options for **compact** include
\r
396 + ``--backup=``\ <directory>
\r
397 + Save the current database to the given directory before
\r
398 + replacing it with the compacted database. The backup directory
\r
399 + must not exist and it must reside on the same mounted filesystem
\r
400 + as the current database.
\r
403 + Do not report database compaction progress to stdout.
\r
408 +The following environment variables can be used to control the behavior
\r
411 +**NOTMUCH\_CONFIG**
\r
412 + Specifies the location of the notmuch configuration file. Notmuch
\r
413 + will use ${HOME}/.notmuch-config if this variable is not set.
\r
418 +**notmuch(1)**, **notmuch-count(1)**, **notmuch-dump(1)**,
\r
419 +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
420 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
421 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
422 diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst
\r
423 new file mode 100644
\r
424 index 0000000..3c9a568
\r
426 +++ b/doc/man1/notmuch-config.rst
\r
435 +**notmuch** **config** **get** <*section*>.<*item*>
\r
437 +**notmuch** **config** **set** <*section*>.<*item*> [*value* ...]
\r
439 +**notmuch** **config** **list**
\r
444 +The **config** command can be used to get or set settings in the notmuch
\r
445 +configuration file.
\r
448 + The value of the specified configuration item is printed to
\r
449 + stdout. If the item has multiple values (it is a list), each
\r
450 + value is separated by a newline character.
\r
453 + The specified configuration item is set to the given value. To
\r
454 + specify a multiple-value item (a list), provide each value as a
\r
455 + separate command-line argument.
\r
457 + If no values are provided, the specified configuration item will
\r
458 + be removed from the configuration file.
\r
461 + Every configuration item is printed to stdout, each on a
\r
462 + separate line of the form:
\r
464 + *section*.\ *item*\ =\ *value*
\r
466 + No additional whitespace surrounds the dot or equals sign
\r
467 + characters. In a multiple-value item (a list), the values are
\r
468 + separated by semicolon characters.
\r
470 +The available configuration items are described below.
\r
472 + **database.path**
\r
473 + The top-level directory where your mail currently exists and to
\r
474 + where mail will be delivered in the future. Files should be
\r
475 + individual email messages. Notmuch will store its database
\r
476 + within a sub-directory of the path configured here named
\r
482 + **user.primary\_email**
\r
483 + Your primary email address.
\r
485 + **user.other\_email**
\r
486 + A list of other email addresses at which you receive email.
\r
489 + A list of tags that will be added to all messages incorporated
\r
490 + by **notmuch new**.
\r
493 + A list of file and directory names, without path, that will not
\r
494 + be searched for messages by **notmuch new**. All the files and
\r
495 + directories matching any of the names specified here will be
\r
496 + ignored, regardless of the location in the mail store directory
\r
499 + **search.exclude\_tags**
\r
500 + A list of tags that will be excluded from search results by
\r
501 + default. Using an excluded tag in a query will override that
\r
504 + **maildir.synchronize\_flags**
\r
505 + If true, then the following maildir flags (in message filenames)
\r
506 + will be synchronized with the corresponding notmuch tags:
\r
508 + +--------+-----------------------------------------------+
\r
510 + +========+===============================================+
\r
512 + +--------+-----------------------------------------------+
\r
514 + +--------+-----------------------------------------------+
\r
516 + +--------+-----------------------------------------------+
\r
518 + +--------+-----------------------------------------------+
\r
519 + | S | unread (added when 'S' flag is not present) |
\r
520 + +--------+-----------------------------------------------+
\r
522 + The **notmuch new** command will notice flag changes in
\r
523 + filenames and update tags, while the **notmuch tag** and
\r
524 + **notmuch restore** commands will notice tag changes and update
\r
525 + flags in filenames.
\r
527 + If there have been any changes in the maildir (new messages
\r
528 + added, old ones removed or renamed, maildir flags changed,
\r
529 + etc.), it is advisable to run **notmuch new** before **notmuch
\r
530 + tag** or **notmuch restore** commands to ensure the tag changes
\r
531 + are properly synchronized to the maildir flags, as the commands
\r
532 + expect the database and maildir to be in sync.
\r
537 +The following environment variables can be used to control the behavior
\r
540 +**NOTMUCH\_CONFIG**
\r
541 + Specifies the location of the notmuch configuration file. Notmuch
\r
542 + will use ${HOME}/.notmuch-config if this variable is not set.
\r
547 +**notmuch(1)**, **notmuch-count(1)**, **notmuch-dump(1)**,
\r
548 +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
549 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
550 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
551 diff --git a/doc/man1/notmuch-count.rst b/doc/man1/notmuch-count.rst
\r
552 new file mode 100644
\r
553 index 0000000..ca78c18
\r
555 +++ b/doc/man1/notmuch-count.rst
\r
564 +**notmuch** **count** [*option* ...] <*search-term*> ...
\r
569 +Count messages matching the search terms.
\r
571 +The number of matching messages (or threads) is output to stdout.
\r
573 +With no search terms, a count of all messages (or threads) in the
\r
574 +database will be displayed.
\r
576 +See **notmuch-search-terms(7)** for details of the supported syntax for
\r
579 +Supported options for **count** include
\r
581 + ``--output=(messages|threads|files)``
\r
584 + Output the number of matching messages. This is the default.
\r
587 + Output the number of matching threads.
\r
590 + Output the number of files associated with matching
\r
591 + messages. This may be bigger than the number of matching
\r
592 + messages due to duplicates (i.e. multiple files having the
\r
593 + same message-id).
\r
595 + ``--exclude=(true|false)``
\r
596 + Specify whether to omit messages matching search.tag\_exclude
\r
597 + from the count (the default) or not.
\r
600 + Read queries from a file (stdin by default), one per line, and
\r
601 + output the number of matching messages (or threads) to stdout,
\r
602 + one per line. On an empty input line the count of all messages
\r
603 + (or threads) in the database will be output. This option is not
\r
604 + compatible with specifying search terms on the command line.
\r
606 + ``--input=``\ <filename>
\r
607 + Read input from given file, instead of from stdin. Implies
\r
613 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-dump(1)**,
\r
614 +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
615 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
616 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
617 diff --git a/doc/man1/notmuch-dump.rst b/doc/man1/notmuch-dump.rst
\r
618 new file mode 100644
\r
619 index 0000000..17d1da5
\r
621 +++ b/doc/man1/notmuch-dump.rst
\r
630 +**notmuch** **dump** [--format=(batch-tag|sup)] [--] [--output=<*file*>] [--] [<*search-term*> ...]
\r
635 +Dump tags for messages matching the given search terms.
\r
637 +Output is to the given filename, if any, or to stdout.
\r
639 +These tags are the only data in the notmuch database that can't be
\r
640 +recreated from the messages themselves. The output of notmuch dump is
\r
641 +therefore the only critical thing to backup (and much more friendly to
\r
642 +incremental backup than the native database files.)
\r
644 +``--format=(sup|batch-tag)``
\r
645 + Notmuch restore supports two plain text dump formats, both with one
\r
646 + message-id per line, followed by a list of tags.
\r
649 + The default **batch-tag** dump format is intended to more robust
\r
650 + against malformed message-ids and tags containing whitespace or
\r
651 + non-\ **ascii(7)** characters. Each line has the form
\r
653 + +<*encoded-tag*\ > +<*encoded-tag*\ > ... --
\r
654 + id:<*quoted-message-id*\ >
\r
656 + Tags are hex-encoded by replacing every byte not matching the
\r
657 + regex **[A-Za-z0-9@=.,\_+-]** with **%nn** where nn is the two
\r
658 + digit hex encoding. The message ID is a valid Xapian query,
\r
659 + quoted using Xapian boolean term quoting rules: if the ID
\r
660 + contains whitespace or a close paren or starts with a double
\r
661 + quote, it must be enclosed in double quotes and double quotes
\r
662 + inside the ID must be doubled. The astute reader will notice
\r
663 + this is a special case of the batch input format for
\r
664 + **notmuch-tag(1)**; note that the single message-id query is
\r
665 + mandatory for **notmuch-restore(1)**.
\r
668 + The **sup** dump file format is specifically chosen to be
\r
669 + compatible with the format of files produced by sup-dump. So if
\r
670 + you've previously been using sup for mail, then the **notmuch
\r
671 + restore** command provides you a way to import all of your tags
\r
672 + (or labels as sup calls them). Each line has the following form
\r
674 + <*message-id*\ > **(** <*tag*\ > ... **)**
\r
676 + with zero or more tags are separated by spaces. Note that
\r
677 + (malformed) message-ids may contain arbitrary non-null
\r
678 + characters. Note also that tags with spaces will not be
\r
679 + correctly restored with this format.
\r
681 + With no search terms, a dump of all messages in the database will be
\r
682 + generated. A "--" argument instructs notmuch that the remaining
\r
683 + arguments are search terms.
\r
685 + See **notmuch-search-terms(7)** for details of the supported syntax
\r
686 + for <search-terms>.
\r
691 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
692 +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
693 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
694 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
695 diff --git a/doc/man1/notmuch-insert.rst b/doc/man1/notmuch-insert.rst
\r
696 new file mode 100644
\r
697 index 0000000..2be1a7b
\r
699 +++ b/doc/man1/notmuch-insert.rst
\r
708 +**notmuch** **insert** [option ...] [+<*tag*>|-<*tag*> ...]
\r
713 +**notmuch insert** reads a message from standard input and delivers it
\r
714 +into the maildir directory given by configuration option
\r
715 +**database.path**, then incorporates the message into the notmuch
\r
716 +database. It is an alternative to using a separate tool to deliver the
\r
717 +message then running **notmuch new** afterwards.
\r
719 +The new message will be tagged with the tags specified by the
\r
720 +**new.tags** configuration option, then by operations specified on the
\r
721 +command-line: tags prefixed by '+' are added while those prefixed by '-'
\r
724 +If the new message is a duplicate of an existing message in the database
\r
725 +(it has same Message-ID), it will be added to the maildir folder and
\r
726 +notmuch database, but the tags will not be changed.
\r
728 +Option arguments must appear before any tag operation arguments.
\r
729 +Supported options for **insert** include
\r
731 + ``--folder=<``\ folder\ **>**
\r
732 + Deliver the message to the specified folder, relative to the
\r
733 + top-level directory given by the value of **database.path**. The
\r
734 + default is to deliver to the top-level directory.
\r
736 + ``--create-folder``
\r
737 + Try to create the folder named by the ``--folder`` option, if it
\r
738 + does not exist. Otherwise the folder must already exist for mail
\r
739 + delivery to succeed.
\r
744 +This command returns exit status 0 if the message was successfully added
\r
745 +to the mail directory, even if the message could not be indexed and
\r
746 +added to the notmuch database. In the latter case, a warning will be
\r
747 +printed to standard error but the message file will be left on disk.
\r
749 +If the message could not be written to disk then a non-zero exit status
\r
755 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
756 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-reply(1)**,
\r
757 +**notmuch-restore(1)**, **notmuch-search(1)**,
\r
758 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
759 diff --git a/doc/man1/notmuch-new.rst b/doc/man1/notmuch-new.rst
\r
760 new file mode 100644
\r
761 index 0000000..d11fcee
\r
763 +++ b/doc/man1/notmuch-new.rst
\r
772 +**notmuch** **new** [--no-hooks]
\r
777 +Find and import any new messages to the database.
\r
779 +The **new** command scans all sub-directories of the database,
\r
780 +performing full-text indexing on new messages that are found. Each new
\r
781 +message will automatically be tagged with both the **inbox** and
\r
784 +You should run **notmuch new** once after first running **notmuch
\r
785 +setup** to create the initial database. The first run may take a long
\r
786 +time if you have a significant amount of mail (several hundred thousand
\r
787 +messages or more). Subsequently, you should run **notmuch new** whenever
\r
788 +new mail is delivered and you wish to incorporate it into the database.
\r
789 +These subsequent runs will be much quicker than the initial run.
\r
791 +Invoking ``notmuch`` with no command argument will run **new** if
\r
792 +**notmuch setup** has previously been completed, but **notmuch new** has
\r
793 +not previously been run.
\r
795 +**notmuch new** updates tags according to maildir flag changes if the
\r
796 +**maildir.synchronize\_flags** configuration option is enabled. See
\r
797 +**notmuch-config(1)** for details.
\r
799 +The **new** command supports hooks. See **notmuch-hooks(5)** for more
\r
802 +Supported options for **new** include
\r
805 + Prevents hooks from being run.
\r
808 + Do not print progress or results.
\r
813 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
814 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
815 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
816 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
817 diff --git a/doc/man1/notmuch-reply.rst b/doc/man1/notmuch-reply.rst
\r
818 new file mode 100644
\r
819 index 0000000..cfbd4ea
\r
821 +++ b/doc/man1/notmuch-reply.rst
\r
830 +**notmuch** **reply** [option ...] <*search-term*> ...
\r
835 +Constructs a reply template for a set of messages.
\r
837 +To make replying to email easier, **notmuch reply** takes an existing
\r
838 +set of messages and constructs a suitable mail template. The Reply-to:
\r
839 +header (if any, otherwise From:) is used for the To: address. Unless
\r
840 +``--reply-to=sender`` is specified, values from the To: and Cc: headers
\r
841 +are copied, but not including any of the current user's email addresses
\r
842 +(as configured in primary\_mail or other\_email in the .notmuch-config
\r
843 +file) in the recipient list.
\r
845 +It also builds a suitable new subject, including Re: at the front (if
\r
846 +not already present), and adding the message IDs of the messages being
\r
847 +replied to to the References list and setting the In-Reply-To: field
\r
850 +Finally, the original contents of the emails are quoted by prefixing
\r
851 +each line with '> ' and included in the body.
\r
853 +The resulting message template is output to stdout.
\r
855 +Supported options for **reply** include
\r
857 + ``--format=``\ (**default**\ \|\ **json**\ \|\ **sexp**\ \|\ **headers-only**)
\r
860 + Includes subject and quoted message body as an RFC 2822
\r
864 + Produces JSON output containing headers for a reply message
\r
865 + and the contents of the original message. This output can be
\r
866 + used by a client to create a reply message intelligently.
\r
869 + Produces S-Expression output containing headers for a reply
\r
870 + message and the contents of the original message. This
\r
871 + output can be used by a client to create a reply message
\r
875 + Only produces In-Reply-To, References, To, Cc, and Bcc
\r
878 + ``--format-version=N``
\r
879 + Use the specified structured output format version. This is
\r
880 + intended for programs that invoke **notmuch(1)** internally. If
\r
881 + omitted, the latest supported version will be used.
\r
883 + ``--reply-to=``\ (**all**\ \|\ **sender**)
\r
885 + **all** (default)
\r
886 + Replies to all addresses.
\r
889 + Replies only to the sender. If replying to user's own
\r
890 + message (Reply-to: or From: header is one of the user's
\r
891 + configured email addresses), try To:, Cc:, and Bcc: headers
\r
892 + in this order, and copy values from the first that contains
\r
893 + something other than only the user's addresses.
\r
896 + Decrypt any MIME encrypted parts found in the selected content
\r
897 + (ie. "multipart/encrypted" parts). Status of the decryption will
\r
898 + be reported (currently only supported with --format=json and
\r
899 + --format=sexp) and on successful decryption the
\r
900 + multipart/encrypted part will be replaced by the decrypted
\r
903 + Decryption expects a functioning **gpg-agent(1)** to provide any
\r
904 + needed credentials. Without one, the decryption will fail.
\r
906 +See **notmuch-search-terms(7)** for details of the supported syntax for
\r
909 +Note: It is most common to use **notmuch reply** with a search string
\r
910 +matching a single message, (such as id:<message-id>), but it can be
\r
911 +useful to reply to several messages at once. For example, when a series
\r
912 +of patches are sent in a single thread, replying to the entire thread
\r
913 +allows for the reply to comment on issues found in multiple patches. The
\r
914 +default format supports replying to multiple messages at once, but the
\r
915 +JSON and S-Expression formats do not.
\r
920 +This command supports the following special exit status codes
\r
923 + The requested format version is too old.
\r
926 + The requested format version is too new.
\r
931 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
932 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
933 +**notmuch-new(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
934 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
935 diff --git a/doc/man1/notmuch-restore.rst b/doc/man1/notmuch-restore.rst
\r
936 new file mode 100644
\r
937 index 0000000..d6cf19a
\r
939 +++ b/doc/man1/notmuch-restore.rst
\r
948 +**notmuch** **restore** [--accumulate] [--format=(auto|batch-tag|sup)] [--input=<*filename*>]
\r
953 +Restores the tags from the given file (see **notmuch dump**).
\r
955 +The input is read from the given filename, if any, or from stdin.
\r
957 +Supported options for **restore** include
\r
960 + The union of the existing and new tags is applied, instead of
\r
961 + replacing each message's tags as they are read in from the dump
\r
964 + ``--format=(sup|batch-tag|auto)``
\r
965 + Notmuch restore supports two plain text dump formats, with each
\r
966 + line specifying a message-id and a set of tags. For details of
\r
967 + the actual formats, see **notmuch-dump(1)**.
\r
970 + The **sup** dump file format is specifically chosen to be
\r
971 + compatible with the format of files produced by sup-dump. So
\r
972 + if you've previously been using sup for mail, then the
\r
973 + **notmuch restore** command provides you a way to import all
\r
974 + of your tags (or labels as sup calls them).
\r
977 + The **batch-tag** dump format is intended to more robust
\r
978 + against malformed message-ids and tags containing whitespace
\r
979 + or non-\ **ascii(7)** characters. See **notmuch-dump(1)**
\r
980 + for details on this format.
\r
982 + **notmuch restore** updates the maildir flags according to
\r
983 + tag changes if the **maildir.synchronize\_flags**
\r
984 + configuration option is enabled. See **notmuch-config(1)**
\r
988 + This option (the default) tries to guess the format from the
\r
989 + input. For correctly formed input in either supported
\r
990 + format, this heuristic, based the fact that batch-tag format
\r
991 + contains no parentheses, should be accurate.
\r
996 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
997 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
998 +**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-search(1)**,
\r
999 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1000 diff --git a/doc/man1/notmuch-search.rst b/doc/man1/notmuch-search.rst
\r
1001 new file mode 100644
\r
1002 index 0000000..7ac6c68
\r
1004 +++ b/doc/man1/notmuch-search.rst
\r
1013 +**notmuch** **search** [*option* ...] <*search-term*> ...
\r
1018 +Search for messages matching the given search terms, and display as
\r
1019 +results the threads containing the matched messages.
\r
1021 +The output consists of one line per thread, giving a thread ID, the date
\r
1022 +of the newest (or oldest, depending on the sort option) matched message
\r
1023 +in the thread, the number of matched messages and total messages in the
\r
1024 +thread, the names of all participants in the thread, and the subject of
\r
1025 +the newest (or oldest) message.
\r
1027 +See **notmuch-search-terms(7)** for details of the supported syntax for
\r
1030 +Supported options for **search** include
\r
1032 + ``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**)
\r
1033 + Presents the results in either JSON, S-Expressions, newline
\r
1034 + character separated plain-text (default), or null character
\r
1035 + separated plain-text (compatible with **xargs(1)** -0 option
\r
1036 + where available).
\r
1038 + ``--format-version=N``
\r
1039 + Use the specified structured output format version. This is
\r
1040 + intended for programs that invoke **notmuch(1)** internally. If
\r
1041 + omitted, the latest supported version will be used.
\r
1043 + ``--output=(summary|threads|messages|files|tags)``
\r
1046 + Output a summary of each thread with any message matching
\r
1047 + the search terms. The summary includes the thread ID, date,
\r
1048 + the number of messages in the thread (both the number
\r
1049 + matched and the total number), the authors of the thread and
\r
1053 + Output the thread IDs of all threads with any message
\r
1054 + matching the search terms, either one per line
\r
1055 + (--format=text), separated by null characters
\r
1056 + (--format=text0), as a JSON array (--format=json), or an
\r
1057 + S-Expression list (--format=sexp).
\r
1060 + Output the message IDs of all messages matching the search
\r
1061 + terms, either one per line (--format=text), separated by
\r
1062 + null characters (--format=text0), as a JSON array
\r
1063 + (--format=json), or as an S-Expression list (--format=sexp).
\r
1066 + Output the filenames of all messages matching the search
\r
1067 + terms, either one per line (--format=text), separated by
\r
1068 + null characters (--format=text0), as a JSON array
\r
1069 + (--format=json), or as an S-Expression list (--format=sexp).
\r
1071 + Note that each message may have multiple filenames
\r
1072 + associated with it. All of them are included in the output,
\r
1073 + unless limited with the --duplicate=N option.
\r
1076 + Output all tags that appear on any message matching the
\r
1077 + search terms, either one per line (--format=text), separated
\r
1078 + by null characters (--format=text0), as a JSON array
\r
1079 + (--format=json), or as an S-Expression list (--format=sexp).
\r
1081 + ``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
\r
1082 + This option can be used to present results in either
\r
1083 + chronological order (**oldest-first**) or reverse chronological
\r
1084 + order (**newest-first**).
\r
1086 + Note: The thread order will be distinct between these two
\r
1087 + options (beyond being simply reversed). When sorting by
\r
1088 + **oldest-first** the threads will be sorted by the oldest
\r
1089 + message in each thread, but when sorting by **newest-first** the
\r
1090 + threads will be sorted by the newest message in each thread.
\r
1092 + By default, results will be displayed in reverse chronological
\r
1093 + order, (that is, the newest results will be displayed first).
\r
1095 + ``--offset=[-]N``
\r
1096 + Skip displaying the first N results. With the leading '-', start
\r
1097 + at the Nth result from the end.
\r
1100 + Limit the number of displayed results to N.
\r
1102 + ``--exclude=(true|false|all|flag)``
\r
1103 + A message is called "excluded" if it matches at least one tag in
\r
1104 + search.tag\_exclude that does not appear explicitly in the
\r
1105 + search terms. This option specifies whether to omit excluded
\r
1106 + messages in the search process.
\r
1108 + The default value, **true**, prevents excluded messages from
\r
1109 + matching the search terms.
\r
1111 + **all** additionally prevents excluded messages from appearing
\r
1112 + in displayed results, in effect behaving as though the excluded
\r
1113 + messages do not exist.
\r
1115 + **false** allows excluded messages to match search terms and
\r
1116 + appear in displayed results. Excluded messages are still marked
\r
1117 + in the relevant outputs.
\r
1119 + **flag** only has an effect when ``--output=summary``. The
\r
1120 + output is almost identical to **false**, but the "match count"
\r
1121 + is the number of matching non-excluded messages in the thread,
\r
1122 + rather than the number of matching messages.
\r
1124 + ``--duplicate=N``
\r
1125 + Effective with ``--output=files``, output the Nth filename
\r
1126 + associated with each message matching the query (N is 1-based).
\r
1127 + If N is greater than the number of files associated with the
\r
1128 + message, don't print anything.
\r
1130 + Note that this option is orthogonal with the **folder:** search
\r
1131 + prefix. The prefix matches messages based on filenames. This
\r
1132 + option filters filenames of the matching messages.
\r
1137 +This command supports the following special exit status codes
\r
1140 + The requested format version is too old.
\r
1143 + The requested format version is too new.
\r
1148 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1149 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
1150 +**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
\r
1151 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1152 diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst
\r
1153 new file mode 100644
\r
1154 index 0000000..bad868b
\r
1156 +++ b/doc/man1/notmuch-show.rst
\r
1165 +**notmuch** **show** [*option* ...] <*search-term*> ...
\r
1170 +Shows all messages matching the search terms.
\r
1172 +See **notmuch-search-terms(7)** for details of the supported syntax for
\r
1175 +The messages will be grouped and sorted based on the threading (all
\r
1176 +replies to a particular message will appear immediately after that
\r
1177 +message in date order). The output is not indented by default, but depth
\r
1178 +tags are printed so that proper indentation can be performed by a
\r
1179 +post-processor (such as the emacs interface to notmuch).
\r
1181 +Supported options for **show** include
\r
1183 + ``--entire-thread=(true|false)``
\r
1184 + If true, **notmuch show** outputs all messages in the thread of
\r
1185 + any message matching the search terms; if false, it outputs only
\r
1186 + the matching messages. For ``--format=json`` and
\r
1187 + ``--format=sexp`` this defaults to true. For other formats, this
\r
1188 + defaults to false.
\r
1190 + ``--format=(text|json|sexp|mbox|raw)``
\r
1192 + **text** (default for messages)
\r
1193 + The default plain-text format has all text-content MIME
\r
1194 + parts decoded. Various components in the output,
\r
1195 + (**message**, **header**, **body**, **attachment**, and MIME
\r
1196 + **part**), will be delimited by easily-parsed markers. Each
\r
1197 + marker consists of a Control-L character (ASCII decimal 12),
\r
1198 + the name of the marker, and then either an opening or
\r
1199 + closing brace, ('{' or '}'), to either open or close the
\r
1200 + component. For a multipart MIME message, these parts will be
\r
1204 + The output is formatted with Javascript Object Notation
\r
1205 + (JSON). This format is more robust than the text format for
\r
1206 + automated processing. The nested structure of multipart MIME
\r
1207 + messages is reflected in nested JSON output. By default JSON
\r
1208 + output includes all messages in a matching thread; that is,
\r
1211 + ``--format=json`` sets ``--entire-thread`` The caller can
\r
1212 + disable this behaviour by setting ``--entire-thread=false``
\r
1215 + The output is formatted as an S-Expression (sexp). This
\r
1216 + format is more robust than the text format for automated
\r
1217 + processing. The nested structure of multipart MIME messages
\r
1218 + is reflected in nested S-Expression output. By default,
\r
1219 + S-Expression output includes all messages in a matching
\r
1220 + thread; that is, by default,
\r
1222 + ``--format=sexp`` sets ``--entire-thread`` The caller can
\r
1223 + disable this behaviour by setting ``--entire-thread=false``
\r
1226 + All matching messages are output in the traditional, Unix
\r
1227 + mbox format with each message being prefixed by a line
\r
1228 + beginning with "From " and a blank line separating each
\r
1229 + message. Lines in the message content beginning with "From "
\r
1230 + (preceded by zero or more '>' characters) have an additional
\r
1231 + '>' character added. This reversible escaping is termed
\r
1232 + "mboxrd" format and described in detail here:
\r
1234 + http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
\r
1236 + **raw** (default for a single part, see --part)
\r
1237 + For a message or an attached message part, the original, raw
\r
1238 + content of the email message is output. Consumers of this
\r
1239 + format should expect to implement MIME decoding and similar
\r
1242 + For a single part (--part) the raw part content is output
\r
1243 + after performing any necessary MIME decoding. Note that
\r
1244 + messages with a simple body still have two parts: part 0 is
\r
1245 + the whole message and part 1 is the body.
\r
1247 + For a multipart part, the part headers and body (including
\r
1248 + all child parts) is output.
\r
1250 + The raw format must only be used with search terms matching
\r
1253 + ``--format-version=N``
\r
1254 + Use the specified structured output format version. This is
\r
1255 + intended for programs that invoke **notmuch(1)** internally. If
\r
1256 + omitted, the latest supported version will be used.
\r
1259 + Output the single decoded MIME part N of a single message. The
\r
1260 + search terms must match only a single message. Message parts are
\r
1261 + numbered in a depth-first walk of the message MIME structure,
\r
1262 + and are identified in the 'json', 'sexp' or 'text' output
\r
1266 + Compute and report the validity of any MIME cryptographic
\r
1267 + signatures found in the selected content (ie. "multipart/signed"
\r
1268 + parts). Status of the signature will be reported (currently only
\r
1269 + supported with --format=json and --format=sexp), and the
\r
1270 + multipart/signed part will be replaced by the signed data.
\r
1273 + Decrypt any MIME encrypted parts found in the selected content
\r
1274 + (ie. "multipart/encrypted" parts). Status of the decryption will
\r
1275 + be reported (currently only supported with --format=json and
\r
1276 + --format=sexp) and on successful decryption the
\r
1277 + multipart/encrypted part will be replaced by the decrypted
\r
1280 + Decryption expects a functioning **gpg-agent(1)** to provide any
\r
1281 + needed credentials. Without one, the decryption will fail.
\r
1283 + Implies --verify.
\r
1285 + ``--exclude=(true|false)``
\r
1286 + Specify whether to omit threads only matching
\r
1287 + search.tag\_exclude from the search results (the default) or
\r
1288 + not. In either case the excluded message will be marked with the
\r
1289 + exclude flag (except when output=mbox when there is nowhere to
\r
1292 + If --entire-thread is specified then complete threads are
\r
1293 + returned regardless (with the excluded flag being set when
\r
1294 + appropriate) but threads that only match in an excluded message
\r
1295 + are not returned when ``--exclude=true.``
\r
1297 + The default is ``--exclude=true.``
\r
1299 + ``--body=(true|false)``
\r
1300 + If true (the default) **notmuch show** includes the bodies of
\r
1301 + the messages in the output; if false, bodies are omitted.
\r
1302 + ``--body=false`` is only implemented for the json and sexp
\r
1303 + formats and it is incompatible with ``--part > 0.``
\r
1305 + This is useful if the caller only needs the headers as body-less
\r
1306 + output is much faster and substantially smaller.
\r
1308 + ``--include-html``
\r
1309 + Include "text/html" parts as part of the output (currently only
\r
1310 + supported with --format=json and --format=sexp). By default,
\r
1311 + unless ``--part=N`` is used to select a specific part or
\r
1312 + ``--include-html`` is used to include all "text/html" parts, no
\r
1313 + part with content type "text/html" is included in the output.
\r
1315 +A common use of **notmuch show** is to display a single thread of email
\r
1316 +messages. For this, use a search term of "thread:<thread-id>" as can be
\r
1317 +seen in the first column of output from the **notmuch search** command.
\r
1322 +This command supports the following special exit status codes
\r
1325 + The requested format version is too old.
\r
1328 + The requested format version is too new.
\r
1333 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1334 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
1335 +**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
\r
1336 +**notmuch-search(1)**, **notmuch-search-terms(7)**, **notmuch-tag(1)**
\r
1337 diff --git a/doc/man1/notmuch-tag.rst b/doc/man1/notmuch-tag.rst
\r
1338 new file mode 100644
\r
1339 index 0000000..2e7e1d3
\r
1341 +++ b/doc/man1/notmuch-tag.rst
\r
1350 +**notmuch** **tag** [options ...] +<*tag*>|-<*tag*> [--] <*search-term*> ...
\r
1352 +**notmuch** **tag** **--batch** [--input=<*filename*>]
\r
1357 +Add/remove tags for all messages matching the search terms.
\r
1359 +See **notmuch-search-terms(7)** for details of the supported syntax for
\r
1360 +<*search-term*\ >.
\r
1362 +Tags prefixed by '+' are added while those prefixed by '-' are removed.
\r
1363 +For each message, tag changes are applied in the order they appear on
\r
1364 +the command line.
\r
1366 +The beginning of the search terms is recognized by the first argument
\r
1367 +that begins with neither '+' nor '-'. Support for an initial search term
\r
1368 +beginning with '+' or '-' is provided by allowing the user to specify a
\r
1369 +"--" argument to separate the tags from the search terms.
\r
1371 +**notmuch tag** updates the maildir flags according to tag changes if
\r
1372 +the **maildir.synchronize\_flags** configuration option is enabled. See
\r
1373 +**notmuch-config(1)** for details.
\r
1375 +Supported options for **tag** include
\r
1377 + ``--remove-all``
\r
1378 + Remove all tags from each message matching the search terms
\r
1379 + before applying the tag changes appearing on the command line.
\r
1380 + This means setting the tags of each message to the tags to be
\r
1381 + added. If there are no tags to be added, the messages will have
\r
1385 + Read batch tagging operations from a file (stdin by default).
\r
1386 + This is more efficient than repeated **notmuch tag**
\r
1387 + invocations. See `TAG FILE FORMAT <#tag_file_format>`__ below
\r
1388 + for the input format. This option is not compatible with
\r
1389 + specifying tagging on the command line.
\r
1391 + ``--input=``\ <filename>
\r
1392 + Read input from given file, instead of from stdin. Implies
\r
1398 +The input must consist of lines of the format:
\r
1400 ++<*tag*\ >\|-<*tag*\ > [...] [--] <*query*\ >
\r
1402 +Each line is interpreted similarly to **notmuch tag** command line
\r
1403 +arguments. The delimiter is one or more spaces ' '. Any characters in
\r
1404 +<*tag*\ > **may** be hex-encoded with %NN where NN is the hexadecimal
\r
1405 +value of the character. To hex-encode a character with a multi-byte
\r
1406 +UTF-8 encoding, hex-encode each byte. Any spaces in <tag> **must** be
\r
1407 +hex-encoded as %20. Any characters that are not part of <*tag*\ > **must
\r
1408 +not** be hex-encoded.
\r
1410 +In the future tag:"tag with spaces" style quoting may be supported for
\r
1411 +<*tag*\ > as well; for this reason all double quote characters in
\r
1412 +<*tag*\ > **should** be hex-encoded.
\r
1414 +The <*query*\ > should be quoted using Xapian boolean term quoting
\r
1415 +rules: if a term contains whitespace or a close paren or starts with a
\r
1416 +double quote, it must be enclosed in double quotes (not including any
\r
1417 +prefix) and double quotes inside the term must be doubled (see below for
\r
1420 +Leading and trailing space ' ' is ignored. Empty lines and lines
\r
1421 +beginning with '#' are ignored.
\r
1426 +The following shows a valid input to batch tagging. Note that only the
\r
1427 +isolated '\*' acts as a wildcard. Also note the two different quotings
\r
1428 +of the tag **space in tags**
\r
1433 + +foo::bar%25 -- (One and Two) or (One and tag:winner)
\r
1434 + +found::it -- tag:foo::bar%
\r
1435 + # ignore this line and the next
\r
1437 + +space%20in%20tags -- Two
\r
1438 + # add tag '(tags)', among other stunts.
\r
1439 + +crazy{ +(tags) +&are +#possible\ -- tag:"space in tags"
\r
1440 + +match*crazy -- tag:crazy{
\r
1441 + +some_tag -- id:"this is ""nauty)"""
\r
1446 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1447 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
1448 +**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
\r
1449 +**notmuch-search(1)**, **notmuch-search-terms(7)**, **notmuch-show(1)**,
\r
1450 diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst
\r
1451 new file mode 100644
\r
1452 index 0000000..343927f
\r
1454 +++ b/doc/man1/notmuch.rst
\r
1463 +**notmuch** [option ...] **command** [arg ...]
\r
1468 +Notmuch is a command-line based program for indexing, searching,
\r
1469 +reading, and tagging large collections of email messages.
\r
1471 +This page describes how to get started using notmuch from the command
\r
1472 +line, and gives a brief overview of the commands available. For more
\r
1473 +information on e.g. **notmuch show** consult the **notmuch-show(1)** man
\r
1474 +page, also accessible via **notmuch help show**
\r
1476 +The quickest way to get started with Notmuch is to simply invoke the
\r
1477 +``notmuch`` command with no arguments, which will interactively guide
\r
1478 +you through the process of indexing your mail.
\r
1483 +While the command-line program ``notmuch`` provides powerful
\r
1484 +functionality, it does not provide the most convenient interface for
\r
1485 +that functionality. More sophisticated interfaces are expected to be
\r
1486 +built on top of either the command-line interface, or more likely, on
\r
1487 +top of the notmuch library interface. See http://notmuchmail.org for
\r
1488 +more about alternate interfaces to notmuch. The emacs-based interface to
\r
1489 +notmuch (available under **emacs/** in the Notmuch source distribution)
\r
1490 +is probably the most widely used at this time.
\r
1495 +Supported global options for ``notmuch`` include
\r
1498 + Print a synopsis of available commands and exit.
\r
1501 + Print the installed version of notmuch, and exit.
\r
1503 + ``--config=FILE``
\r
1504 + Specify the configuration file to use. This overrides any
\r
1505 + configuration file specified by ${NOTMUCH\_CONFIG}.
\r
1513 +The **notmuch setup** command is used to configure Notmuch for first
\r
1514 +use, (or to reconfigure it later).
\r
1516 +The setup command will prompt for your full name, your primary email
\r
1517 +address, any alternate email addresses you use, and the directory
\r
1518 +containing your email archives. Your answers will be written to a
\r
1519 +configuration file in ${NOTMUCH\_CONFIG} (if set) or
\r
1520 +${HOME}/.notmuch-config . This configuration file will be created with
\r
1521 +descriptive comments, making it easy to edit by hand later to change the
\r
1522 +configuration. Or you can run **notmuch setup** again to change the
\r
1525 +The mail directory you specify can contain any number of sub-directories
\r
1526 +and should primarily contain only files with individual email messages
\r
1527 +(eg. maildir or mh archives are perfect). If there are other, non-email
\r
1528 +files (such as indexes maintained by other email programs) then notmuch
\r
1529 +will do its best to detect those and ignore them.
\r
1531 +Mail storage that uses mbox format, (where one mbox file contains many
\r
1532 +messages), will not work with notmuch. If that's how your mail is
\r
1533 +currently stored, it is recommended you first convert it to maildir
\r
1534 +format with a utility such as mb2md before running **notmuch setup .**
\r
1536 +Invoking ``notmuch`` with no command argument will run **setup** if the
\r
1537 +setup command has not previously been completed.
\r
1542 +Several of the notmuch commands accept search terms with a common
\r
1543 +syntax. See *notmuch-search-terms*\ (7) for more details on the
\r
1544 +supported syntax.
\r
1546 +The **search**, **show** and **count** commands are used to query the
\r
1549 +The **reply** command is useful for preparing a template for an email
\r
1552 +The **tag** command is the only command available for manipulating
\r
1553 +database contents.
\r
1555 +The **dump** and **restore** commands can be used to create a textual
\r
1556 +dump of email tags for backup purposes, and to restore from that dump.
\r
1558 +The **config** command can be used to get or set settings in the notmuch
\r
1559 +configuration file.
\r
1564 +The following environment variables can be used to control the behavior
\r
1567 +**NOTMUCH\_CONFIG**
\r
1568 + Specifies the location of the notmuch configuration file. Notmuch
\r
1569 + will use ${HOME}/.notmuch-config if this variable is not set.
\r
1571 +**NOTMUCH\_TALLOC\_REPORT**
\r
1572 + Location to write a talloc memory usage report. See
\r
1573 + **talloc\_enable\_leak\_report\_full** in **talloc(3)** for more
\r
1576 +**NOTMUCH\_DEBUG\_QUERY**
\r
1577 + If set to a non-empty value, the notmuch library will print (to
\r
1578 + stderr) Xapian queries it constructs.
\r
1583 +**notmuch-config(1)**, **notmuch-count(1)**, **notmuch-dump(1)**,
\r
1584 +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
1585 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
1586 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1588 +The notmuch website: **http://notmuchmail.org**
\r
1593 +Feel free to send questions, comments, or kudos to the notmuch mailing
\r
1594 +list <notmuch@notmuchmail.org> . Subscription is not required before
\r
1595 +posting, but is available from the notmuchmail.org website.
\r
1597 +Real-time interaction with the Notmuch community is available via IRC
\r
1598 +(server: irc.freenode.net, channel: #notmuch).
\r
1599 diff --git a/doc/man5/notmuch-hooks.rst b/doc/man5/notmuch-hooks.rst
\r
1600 new file mode 100644
\r
1601 index 0000000..493abf2
\r
1603 +++ b/doc/man5/notmuch-hooks.rst
\r
1612 + $DATABASEDIR/.notmuch/hooks/*
\r
1617 +Hooks are scripts (or arbitrary executables or symlinks to such) that
\r
1618 +notmuch invokes before and after certain actions. These scripts reside
\r
1619 +in the .notmuch/hooks directory within the database directory and must
\r
1620 +have executable permissions.
\r
1622 +The currently available hooks are described below.
\r
1625 + This hook is invoked by the **new** command before scanning or
\r
1626 + importing new messages into the database. If this hook exits
\r
1627 + with a non-zero status, notmuch will abort further processing of
\r
1628 + the **new** command.
\r
1630 + Typically this hook is used for fetching or delivering new mail
\r
1631 + to be imported into the database.
\r
1634 + This hook is invoked by the **new** command after new messages
\r
1635 + have been imported into the database and initial tags have been
\r
1636 + applied. The hook will not be run if there have been any errors
\r
1637 + during the scan or import.
\r
1639 + Typically this hook is used to perform additional query-based
\r
1640 + tagging on the imported messages.
\r
1645 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1646 +**notmuch-dump(1)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
1647 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
1648 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1649 diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst
\r
1650 new file mode 100644
\r
1651 index 0000000..99148b2
\r
1653 +++ b/doc/man7/notmuch-search-terms.rst
\r
1655 +====================
\r
1656 +notmuch-search-terms
\r
1657 +====================
\r
1662 +**notmuch** **count** [option ...] <*search-term*> ...
\r
1664 +**notmuch** **dump** **--format=(batch-tag|sup)** [--] [--output=<*file*>] [--] [<*search-term*> ...]
\r
1666 +**notmuch** **search** [option ...] <*search-term*> ...
\r
1668 +**notmuch** **show** [option ...] <*search-term*> ...
\r
1670 +**notmuch** **tag** +<*tag*> ... -<*tag*> [--] <*search-term*> ...
\r
1675 +Several notmuch commands accept a common syntax for search terms.
\r
1677 +The search terms can consist of free-form text (and quoted phrases)
\r
1678 +which will match all messages that contain all of the given
\r
1679 +terms/phrases in the body, the subject, or any of the sender or
\r
1680 +recipient headers.
\r
1682 +As a special case, a search string consisting of exactly a single
\r
1683 +asterisk ("\*") will match all messages.
\r
1685 +In addition to free text, the following prefixes can be used to force
\r
1686 +terms to match against specific portions of an email, (where <brackets>
\r
1687 +indicate user-supplied values):
\r
1689 +- from:<name-or-address>
\r
1691 +- to:<name-or-address>
\r
1693 +- subject:<word-or-quoted-phrase>
\r
1695 +- attachment:<word>
\r
1697 +- tag:<tag> (or is:<tag>)
\r
1699 +- id:<message-id>
\r
1701 +- thread:<thread-id>
\r
1703 +- folder:<directory-path>
\r
1705 +- date:<since>..<until>
\r
1707 +The **from:** prefix is used to match the name or address of the sender
\r
1708 +of an email message.
\r
1710 +The **to:** prefix is used to match the names or addresses of any
\r
1711 +recipient of an email message, (whether To, Cc, or Bcc).
\r
1713 +Any term prefixed with **subject:** will match only text from the
\r
1714 +subject of an email. Searching for a phrase in the subject is supported
\r
1715 +by including quotation marks around the phrase, immediately following
\r
1718 +The **attachment:** prefix can be used to search for specific filenames
\r
1719 +(or extensions) of attachments to email messages.
\r
1721 +For **tag:** and **is:** valid tag values include **inbox** and
\r
1722 +**unread** by default for new messages added by **notmuch new** as well
\r
1723 +as any other tag values added manually with **notmuch tag**.
\r
1725 +For **id:**, message ID values are the literal contents of the
\r
1726 +Message-ID: header of email messages, but without the '<', '>'
\r
1729 +The **thread:** prefix can be used with the thread ID values that are
\r
1730 +generated internally by notmuch (and do not appear in email messages).
\r
1731 +These thread ID values can be seen in the first column of output from
\r
1732 +**notmuch search**
\r
1734 +The **folder:** prefix can be used to search for email message files
\r
1735 +that are contained within particular directories within the mail store.
\r
1736 +If the same email message has multiple message files associated with it,
\r
1737 +it's sufficient for a match that at least one of the files is contained
\r
1738 +within a matching directory. Only the directory components below the
\r
1739 +top-level mail database path are available to be searched.
\r
1741 +The **date:** prefix can be used to restrict the results to only
\r
1742 +messages within a particular time range (based on the Date: header) with
\r
1743 +a range syntax of:
\r
1745 +date:<since>..<until>
\r
1747 +See **DATE AND TIME SEARCH** below for details on the range expression,
\r
1748 +and supported syntax for <since> and <until> date and time expressions.
\r
1750 +The time range can also be specified using timestamps with a syntax of:
\r
1752 +<initial-timestamp>..<final-timestamp>
\r
1754 +Each timestamp is a number representing the number of seconds since
\r
1755 +1970-01-01 00:00:00 UTC.
\r
1757 +In addition to individual terms, multiple terms can be combined with
\r
1758 +Boolean operators ( **and**, **or**, **not** , etc.). Each term in the
\r
1759 +query will be implicitly connected by a logical AND if no explicit
\r
1760 +operator is provided, (except that terms with a common prefix will be
\r
1761 +implicitly combined with OR until we get Xapian defect #402 fixed).
\r
1763 +Parentheses can also be used to control the combination of the Boolean
\r
1764 +operators, but will have to be protected from interpretation by the
\r
1765 +shell, (such as by putting quotation marks around any parenthesized
\r
1768 +DATE AND TIME SEARCH
\r
1769 +====================
\r
1771 +notmuch understands a variety of standard and natural ways of expressing
\r
1772 +dates and times, both in absolute terms ("2012-10-24") and in relative
\r
1773 +terms ("yesterday"). Any number of relative terms can be combined ("1
\r
1774 +hour 25 minutes") and an absolute date/time can be combined with
\r
1775 +relative terms to further adjust it. A non-exhaustive description of the
\r
1776 +syntax supported for absolute and relative terms is given below.
\r
1778 +The range expression
\r
1779 +--------------------
\r
1781 +**date:<since>..<until>**
\r
1783 +The above expression restricts the results to only messages from <since>
\r
1784 +to <until>, based on the Date: header.
\r
1786 +<since> and <until> can describe imprecise times, such as "yesterday".
\r
1787 +In this case, <since> is taken as the earliest time it could describe
\r
1788 +(the beginning of yesterday) and <until> is taken as the latest time it
\r
1789 +could describe (the end of yesterday). Similarly, date:january..february
\r
1790 +matches from the beginning of January to the end of February.
\r
1792 +Currently, we do not support spaces in range expressions. You can
\r
1793 +replace the spaces with '\_', or (in most cases) '-', or (in some cases)
\r
1794 +leave the spaces out altogether. Examples in this man page use spaces
\r
1797 +Open-ended ranges are supported (since Xapian 1.2.1), i.e. it's possible
\r
1798 +to specify date:..<until> or date:<since>.. to not limit the start or
\r
1799 +end time, respectively. Pre-1.2.1 Xapian does not report an error on
\r
1800 +open ended ranges, but it does not work as expected either.
\r
1802 +Entering date:expr without ".." (for example date:yesterday) won't work,
\r
1803 +as it's not interpreted as a range expression at all. You can achieve
\r
1804 +the expected result by duplicating the expr both sides of ".." (for
\r
1805 +example date:yesterday..yesterday).
\r
1807 +Relative date and time
\r
1808 +----------------------
\r
1811 +(years\|months\|weeks\|days\|hours\|hrs\|minutes\|mins\|seconds\|secs)
\r
1814 +All refer to past, can be repeated and will be accumulated.
\r
1816 +Units can be abbreviated to any length, with the otherwise ambiguous
\r
1817 +single m being m for minutes and M for months.
\r
1819 +Number can also be written out one, two, ..., ten, dozen, hundred.
\r
1820 +Additionally, the unit may be preceded by "last" or "this" (e.g., "last
\r
1821 +week" or "this month").
\r
1823 +When combined with absolute date and time, the relative date and time
\r
1824 +specification will be relative from the specified absolute date and
\r
1827 +Examples: 5M2d, two weeks
\r
1829 +Supported absolute time formats
\r
1830 +-------------------------------
\r
1832 +- H[H]:MM[:SS] [(am\|a.m.\|pm\|p.m.)]
\r
1834 +- H[H] (am\|a.m.\|pm\|p.m.)
\r
1844 +- Examples: 17:05, 5pm
\r
1846 +Supported absolute date formats
\r
1847 +-------------------------------
\r
1855 +- M[M]/D[D][/[YY]YY]
\r
1859 +- D[D].M[M][.[YY]YY]
\r
1861 +- D[D][(st\|nd\|rd\|th)] Mon[thname] [YYYY]
\r
1863 +- Mon[thname] D[D][(st\|nd\|rd\|th)] [YYYY]
\r
1867 +Month names can be abbreviated at three or more characters.
\r
1869 +Weekday names can be abbreviated at three or more characters.
\r
1871 +Examples: 2012-07-31, 31-07-2012, 7/31/2012, August 3
\r
1880 +Some time zone codes, e.g. UTC, EET.
\r
1885 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1886 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
1887 +**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
\r
1888 +**notmuch-search(1)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1889 diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
\r
1890 new file mode 100644
\r
1891 index 0000000..28301b3
\r
1893 +++ b/doc/notmuch-emacs.rst
\r
1899 +About this Manual
\r
1900 +=================
\r
1902 +This manual covers only the emacs interface to notmuch. For information
\r
1903 +on the command line interface, see See section “Description” in Notmuch
\r
1904 +Manual Pager. To save typing, we will sometimes use *notmuch* in this
\r
1905 +manual to refer to the Emacs interface to notmuch. If the distinction
\r
1906 +should every be important, we’ll refer to the Emacs inteface as
\r
1909 +Notmuch-emacs is highly customizable via the the Emacs customization
\r
1910 +framework (or just by setting the appropriate variables). We try to
\r
1911 +point out relevant variables in this manual, but in order to avoid
\r
1912 +duplication of information, but you can usually find the most detailed
\r
1913 +description in the varables docstring.
\r
1919 + single: notmuch-hello
\r
1922 +``notmuch-hello`` is the main entry point for notmuch. You can start it
\r
1923 +with ``M-x notmuch`` or ``M-x notmuch-hello``. The startup screen looks
\r
1924 +something like the following. There are some hints at the bottom of the
\r
1925 +screen. There are three main parts to the notmuch-hello screen,
\r
1926 +discussed below. The **bold** text indicates buttons you can click with
\r
1927 +a mouse or by positioning the cursor and pressing ``<return>``
\r
1929 +| Welcome to **notmuch** You have 52 messages.
\r
1931 +| Saved searches: **[edit]**
\r
1933 +| 52 **inbox** 52 **unread**
\r
1935 +| Search: ____________________________________
\r
1937 +| All tags: **[show]**
\r
1939 +| Type a search query and hit RET to view matching threads.
\r
1940 +| Edit saved searches with the ``edit`` button.
\r
1941 +| Hit RET or click on a saved search or tag name to view matching threads.
\r
1942 +| ``=`` to refresh this screen. ``s`` to search messages. ``q`` to quit.
\r
1943 +| **Customize** this page.
\r
1945 +You can change the overall appearence of the notmuch-hello screen by
\r
1946 +customizing the variable :index:`notmuch-hello-sections`.
\r
1950 +notmuch-hello key bindings
\r
1951 +--------------------------
\r
1954 + Move to the next widget (button or text entry field)
\r
1957 + Move to the previous widget.
\r
1960 + Activate the current widget.
\r
1963 + Refresh the buffer; mainly update the counts of messages for various
\r
1967 + Import mail, See :ref:`importing`
\r
1970 + Compose a message
\r
1973 + Search the notmuch database using :ref:`notmuch-search`
\r
1976 + Print notmuch version
\r
1981 +.. _saved-searches:
\r
1986 +Notmuch replaces the static assignment of messages with the more dynamic
\r
1987 +notion of searching. Notmuch-hello presents the user with a customizable
\r
1988 +set of saved searchs. The initial defaults are ``tag:inbox`` and
\r
1989 +``tag:unread``, but you can customize the following variables
\r
1991 +:index:`notmuch-saved-searches`
\r
1992 + A list of cons pairs, the first being the name to display, the
\r
1993 + second being a query string for notmuch. See section “Description”
\r
1994 + in Notmuch Query Syntax.
\r
1996 +:index:`notmuch-saved-searches-sort-function`
\r
1997 + This variable controls how saved searches should be sorted. A value
\r
1998 + of ``nil`` displays the saved searches in the order they are stored
\r
1999 + in ‘notmuch-saved-searches’.
\r
2001 +:index:`notmuch-column-control`
\r
2002 + Controls the number of columns for displaying saved-searches/tags
\r
2007 +The search box lets the user enter an notmuch query. See section
\r
2008 +“Description” in Notmuch Query Syntax, for more info on notmuch query
\r
2009 +syntax. A history of recent searches is also displayed by default. The
\r
2010 +latter is controlled by the variable :index:`notmuch-hello-recent-searches-max`.
\r
2015 +One special kind of saved search provided by default is for each
\r
2016 +individual tag defined in the database. This can be controlled via the
\r
2017 +following variables.
\r
2019 +:index:`notmuch-hello-tag-list-make-query`
\r
2020 + Control how to construct a search (“virtual folder”) from a given
\r
2023 +:index:`notmuch-hello-hide-tags`
\r
2024 + Which tags not to display at all.
\r
2026 +:index:`notmuch-column-control`
\r
2027 + Controls the number of columns for displaying saved-searches/tags
\r
2029 +.. _notmuch-search:
\r
2034 +``notmuch-search-mode`` is used to display the results from executing
\r
2035 +a query via ``notmuch-search``. The syntax for these queries is the
\r
2036 +the same as :ref:`saved-searches`. For details of this syntax see
\r
2037 +info:notmuch-search-terms
\r
2039 +By default the output approximates that of the command line See section
\r
2040 +“Description” in notmuch search command.
\r
2042 +The main purpose of the ``notmuch-search-mode`` buffer is to act as a
\r
2043 +menu of results that the user can explore further by pressing
\r
2044 +``<return>`` on the appropriate line.
\r
2047 + Move to next line
\r
2050 + Move to previous line
\r
2053 + Open thread on current line in :ref:`notmuch-show` mode
\r
2056 + Display full set of key bindings
\r
2058 +The presentation of results can be controlled by the following
\r
2061 +:index:`notmuch-search-result-format`
\r
2062 + Control how each thread of messages is presented in the
\r
2063 + ``notmuch-show-mode`` buffer
\r
2065 +:index:`notmuch-search-oldest-first`
\r
2066 + Display the oldest threads at the top of the buffer
\r
2068 +.. _notmuch-show:
\r
2084 +:index:`notmuch-poll`
\r
2086 +:index:`notmuch-poll-script`
\r