debian/notmuch
1
0
Fork 0
mirror of https://git.notmuchmail.org/git/notmuch synced 2024-12-22 01:14:53 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: convert sphinx based docs

Browse source 
This is the output from sphinx-quickstart, massaged a bit, along with
our existing man pages converted to rst.

A skeleton notmuch-emacs manual is also included. It is not suitable
for end user use yet.
This commit is contained in:
David Bremner 2014-01-28 12:12:37 -04:00
parent 029790d3ff
commit d736260385
24 changed files with 1905 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
INSTALL
View file

@ -60,16 +60,30 @@ Talloc which are each described below:
Talloc is available from http://talloc.samba.org/
Building Documentation
----------------------
By default the documentation for notmuch is built using sphinx.
Sphinx is available from www.sphinx-doc.org.
If you prefer, you can build the man pages using rst2man, from the
python docutils package. See doc/INSTALL for details.
Installing Dependencies from Packages
-------------------------------------
On a modern, package-based operating system you can install all of the
dependencies with a simple simple command line. For example:
For Debian and similar:
sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev
sudo apt-get install libxapian-dev libgmime-2.6-dev libtalloc-dev python-sphinx
For Fedora and similar:
sudo yum install xapian-core-devel gmime-devel libtalloc-devel
sudo yum install xapian-core-devel gmime-devel libtalloc-devel python-sphinx
On other systems, a similar command can be used, but the details of
the package names may be different.

2
Makefile
View file

@ -5,7 +5,7 @@ all:
# List all subdirectories here. Each contains its own Makefile.local.
# Use of '=', without '+=', seems to be required for out-of-tree
# builds to work.
subdirs = compat completion emacs lib man parse-time-string performance-test util test
subdirs = compat completion doc emacs lib man parse-time-string performance-test util test
# We make all targets depend on the Makefiles themselves.
global_deps = Makefile Makefile.config Makefile.local \

1
debian/control vendored
View file

@ -15,6 +15,7 @@ Build-Depends:
libz-dev,
python-all (>= 2.6.6-3~),
python3-all (>= 3.1.2-7~),
python-sphinx (>= 1.0),
ruby, ruby-dev (>>1:1.9.3~),
emacs23-nox | emacs23 (>=23~) | emacs23-lucid (>=23~) |
emacs24-nox | emacs24 (>=24~) | emacs24-lucid (>=24~),

2
doc/.gitignore vendored Normal file
View file

@ -0,0 +1,2 @@
docdeps.mk
_build

24
doc/INSTALL Normal file
View file

@ -0,0 +1,24 @@
This file contains some more detailed information about building and
installing the documentation.
Building with sphinx.
---------------------
- You need sphinx at least version 1.0.
- You can build build and install man pages with 'make install-man'
- You can build man, info, html, and pdf versions of the docs
(currently only the man pages) with
'make install-{man|info|html|pdf}'
Building the man pages
----------------------
- You can build the man pages with rst2man (from python-docutils) with
'make rst2man'.
- Currently there is no support to automagically install the resulting
nroff files, but it should work to modify the target install-man
in doc/Makefile.local.

5
doc/Makefile Normal file
View file

@ -0,0 +1,5 @@
all:
$(MAKE) -C .. all
.DEFAULT:
$(MAKE) -C .. $@

27
doc/Makefile.local Normal file
View file

@ -0,0 +1,27 @@
# -*- makefile -*-
dir := doc
# You can set these variables from the command line.
SPHINXOPTS := -q -c $(dir)
SPHINXBUILD = sphinx-build
DOCBUILDDIR := $(dir)/_build
# Internal variables.
ALLSPHINXOPTS := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(dir)
.PHONY: sphinx-html sphinx-man sphinx-texinfo sphinx-info
sphinx-html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DOCBUILDDIR)/html
sphinx-man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(DOCBUILDDIR)/man
sphinx-texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(DOCBUILDDIR)/texinfo
sphinx-info: sphinx-texinfo
make -C $(DOCBUILDDIR)/texinfo info
CLEAN := $(CLEAN) $(DOCBUILDDIR)

166
doc/conf.py Normal file
View file

@ -0,0 +1,166 @@
# -*- coding: utf-8 -*-
import sys
import os
# The suffix of source filenames.
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'notmuch'
copyright = u'2014, Carl Worth and many others'
# The short X.Y version.
version = '0.17'
# The full version, including alpha/beta/rc tags.
release = '0.17'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build', 'notmuch-emacs.rst']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Output file base name for HTML help builder.
htmlhelp_basename = 'notmuchdoc'
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('man1/notmuch','notmuch',
u'thread-based email index, search, and tagging',
[u'Carl Worth and many others'], 1),
('man1/notmuch-compact','notmuch-compact',
u'compact the notmuch database',
[u'Carl Worth and many others'], 1),
('man1/notmuch-config','notmuch-config',
u'access notmuch configuration file',
[u'Carl Worth and many others'], 1),
('man1/notmuch-count','notmuch-count',
u'count messages matching the given search terms',
[u'Carl Worth and many others'], 1),
('man1/notmuch-dump','notmuch-dump',
u'creates a plain-text dump of the tags of each message',
[u'Carl Worth and many others'], 1),
('man5/notmuch-hooks','notmuch-hooks',
u'hooks for notmuch',
[u'Carl Worth and many others'], 5),
('man1/notmuch-insert','notmuch-insert',
u'add a message to the maildir and notmuch database',
[u'Carl Worth and many others'], 1),
('man1/notmuch-new','notmuch-new',
u'incorporate new mail into the notmuch database',
[u'Carl Worth and many others'], 1),
('man1/notmuch-reply','notmuch-reply',
u'constructs a reply template for a set of messages',
[u'Carl Worth and many others'], 1),
('man1/notmuch-restore','notmuch-restore',
u'restores the tags from the given file (see notmuch dump)',
[u'Carl Worth and many others'], 1),
('man1/notmuch-search','notmuch-search',
u'search for messages matching the given search terms',
[u'Carl Worth and many others'], 1),
('man7/notmuch-search-terms','notmuch-search-terms',
u'syntax for notmuch queries',
[u'Carl Worth and many others'], 7),
('man1/notmuch-show','notmuch-show',
u'show messages matching the given search terms',
[u'Carl Worth and many others'], 1),
('man1/notmuch-tag','notmuch-tag',
u'add/remove tags for all messages matching the search terms',
[u'Carl Worth and many others'], 1),
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
# If true, do not generate a @detailmenu in the "Top" node's menu.
texinfo_no_detailmenu = True
texinfo_documents = [
('notmuch-emacs', 'notmuch-emacs', u'notmuch Documentation',
u'Carl Worth and many others', 'notmuch-emacs',
'emacs based front-end for notmuch', 'Miscellaneous'),
('man1/notmuch','notmuch',u'notmuch Documentation',
u'Carl Worth and many others', 'notmuch',
'thread-based email index, search, and tagging','Miscellaneous'),
('man1/notmuch-compact','notmuch-compact',u'notmuch Documentation',
u'Carl Worth and many others', 'notmuch-compact',
'compact the notmuch database','Miscellaneous'),
('man1/notmuch-config','notmuch-config',u'notmuch Documentation',
u'Carl Worth and many others', 'notmuch-config',
'access notmuch configuration file','Miscellaneous'),
('man1/notmuch-count','notmuch-count',u'notmuch Documentation',
u'Carl Worth and many others', 'notmuch-count',
'count messages matching the given search terms','Miscellaneous'),
('man1/notmuch-dump','notmuch-dump',u'notmuch Documentation',
u'Carl Worth and many others', 'notmuch-dump',
'creates a plain-text dump of the tags of each message','Miscellaneous'),
('man5/notmuch-hooks','notmuch-hooks',u'notmuch Documentation',
u'Carl Worth and many others', 'notmuch-hooks',
'hooks for notmuch','Miscellaneous'),
('man1/notmuch-insert','notmuch-insert',u'notmuch Documentation',
u'Carl Worth and many others', 'notmuch-insert',
'add a message to the maildir and notmuch database','Miscellaneous'),
('man1/notmuch-new','notmuch-new',u'notmuch Documentation',
u'Carl Worth and many others', 'notmuch-new',
'incorporate new mail into the notmuch database','Miscellaneous'),
('man1/notmuch-reply','notmuch-reply',u'notmuch Documentation',
u'Carl Worth and many others', 'notmuch-reply',
'constructs a reply template for a set of messages','Miscellaneous'),
('man1/notmuch-restore','notmuch-restore',u'notmuch Documentation',
u'Carl Worth and many others', 'notmuch-restore',
'restores the tags from the given file (see notmuch dump)','Miscellaneous'),
('man1/notmuch-search','notmuch-search',u'notmuch Documentation',
u'Carl Worth and many others', 'notmuch-search',
'search for messages matching the given search terms','Miscellaneous'),
('man7/notmuch-search-terms','notmuch-search-terms',u'notmuch Documentation',
u'Carl Worth and many others', 'notmuch-search-terms',
'syntax for notmuch queries','Miscellaneous'),
('man1/notmuch-show','notmuch-show',u'notmuch Documentation',
u'Carl Worth and many others', 'notmuch-show',
'show messages matching the given search terms','Miscellaneous'),
('man1/notmuch-tag','notmuch-tag',u'notmuch Documentation',
u'Carl Worth and many others', 'notmuch-tag',
'add/remove tags for all messages matching the search terms','Miscellaneous'),
]

