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 4578F431E84
\r
6 for <notmuch@notmuchmail.org>; Thu, 6 Mar 2014 05:21:44 -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 4RGc26ILo9gv for <notmuch@notmuchmail.org>;
\r
16 Thu, 6 Mar 2014 05:21:29 -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 BD6A6431FCF
\r
21 for <notmuch@notmuchmail.org>; Thu, 6 Mar 2014 05:21:14 -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 1WLYEc-0000vv-EC; Thu, 06 Mar 2014 09:21:14 -0400
\r
25 Received: (nullmailer pid 2394 invoked by uid 1000); Thu, 06 Mar 2014
\r
27 From: David Bremner <david@tethera.net>
\r
28 To: notmuch@notmuchmail.org
\r
29 Subject: [PATCH v2 1/4] doc: convert sphinx based docs
\r
30 Date: Thu, 6 Mar 2014 09:20:45 -0400
\r
31 Message-Id: <1394112048-2151-2-git-send-email-david@tethera.net>
\r
32 X-Mailer: git-send-email 1.8.5.3
\r
33 In-Reply-To: <1394112048-2151-1-git-send-email-david@tethera.net>
\r
34 References: <m2d2i0jz2h.fsf@guru.guru-group.fi>
\r
35 <1394112048-2151-1-git-send-email-david@tethera.net>
\r
37 Content-Type: text/plain; charset=UTF-8
\r
38 Content-Transfer-Encoding: 8bit
\r
39 X-BeenThere: notmuch@notmuchmail.org
\r
40 X-Mailman-Version: 2.1.13
\r
42 List-Id: "Use and development of the notmuch mail system."
\r
43 <notmuch.notmuchmail.org>
\r
44 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,
\r
45 <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>
\r
46 List-Archive: <http://notmuchmail.org/pipermail/notmuch>
\r
47 List-Post: <mailto:notmuch@notmuchmail.org>
\r
48 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>
\r
49 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,
\r
50 <mailto:notmuch-request@notmuchmail.org?subject=subscribe>
\r
51 X-List-Received-Date: Thu, 06 Mar 2014 13:21:44 -0000
\r
53 This is the output from sphinx-quickstart, massaged a bit, along with
\r
54 our existing man pages converted to rst.
\r
56 A skeleton notmuch-emacs manual is also included. It is not suitable
\r
57 for end user use yet.
\r
61 debian/control | 1 +
\r
62 doc/.gitignore | 2 +
\r
63 doc/INSTALL | 24 ++++
\r
65 doc/Makefile.local | 27 +++++
\r
66 doc/conf.py | 166 +++++++++++++++++++++++++++
\r
67 doc/index.rst | 30 +++++
\r
68 doc/man1/notmuch-compact.rst | 52 +++++++++
\r
69 doc/man1/notmuch-config.rst | 123 ++++++++++++++++++++
\r
70 doc/man1/notmuch-count.rst | 60 ++++++++++
\r
71 doc/man1/notmuch-dump.rst | 72 ++++++++++++
\r
72 doc/man1/notmuch-insert.rst | 58 ++++++++++
\r
73 doc/man1/notmuch-new.rst | 52 +++++++++
\r
74 doc/man1/notmuch-reply.rst | 112 ++++++++++++++++++
\r
75 doc/man1/notmuch-restore.rst | 59 ++++++++++
\r
76 doc/man1/notmuch-search.rst | 146 ++++++++++++++++++++++++
\r
77 doc/man1/notmuch-show.rst | 179 +++++++++++++++++++++++++++++
\r
78 doc/man1/notmuch-tag.rst | 107 +++++++++++++++++
\r
79 doc/man1/notmuch.rst | 143 +++++++++++++++++++++++
\r
80 doc/man5/notmuch-hooks.rst | 44 +++++++
\r
81 doc/man7/notmuch-search-terms.rst | 234 ++++++++++++++++++++++++++++++++++++++
\r
82 doc/notmuch-emacs.rst | 192 +++++++++++++++++++++++++++++++
\r
83 24 files changed, 1905 insertions(+), 3 deletions(-)
\r
84 create mode 100644 doc/.gitignore
\r
85 create mode 100644 doc/INSTALL
\r
86 create mode 100644 doc/Makefile
\r
87 create mode 100644 doc/Makefile.local
\r
88 create mode 100644 doc/conf.py
\r
89 create mode 100644 doc/index.rst
\r
90 create mode 100644 doc/man1/notmuch-compact.rst
\r
91 create mode 100644 doc/man1/notmuch-config.rst
\r
92 create mode 100644 doc/man1/notmuch-count.rst
\r
93 create mode 100644 doc/man1/notmuch-dump.rst
\r
94 create mode 100644 doc/man1/notmuch-insert.rst
\r
95 create mode 100644 doc/man1/notmuch-new.rst
\r
96 create mode 100644 doc/man1/notmuch-reply.rst
\r
97 create mode 100644 doc/man1/notmuch-restore.rst
\r
98 create mode 100644 doc/man1/notmuch-search.rst
\r
99 create mode 100644 doc/man1/notmuch-show.rst
\r
100 create mode 100644 doc/man1/notmuch-tag.rst
\r
101 create mode 100644 doc/man1/notmuch.rst
\r
102 create mode 100644 doc/man5/notmuch-hooks.rst
\r
103 create mode 100644 doc/man7/notmuch-search-terms.rst
\r
104 create mode 100644 doc/notmuch-emacs.rst
\r
106 diff --git a/INSTALL b/INSTALL
\r
107 index fce9352..690b0ef 100644
\r
110 @@ -60,16 +60,30 @@ Talloc which are each described below:
\r
112 Talloc is available from http://talloc.samba.org/
\r
114 +Building Documentation
\r
115 +----------------------
\r
117 +By default the documentation for notmuch is built using sphinx.
\r
119 +Sphinx is available from www.sphinx-doc.org.
\r
121 +If you prefer, you can build the man pages using rst2man, from the
\r
122 +python docutils package. See doc/INSTALL for details.
\r
125 +Installing Dependencies from Packages
\r
126 +-------------------------------------
\r
128 On a modern, package-based operating system you can install all of the
\r
129 dependencies with a simple simple command line. For example:
\r
131 For Debian and similar:
\r
133 - sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev
\r
134 + sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev python-sphinx
\r
136 For Fedora and similar:
\r
138 - sudo yum install xapian-core-devel gmime-devel libtalloc-devel
\r
139 + sudo yum install xapian-core-devel gmime-devel libtalloc-devel python-sphinx
\r
141 On other systems, a similar command can be used, but the details of
\r
142 the package names may be different.
\r
143 diff --git a/Makefile b/Makefile
\r
144 index 0428160..39f0e62 100644
\r
147 @@ -5,7 +5,7 @@ all:
\r
148 # List all subdirectories here. Each contains its own Makefile.local.
\r
149 # Use of '=', without '+=', seems to be required for out-of-tree
\r
151 -subdirs = compat completion emacs lib man parse-time-string performance-test util test
\r
152 +subdirs = compat completion doc emacs lib man parse-time-string performance-test util test
\r
154 # We make all targets depend on the Makefiles themselves.
\r
155 global_deps = Makefile Makefile.config Makefile.local \
\r
156 diff --git a/debian/control b/debian/control
\r
157 index 475b787..caf8a5d 100644
\r
158 --- a/debian/control
\r
159 +++ b/debian/control
\r
160 @@ -15,6 +15,7 @@ Build-Depends:
\r
162 python-all (>= 2.6.6-3~),
\r
163 python3-all (>= 3.1.2-7~),
\r
164 + python-sphinx (>= 1.0),
\r
165 ruby, ruby-dev (>>1:1.9.3~),
\r
166 emacs23-nox | emacs23 (>=23~) | emacs23-lucid (>=23~) |
\r
167 emacs24-nox | emacs24 (>=24~) | emacs24-lucid (>=24~),
\r
168 diff --git a/doc/.gitignore b/doc/.gitignore
\r
169 new file mode 100644
\r
170 index 0000000..a60fb31
\r
172 +++ b/doc/.gitignore
\r
176 diff --git a/doc/INSTALL b/doc/INSTALL
\r
177 new file mode 100644
\r
178 index 0000000..e37c2b9
\r
182 +This file contains some more detailed information about building and
\r
183 +installing the documentation.
\r
185 +Building with sphinx.
\r
186 +---------------------
\r
188 +- You need sphinx at least version 1.0.
\r
190 +- You can build build and install man pages with 'make install-man'
\r
192 +- You can build man, info, html, and pdf versions of the docs
\r
193 + (currently only the man pages) with
\r
195 + 'make install-{man|info|html|pdf}'
\r
197 +Building the man pages
\r
198 +----------------------
\r
200 +- You can build the man pages with rst2man (from python-docutils) with
\r
203 +- Currently there is no support to automagically install the resulting
\r
204 + nroff files, but it should work to modify the target install-man
\r
205 + in doc/Makefile.local.
\r
206 diff --git a/doc/Makefile b/doc/Makefile
\r
207 new file mode 100644
\r
208 index 0000000..fa25832
\r
213 + $(MAKE) -C .. all
\r
217 diff --git a/doc/Makefile.local b/doc/Makefile.local
\r
218 new file mode 100644
\r
219 index 0000000..ec23012
\r
221 +++ b/doc/Makefile.local
\r
223 +# -*- makefile -*-
\r
227 +# You can set these variables from the command line.
\r
228 +SPHINXOPTS := -q -c $(dir)
\r
229 +SPHINXBUILD = sphinx-build
\r
230 +DOCBUILDDIR := $(dir)/_build
\r
232 +# Internal variables.
\r
233 +ALLSPHINXOPTS := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(dir)
\r
235 +.PHONY: sphinx-html sphinx-man sphinx-texinfo sphinx-info
\r
238 + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DOCBUILDDIR)/html
\r
241 + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(DOCBUILDDIR)/man
\r
244 + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(DOCBUILDDIR)/texinfo
\r
246 +sphinx-info: sphinx-texinfo
\r
247 + make -C $(DOCBUILDDIR)/texinfo info
\r
249 +CLEAN := $(CLEAN) $(DOCBUILDDIR)
\r
250 diff --git a/doc/conf.py b/doc/conf.py
\r
251 new file mode 100644
\r
252 index 0000000..6c2806d
\r
257 +# -*- coding: utf-8 -*-
\r
262 +# The suffix of source filenames.
\r
263 +source_suffix = '.rst'
\r
265 +# The master toctree document.
\r
266 +master_doc = 'index'
\r
268 +# General information about the project.
\r
269 +project = u'notmuch'
\r
270 +copyright = u'2014, Carl Worth and many others'
\r
272 +# The short X.Y version.
\r
274 +# The full version, including alpha/beta/rc tags.
\r
277 +# List of patterns, relative to source directory, that match files and
\r
278 +# directories to ignore when looking for source files.
\r
279 +exclude_patterns = ['_build', 'notmuch-emacs.rst']
\r
281 +# The name of the Pygments (syntax highlighting) style to use.
\r
282 +pygments_style = 'sphinx'
\r
284 +# -- Options for HTML output ----------------------------------------------
\r
286 +# The theme to use for HTML and HTML Help pages. See the documentation for
\r
287 +# a list of builtin themes.
\r
288 +html_theme = 'default'
\r
291 +# Add any paths that contain custom static files (such as style sheets) here,
\r
292 +# relative to this directory. They are copied after the builtin static files,
\r
293 +# so a file named "default.css" will overwrite the builtin "default.css".
\r
294 +html_static_path = ['_static']
\r
296 +# Output file base name for HTML help builder.
\r
297 +htmlhelp_basename = 'notmuchdoc'
\r
299 +# -- Options for manual page output ---------------------------------------
\r
301 +# One entry per manual page. List of tuples
\r
302 +# (source start file, name, description, authors, manual section).
\r
306 +('man1/notmuch','notmuch',
\r
307 + u'thread-based email index, search, and tagging',
\r
308 + [u'Carl Worth and many others'], 1),
\r
310 +('man1/notmuch-compact','notmuch-compact',
\r
311 + u'compact the notmuch database',
\r
312 + [u'Carl Worth and many others'], 1),
\r
314 +('man1/notmuch-config','notmuch-config',
\r
315 + u'access notmuch configuration file',
\r
316 + [u'Carl Worth and many others'], 1),
\r
318 +('man1/notmuch-count','notmuch-count',
\r
319 + u'count messages matching the given search terms',
\r
320 + [u'Carl Worth and many others'], 1),
\r
322 +('man1/notmuch-dump','notmuch-dump',
\r
323 + u'creates a plain-text dump of the tags of each message',
\r
324 + [u'Carl Worth and many others'], 1),
\r
326 +('man5/notmuch-hooks','notmuch-hooks',
\r
327 + u'hooks for notmuch',
\r
328 + [u'Carl Worth and many others'], 5),
\r
330 +('man1/notmuch-insert','notmuch-insert',
\r
331 + u'add a message to the maildir and notmuch database',
\r
332 + [u'Carl Worth and many others'], 1),
\r
334 +('man1/notmuch-new','notmuch-new',
\r
335 + u'incorporate new mail into the notmuch database',
\r
336 + [u'Carl Worth and many others'], 1),
\r
338 +('man1/notmuch-reply','notmuch-reply',
\r
339 + u'constructs a reply template for a set of messages',
\r
340 + [u'Carl Worth and many others'], 1),
\r
342 +('man1/notmuch-restore','notmuch-restore',
\r
343 + u'restores the tags from the given file (see notmuch dump)',
\r
344 + [u'Carl Worth and many others'], 1),
\r
346 +('man1/notmuch-search','notmuch-search',
\r
347 + u'search for messages matching the given search terms',
\r
348 + [u'Carl Worth and many others'], 1),
\r
350 +('man7/notmuch-search-terms','notmuch-search-terms',
\r
351 + u'syntax for notmuch queries',
\r
352 + [u'Carl Worth and many others'], 7),
\r
354 +('man1/notmuch-show','notmuch-show',
\r
355 + u'show messages matching the given search terms',
\r
356 + [u'Carl Worth and many others'], 1),
\r
358 +('man1/notmuch-tag','notmuch-tag',
\r
359 + u'add/remove tags for all messages matching the search terms',
\r
360 + [u'Carl Worth and many others'], 1),
\r
364 +# If true, show URL addresses after external links.
\r
365 +#man_show_urls = False
\r
367 +# -- Options for Texinfo output -------------------------------------------
\r
369 +# Grouping the document tree into Texinfo files. List of tuples
\r
370 +# (source start file, target name, title, author,
\r
371 +# dir menu entry, description, category)
\r
372 +# If true, do not generate a @detailmenu in the "Top" node's menu.
\r
373 +texinfo_no_detailmenu = True
\r
375 +texinfo_documents = [
\r
376 + ('notmuch-emacs', 'notmuch-emacs', u'notmuch Documentation',
\r
377 + u'Carl Worth and many others', 'notmuch-emacs',
\r
378 + 'emacs based front-end for notmuch', 'Miscellaneous'),
\r
379 +('man1/notmuch','notmuch',u'notmuch Documentation',
\r
380 + u'Carl Worth and many others', 'notmuch',
\r
381 + 'thread-based email index, search, and tagging','Miscellaneous'),
\r
382 +('man1/notmuch-compact','notmuch-compact',u'notmuch Documentation',
\r
383 + u'Carl Worth and many others', 'notmuch-compact',
\r
384 + 'compact the notmuch database','Miscellaneous'),
\r
385 +('man1/notmuch-config','notmuch-config',u'notmuch Documentation',
\r
386 + u'Carl Worth and many others', 'notmuch-config',
\r
387 + 'access notmuch configuration file','Miscellaneous'),
\r
388 +('man1/notmuch-count','notmuch-count',u'notmuch Documentation',
\r
389 + u'Carl Worth and many others', 'notmuch-count',
\r
390 + 'count messages matching the given search terms','Miscellaneous'),
\r
391 +('man1/notmuch-dump','notmuch-dump',u'notmuch Documentation',
\r
392 + u'Carl Worth and many others', 'notmuch-dump',
\r
393 + 'creates a plain-text dump of the tags of each message','Miscellaneous'),
\r
394 +('man5/notmuch-hooks','notmuch-hooks',u'notmuch Documentation',
\r
395 + u'Carl Worth and many others', 'notmuch-hooks',
\r
396 + 'hooks for notmuch','Miscellaneous'),
\r
397 +('man1/notmuch-insert','notmuch-insert',u'notmuch Documentation',
\r
398 + u'Carl Worth and many others', 'notmuch-insert',
\r
399 + 'add a message to the maildir and notmuch database','Miscellaneous'),
\r
400 +('man1/notmuch-new','notmuch-new',u'notmuch Documentation',
\r
401 + u'Carl Worth and many others', 'notmuch-new',
\r
402 + 'incorporate new mail into the notmuch database','Miscellaneous'),
\r
403 +('man1/notmuch-reply','notmuch-reply',u'notmuch Documentation',
\r
404 + u'Carl Worth and many others', 'notmuch-reply',
\r
405 + 'constructs a reply template for a set of messages','Miscellaneous'),
\r
406 +('man1/notmuch-restore','notmuch-restore',u'notmuch Documentation',
\r
407 + u'Carl Worth and many others', 'notmuch-restore',
\r
408 + 'restores the tags from the given file (see notmuch dump)','Miscellaneous'),
\r
409 +('man1/notmuch-search','notmuch-search',u'notmuch Documentation',
\r
410 + u'Carl Worth and many others', 'notmuch-search',
\r
411 + 'search for messages matching the given search terms','Miscellaneous'),
\r
412 +('man7/notmuch-search-terms','notmuch-search-terms',u'notmuch Documentation',
\r
413 + u'Carl Worth and many others', 'notmuch-search-terms',
\r
414 + 'syntax for notmuch queries','Miscellaneous'),
\r
415 +('man1/notmuch-show','notmuch-show',u'notmuch Documentation',
\r
416 + u'Carl Worth and many others', 'notmuch-show',
\r
417 + 'show messages matching the given search terms','Miscellaneous'),
\r
418 +('man1/notmuch-tag','notmuch-tag',u'notmuch Documentation',
\r
419 + u'Carl Worth and many others', 'notmuch-tag',
\r
420 + 'add/remove tags for all messages matching the search terms','Miscellaneous'),
\r
422 diff --git a/doc/index.rst b/doc/index.rst
\r
423 new file mode 100644
\r
424 index 0000000..b33aa9f
\r
426 +++ b/doc/index.rst
\r
429 +Welcome to notmuch's documentation!
\r
430 +===================================
\r
438 + man1/notmuch-compact
\r
439 + man1/notmuch-config
\r
440 + man1/notmuch-count
\r
441 + man1/notmuch-dump
\r
442 + man5/notmuch-hooks
\r
443 + man1/notmuch-insert
\r
445 + man1/notmuch-reply
\r
446 + man1/notmuch-restore
\r
447 + man1/notmuch-search
\r
448 + man7/notmuch-search-terms
\r
449 + man1/notmuch-show
\r
452 +Indices and tables
\r
453 +==================
\r
458 diff --git a/doc/man1/notmuch-compact.rst b/doc/man1/notmuch-compact.rst
\r
459 new file mode 100644
\r
460 index 0000000..e0109dc
\r
462 +++ b/doc/man1/notmuch-compact.rst
\r
471 +**notmuch** **compact** [--quiet] [--backup=<*directory*>]
\r
476 +The **compact** command can be used to compact the notmuch database.
\r
477 +This can both reduce the space required by the database and improve
\r
478 +lookup performance.
\r
480 +The compacted database is built in a temporary directory and is later
\r
481 +moved into the place of the origin database. The original uncompacted
\r
482 +database is discarded, unless the ``--backup=``\ <directory> option is
\r
485 +Note that the database write lock will be held during the compaction
\r
486 +process (which may be quite long) to protect data integrity.
\r
488 +Supported options for **compact** include
\r
490 + ``--backup=``\ <directory>
\r
491 + Save the current database to the given directory before
\r
492 + replacing it with the compacted database. The backup directory
\r
493 + must not exist and it must reside on the same mounted filesystem
\r
494 + as the current database.
\r
497 + Do not report database compaction progress to stdout.
\r
502 +The following environment variables can be used to control the behavior
\r
505 +**NOTMUCH\_CONFIG**
\r
506 + Specifies the location of the notmuch configuration file. Notmuch
\r
507 + will use ${HOME}/.notmuch-config if this variable is not set.
\r
512 +**notmuch(1)**, **notmuch-count(1)**, **notmuch-dump(1)**,
\r
513 +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
514 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
515 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
516 diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst
\r
517 new file mode 100644
\r
518 index 0000000..3c9a568
\r
520 +++ b/doc/man1/notmuch-config.rst
\r
529 +**notmuch** **config** **get** <*section*>.<*item*>
\r
531 +**notmuch** **config** **set** <*section*>.<*item*> [*value* ...]
\r
533 +**notmuch** **config** **list**
\r
538 +The **config** command can be used to get or set settings in the notmuch
\r
539 +configuration file.
\r
542 + The value of the specified configuration item is printed to
\r
543 + stdout. If the item has multiple values (it is a list), each
\r
544 + value is separated by a newline character.
\r
547 + The specified configuration item is set to the given value. To
\r
548 + specify a multiple-value item (a list), provide each value as a
\r
549 + separate command-line argument.
\r
551 + If no values are provided, the specified configuration item will
\r
552 + be removed from the configuration file.
\r
555 + Every configuration item is printed to stdout, each on a
\r
556 + separate line of the form:
\r
558 + *section*.\ *item*\ =\ *value*
\r
560 + No additional whitespace surrounds the dot or equals sign
\r
561 + characters. In a multiple-value item (a list), the values are
\r
562 + separated by semicolon characters.
\r
564 +The available configuration items are described below.
\r
566 + **database.path**
\r
567 + The top-level directory where your mail currently exists and to
\r
568 + where mail will be delivered in the future. Files should be
\r
569 + individual email messages. Notmuch will store its database
\r
570 + within a sub-directory of the path configured here named
\r
576 + **user.primary\_email**
\r
577 + Your primary email address.
\r
579 + **user.other\_email**
\r
580 + A list of other email addresses at which you receive email.
\r
583 + A list of tags that will be added to all messages incorporated
\r
584 + by **notmuch new**.
\r
587 + A list of file and directory names, without path, that will not
\r
588 + be searched for messages by **notmuch new**. All the files and
\r
589 + directories matching any of the names specified here will be
\r
590 + ignored, regardless of the location in the mail store directory
\r
593 + **search.exclude\_tags**
\r
594 + A list of tags that will be excluded from search results by
\r
595 + default. Using an excluded tag in a query will override that
\r
598 + **maildir.synchronize\_flags**
\r
599 + If true, then the following maildir flags (in message filenames)
\r
600 + will be synchronized with the corresponding notmuch tags:
\r
602 + +--------+-----------------------------------------------+
\r
604 + +========+===============================================+
\r
606 + +--------+-----------------------------------------------+
\r
608 + +--------+-----------------------------------------------+
\r
610 + +--------+-----------------------------------------------+
\r
612 + +--------+-----------------------------------------------+
\r
613 + | S | unread (added when 'S' flag is not present) |
\r
614 + +--------+-----------------------------------------------+
\r
616 + The **notmuch new** command will notice flag changes in
\r
617 + filenames and update tags, while the **notmuch tag** and
\r
618 + **notmuch restore** commands will notice tag changes and update
\r
619 + flags in filenames.
\r
621 + If there have been any changes in the maildir (new messages
\r
622 + added, old ones removed or renamed, maildir flags changed,
\r
623 + etc.), it is advisable to run **notmuch new** before **notmuch
\r
624 + tag** or **notmuch restore** commands to ensure the tag changes
\r
625 + are properly synchronized to the maildir flags, as the commands
\r
626 + expect the database and maildir to be in sync.
\r
631 +The following environment variables can be used to control the behavior
\r
634 +**NOTMUCH\_CONFIG**
\r
635 + Specifies the location of the notmuch configuration file. Notmuch
\r
636 + will use ${HOME}/.notmuch-config if this variable is not set.
\r
641 +**notmuch(1)**, **notmuch-count(1)**, **notmuch-dump(1)**,
\r
642 +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
643 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
644 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
645 diff --git a/doc/man1/notmuch-count.rst b/doc/man1/notmuch-count.rst
\r
646 new file mode 100644
\r
647 index 0000000..ca78c18
\r
649 +++ b/doc/man1/notmuch-count.rst
\r
658 +**notmuch** **count** [*option* ...] <*search-term*> ...
\r
663 +Count messages matching the search terms.
\r
665 +The number of matching messages (or threads) is output to stdout.
\r
667 +With no search terms, a count of all messages (or threads) in the
\r
668 +database will be displayed.
\r
670 +See **notmuch-search-terms(7)** for details of the supported syntax for
\r
673 +Supported options for **count** include
\r
675 + ``--output=(messages|threads|files)``
\r
678 + Output the number of matching messages. This is the default.
\r
681 + Output the number of matching threads.
\r
684 + Output the number of files associated with matching
\r
685 + messages. This may be bigger than the number of matching
\r
686 + messages due to duplicates (i.e. multiple files having the
\r
687 + same message-id).
\r
689 + ``--exclude=(true|false)``
\r
690 + Specify whether to omit messages matching search.tag\_exclude
\r
691 + from the count (the default) or not.
\r
694 + Read queries from a file (stdin by default), one per line, and
\r
695 + output the number of matching messages (or threads) to stdout,
\r
696 + one per line. On an empty input line the count of all messages
\r
697 + (or threads) in the database will be output. This option is not
\r
698 + compatible with specifying search terms on the command line.
\r
700 + ``--input=``\ <filename>
\r
701 + Read input from given file, instead of from stdin. Implies
\r
707 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-dump(1)**,
\r
708 +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
709 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
710 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
711 diff --git a/doc/man1/notmuch-dump.rst b/doc/man1/notmuch-dump.rst
\r
712 new file mode 100644
\r
713 index 0000000..17d1da5
\r
715 +++ b/doc/man1/notmuch-dump.rst
\r
724 +**notmuch** **dump** [--format=(batch-tag|sup)] [--] [--output=<*file*>] [--] [<*search-term*> ...]
\r
729 +Dump tags for messages matching the given search terms.
\r
731 +Output is to the given filename, if any, or to stdout.
\r
733 +These tags are the only data in the notmuch database that can't be
\r
734 +recreated from the messages themselves. The output of notmuch dump is
\r
735 +therefore the only critical thing to backup (and much more friendly to
\r
736 +incremental backup than the native database files.)
\r
738 +``--format=(sup|batch-tag)``
\r
739 + Notmuch restore supports two plain text dump formats, both with one
\r
740 + message-id per line, followed by a list of tags.
\r
743 + The default **batch-tag** dump format is intended to more robust
\r
744 + against malformed message-ids and tags containing whitespace or
\r
745 + non-\ **ascii(7)** characters. Each line has the form
\r
747 + +<*encoded-tag*\ > +<*encoded-tag*\ > ... --
\r
748 + id:<*quoted-message-id*\ >
\r
750 + Tags are hex-encoded by replacing every byte not matching the
\r
751 + regex **[A-Za-z0-9@=.,\_+-]** with **%nn** where nn is the two
\r
752 + digit hex encoding. The message ID is a valid Xapian query,
\r
753 + quoted using Xapian boolean term quoting rules: if the ID
\r
754 + contains whitespace or a close paren or starts with a double
\r
755 + quote, it must be enclosed in double quotes and double quotes
\r
756 + inside the ID must be doubled. The astute reader will notice
\r
757 + this is a special case of the batch input format for
\r
758 + **notmuch-tag(1)**; note that the single message-id query is
\r
759 + mandatory for **notmuch-restore(1)**.
\r
762 + The **sup** dump file format is specifically chosen to be
\r
763 + compatible with the format of files produced by sup-dump. So if
\r
764 + you've previously been using sup for mail, then the **notmuch
\r
765 + restore** command provides you a way to import all of your tags
\r
766 + (or labels as sup calls them). Each line has the following form
\r
768 + <*message-id*\ > **(** <*tag*\ > ... **)**
\r
770 + with zero or more tags are separated by spaces. Note that
\r
771 + (malformed) message-ids may contain arbitrary non-null
\r
772 + characters. Note also that tags with spaces will not be
\r
773 + correctly restored with this format.
\r
775 + With no search terms, a dump of all messages in the database will be
\r
776 + generated. A "--" argument instructs notmuch that the remaining
\r
777 + arguments are search terms.
\r
779 + See **notmuch-search-terms(7)** for details of the supported syntax
\r
780 + for <search-terms>.
\r
785 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
786 +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
787 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
788 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
789 diff --git a/doc/man1/notmuch-insert.rst b/doc/man1/notmuch-insert.rst
\r
790 new file mode 100644
\r
791 index 0000000..2be1a7b
\r
793 +++ b/doc/man1/notmuch-insert.rst
\r
802 +**notmuch** **insert** [option ...] [+<*tag*>|-<*tag*> ...]
\r
807 +**notmuch insert** reads a message from standard input and delivers it
\r
808 +into the maildir directory given by configuration option
\r
809 +**database.path**, then incorporates the message into the notmuch
\r
810 +database. It is an alternative to using a separate tool to deliver the
\r
811 +message then running **notmuch new** afterwards.
\r
813 +The new message will be tagged with the tags specified by the
\r
814 +**new.tags** configuration option, then by operations specified on the
\r
815 +command-line: tags prefixed by '+' are added while those prefixed by '-'
\r
818 +If the new message is a duplicate of an existing message in the database
\r
819 +(it has same Message-ID), it will be added to the maildir folder and
\r
820 +notmuch database, but the tags will not be changed.
\r
822 +Option arguments must appear before any tag operation arguments.
\r
823 +Supported options for **insert** include
\r
825 + ``--folder=<``\ folder\ **>**
\r
826 + Deliver the message to the specified folder, relative to the
\r
827 + top-level directory given by the value of **database.path**. The
\r
828 + default is to deliver to the top-level directory.
\r
830 + ``--create-folder``
\r
831 + Try to create the folder named by the ``--folder`` option, if it
\r
832 + does not exist. Otherwise the folder must already exist for mail
\r
833 + delivery to succeed.
\r
838 +This command returns exit status 0 if the message was successfully added
\r
839 +to the mail directory, even if the message could not be indexed and
\r
840 +added to the notmuch database. In the latter case, a warning will be
\r
841 +printed to standard error but the message file will be left on disk.
\r
843 +If the message could not be written to disk then a non-zero exit status
\r
849 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
850 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-reply(1)**,
\r
851 +**notmuch-restore(1)**, **notmuch-search(1)**,
\r
852 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
853 diff --git a/doc/man1/notmuch-new.rst b/doc/man1/notmuch-new.rst
\r
854 new file mode 100644
\r
855 index 0000000..d11fcee
\r
857 +++ b/doc/man1/notmuch-new.rst
\r
866 +**notmuch** **new** [--no-hooks]
\r
871 +Find and import any new messages to the database.
\r
873 +The **new** command scans all sub-directories of the database,
\r
874 +performing full-text indexing on new messages that are found. Each new
\r
875 +message will automatically be tagged with both the **inbox** and
\r
878 +You should run **notmuch new** once after first running **notmuch
\r
879 +setup** to create the initial database. The first run may take a long
\r
880 +time if you have a significant amount of mail (several hundred thousand
\r
881 +messages or more). Subsequently, you should run **notmuch new** whenever
\r
882 +new mail is delivered and you wish to incorporate it into the database.
\r
883 +These subsequent runs will be much quicker than the initial run.
\r
885 +Invoking ``notmuch`` with no command argument will run **new** if
\r
886 +**notmuch setup** has previously been completed, but **notmuch new** has
\r
887 +not previously been run.
\r
889 +**notmuch new** updates tags according to maildir flag changes if the
\r
890 +**maildir.synchronize\_flags** configuration option is enabled. See
\r
891 +**notmuch-config(1)** for details.
\r
893 +The **new** command supports hooks. See **notmuch-hooks(5)** for more
\r
896 +Supported options for **new** include
\r
899 + Prevents hooks from being run.
\r
902 + Do not print progress or results.
\r
907 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
908 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
909 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
910 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
911 diff --git a/doc/man1/notmuch-reply.rst b/doc/man1/notmuch-reply.rst
\r
912 new file mode 100644
\r
913 index 0000000..cfbd4ea
\r
915 +++ b/doc/man1/notmuch-reply.rst
\r
924 +**notmuch** **reply** [option ...] <*search-term*> ...
\r
929 +Constructs a reply template for a set of messages.
\r
931 +To make replying to email easier, **notmuch reply** takes an existing
\r
932 +set of messages and constructs a suitable mail template. The Reply-to:
\r
933 +header (if any, otherwise From:) is used for the To: address. Unless
\r
934 +``--reply-to=sender`` is specified, values from the To: and Cc: headers
\r
935 +are copied, but not including any of the current user's email addresses
\r
936 +(as configured in primary\_mail or other\_email in the .notmuch-config
\r
937 +file) in the recipient list.
\r
939 +It also builds a suitable new subject, including Re: at the front (if
\r
940 +not already present), and adding the message IDs of the messages being
\r
941 +replied to to the References list and setting the In-Reply-To: field
\r
944 +Finally, the original contents of the emails are quoted by prefixing
\r
945 +each line with '> ' and included in the body.
\r
947 +The resulting message template is output to stdout.
\r
949 +Supported options for **reply** include
\r
951 + ``--format=``\ (**default**\ \|\ **json**\ \|\ **sexp**\ \|\ **headers-only**)
\r
954 + Includes subject and quoted message body as an RFC 2822
\r
958 + Produces JSON output containing headers for a reply message
\r
959 + and the contents of the original message. This output can be
\r
960 + used by a client to create a reply message intelligently.
\r
963 + Produces S-Expression output containing headers for a reply
\r
964 + message and the contents of the original message. This
\r
965 + output can be used by a client to create a reply message
\r
969 + Only produces In-Reply-To, References, To, Cc, and Bcc
\r
972 + ``--format-version=N``
\r
973 + Use the specified structured output format version. This is
\r
974 + intended for programs that invoke **notmuch(1)** internally. If
\r
975 + omitted, the latest supported version will be used.
\r
977 + ``--reply-to=``\ (**all**\ \|\ **sender**)
\r
979 + **all** (default)
\r
980 + Replies to all addresses.
\r
983 + Replies only to the sender. If replying to user's own
\r
984 + message (Reply-to: or From: header is one of the user's
\r
985 + configured email addresses), try To:, Cc:, and Bcc: headers
\r
986 + in this order, and copy values from the first that contains
\r
987 + something other than only the user's addresses.
\r
990 + Decrypt any MIME encrypted parts found in the selected content
\r
991 + (ie. "multipart/encrypted" parts). Status of the decryption will
\r
992 + be reported (currently only supported with --format=json and
\r
993 + --format=sexp) and on successful decryption the
\r
994 + multipart/encrypted part will be replaced by the decrypted
\r
997 + Decryption expects a functioning **gpg-agent(1)** to provide any
\r
998 + needed credentials. Without one, the decryption will fail.
\r
1000 +See **notmuch-search-terms(7)** for details of the supported syntax for
\r
1003 +Note: It is most common to use **notmuch reply** with a search string
\r
1004 +matching a single message, (such as id:<message-id>), but it can be
\r
1005 +useful to reply to several messages at once. For example, when a series
\r
1006 +of patches are sent in a single thread, replying to the entire thread
\r
1007 +allows for the reply to comment on issues found in multiple patches. The
\r
1008 +default format supports replying to multiple messages at once, but the
\r
1009 +JSON and S-Expression formats do not.
\r
1014 +This command supports the following special exit status codes
\r
1017 + The requested format version is too old.
\r
1020 + The requested format version is too new.
\r
1025 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1026 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
1027 +**notmuch-new(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
1028 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1029 diff --git a/doc/man1/notmuch-restore.rst b/doc/man1/notmuch-restore.rst
\r
1030 new file mode 100644
\r
1031 index 0000000..d6cf19a
\r
1033 +++ b/doc/man1/notmuch-restore.rst
\r
1042 +**notmuch** **restore** [--accumulate] [--format=(auto|batch-tag|sup)] [--input=<*filename*>]
\r
1047 +Restores the tags from the given file (see **notmuch dump**).
\r
1049 +The input is read from the given filename, if any, or from stdin.
\r
1051 +Supported options for **restore** include
\r
1053 + ``--accumulate``
\r
1054 + The union of the existing and new tags is applied, instead of
\r
1055 + replacing each message's tags as they are read in from the dump
\r
1058 + ``--format=(sup|batch-tag|auto)``
\r
1059 + Notmuch restore supports two plain text dump formats, with each
\r
1060 + line specifying a message-id and a set of tags. For details of
\r
1061 + the actual formats, see **notmuch-dump(1)**.
\r
1064 + The **sup** dump file format is specifically chosen to be
\r
1065 + compatible with the format of files produced by sup-dump. So
\r
1066 + if you've previously been using sup for mail, then the
\r
1067 + **notmuch restore** command provides you a way to import all
\r
1068 + of your tags (or labels as sup calls them).
\r
1071 + The **batch-tag** dump format is intended to more robust
\r
1072 + against malformed message-ids and tags containing whitespace
\r
1073 + or non-\ **ascii(7)** characters. See **notmuch-dump(1)**
\r
1074 + for details on this format.
\r
1076 + **notmuch restore** updates the maildir flags according to
\r
1077 + tag changes if the **maildir.synchronize\_flags**
\r
1078 + configuration option is enabled. See **notmuch-config(1)**
\r
1082 + This option (the default) tries to guess the format from the
\r
1083 + input. For correctly formed input in either supported
\r
1084 + format, this heuristic, based the fact that batch-tag format
\r
1085 + contains no parentheses, should be accurate.
\r
1090 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1091 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
1092 +**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-search(1)**,
\r
1093 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1094 diff --git a/doc/man1/notmuch-search.rst b/doc/man1/notmuch-search.rst
\r
1095 new file mode 100644
\r
1096 index 0000000..7ac6c68
\r
1098 +++ b/doc/man1/notmuch-search.rst
\r
1107 +**notmuch** **search** [*option* ...] <*search-term*> ...
\r
1112 +Search for messages matching the given search terms, and display as
\r
1113 +results the threads containing the matched messages.
\r
1115 +The output consists of one line per thread, giving a thread ID, the date
\r
1116 +of the newest (or oldest, depending on the sort option) matched message
\r
1117 +in the thread, the number of matched messages and total messages in the
\r
1118 +thread, the names of all participants in the thread, and the subject of
\r
1119 +the newest (or oldest) message.
\r
1121 +See **notmuch-search-terms(7)** for details of the supported syntax for
\r
1124 +Supported options for **search** include
\r
1126 + ``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**)
\r
1127 + Presents the results in either JSON, S-Expressions, newline
\r
1128 + character separated plain-text (default), or null character
\r
1129 + separated plain-text (compatible with **xargs(1)** -0 option
\r
1130 + where available).
\r
1132 + ``--format-version=N``
\r
1133 + Use the specified structured output format version. This is
\r
1134 + intended for programs that invoke **notmuch(1)** internally. If
\r
1135 + omitted, the latest supported version will be used.
\r
1137 + ``--output=(summary|threads|messages|files|tags)``
\r
1140 + Output a summary of each thread with any message matching
\r
1141 + the search terms. The summary includes the thread ID, date,
\r
1142 + the number of messages in the thread (both the number
\r
1143 + matched and the total number), the authors of the thread and
\r
1147 + Output the thread IDs of all threads with any message
\r
1148 + matching the search terms, either one per line
\r
1149 + (--format=text), separated by null characters
\r
1150 + (--format=text0), as a JSON array (--format=json), or an
\r
1151 + S-Expression list (--format=sexp).
\r
1154 + Output the message IDs of all messages matching the search
\r
1155 + terms, either one per line (--format=text), separated by
\r
1156 + null characters (--format=text0), as a JSON array
\r
1157 + (--format=json), or as an S-Expression list (--format=sexp).
\r
1160 + Output the filenames of all messages matching the search
\r
1161 + terms, either one per line (--format=text), separated by
\r
1162 + null characters (--format=text0), as a JSON array
\r
1163 + (--format=json), or as an S-Expression list (--format=sexp).
\r
1165 + Note that each message may have multiple filenames
\r
1166 + associated with it. All of them are included in the output,
\r
1167 + unless limited with the --duplicate=N option.
\r
1170 + Output all tags that appear on any message matching the
\r
1171 + search terms, either one per line (--format=text), separated
\r
1172 + by null characters (--format=text0), as a JSON array
\r
1173 + (--format=json), or as an S-Expression list (--format=sexp).
\r
1175 + ``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
\r
1176 + This option can be used to present results in either
\r
1177 + chronological order (**oldest-first**) or reverse chronological
\r
1178 + order (**newest-first**).
\r
1180 + Note: The thread order will be distinct between these two
\r
1181 + options (beyond being simply reversed). When sorting by
\r
1182 + **oldest-first** the threads will be sorted by the oldest
\r
1183 + message in each thread, but when sorting by **newest-first** the
\r
1184 + threads will be sorted by the newest message in each thread.
\r
1186 + By default, results will be displayed in reverse chronological
\r
1187 + order, (that is, the newest results will be displayed first).
\r
1189 + ``--offset=[-]N``
\r
1190 + Skip displaying the first N results. With the leading '-', start
\r
1191 + at the Nth result from the end.
\r
1194 + Limit the number of displayed results to N.
\r
1196 + ``--exclude=(true|false|all|flag)``
\r
1197 + A message is called "excluded" if it matches at least one tag in
\r
1198 + search.tag\_exclude that does not appear explicitly in the
\r
1199 + search terms. This option specifies whether to omit excluded
\r
1200 + messages in the search process.
\r
1202 + The default value, **true**, prevents excluded messages from
\r
1203 + matching the search terms.
\r
1205 + **all** additionally prevents excluded messages from appearing
\r
1206 + in displayed results, in effect behaving as though the excluded
\r
1207 + messages do not exist.
\r
1209 + **false** allows excluded messages to match search terms and
\r
1210 + appear in displayed results. Excluded messages are still marked
\r
1211 + in the relevant outputs.
\r
1213 + **flag** only has an effect when ``--output=summary``. The
\r
1214 + output is almost identical to **false**, but the "match count"
\r
1215 + is the number of matching non-excluded messages in the thread,
\r
1216 + rather than the number of matching messages.
\r
1218 + ``--duplicate=N``
\r
1219 + Effective with ``--output=files``, output the Nth filename
\r
1220 + associated with each message matching the query (N is 1-based).
\r
1221 + If N is greater than the number of files associated with the
\r
1222 + message, don't print anything.
\r
1224 + Note that this option is orthogonal with the **folder:** search
\r
1225 + prefix. The prefix matches messages based on filenames. This
\r
1226 + option filters filenames of the matching messages.
\r
1231 +This command supports the following special exit status codes
\r
1234 + The requested format version is too old.
\r
1237 + The requested format version is too new.
\r
1242 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1243 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
1244 +**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
\r
1245 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1246 diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst
\r
1247 new file mode 100644
\r
1248 index 0000000..bad868b
\r
1250 +++ b/doc/man1/notmuch-show.rst
\r
1259 +**notmuch** **show** [*option* ...] <*search-term*> ...
\r
1264 +Shows all messages matching the search terms.
\r
1266 +See **notmuch-search-terms(7)** for details of the supported syntax for
\r
1269 +The messages will be grouped and sorted based on the threading (all
\r
1270 +replies to a particular message will appear immediately after that
\r
1271 +message in date order). The output is not indented by default, but depth
\r
1272 +tags are printed so that proper indentation can be performed by a
\r
1273 +post-processor (such as the emacs interface to notmuch).
\r
1275 +Supported options for **show** include
\r
1277 + ``--entire-thread=(true|false)``
\r
1278 + If true, **notmuch show** outputs all messages in the thread of
\r
1279 + any message matching the search terms; if false, it outputs only
\r
1280 + the matching messages. For ``--format=json`` and
\r
1281 + ``--format=sexp`` this defaults to true. For other formats, this
\r
1282 + defaults to false.
\r
1284 + ``--format=(text|json|sexp|mbox|raw)``
\r
1286 + **text** (default for messages)
\r
1287 + The default plain-text format has all text-content MIME
\r
1288 + parts decoded. Various components in the output,
\r
1289 + (**message**, **header**, **body**, **attachment**, and MIME
\r
1290 + **part**), will be delimited by easily-parsed markers. Each
\r
1291 + marker consists of a Control-L character (ASCII decimal 12),
\r
1292 + the name of the marker, and then either an opening or
\r
1293 + closing brace, ('{' or '}'), to either open or close the
\r
1294 + component. For a multipart MIME message, these parts will be
\r
1298 + The output is formatted with Javascript Object Notation
\r
1299 + (JSON). This format is more robust than the text format for
\r
1300 + automated processing. The nested structure of multipart MIME
\r
1301 + messages is reflected in nested JSON output. By default JSON
\r
1302 + output includes all messages in a matching thread; that is,
\r
1305 + ``--format=json`` sets ``--entire-thread`` The caller can
\r
1306 + disable this behaviour by setting ``--entire-thread=false``
\r
1309 + The output is formatted as an S-Expression (sexp). This
\r
1310 + format is more robust than the text format for automated
\r
1311 + processing. The nested structure of multipart MIME messages
\r
1312 + is reflected in nested S-Expression output. By default,
\r
1313 + S-Expression output includes all messages in a matching
\r
1314 + thread; that is, by default,
\r
1316 + ``--format=sexp`` sets ``--entire-thread`` The caller can
\r
1317 + disable this behaviour by setting ``--entire-thread=false``
\r
1320 + All matching messages are output in the traditional, Unix
\r
1321 + mbox format with each message being prefixed by a line
\r
1322 + beginning with "From " and a blank line separating each
\r
1323 + message. Lines in the message content beginning with "From "
\r
1324 + (preceded by zero or more '>' characters) have an additional
\r
1325 + '>' character added. This reversible escaping is termed
\r
1326 + "mboxrd" format and described in detail here:
\r
1328 + http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
\r
1330 + **raw** (default for a single part, see --part)
\r
1331 + For a message or an attached message part, the original, raw
\r
1332 + content of the email message is output. Consumers of this
\r
1333 + format should expect to implement MIME decoding and similar
\r
1336 + For a single part (--part) the raw part content is output
\r
1337 + after performing any necessary MIME decoding. Note that
\r
1338 + messages with a simple body still have two parts: part 0 is
\r
1339 + the whole message and part 1 is the body.
\r
1341 + For a multipart part, the part headers and body (including
\r
1342 + all child parts) is output.
\r
1344 + The raw format must only be used with search terms matching
\r
1347 + ``--format-version=N``
\r
1348 + Use the specified structured output format version. This is
\r
1349 + intended for programs that invoke **notmuch(1)** internally. If
\r
1350 + omitted, the latest supported version will be used.
\r
1353 + Output the single decoded MIME part N of a single message. The
\r
1354 + search terms must match only a single message. Message parts are
\r
1355 + numbered in a depth-first walk of the message MIME structure,
\r
1356 + and are identified in the 'json', 'sexp' or 'text' output
\r
1360 + Compute and report the validity of any MIME cryptographic
\r
1361 + signatures found in the selected content (ie. "multipart/signed"
\r
1362 + parts). Status of the signature will be reported (currently only
\r
1363 + supported with --format=json and --format=sexp), and the
\r
1364 + multipart/signed part will be replaced by the signed data.
\r
1367 + Decrypt any MIME encrypted parts found in the selected content
\r
1368 + (ie. "multipart/encrypted" parts). Status of the decryption will
\r
1369 + be reported (currently only supported with --format=json and
\r
1370 + --format=sexp) and on successful decryption the
\r
1371 + multipart/encrypted part will be replaced by the decrypted
\r
1374 + Decryption expects a functioning **gpg-agent(1)** to provide any
\r
1375 + needed credentials. Without one, the decryption will fail.
\r
1377 + Implies --verify.
\r
1379 + ``--exclude=(true|false)``
\r
1380 + Specify whether to omit threads only matching
\r
1381 + search.tag\_exclude from the search results (the default) or
\r
1382 + not. In either case the excluded message will be marked with the
\r
1383 + exclude flag (except when output=mbox when there is nowhere to
\r
1386 + If --entire-thread is specified then complete threads are
\r
1387 + returned regardless (with the excluded flag being set when
\r
1388 + appropriate) but threads that only match in an excluded message
\r
1389 + are not returned when ``--exclude=true.``
\r
1391 + The default is ``--exclude=true.``
\r
1393 + ``--body=(true|false)``
\r
1394 + If true (the default) **notmuch show** includes the bodies of
\r
1395 + the messages in the output; if false, bodies are omitted.
\r
1396 + ``--body=false`` is only implemented for the json and sexp
\r
1397 + formats and it is incompatible with ``--part > 0.``
\r
1399 + This is useful if the caller only needs the headers as body-less
\r
1400 + output is much faster and substantially smaller.
\r
1402 + ``--include-html``
\r
1403 + Include "text/html" parts as part of the output (currently only
\r
1404 + supported with --format=json and --format=sexp). By default,
\r
1405 + unless ``--part=N`` is used to select a specific part or
\r
1406 + ``--include-html`` is used to include all "text/html" parts, no
\r
1407 + part with content type "text/html" is included in the output.
\r
1409 +A common use of **notmuch show** is to display a single thread of email
\r
1410 +messages. For this, use a search term of "thread:<thread-id>" as can be
\r
1411 +seen in the first column of output from the **notmuch search** command.
\r
1416 +This command supports the following special exit status codes
\r
1419 + The requested format version is too old.
\r
1422 + The requested format version is too new.
\r
1427 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1428 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
1429 +**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
\r
1430 +**notmuch-search(1)**, **notmuch-search-terms(7)**, **notmuch-tag(1)**
\r
1431 diff --git a/doc/man1/notmuch-tag.rst b/doc/man1/notmuch-tag.rst
\r
1432 new file mode 100644
\r
1433 index 0000000..2e7e1d3
\r
1435 +++ b/doc/man1/notmuch-tag.rst
\r
1444 +**notmuch** **tag** [options ...] +<*tag*>|-<*tag*> [--] <*search-term*> ...
\r
1446 +**notmuch** **tag** **--batch** [--input=<*filename*>]
\r
1451 +Add/remove tags for all messages matching the search terms.
\r
1453 +See **notmuch-search-terms(7)** for details of the supported syntax for
\r
1454 +<*search-term*\ >.
\r
1456 +Tags prefixed by '+' are added while those prefixed by '-' are removed.
\r
1457 +For each message, tag changes are applied in the order they appear on
\r
1458 +the command line.
\r
1460 +The beginning of the search terms is recognized by the first argument
\r
1461 +that begins with neither '+' nor '-'. Support for an initial search term
\r
1462 +beginning with '+' or '-' is provided by allowing the user to specify a
\r
1463 +"--" argument to separate the tags from the search terms.
\r
1465 +**notmuch tag** updates the maildir flags according to tag changes if
\r
1466 +the **maildir.synchronize\_flags** configuration option is enabled. See
\r
1467 +**notmuch-config(1)** for details.
\r
1469 +Supported options for **tag** include
\r
1471 + ``--remove-all``
\r
1472 + Remove all tags from each message matching the search terms
\r
1473 + before applying the tag changes appearing on the command line.
\r
1474 + This means setting the tags of each message to the tags to be
\r
1475 + added. If there are no tags to be added, the messages will have
\r
1479 + Read batch tagging operations from a file (stdin by default).
\r
1480 + This is more efficient than repeated **notmuch tag**
\r
1481 + invocations. See `TAG FILE FORMAT <#tag_file_format>`__ below
\r
1482 + for the input format. This option is not compatible with
\r
1483 + specifying tagging on the command line.
\r
1485 + ``--input=``\ <filename>
\r
1486 + Read input from given file, instead of from stdin. Implies
\r
1492 +The input must consist of lines of the format:
\r
1494 ++<*tag*\ >\|-<*tag*\ > [...] [--] <*query*\ >
\r
1496 +Each line is interpreted similarly to **notmuch tag** command line
\r
1497 +arguments. The delimiter is one or more spaces ' '. Any characters in
\r
1498 +<*tag*\ > **may** be hex-encoded with %NN where NN is the hexadecimal
\r
1499 +value of the character. To hex-encode a character with a multi-byte
\r
1500 +UTF-8 encoding, hex-encode each byte. Any spaces in <tag> **must** be
\r
1501 +hex-encoded as %20. Any characters that are not part of <*tag*\ > **must
\r
1502 +not** be hex-encoded.
\r
1504 +In the future tag:"tag with spaces" style quoting may be supported for
\r
1505 +<*tag*\ > as well; for this reason all double quote characters in
\r
1506 +<*tag*\ > **should** be hex-encoded.
\r
1508 +The <*query*\ > should be quoted using Xapian boolean term quoting
\r
1509 +rules: if a term contains whitespace or a close paren or starts with a
\r
1510 +double quote, it must be enclosed in double quotes (not including any
\r
1511 +prefix) and double quotes inside the term must be doubled (see below for
\r
1514 +Leading and trailing space ' ' is ignored. Empty lines and lines
\r
1515 +beginning with '#' are ignored.
\r
1520 +The following shows a valid input to batch tagging. Note that only the
\r
1521 +isolated '\*' acts as a wildcard. Also note the two different quotings
\r
1522 +of the tag **space in tags**
\r
1527 + +foo::bar%25 -- (One and Two) or (One and tag:winner)
\r
1528 + +found::it -- tag:foo::bar%
\r
1529 + # ignore this line and the next
\r
1531 + +space%20in%20tags -- Two
\r
1532 + # add tag '(tags)', among other stunts.
\r
1533 + +crazy{ +(tags) +&are +#possible\ -- tag:"space in tags"
\r
1534 + +match*crazy -- tag:crazy{
\r
1535 + +some_tag -- id:"this is ""nauty)"""
\r
1540 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1541 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
1542 +**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
\r
1543 +**notmuch-search(1)**, **notmuch-search-terms(7)**, **notmuch-show(1)**,
\r
1544 diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst
\r
1545 new file mode 100644
\r
1546 index 0000000..9710294
\r
1548 +++ b/doc/man1/notmuch.rst
\r
1557 +**notmuch** [option ...] **command** [arg ...]
\r
1562 +Notmuch is a command-line based program for indexing, searching,
\r
1563 +reading, and tagging large collections of email messages.
\r
1565 +This page describes how to get started using notmuch from the command
\r
1566 +line, and gives a brief overview of the commands available. For more
\r
1567 +information on e.g. **notmuch show** consult the **notmuch-show(1)** man
\r
1568 +page, also accessible via **notmuch help show**
\r
1570 +The quickest way to get started with Notmuch is to simply invoke the
\r
1571 +``notmuch`` command with no arguments, which will interactively guide
\r
1572 +you through the process of indexing your mail.
\r
1577 +While the command-line program ``notmuch`` provides powerful
\r
1578 +functionality, it does not provide the most convenient interface for
\r
1579 +that functionality. More sophisticated interfaces are expected to be
\r
1580 +built on top of either the command-line interface, or more likely, on
\r
1581 +top of the notmuch library interface. See http://notmuchmail.org for
\r
1582 +more about alternate interfaces to notmuch. The emacs-based interface to
\r
1583 +notmuch (available under **emacs/** in the Notmuch source distribution)
\r
1584 +is probably the most widely used at this time.
\r
1589 +Supported global options for ``notmuch`` include
\r
1592 + Print a synopsis of available commands and exit.
\r
1595 + Print the installed version of notmuch, and exit.
\r
1597 + ``--config=FILE``
\r
1598 + Specify the configuration file to use. This overrides any
\r
1599 + configuration file specified by ${NOTMUCH\_CONFIG}.
\r
1607 +The **notmuch setup** command is used to configure Notmuch for first
\r
1608 +use, (or to reconfigure it later).
\r
1610 +The setup command will prompt for your full name, your primary email
\r
1611 +address, any alternate email addresses you use, and the directory
\r
1612 +containing your email archives. Your answers will be written to a
\r
1613 +configuration file in ${NOTMUCH\_CONFIG} (if set) or
\r
1614 +${HOME}/.notmuch-config . This configuration file will be created with
\r
1615 +descriptive comments, making it easy to edit by hand later to change the
\r
1616 +configuration. Or you can run **notmuch setup** again to change the
\r
1619 +The mail directory you specify can contain any number of sub-directories
\r
1620 +and should primarily contain only files with individual email messages
\r
1621 +(eg. maildir or mh archives are perfect). If there are other, non-email
\r
1622 +files (such as indexes maintained by other email programs) then notmuch
\r
1623 +will do its best to detect those and ignore them.
\r
1625 +Mail storage that uses mbox format, (where one mbox file contains many
\r
1626 +messages), will not work with notmuch. If that's how your mail is
\r
1627 +currently stored, it is recommended you first convert it to maildir
\r
1628 +format with a utility such as mb2md before running **notmuch setup .**
\r
1630 +Invoking ``notmuch`` with no command argument will run **setup** if the
\r
1631 +setup command has not previously been completed.
\r
1636 +Several of the notmuch commands accept search terms with a common
\r
1637 +syntax. See **notmuch-search-terms**\ (7) for more details on the
\r
1638 +supported syntax.
\r
1640 +The **search**, **show** and **count** commands are used to query the
\r
1643 +The **reply** command is useful for preparing a template for an email
\r
1646 +The **tag** command is the only command available for manipulating
\r
1647 +database contents.
\r
1649 +The **dump** and **restore** commands can be used to create a textual
\r
1650 +dump of email tags for backup purposes, and to restore from that dump.
\r
1652 +The **config** command can be used to get or set settings in the notmuch
\r
1653 +configuration file.
\r
1658 +The following environment variables can be used to control the behavior
\r
1661 +**NOTMUCH\_CONFIG**
\r
1662 + Specifies the location of the notmuch configuration file. Notmuch
\r
1663 + will use ${HOME}/.notmuch-config if this variable is not set.
\r
1665 +**NOTMUCH\_TALLOC\_REPORT**
\r
1666 + Location to write a talloc memory usage report. See
\r
1667 + **talloc\_enable\_leak\_report\_full** in **talloc(3)** for more
\r
1670 +**NOTMUCH\_DEBUG\_QUERY**
\r
1671 + If set to a non-empty value, the notmuch library will print (to
\r
1672 + stderr) Xapian queries it constructs.
\r
1677 +**notmuch-config(1)**, **notmuch-count(1)**, **notmuch-dump(1)**,
\r
1678 +**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
1679 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
1680 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1682 +The notmuch website: **http://notmuchmail.org**
\r
1687 +Feel free to send questions, comments, or kudos to the notmuch mailing
\r
1688 +list <notmuch@notmuchmail.org> . Subscription is not required before
\r
1689 +posting, but is available from the notmuchmail.org website.
\r
1691 +Real-time interaction with the Notmuch community is available via IRC
\r
1692 +(server: irc.freenode.net, channel: #notmuch).
\r
1693 diff --git a/doc/man5/notmuch-hooks.rst b/doc/man5/notmuch-hooks.rst
\r
1694 new file mode 100644
\r
1695 index 0000000..493abf2
\r
1697 +++ b/doc/man5/notmuch-hooks.rst
\r
1706 + $DATABASEDIR/.notmuch/hooks/*
\r
1711 +Hooks are scripts (or arbitrary executables or symlinks to such) that
\r
1712 +notmuch invokes before and after certain actions. These scripts reside
\r
1713 +in the .notmuch/hooks directory within the database directory and must
\r
1714 +have executable permissions.
\r
1716 +The currently available hooks are described below.
\r
1719 + This hook is invoked by the **new** command before scanning or
\r
1720 + importing new messages into the database. If this hook exits
\r
1721 + with a non-zero status, notmuch will abort further processing of
\r
1722 + the **new** command.
\r
1724 + Typically this hook is used for fetching or delivering new mail
\r
1725 + to be imported into the database.
\r
1728 + This hook is invoked by the **new** command after new messages
\r
1729 + have been imported into the database and initial tags have been
\r
1730 + applied. The hook will not be run if there have been any errors
\r
1731 + during the scan or import.
\r
1733 + Typically this hook is used to perform additional query-based
\r
1734 + tagging on the imported messages.
\r
1739 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1740 +**notmuch-dump(1)**, **notmuch-insert(1)**, **notmuch-new(1)**,
\r
1741 +**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
\r
1742 +**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1743 diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst
\r
1744 new file mode 100644
\r
1745 index 0000000..99148b2
\r
1747 +++ b/doc/man7/notmuch-search-terms.rst
\r
1749 +====================
\r
1750 +notmuch-search-terms
\r
1751 +====================
\r
1756 +**notmuch** **count** [option ...] <*search-term*> ...
\r
1758 +**notmuch** **dump** **--format=(batch-tag|sup)** [--] [--output=<*file*>] [--] [<*search-term*> ...]
\r
1760 +**notmuch** **search** [option ...] <*search-term*> ...
\r
1762 +**notmuch** **show** [option ...] <*search-term*> ...
\r
1764 +**notmuch** **tag** +<*tag*> ... -<*tag*> [--] <*search-term*> ...
\r
1769 +Several notmuch commands accept a common syntax for search terms.
\r
1771 +The search terms can consist of free-form text (and quoted phrases)
\r
1772 +which will match all messages that contain all of the given
\r
1773 +terms/phrases in the body, the subject, or any of the sender or
\r
1774 +recipient headers.
\r
1776 +As a special case, a search string consisting of exactly a single
\r
1777 +asterisk ("\*") will match all messages.
\r
1779 +In addition to free text, the following prefixes can be used to force
\r
1780 +terms to match against specific portions of an email, (where <brackets>
\r
1781 +indicate user-supplied values):
\r
1783 +- from:<name-or-address>
\r
1785 +- to:<name-or-address>
\r
1787 +- subject:<word-or-quoted-phrase>
\r
1789 +- attachment:<word>
\r
1791 +- tag:<tag> (or is:<tag>)
\r
1793 +- id:<message-id>
\r
1795 +- thread:<thread-id>
\r
1797 +- folder:<directory-path>
\r
1799 +- date:<since>..<until>
\r
1801 +The **from:** prefix is used to match the name or address of the sender
\r
1802 +of an email message.
\r
1804 +The **to:** prefix is used to match the names or addresses of any
\r
1805 +recipient of an email message, (whether To, Cc, or Bcc).
\r
1807 +Any term prefixed with **subject:** will match only text from the
\r
1808 +subject of an email. Searching for a phrase in the subject is supported
\r
1809 +by including quotation marks around the phrase, immediately following
\r
1812 +The **attachment:** prefix can be used to search for specific filenames
\r
1813 +(or extensions) of attachments to email messages.
\r
1815 +For **tag:** and **is:** valid tag values include **inbox** and
\r
1816 +**unread** by default for new messages added by **notmuch new** as well
\r
1817 +as any other tag values added manually with **notmuch tag**.
\r
1819 +For **id:**, message ID values are the literal contents of the
\r
1820 +Message-ID: header of email messages, but without the '<', '>'
\r
1823 +The **thread:** prefix can be used with the thread ID values that are
\r
1824 +generated internally by notmuch (and do not appear in email messages).
\r
1825 +These thread ID values can be seen in the first column of output from
\r
1826 +**notmuch search**
\r
1828 +The **folder:** prefix can be used to search for email message files
\r
1829 +that are contained within particular directories within the mail store.
\r
1830 +If the same email message has multiple message files associated with it,
\r
1831 +it's sufficient for a match that at least one of the files is contained
\r
1832 +within a matching directory. Only the directory components below the
\r
1833 +top-level mail database path are available to be searched.
\r
1835 +The **date:** prefix can be used to restrict the results to only
\r
1836 +messages within a particular time range (based on the Date: header) with
\r
1837 +a range syntax of:
\r
1839 +date:<since>..<until>
\r
1841 +See **DATE AND TIME SEARCH** below for details on the range expression,
\r
1842 +and supported syntax for <since> and <until> date and time expressions.
\r
1844 +The time range can also be specified using timestamps with a syntax of:
\r
1846 +<initial-timestamp>..<final-timestamp>
\r
1848 +Each timestamp is a number representing the number of seconds since
\r
1849 +1970-01-01 00:00:00 UTC.
\r
1851 +In addition to individual terms, multiple terms can be combined with
\r
1852 +Boolean operators ( **and**, **or**, **not** , etc.). Each term in the
\r
1853 +query will be implicitly connected by a logical AND if no explicit
\r
1854 +operator is provided, (except that terms with a common prefix will be
\r
1855 +implicitly combined with OR until we get Xapian defect #402 fixed).
\r
1857 +Parentheses can also be used to control the combination of the Boolean
\r
1858 +operators, but will have to be protected from interpretation by the
\r
1859 +shell, (such as by putting quotation marks around any parenthesized
\r
1862 +DATE AND TIME SEARCH
\r
1863 +====================
\r
1865 +notmuch understands a variety of standard and natural ways of expressing
\r
1866 +dates and times, both in absolute terms ("2012-10-24") and in relative
\r
1867 +terms ("yesterday"). Any number of relative terms can be combined ("1
\r
1868 +hour 25 minutes") and an absolute date/time can be combined with
\r
1869 +relative terms to further adjust it. A non-exhaustive description of the
\r
1870 +syntax supported for absolute and relative terms is given below.
\r
1872 +The range expression
\r
1873 +--------------------
\r
1875 +**date:<since>..<until>**
\r
1877 +The above expression restricts the results to only messages from <since>
\r
1878 +to <until>, based on the Date: header.
\r
1880 +<since> and <until> can describe imprecise times, such as "yesterday".
\r
1881 +In this case, <since> is taken as the earliest time it could describe
\r
1882 +(the beginning of yesterday) and <until> is taken as the latest time it
\r
1883 +could describe (the end of yesterday). Similarly, date:january..february
\r
1884 +matches from the beginning of January to the end of February.
\r
1886 +Currently, we do not support spaces in range expressions. You can
\r
1887 +replace the spaces with '\_', or (in most cases) '-', or (in some cases)
\r
1888 +leave the spaces out altogether. Examples in this man page use spaces
\r
1891 +Open-ended ranges are supported (since Xapian 1.2.1), i.e. it's possible
\r
1892 +to specify date:..<until> or date:<since>.. to not limit the start or
\r
1893 +end time, respectively. Pre-1.2.1 Xapian does not report an error on
\r
1894 +open ended ranges, but it does not work as expected either.
\r
1896 +Entering date:expr without ".." (for example date:yesterday) won't work,
\r
1897 +as it's not interpreted as a range expression at all. You can achieve
\r
1898 +the expected result by duplicating the expr both sides of ".." (for
\r
1899 +example date:yesterday..yesterday).
\r
1901 +Relative date and time
\r
1902 +----------------------
\r
1905 +(years\|months\|weeks\|days\|hours\|hrs\|minutes\|mins\|seconds\|secs)
\r
1908 +All refer to past, can be repeated and will be accumulated.
\r
1910 +Units can be abbreviated to any length, with the otherwise ambiguous
\r
1911 +single m being m for minutes and M for months.
\r
1913 +Number can also be written out one, two, ..., ten, dozen, hundred.
\r
1914 +Additionally, the unit may be preceded by "last" or "this" (e.g., "last
\r
1915 +week" or "this month").
\r
1917 +When combined with absolute date and time, the relative date and time
\r
1918 +specification will be relative from the specified absolute date and
\r
1921 +Examples: 5M2d, two weeks
\r
1923 +Supported absolute time formats
\r
1924 +-------------------------------
\r
1926 +- H[H]:MM[:SS] [(am\|a.m.\|pm\|p.m.)]
\r
1928 +- H[H] (am\|a.m.\|pm\|p.m.)
\r
1938 +- Examples: 17:05, 5pm
\r
1940 +Supported absolute date formats
\r
1941 +-------------------------------
\r
1949 +- M[M]/D[D][/[YY]YY]
\r
1953 +- D[D].M[M][.[YY]YY]
\r
1955 +- D[D][(st\|nd\|rd\|th)] Mon[thname] [YYYY]
\r
1957 +- Mon[thname] D[D][(st\|nd\|rd\|th)] [YYYY]
\r
1961 +Month names can be abbreviated at three or more characters.
\r
1963 +Weekday names can be abbreviated at three or more characters.
\r
1965 +Examples: 2012-07-31, 31-07-2012, 7/31/2012, August 3
\r
1974 +Some time zone codes, e.g. UTC, EET.
\r
1979 +**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
\r
1980 +**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
\r
1981 +**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
\r
1982 +**notmuch-search(1)**, **notmuch-show(1)**, **notmuch-tag(1)**
\r
1983 diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
\r
1984 new file mode 100644
\r
1985 index 0000000..28301b3
\r
1987 +++ b/doc/notmuch-emacs.rst
\r
1993 +About this Manual
\r
1994 +=================
\r
1996 +This manual covers only the emacs interface to notmuch. For information
\r
1997 +on the command line interface, see See section “Description” in Notmuch
\r
1998 +Manual Pager. To save typing, we will sometimes use *notmuch* in this
\r
1999 +manual to refer to the Emacs interface to notmuch. If the distinction
\r
2000 +should every be important, we’ll refer to the Emacs inteface as
\r
2003 +Notmuch-emacs is highly customizable via the the Emacs customization
\r
2004 +framework (or just by setting the appropriate variables). We try to
\r
2005 +point out relevant variables in this manual, but in order to avoid
\r
2006 +duplication of information, but you can usually find the most detailed
\r
2007 +description in the varables docstring.
\r
2013 + single: notmuch-hello
\r
2016 +``notmuch-hello`` is the main entry point for notmuch. You can start it
\r
2017 +with ``M-x notmuch`` or ``M-x notmuch-hello``. The startup screen looks
\r
2018 +something like the following. There are some hints at the bottom of the
\r
2019 +screen. There are three main parts to the notmuch-hello screen,
\r
2020 +discussed below. The **bold** text indicates buttons you can click with
\r
2021 +a mouse or by positioning the cursor and pressing ``<return>``
\r
2023 +| Welcome to **notmuch** You have 52 messages.
\r
2025 +| Saved searches: **[edit]**
\r
2027 +| 52 **inbox** 52 **unread**
\r
2029 +| Search: ____________________________________
\r
2031 +| All tags: **[show]**
\r
2033 +| Type a search query and hit RET to view matching threads.
\r
2034 +| Edit saved searches with the ``edit`` button.
\r
2035 +| Hit RET or click on a saved search or tag name to view matching threads.
\r
2036 +| ``=`` to refresh this screen. ``s`` to search messages. ``q`` to quit.
\r
2037 +| **Customize** this page.
\r
2039 +You can change the overall appearence of the notmuch-hello screen by
\r
2040 +customizing the variable :index:`notmuch-hello-sections`.
\r
2044 +notmuch-hello key bindings
\r
2045 +--------------------------
\r
2048 + Move to the next widget (button or text entry field)
\r
2051 + Move to the previous widget.
\r
2054 + Activate the current widget.
\r
2057 + Refresh the buffer; mainly update the counts of messages for various
\r
2061 + Import mail, See :ref:`importing`
\r
2064 + Compose a message
\r
2067 + Search the notmuch database using :ref:`notmuch-search`
\r
2070 + Print notmuch version
\r
2075 +.. _saved-searches:
\r
2080 +Notmuch replaces the static assignment of messages with the more dynamic
\r
2081 +notion of searching. Notmuch-hello presents the user with a customizable
\r
2082 +set of saved searchs. The initial defaults are ``tag:inbox`` and
\r
2083 +``tag:unread``, but you can customize the following variables
\r
2085 +:index:`notmuch-saved-searches`
\r
2086 + A list of cons pairs, the first being the name to display, the
\r
2087 + second being a query string for notmuch. See section “Description”
\r
2088 + in Notmuch Query Syntax.
\r
2090 +:index:`notmuch-saved-searches-sort-function`
\r
2091 + This variable controls how saved searches should be sorted. A value
\r
2092 + of ``nil`` displays the saved searches in the order they are stored
\r
2093 + in ‘notmuch-saved-searches’.
\r
2095 +:index:`notmuch-column-control`
\r
2096 + Controls the number of columns for displaying saved-searches/tags
\r
2101 +The search box lets the user enter an notmuch query. See section
\r
2102 +“Description” in Notmuch Query Syntax, for more info on notmuch query
\r
2103 +syntax. A history of recent searches is also displayed by default. The
\r
2104 +latter is controlled by the variable :index:`notmuch-hello-recent-searches-max`.
\r
2109 +One special kind of saved search provided by default is for each
\r
2110 +individual tag defined in the database. This can be controlled via the
\r
2111 +following variables.
\r
2113 +:index:`notmuch-hello-tag-list-make-query`
\r
2114 + Control how to construct a search (“virtual folder”) from a given
\r
2117 +:index:`notmuch-hello-hide-tags`
\r
2118 + Which tags not to display at all.
\r
2120 +:index:`notmuch-column-control`
\r
2121 + Controls the number of columns for displaying saved-searches/tags
\r
2123 +.. _notmuch-search:
\r
2128 +``notmuch-search-mode`` is used to display the results from executing
\r
2129 +a query via ``notmuch-search``. The syntax for these queries is the
\r
2130 +the same as :ref:`saved-searches`. For details of this syntax see
\r
2131 +info:notmuch-search-terms
\r
2133 +By default the output approximates that of the command line See section
\r
2134 +“Description” in notmuch search command.
\r
2136 +The main purpose of the ``notmuch-search-mode`` buffer is to act as a
\r
2137 +menu of results that the user can explore further by pressing
\r
2138 +``<return>`` on the appropriate line.
\r
2141 + Move to next line
\r
2144 + Move to previous line
\r
2147 + Open thread on current line in :ref:`notmuch-show` mode
\r
2150 + Display full set of key bindings
\r
2152 +The presentation of results can be controlled by the following
\r
2155 +:index:`notmuch-search-result-format`
\r
2156 + Control how each thread of messages is presented in the
\r
2157 + ``notmuch-show-mode`` buffer
\r
2159 +:index:`notmuch-search-oldest-first`
\r
2160 + Display the oldest threads at the top of the buffer
\r
2162 +.. _notmuch-show:
\r
2178 +:index:`notmuch-poll`
\r
2180 +:index:`notmuch-poll-script`
\r
projects / notmuch-archives.git / blob