30
doc/index.rst Normal file
View file

@ -0,0 +1,30 @@
Welcome to notmuch's documentation!
===================================
Contents:
.. toctree::
:titlesonly:
man1/notmuch
man1/notmuch-compact
man1/notmuch-config
man1/notmuch-count
man1/notmuch-dump
man5/notmuch-hooks
man1/notmuch-insert
man1/notmuch-new
man1/notmuch-reply
man1/notmuch-restore
man1/notmuch-search
man7/notmuch-search-terms
man1/notmuch-show
man1/notmuch-tag
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

52
doc/man1/notmuch-compact.rst Normal file
View file

@ -0,0 +1,52 @@
===============
notmuch-compact
===============
SYNOPSIS
========
**notmuch** **compact** [--quiet] [--backup=<*directory*>]
DESCRIPTION
===========
The **compact** command can be used to compact the notmuch database.
This can both reduce the space required by the database and improve
lookup performance.
The compacted database is built in a temporary directory and is later
moved into the place of the origin database. The original uncompacted
database is discarded, unless the ``--backup=``\ <directory> option is
used.
Note that the database write lock will be held during the compaction
process (which may be quite long) to protect data integrity.
Supported options for **compact** include
``--backup=``\ <directory>
Save the current database to the given directory before
replacing it with the compacted database. The backup directory
must not exist and it must reside on the same mounted filesystem
as the current database.
``--quiet``
Do not report database compaction progress to stdout.
ENVIRONMENT
===========
The following environment variables can be used to control the behavior
of notmuch.
**NOTMUCH\_CONFIG**
Specifies the location of the notmuch configuration file. Notmuch
will use ${HOME}/.notmuch-config if this variable is not set.
SEE ALSO
========
**notmuch(1)**, **notmuch-count(1)**, **notmuch-dump(1)**,
**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**

123
doc/man1/notmuch-config.rst Normal file
View file

@ -0,0 +1,123 @@
==============
notmuch-config
==============
SYNOPSIS
========
**notmuch** **config** **get** <*section*>.<*item*>
**notmuch** **config** **set** <*section*>.<*item*> [*value* ...]
**notmuch** **config** **list**
DESCRIPTION
===========
The **config** command can be used to get or set settings in the notmuch
configuration file.
**get**
The value of the specified configuration item is printed to
stdout. If the item has multiple values (it is a list), each
value is separated by a newline character.
**set**
The specified configuration item is set to the given value. To
specify a multiple-value item (a list), provide each value as a
separate command-line argument.
If no values are provided, the specified configuration item will
be removed from the configuration file.
**list**
Every configuration item is printed to stdout, each on a
separate line of the form:
*section*.\ *item*\ =\ *value*
No additional whitespace surrounds the dot or equals sign
characters. In a multiple-value item (a list), the values are
separated by semicolon characters.
The available configuration items are described below.
**database.path**
The top-level directory where your mail currently exists and to
where mail will be delivered in the future. Files should be
individual email messages. Notmuch will store its database
within a sub-directory of the path configured here named
``.notmuch``.
**user.name**
Your full name.
**user.primary\_email**
Your primary email address.
**user.other\_email**
A list of other email addresses at which you receive email.
**new.tags**
A list of tags that will be added to all messages incorporated
by **notmuch new**.
**new.ignore**
A list of file and directory names, without path, that will not
be searched for messages by **notmuch new**. All the files and
directories matching any of the names specified here will be
ignored, regardless of the location in the mail store directory
hierarchy.
**search.exclude\_tags**
A list of tags that will be excluded from search results by
default. Using an excluded tag in a query will override that
exclusion.
**maildir.synchronize\_flags**
If true, then the following maildir flags (in message filenames)
will be synchronized with the corresponding notmuch tags:
+--------+-----------------------------------------------+
| Flag | Tag |
+========+===============================================+
| D | draft |
+--------+-----------------------------------------------+
| F | flagged |
+--------+-----------------------------------------------+
| P | passed |
+--------+-----------------------------------------------+
| R | replied |
+--------+-----------------------------------------------+
| S | unread (added when 'S' flag is not present) |
+--------+-----------------------------------------------+
The **notmuch new** command will notice flag changes in
filenames and update tags, while the **notmuch tag** and
**notmuch restore** commands will notice tag changes and update
flags in filenames.
If there have been any changes in the maildir (new messages
added, old ones removed or renamed, maildir flags changed,
etc.), it is advisable to run **notmuch new** before **notmuch
tag** or **notmuch restore** commands to ensure the tag changes
are properly synchronized to the maildir flags, as the commands
expect the database and maildir to be in sync.
ENVIRONMENT
===========
The following environment variables can be used to control the behavior
of notmuch.
**NOTMUCH\_CONFIG**
Specifies the location of the notmuch configuration file. Notmuch
will use ${HOME}/.notmuch-config if this variable is not set.
SEE ALSO
========
**notmuch(1)**, **notmuch-count(1)**, **notmuch-dump(1)**,
**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**

60
doc/man1/notmuch-count.rst Normal file
View file

@ -0,0 +1,60 @@
=============
notmuch-count
=============
SYNOPSIS
========
**notmuch** **count** [*option* ...] <*search-term*> ...
DESCRIPTION
===========
Count messages matching the search terms.
The number of matching messages (or threads) is output to stdout.
With no search terms, a count of all messages (or threads) in the
database will be displayed.
See **notmuch-search-terms(7)** for details of the supported syntax for
<search-terms>.
Supported options for **count** include
``--output=(messages|threads|files)``
**messages**
Output the number of matching messages. This is the default.
**threads**
Output the number of matching threads.
**files**
Output the number of files associated with matching
messages. This may be bigger than the number of matching
messages due to duplicates (i.e. multiple files having the
same message-id).
``--exclude=(true|false)``
Specify whether to omit messages matching search.tag\_exclude
from the count (the default) or not.
``--batch``
Read queries from a file (stdin by default), one per line, and
output the number of matching messages (or threads) to stdout,
one per line. On an empty input line the count of all messages
(or threads) in the database will be output. This option is not
compatible with specifying search terms on the command line.
``--input=``\ <filename>
Read input from given file, instead of from stdin. Implies
``--batch``.
SEE ALSO
========
**notmuch(1)**, **notmuch-config(1)**, **notmuch-dump(1)**,
**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**

72
doc/man1/notmuch-dump.rst Normal file
View file

@ -0,0 +1,72 @@
============
notmuch-dump
============
SYNOPSIS
========
**notmuch** **dump** [--format=(batch-tag|sup)] [--] [--output=<*file*>] [--] [<*search-term*> ...]
DESCRIPTION
===========
Dump tags for messages matching the given search terms.
Output is to the given filename, if any, or to stdout.
These tags are the only data in the notmuch database that can't be
recreated from the messages themselves. The output of notmuch dump is
therefore the only critical thing to backup (and much more friendly to
incremental backup than the native database files.)
``--format=(sup|batch-tag)``
Notmuch restore supports two plain text dump formats, both with one
message-id per line, followed by a list of tags.
**batch-tag**
The default **batch-tag** dump format is intended to more robust
against malformed message-ids and tags containing whitespace or
non-\ **ascii(7)** characters. Each line has the form
+<*encoded-tag*\ > +<*encoded-tag*\ > ... --
id:<*quoted-message-id*\ >
Tags are hex-encoded by replacing every byte not matching the
regex **[A-Za-z0-9@=.,\_+-]** with **%nn** where nn is the two
digit hex encoding. The message ID is a valid Xapian query,
quoted using Xapian boolean term quoting rules: if the ID
contains whitespace or a close paren or starts with a double
quote, it must be enclosed in double quotes and double quotes
inside the ID must be doubled. The astute reader will notice
this is a special case of the batch input format for
**notmuch-tag(1)**; note that the single message-id query is
mandatory for **notmuch-restore(1)**.
**sup**
The **sup** dump file format is specifically chosen to be
compatible with the format of files produced by sup-dump. So if
you've previously been using sup for mail, then the **notmuch
restore** command provides you a way to import all of your tags
(or labels as sup calls them). Each line has the following form
<*message-id*\ > **(** <*tag*\ > ... **)**
with zero or more tags are separated by spaces. Note that
(malformed) message-ids may contain arbitrary non-null
characters. Note also that tags with spaces will not be
correctly restored with this format.
With no search terms, a dump of all messages in the database will be
generated. A "--" argument instructs notmuch that the remaining
arguments are search terms.
See **notmuch-search-terms(7)** for details of the supported syntax
for <search-terms>.
SEE ALSO
========
**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**

58
doc/man1/notmuch-insert.rst Normal file
View file

@ -0,0 +1,58 @@
==============
notmuch-insert
==============
SYNOPSIS
========
**notmuch** **insert** [option ...] [+<*tag*>|-<*tag*> ...]
DESCRIPTION
===========
**notmuch insert** reads a message from standard input and delivers it
into the maildir directory given by configuration option
**database.path**, then incorporates the message into the notmuch
database. It is an alternative to using a separate tool to deliver the
message then running **notmuch new** afterwards.
The new message will be tagged with the tags specified by the
**new.tags** configuration option, then by operations specified on the
command-line: tags prefixed by '+' are added while those prefixed by '-'
are removed.
If the new message is a duplicate of an existing message in the database
(it has same Message-ID), it will be added to the maildir folder and
notmuch database, but the tags will not be changed.
Option arguments must appear before any tag operation arguments.
Supported options for **insert** include
``--folder=<``\ folder\ **>**
Deliver the message to the specified folder, relative to the
top-level directory given by the value of **database.path**. The
default is to deliver to the top-level directory.
``--create-folder``
Try to create the folder named by the ``--folder`` option, if it
does not exist. Otherwise the folder must already exist for mail
delivery to succeed.
EXIT STATUS
===========
This command returns exit status 0 if the message was successfully added
to the mail directory, even if the message could not be indexed and
added to the notmuch database. In the latter case, a warning will be
printed to standard error but the message file will be left on disk.
If the message could not be written to disk then a non-zero exit status
is returned.
SEE ALSO
========
**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-reply(1)**,
**notmuch-restore(1)**, **notmuch-search(1)**,
**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**

52
doc/man1/notmuch-new.rst Normal file
View file

@ -0,0 +1,52 @@
===========
notmuch-new
===========
SYNOPSIS
========
**notmuch** **new** [--no-hooks]
DESCRIPTION
===========
Find and import any new messages to the database.
The **new** command scans all sub-directories of the database,
performing full-text indexing on new messages that are found. Each new
message will automatically be tagged with both the **inbox** and
**unread** tags.
You should run **notmuch new** once after first running **notmuch
setup** to create the initial database. The first run may take a long
time if you have a significant amount of mail (several hundred thousand
messages or more). Subsequently, you should run **notmuch new** whenever
new mail is delivered and you wish to incorporate it into the database.
These subsequent runs will be much quicker than the initial run.
Invoking ``notmuch`` with no command argument will run **new** if
**notmuch setup** has previously been completed, but **notmuch new** has
not previously been run.
**notmuch new** updates tags according to maildir flag changes if the
**maildir.synchronize\_flags** configuration option is enabled. See
**notmuch-config(1)** for details.
The **new** command supports hooks. See **notmuch-hooks(5)** for more
details on hooks.
Supported options for **new** include
``--no-hooks``
Prevents hooks from being run.
``--quiet``
Do not print progress or results.
SEE ALSO
========
**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**

112
doc/man1/notmuch-reply.rst Normal file
View file

@ -0,0 +1,112 @@
=============
notmuch-reply
=============
SYNOPSIS
========
**notmuch** **reply** [option ...] <*search-term*> ...
DESCRIPTION
===========
Constructs a reply template for a set of messages.
To make replying to email easier, **notmuch reply** takes an existing
set of messages and constructs a suitable mail template. The Reply-to:
header (if any, otherwise From:) is used for the To: address. Unless
``--reply-to=sender`` is specified, values from the To: and Cc: headers
are copied, but not including any of the current user's email addresses
(as configured in primary\_mail or other\_email in the .notmuch-config
file) in the recipient list.
It also builds a suitable new subject, including Re: at the front (if
not already present), and adding the message IDs of the messages being
replied to to the References list and setting the In-Reply-To: field
correctly.
Finally, the original contents of the emails are quoted by prefixing
each line with '> ' and included in the body.
The resulting message template is output to stdout.
Supported options for **reply** include
``--format=``\ (**default**\ \|\ **json**\ \|\ **sexp**\ \|\ **headers-only**)
**default**
Includes subject and quoted message body as an RFC 2822
message.
**json**
Produces JSON output containing headers for a reply message
and the contents of the original message. This output can be
used by a client to create a reply message intelligently.
**sexp**
Produces S-Expression output containing headers for a reply
message and the contents of the original message. This
output can be used by a client to create a reply message
intelligently.
**headers-only**
Only produces In-Reply-To, References, To, Cc, and Bcc
headers.
``--format-version=N``
Use the specified structured output format version. This is
intended for programs that invoke **notmuch(1)** internally. If
omitted, the latest supported version will be used.
``--reply-to=``\ (**all**\ \|\ **sender**)
**all** (default)
Replies to all addresses.
**sender**
Replies only to the sender. If replying to user's own
message (Reply-to: or From: header is one of the user's
configured email addresses), try To:, Cc:, and Bcc: headers
in this order, and copy values from the first that contains
something other than only the user's addresses.
``--decrypt``
Decrypt any MIME encrypted parts found in the selected content
(ie. "multipart/encrypted" parts). Status of the decryption will
be reported (currently only supported with --format=json and
--format=sexp) and on successful decryption the
multipart/encrypted part will be replaced by the decrypted
content.
Decryption expects a functioning **gpg-agent(1)** to provide any
needed credentials. Without one, the decryption will fail.
See **notmuch-search-terms(7)** for details of the supported syntax for
<search-terms>.
Note: It is most common to use **notmuch reply** with a search string
matching a single message, (such as id:<message-id>), but it can be
useful to reply to several messages at once. For example, when a series
of patches are sent in a single thread, replying to the entire thread
allows for the reply to comment on issues found in multiple patches. The
default format supports replying to multiple messages at once, but the
JSON and S-Expression formats do not.
EXIT STATUS
===========
This command supports the following special exit status codes
``20``
The requested format version is too old.
``21``
The requested format version is too new.
SEE ALSO
========
**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
**notmuch-new(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**

59
doc/man1/notmuch-restore.rst Normal file
View file

@ -0,0 +1,59 @@
===============
notmuch-restore
===============
SYNOPSIS
========
**notmuch** **restore** [--accumulate] [--format=(auto|batch-tag|sup)] [--input=<*filename*>]
DESCRIPTION
===========
Restores the tags from the given file (see **notmuch dump**).
The input is read from the given filename, if any, or from stdin.
Supported options for **restore** include
``--accumulate``
The union of the existing and new tags is applied, instead of
replacing each message's tags as they are read in from the dump
file.
``--format=(sup|batch-tag|auto)``
Notmuch restore supports two plain text dump formats, with each
line specifying a message-id and a set of tags. For details of
the actual formats, see **notmuch-dump(1)**.
**sup**
The **sup** dump file format is specifically chosen to be
compatible with the format of files produced by sup-dump. So
if you've previously been using sup for mail, then the
**notmuch restore** command provides you a way to import all
of your tags (or labels as sup calls them).
**batch-tag**
The **batch-tag** dump format is intended to more robust
against malformed message-ids and tags containing whitespace
or non-\ **ascii(7)** characters. See **notmuch-dump(1)**
for details on this format.
**notmuch restore** updates the maildir flags according to
tag changes if the **maildir.synchronize\_flags**
configuration option is enabled. See **notmuch-config(1)**
for details.
**auto**
This option (the default) tries to guess the format from the
input. For correctly formed input in either supported
format, this heuristic, based the fact that batch-tag format
contains no parentheses, should be accurate.
SEE ALSO
========
**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-search(1)**,
**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**

146
doc/man1/notmuch-search.rst Normal file
View file

@ -0,0 +1,146 @@
==============
notmuch-search
==============
SYNOPSIS
========
**notmuch** **search** [*option* ...] <*search-term*> ...
DESCRIPTION
===========
Search for messages matching the given search terms, and display as
results the threads containing the matched messages.
The output consists of one line per thread, giving a thread ID, the date
of the newest (or oldest, depending on the sort option) matched message
in the thread, the number of matched messages and total messages in the
thread, the names of all participants in the thread, and the subject of
the newest (or oldest) message.
See **notmuch-search-terms(7)** for details of the supported syntax for
<search-terms>.
Supported options for **search** include
``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**)
Presents the results in either JSON, S-Expressions, newline
character separated plain-text (default), or null character
separated plain-text (compatible with **xargs(1)** -0 option
where available).
``--format-version=N``
Use the specified structured output format version. This is
intended for programs that invoke **notmuch(1)** internally. If
omitted, the latest supported version will be used.
``--output=(summary|threads|messages|files|tags)``
**summary**
Output a summary of each thread with any message matching
the search terms. The summary includes the thread ID, date,
the number of messages in the thread (both the number
matched and the total number), the authors of the thread and
the subject.
**threads**
Output the thread IDs of all threads with any message
matching the search terms, either one per line
(--format=text), separated by null characters
(--format=text0), as a JSON array (--format=json), or an
S-Expression list (--format=sexp).
**messages**
Output the message IDs of all messages matching the search
terms, either one per line (--format=text), separated by
null characters (--format=text0), as a JSON array
(--format=json), or as an S-Expression list (--format=sexp).
**files**
Output the filenames of all messages matching the search
terms, either one per line (--format=text), separated by
null characters (--format=text0), as a JSON array
(--format=json), or as an S-Expression list (--format=sexp).
Note that each message may have multiple filenames
associated with it. All of them are included in the output,
unless limited with the --duplicate=N option.
**tags**
Output all tags that appear on any message matching the
search terms, either one per line (--format=text), separated
by null characters (--format=text0), as a JSON array
(--format=json), or as an S-Expression list (--format=sexp).
``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
This option can be used to present results in either
chronological order (**oldest-first**) or reverse chronological
order (**newest-first**).
Note: The thread order will be distinct between these two
options (beyond being simply reversed). When sorting by
**oldest-first** the threads will be sorted by the oldest
message in each thread, but when sorting by **newest-first** the
threads will be sorted by the newest message in each thread.
By default, results will be displayed in reverse chronological
order, (that is, the newest results will be displayed first).
``--offset=[-]N``
Skip displaying the first N results. With the leading '-', start
at the Nth result from the end.
``--limit=N``
Limit the number of displayed results to N.
``--exclude=(true|false|all|flag)``
A message is called "excluded" if it matches at least one tag in
search.tag\_exclude that does not appear explicitly in the
search terms. This option specifies whether to omit excluded
messages in the search process.
The default value, **true**, prevents excluded messages from
matching the search terms.
**all** additionally prevents excluded messages from appearing
in displayed results, in effect behaving as though the excluded
messages do not exist.
**false** allows excluded messages to match search terms and
appear in displayed results. Excluded messages are still marked
in the relevant outputs.
**flag** only has an effect when ``--output=summary``. The
output is almost identical to **false**, but the "match count"
is the number of matching non-excluded messages in the thread,
rather than the number of matching messages.
``--duplicate=N``
Effective with ``--output=files``, output the Nth filename
associated with each message matching the query (N is 1-based).
If N is greater than the number of files associated with the
message, don't print anything.
Note that this option is orthogonal with the **folder:** search
prefix. The prefix matches messages based on filenames. This
option filters filenames of the matching messages.
EXIT STATUS
===========
This command supports the following special exit status codes
``20``
The requested format version is too old.
``21``
The requested format version is too new.
SEE ALSO
========
**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**

179
doc/man1/notmuch-show.rst Normal file
View file

@ -0,0 +1,179 @@
============
notmuch-show
============
SYNOPSIS
========
**notmuch** **show** [*option* ...] <*search-term*> ...
DESCRIPTION
===========
Shows all messages matching the search terms.
See **notmuch-search-terms(7)** for details of the supported syntax for
<search-terms>.
The messages will be grouped and sorted based on the threading (all
replies to a particular message will appear immediately after that
message in date order). The output is not indented by default, but depth
tags are printed so that proper indentation can be performed by a
post-processor (such as the emacs interface to notmuch).
Supported options for **show** include
``--entire-thread=(true|false)``
If true, **notmuch show** outputs all messages in the thread of
any message matching the search terms; if false, it outputs only
the matching messages. For ``--format=json`` and
``--format=sexp`` this defaults to true. For other formats, this
defaults to false.
``--format=(text|json|sexp|mbox|raw)``
**text** (default for messages)
The default plain-text format has all text-content MIME
parts decoded. Various components in the output,
(**message**, **header**, **body**, **attachment**, and MIME
**part**), will be delimited by easily-parsed markers. Each
marker consists of a Control-L character (ASCII decimal 12),
the name of the marker, and then either an opening or
closing brace, ('{' or '}'), to either open or close the
component. For a multipart MIME message, these parts will be
nested.
**json**
The output is formatted with Javascript Object Notation
(JSON). This format is more robust than the text format for
automated processing. The nested structure of multipart MIME
messages is reflected in nested JSON output. By default JSON
output includes all messages in a matching thread; that is,
by default,
``--format=json`` sets ``--entire-thread`` The caller can
disable this behaviour by setting ``--entire-thread=false``
**sexp**
The output is formatted as an S-Expression (sexp). This
format is more robust than the text format for automated
processing. The nested structure of multipart MIME messages
is reflected in nested S-Expression output. By default,
S-Expression output includes all messages in a matching
thread; that is, by default,
``--format=sexp`` sets ``--entire-thread`` The caller can
disable this behaviour by setting ``--entire-thread=false``
**mbox**
All matching messages are output in the traditional, Unix
mbox format with each message being prefixed by a line
beginning with "From " and a blank line separating each
message. Lines in the message content beginning with "From "
(preceded by zero or more '>' characters) have an additional
'>' character added. This reversible escaping is termed
"mboxrd" format and described in detail here:
http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
**raw** (default for a single part, see --part)
For a message or an attached message part, the original, raw
content of the email message is output. Consumers of this
format should expect to implement MIME decoding and similar
functions.
For a single part (--part) the raw part content is output
after performing any necessary MIME decoding. Note that
messages with a simple body still have two parts: part 0 is
the whole message and part 1 is the body.
For a multipart part, the part headers and body (including
all child parts) is output.
The raw format must only be used with search terms matching
single message.
``--format-version=N``
Use the specified structured output format version. This is
intended for programs that invoke **notmuch(1)** internally. If
omitted, the latest supported version will be used.
``--part=N``
Output the single decoded MIME part N of a single message. The
search terms must match only a single message. Message parts are
numbered in a depth-first walk of the message MIME structure,
and are identified in the 'json', 'sexp' or 'text' output
formats.
``--verify``
Compute and report the validity of any MIME cryptographic
signatures found in the selected content (ie. "multipart/signed"
parts). Status of the signature will be reported (currently only
supported with --format=json and --format=sexp), and the
multipart/signed part will be replaced by the signed data.
``--decrypt``
Decrypt any MIME encrypted parts found in the selected content
(ie. "multipart/encrypted" parts). Status of the decryption will
be reported (currently only supported with --format=json and
--format=sexp) and on successful decryption the
multipart/encrypted part will be replaced by the decrypted
content.
Decryption expects a functioning **gpg-agent(1)** to provide any
needed credentials. Without one, the decryption will fail.
Implies --verify.
``--exclude=(true|false)``
Specify whether to omit threads only matching
search.tag\_exclude from the search results (the default) or
not. In either case the excluded message will be marked with the
exclude flag (except when output=mbox when there is nowhere to
put the flag).
If --entire-thread is specified then complete threads are
returned regardless (with the excluded flag being set when
appropriate) but threads that only match in an excluded message
are not returned when ``--exclude=true.``
The default is ``--exclude=true.``
``--body=(true|false)``
If true (the default) **notmuch show** includes the bodies of
the messages in the output; if false, bodies are omitted.
``--body=false`` is only implemented for the json and sexp
formats and it is incompatible with ``--part > 0.``
This is useful if the caller only needs the headers as body-less
output is much faster and substantially smaller.
``--include-html``
Include "text/html" parts as part of the output (currently only
supported with --format=json and --format=sexp). By default,
unless ``--part=N`` is used to select a specific part or
``--include-html`` is used to include all "text/html" parts, no
part with content type "text/html" is included in the output.
A common use of **notmuch show** is to display a single thread of email
messages. For this, use a search term of "thread:<thread-id>" as can be
seen in the first column of output from the **notmuch search** command.
EXIT STATUS
===========
This command supports the following special exit status codes
``20``
The requested format version is too old.
``21``
The requested format version is too new.
SEE ALSO
========
**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
**notmuch-search(1)**, **notmuch-search-terms(7)**, **notmuch-tag(1)**

107
doc/man1/notmuch-tag.rst Normal file
View file

@ -0,0 +1,107 @@
===========
notmuch-tag
===========
SYNOPSIS
========
**notmuch** **tag** [options ...] +<*tag*>|-<*tag*> [--] <*search-term*> ...
**notmuch** **tag** **--batch** [--input=<*filename*>]
DESCRIPTION
===========
Add/remove tags for all messages matching the search terms.
See **notmuch-search-terms(7)** for details of the supported syntax for
<*search-term*\ >.
Tags prefixed by '+' are added while those prefixed by '-' are removed.
For each message, tag changes are applied in the order they appear on
the command line.
The beginning of the search terms is recognized by the first argument
that begins with neither '+' nor '-'. Support for an initial search term
beginning with '+' or '-' is provided by allowing the user to specify a
"--" argument to separate the tags from the search terms.
**notmuch tag** updates the maildir flags according to tag changes if
the **maildir.synchronize\_flags** configuration option is enabled. See
**notmuch-config(1)** for details.
Supported options for **tag** include
``--remove-all``
Remove all tags from each message matching the search terms
before applying the tag changes appearing on the command line.
This means setting the tags of each message to the tags to be
added. If there are no tags to be added, the messages will have
no tags.
``--batch``
Read batch tagging operations from a file (stdin by default).
This is more efficient than repeated **notmuch tag**
invocations. See `TAG FILE FORMAT <#tag_file_format>`__ below
for the input format. This option is not compatible with
specifying tagging on the command line.
``--input=``\ <filename>
Read input from given file, instead of from stdin. Implies
``--batch``.
TAG FILE FORMAT
===============
The input must consist of lines of the format:
+<*tag*\ >\|-<*tag*\ > [...] [--] <*query*\ >
Each line is interpreted similarly to **notmuch tag** command line
arguments. The delimiter is one or more spaces ' '. Any characters in
<*tag*\ > **may** be hex-encoded with %NN where NN is the hexadecimal
value of the character. To hex-encode a character with a multi-byte
UTF-8 encoding, hex-encode each byte. Any spaces in <tag> **must** be
hex-encoded as %20. Any characters that are not part of <*tag*\ > **must
not** be hex-encoded.
In the future tag:"tag with spaces" style quoting may be supported for
<*tag*\ > as well; for this reason all double quote characters in
<*tag*\ > **should** be hex-encoded.
The <*query*\ > should be quoted using Xapian boolean term quoting
rules: if a term contains whitespace or a close paren or starts with a
double quote, it must be enclosed in double quotes (not including any
prefix) and double quotes inside the term must be doubled (see below for
examples).
Leading and trailing space ' ' is ignored. Empty lines and lines
beginning with '#' are ignored.
EXAMPLE
-------
The following shows a valid input to batch tagging. Note that only the
isolated '\*' acts as a wildcard. Also note the two different quotings
of the tag **space in tags**
::
+winner *
+foo::bar%25 -- (One and Two) or (One and tag:winner)
+found::it -- tag:foo::bar%
# ignore this line and the next
+space%20in%20tags -- Two
# add tag '(tags)', among other stunts.
+crazy{ +(tags) +&are +#possible\ -- tag:"space in tags"
+match*crazy -- tag:crazy{
+some_tag -- id:"this is ""nauty)"""
SEE ALSO
========
**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
**notmuch-search(1)**, **notmuch-search-terms(7)**, **notmuch-show(1)**,

143
doc/man1/notmuch.rst Normal file
View file

@ -0,0 +1,143 @@
=======
notmuch
=======
SYNOPSIS
========
**notmuch** [option ...] **command** [arg ...]
DESCRIPTION
===========
Notmuch is a command-line based program for indexing, searching,
reading, and tagging large collections of email messages.
This page describes how to get started using notmuch from the command
line, and gives a brief overview of the commands available. For more
information on e.g. **notmuch show** consult the **notmuch-show(1)** man
page, also accessible via **notmuch help show**
The quickest way to get started with Notmuch is to simply invoke the
``notmuch`` command with no arguments, which will interactively guide
you through the process of indexing your mail.
NOTE
====
While the command-line program ``notmuch`` provides powerful
functionality, it does not provide the most convenient interface for
that functionality. More sophisticated interfaces are expected to be
built on top of either the command-line interface, or more likely, on
top of the notmuch library interface. See http://notmuchmail.org for
more about alternate interfaces to notmuch. The emacs-based interface to
notmuch (available under **emacs/** in the Notmuch source distribution)
is probably the most widely used at this time.
OPTIONS
=======
Supported global options for ``notmuch`` include
``--help``
Print a synopsis of available commands and exit.
``--version``
Print the installed version of notmuch, and exit.
``--config=FILE``
Specify the configuration file to use. This overrides any
configuration file specified by ${NOTMUCH\_CONFIG}.
COMMANDS
========
SETUP
-----
The **notmuch setup** command is used to configure Notmuch for first
use, (or to reconfigure it later).
The setup command will prompt for your full name, your primary email
address, any alternate email addresses you use, and the directory
containing your email archives. Your answers will be written to a
configuration file in ${NOTMUCH\_CONFIG} (if set) or
${HOME}/.notmuch-config . This configuration file will be created with
descriptive comments, making it easy to edit by hand later to change the
configuration. Or you can run **notmuch setup** again to change the
configuration.
The mail directory you specify can contain any number of sub-directories
and should primarily contain only files with individual email messages
(eg. maildir or mh archives are perfect). If there are other, non-email
files (such as indexes maintained by other email programs) then notmuch
will do its best to detect those and ignore them.
Mail storage that uses mbox format, (where one mbox file contains many
messages), will not work with notmuch. If that's how your mail is
currently stored, it is recommended you first convert it to maildir
format with a utility such as mb2md before running **notmuch setup .**
Invoking ``notmuch`` with no command argument will run **setup** if the
setup command has not previously been completed.
OTHER COMMANDS
--------------
Several of the notmuch commands accept search terms with a common
syntax. See **notmuch-search-terms**\ (7) for more details on the
supported syntax.
The **search**, **show** and **count** commands are used to query the
email database.
The **reply** command is useful for preparing a template for an email
reply.
The **tag** command is the only command available for manipulating
database contents.
The **dump** and **restore** commands can be used to create a textual
dump of email tags for backup purposes, and to restore from that dump.
The **config** command can be used to get or set settings in the notmuch
configuration file.
ENVIRONMENT
===========
The following environment variables can be used to control the behavior
of notmuch.
**NOTMUCH\_CONFIG**
Specifies the location of the notmuch configuration file. Notmuch
will use ${HOME}/.notmuch-config if this variable is not set.
**NOTMUCH\_TALLOC\_REPORT**
Location to write a talloc memory usage report. See
**talloc\_enable\_leak\_report\_full** in **talloc(3)** for more
information.
**NOTMUCH\_DEBUG\_QUERY**
If set to a non-empty value, the notmuch library will print (to
stderr) Xapian queries it constructs.
SEE ALSO
========
**notmuch-config(1)**, **notmuch-count(1)**, **notmuch-dump(1)**,
**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
The notmuch website: **http://notmuchmail.org**
CONTACT
=======
Feel free to send questions, comments, or kudos to the notmuch mailing
list <notmuch@notmuchmail.org> . Subscription is not required before
posting, but is available from the notmuchmail.org website.
Real-time interaction with the Notmuch community is available via IRC
(server: irc.freenode.net, channel: #notmuch).

44
doc/man5/notmuch-hooks.rst Normal file
View file

@ -0,0 +1,44 @@
=============
notmuch-hooks
=============
SYNOPSIS
========
$DATABASEDIR/.notmuch/hooks/*
DESCRIPTION
===========
Hooks are scripts (or arbitrary executables or symlinks to such) that
notmuch invokes before and after certain actions. These scripts reside
in the .notmuch/hooks directory within the database directory and must
have executable permissions.
The currently available hooks are described below.
**pre-new**
This hook is invoked by the **new** command before scanning or
importing new messages into the database. If this hook exits
with a non-zero status, notmuch will abort further processing of
the **new** command.
Typically this hook is used for fetching or delivering new mail
to be imported into the database.
**post-new**
This hook is invoked by the **new** command after new messages
have been imported into the database and initial tags have been
applied. The hook will not be run if there have been any errors
during the scan or import.
Typically this hook is used to perform additional query-based
tagging on the imported messages.
SEE ALSO
========
**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
**notmuch-dump(1)**, **notmuch-insert(1)**, **notmuch-new(1)**,
**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**

234
doc/man7/notmuch-search-terms.rst Normal file
View file

@ -0,0 +1,234 @@
====================
notmuch-search-terms
====================
SYNOPSIS
========
**notmuch** **count** [option ...] <*search-term*> ...
**notmuch** **dump** [--format=(batch-tag|sup)] [--] [--output=<*file*>] [--] [<*search-term*> ...]
**notmuch** **search** [option ...] <*search-term*> ...
**notmuch** **show** [option ...] <*search-term*> ...
**notmuch** **tag** +<*tag*> ... -<*tag*> [--] <*search-term*> ...
DESCRIPTION
===========
Several notmuch commands accept a common syntax for search terms.
The search terms can consist of free-form text (and quoted phrases)
which will match all messages that contain all of the given
terms/phrases in the body, the subject, or any of the sender or
recipient headers.
As a special case, a search string consisting of exactly a single
asterisk ("\*") will match all messages.
In addition to free text, the following prefixes can be used to force
terms to match against specific portions of an email, (where <brackets>
indicate user-supplied values):
- from:<name-or-address>
- to:<name-or-address>
- subject:<word-or-quoted-phrase>
- attachment:<word>
- tag:<tag> (or is:<tag>)
- id:<message-id>
- thread:<thread-id>
- folder:<directory-path>
- date:<since>..<until>
The **from:** prefix is used to match the name or address of the sender
of an email message.
The **to:** prefix is used to match the names or addresses of any
recipient of an email message, (whether To, Cc, or Bcc).
Any term prefixed with **subject:** will match only text from the
subject of an email. Searching for a phrase in the subject is supported
by including quotation marks around the phrase, immediately following
**subject:**.
The **attachment:** prefix can be used to search for specific filenames
(or extensions) of attachments to email messages.
For **tag:** and **is:** valid tag values include **inbox** and
**unread** by default for new messages added by **notmuch new** as well
as any other tag values added manually with **notmuch tag**.
For **id:**, message ID values are the literal contents of the
Message-ID: header of email messages, but without the '<', '>'
delimiters.
The **thread:** prefix can be used with the thread ID values that are
generated internally by notmuch (and do not appear in email messages).
These thread ID values can be seen in the first column of output from
**notmuch search**
The **folder:** prefix can be used to search for email message files
that are contained within particular directories within the mail store.
If the same email message has multiple message files associated with it,
it's sufficient for a match that at least one of the files is contained
within a matching directory. Only the directory components below the
top-level mail database path are available to be searched.
The **date:** prefix can be used to restrict the results to only
messages within a particular time range (based on the Date: header) with
a range syntax of:
date:<since>..<until>
See **DATE AND TIME SEARCH** below for details on the range expression,
and supported syntax for <since> and <until> date and time expressions.
The time range can also be specified using timestamps with a syntax of:
<initial-timestamp>..<final-timestamp>
Each timestamp is a number representing the number of seconds since
1970-01-01 00:00:00 UTC.
In addition to individual terms, multiple terms can be combined with
Boolean operators ( **and**, **or**, **not** , etc.). Each term in the
query will be implicitly connected by a logical AND if no explicit
operator is provided, (except that terms with a common prefix will be
implicitly combined with OR until we get Xapian defect #402 fixed).
Parentheses can also be used to control the combination of the Boolean
operators, but will have to be protected from interpretation by the
shell, (such as by putting quotation marks around any parenthesized
expression).
DATE AND TIME SEARCH
====================
notmuch understands a variety of standard and natural ways of expressing
dates and times, both in absolute terms ("2012-10-24") and in relative
terms ("yesterday"). Any number of relative terms can be combined ("1
hour 25 minutes") and an absolute date/time can be combined with
relative terms to further adjust it. A non-exhaustive description of the
syntax supported for absolute and relative terms is given below.
The range expression
--------------------
date:<since>..<until>
The above expression restricts the results to only messages from <since>
to <until>, based on the Date: header.
<since> and <until> can describe imprecise times, such as "yesterday".
In this case, <since> is taken as the earliest time it could describe
(the beginning of yesterday) and <until> is taken as the latest time it
could describe (the end of yesterday). Similarly, date:january..february
matches from the beginning of January to the end of February.
Currently, we do not support spaces in range expressions. You can
replace the spaces with '\_', or (in most cases) '-', or (in some cases)
leave the spaces out altogether. Examples in this man page use spaces
for clarity.
Open-ended ranges are supported (since Xapian 1.2.1), i.e. it's possible
to specify date:..<until> or date:<since>.. to not limit the start or
end time, respectively. Pre-1.2.1 Xapian does not report an error on
open ended ranges, but it does not work as expected either.
Entering date:expr without ".." (for example date:yesterday) won't work,
as it's not interpreted as a range expression at all. You can achieve
the expected result by duplicating the expr both sides of ".." (for
example date:yesterday..yesterday).
Relative date and time
----------------------
[N\|number]
(years\|months\|weeks\|days\|hours\|hrs\|minutes\|mins\|seconds\|secs)
[...]
All refer to past, can be repeated and will be accumulated.
Units can be abbreviated to any length, with the otherwise ambiguous
single m being m for minutes and M for months.
Number can also be written out one, two, ..., ten, dozen, hundred.
Additionally, the unit may be preceded by "last" or "this" (e.g., "last
week" or "this month").
When combined with absolute date and time, the relative date and time
specification will be relative from the specified absolute date and
time.
Examples: 5M2d, two weeks
Supported absolute time formats
-------------------------------
- H[H]:MM[:SS] [(am\|a.m.\|pm\|p.m.)]
- H[H] (am\|a.m.\|pm\|p.m.)
- HHMMSS
- now
- noon
- midnight
- Examples: 17:05, 5pm
Supported absolute date formats
-------------------------------
- YYYY-MM[-DD]
- DD-MM[-[YY]YY]
- MM-YYYY
- M[M]/D[D][/[YY]YY]
- M[M]/YYYY
- D[D].M[M][.[YY]YY]
- D[D][(st\|nd\|rd\|th)] Mon[thname] [YYYY]
- Mon[thname] D[D][(st\|nd\|rd\|th)] [YYYY]
- Wee[kday]
Month names can be abbreviated at three or more characters.
Weekday names can be abbreviated at three or more characters.
Examples: 2012-07-31, 31-07-2012, 7/31/2012, August 3
Time zones
----------
- (+\|-)HH:MM
- (+\|-)HH[MM]
Some time zone codes, e.g. UTC, EET.
SEE ALSO
========
**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
**notmuch-search(1)**, **notmuch-show(1)**, **notmuch-tag(1)**

192
doc/notmuch-emacs.rst Normal file
View file

@ -0,0 +1,192 @@
=============
notmuch-emacs
=============
About this Manual
=================
This manual covers only the emacs interface to notmuch. For information
on the command line interface, see See section “Description” in Notmuch
Manual Pager. To save typing, we will sometimes use *notmuch* in this
manual to refer to the Emacs interface to notmuch. If the distinction
should every be important, we’ll refer to the Emacs inteface as
*notmuch-emacs*.
Notmuch-emacs is highly customizable via the the Emacs customization
framework (or just by setting the appropriate variables). We try to
point out relevant variables in this manual, but in order to avoid
duplication of information, but you can usually find the most detailed
description in the varables docstring.
notmuch-hello
=============
.. index::
single: notmuch-hello
single: notmuch
``notmuch-hello`` is the main entry point for notmuch. You can start it
with ``M-x notmuch`` or ``M-x notmuch-hello``. The startup screen looks
something like the following. There are some hints at the bottom of the
screen. There are three main parts to the notmuch-hello screen,
discussed below. The **bold** text indicates buttons you can click with
a mouse or by positioning the cursor and pressing ``<return>``
| Welcome to **notmuch** You have 52 messages.
|
| Saved searches: **[edit]**
|
| 52 **inbox** 52 **unread**
|
| Search: ____________________________________
|
| All tags: **[show]**
|
| Type a search query and hit RET to view matching threads.
| Edit saved searches with the ``edit`` button.
| Hit RET or click on a saved search or tag name to view matching threads.
| ``=`` to refresh this screen. ``s`` to search messages. ``q`` to quit.
| **Customize** this page.
You can change the overall appearence of the notmuch-hello screen by
customizing the variable :index:`notmuch-hello-sections`.
notmuch-hello key bindings
--------------------------
``<tab>``
Move to the next widget (button or text entry field)
``<backtab>``
Move to the previous widget.
``<return>``
Activate the current widget.
``=``
Refresh the buffer; mainly update the counts of messages for various
saved searches.
``G``
Import mail, See :ref:`importing`
``m``
Compose a message
``s``
Search the notmuch database using :ref:`notmuch-search`
``v``
Print notmuch version
``q``
Quit
.. _saved-searches:
Saved Searches
--------------
Notmuch replaces the static assignment of messages with the more dynamic
notion of searching. Notmuch-hello presents the user with a customizable
set of saved searchs. The initial defaults are ``tag:inbox`` and
``tag:unread``, but you can customize the following variables
:index:`notmuch-saved-searches`
A list of cons pairs, the first being the name to display, the
second being a query string for notmuch. See section “Description”
in Notmuch Query Syntax.
:index:`notmuch-saved-searches-sort-function`
This variable controls how saved searches should be sorted. A value
of ``nil`` displays the saved searches in the order they are stored
in ‘notmuch-saved-searches’.
:index:`notmuch-column-control`
Controls the number of columns for displaying saved-searches/tags
Search Box
----------
The search box lets the user enter an notmuch query. See section
“Description” in Notmuch Query Syntax, for more info on notmuch query
syntax. A history of recent searches is also displayed by default. The
latter is controlled by the variable :index:`notmuch-hello-recent-searches-max`.
Known Tags
----------
One special kind of saved search provided by default is for each
individual tag defined in the database. This can be controlled via the
following variables.
:index:`notmuch-hello-tag-list-make-query`
Control how to construct a search (“virtual folder”) from a given
tag.
:index:`notmuch-hello-hide-tags`
Which tags not to display at all.
:index:`notmuch-column-control`
Controls the number of columns for displaying saved-searches/tags
.. _notmuch-search:
notmuch-search
==============
``notmuch-search-mode`` is used to display the results from executing
a query via ``notmuch-search``. The syntax for these queries is the
the same as :ref:`saved-searches`. For details of this syntax see
info:notmuch-search-terms
By default the output approximates that of the command line See section
“Description” in notmuch search command.
The main purpose of the ``notmuch-search-mode`` buffer is to act as a
menu of results that the user can explore further by pressing
``<return>`` on the appropriate line.
``n,C-n,<down>``
Move to next line
``p,C-p,<up>``
Move to previous line
``<return>``
Open thread on current line in :ref:`notmuch-show` mode
``?``
Display full set of key bindings
The presentation of results can be controlled by the following
variables.
:index:`notmuch-search-result-format`
Control how each thread of messages is presented in the
``notmuch-show-mode`` buffer
:index:`notmuch-search-oldest-first`
Display the oldest threads at the top of the buffer
.. _notmuch-show:
notmuch-show
============
notmuch-tree
============
Configuration
=============
.. _importing:
Importing Mail
--------------
:index:`notmuch-poll`
:index:`notmuch-poll-script`