mirror of
https://git.notmuchmail.org/git/notmuch
synced 2024-11-23 19:38:07 +01:00
doc: define and use semantic markup for configuration items
This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
This commit is contained in:
David Bremner
parent
90a7c1af36
commit
306b7028d2
5 changed files with 50 additions and 42 deletions
|
|
@ -200,3 +200,10 @@ texinfo_documents += [
|
|||
x[2], # description
|
||||
'Miscellaneous' # category
|
||||
) for x in man_pages]
|
||||
|
||||
def setup(app):
|
||||
import docutils.nodes
|
||||
# define nmconfig role and directive for config items.
|
||||
app.add_object_type('nmconfig','nmconfig',
|
||||
indextemplate='pair: configuration item; %s',
|
||||
ref_nodeclass=docutils.nodes.generated)
|
||||
|
|
|
|||
|
|
@ -55,13 +55,14 @@ The available configuration items are described below. Non-absolute
|
|||
paths are presumed relative to `$HOME` for items in section
|
||||
**database**.
|
||||
|
||||
built_with.<name>
|
||||
.. nmconfig:: built_with.<name>
|
||||
|
||||
Compile time feature <name>. Current possibilities include
|
||||
"retry_lock" (configure option, included by default).
|
||||
(since notmuch 0.30, "compact" and "field_processor" are
|
||||
always included.)
|
||||
|
||||
database.autocommit
|
||||
.. nmconfig:: database.autocommit
|
||||
|
||||
How often to commit transactions to disk. `0` means wait until
|
||||
command completes, otherwise an integer `n` specifies to commit to
|
||||
|
|
@ -69,7 +70,8 @@ database.autocommit
|
|||
|
||||
History: this configuration value was introduced in notmuch 0.33.
|
||||
|
||||
database.backup_dir
|
||||
.. nmconfig:: database.backup_dir
|
||||
|
||||
Directory to store tag dumps when upgrading database.
|
||||
|
||||
History: this configuration value was introduced in notmuch 0.32.
|
||||
|
|
@ -77,7 +79,8 @@ database.backup_dir
|
|||
Default: A sibling directory of the Xapian database called
|
||||
`backups`.
|
||||
|
||||
database.hook_dir
|
||||
.. nmconfig:: database.hook_dir
|
||||
|
||||
Directory containing hooks run by notmuch commands. See
|
||||
:any:`notmuch-hooks(5)`.
|
||||
|
||||
|
|
@ -85,9 +88,8 @@ database.hook_dir
|
|||
|
||||
Default: See HOOKS, below.
|
||||
|
||||
.. _database.mail_root:
|
||||
.. nmconfig:: database.mail_root
|
||||
|
||||
database.mail_root
|
||||
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.
|
||||
|
|
@ -95,18 +97,18 @@ database.mail_root
|
|||
History: this configuration value was introduced in notmuch 0.32.
|
||||
|
||||
Default: For compatibility with older configurations, the value of
|
||||
database.path is used if **database.mail\_root** is unset.
|
||||
database.path is used if :nmconfig:`database.mail_root` is unset.
|
||||
|
||||
.. nmconfig:: database.path
|
||||
|
||||
database.path
|
||||
Notmuch will store its database here, (in
|
||||
sub-directory named ``.notmuch`` if **database.mail\_root**
|
||||
sub-directory named ``.notmuch`` if :nmconfig:`database.mail_root`
|
||||
is unset).
|
||||
|
||||
Default: see :ref:`database`
|
||||
|
||||
.. _index.decrypt:
|
||||
.. nmconfig:: index.decrypt
|
||||
|
||||
index.decrypt
|
||||
Policy for decrypting encrypted messages during indexing. Must be
|
||||
one of: ``false``, ``auto``, ``nostash``, or ``true``.
|
||||
|
||||
|
|
@ -161,7 +163,8 @@ index.decrypt
|
|||
|
||||
.. _index.header:
|
||||
|
||||
index.header.<prefix>
|
||||
.. nmconfig:: index.header.<prefix>
|
||||
|
||||
Define the query prefix <prefix>, based on a mail header. For
|
||||
example ``index.header.List=List-Id`` will add a probabilistic
|
||||
prefix ``List:`` that searches the ``List-Id`` field. User
|
||||
|
|
@ -170,9 +173,8 @@ index.header.<prefix>
|
|||
supported. See :any:`notmuch-search-terms(7)` for a list of existing
|
||||
prefixes, and an explanation of probabilistic prefixes.
|
||||
|
||||
.. _maildir.synchronize_flags:
|
||||
.. nmconfig:: maildir.synchronize_flags
|
||||
|
||||
maildir.synchronize\_flags
|
||||
If true, then the following maildir flags (in message filenames)
|
||||
will be synchronized with the corresponding notmuch tags:
|
||||
|
||||
|
|
@ -205,9 +207,8 @@ maildir.synchronize\_flags
|
|||
|
||||
Default: ``true``.
|
||||
|
||||
.. _new.ignore:
|
||||
.. nmconfig:: new.ignore
|
||||
|
||||
new.ignore
|
||||
A list to specify files and directories that will not be searched
|
||||
for messages by :any:`notmuch-new(1)`. Each entry in the list is either:
|
||||
|
||||
|
|
@ -225,20 +226,21 @@ new.ignore
|
|||
|
||||
Default: empty list.
|
||||
|
||||
.. _new.tags:
|
||||
.. nmconfig:: new.tags
|
||||
|
||||
new.tags
|
||||
A list of tags that will be added to all messages incorporated by
|
||||
**notmuch new**.
|
||||
|
||||
Default: ``unread;inbox``.
|
||||
|
||||
query.<name>
|
||||
.. nmconfig:: query.<name>
|
||||
|
||||
Expansion for named query called <name>. See
|
||||
:any:`notmuch-search-terms(7)` for more information about named
|
||||
queries.
|
||||
|
||||
search.exclude\_tags
|
||||
.. nmconfig:: 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.
|
||||
|
|
@ -246,9 +248,7 @@ search.exclude\_tags
|
|||
Default: empty list. Note that :any:`notmuch-setup(1)` puts
|
||||
``deleted;spam`` here when creating new configuration file.
|
||||
|
||||
.. _show.extra_headers:
|
||||
|
||||
show.extra\_headers
|
||||
.. nmconfig:: show.extra_headers
|
||||
|
||||
By default :any:`notmuch-show(1)` includes the following headers
|
||||
in structured output if they are present in the message:
|
||||
|
|
@ -260,26 +260,28 @@ show.extra\_headers
|
|||
|
||||
Default: empty list.
|
||||
|
||||
squery.<name>
|
||||
.. nmconfig:: squery.<name>
|
||||
|
||||
Expansion for named query called <name>, using s-expression syntax. See
|
||||
:any:`notmuch-sexp-queries(7)` for more information about s-expression
|
||||
queries.
|
||||
|
||||
user.name
|
||||
.. nmconfig:: user.name
|
||||
|
||||
Your full name.
|
||||
|
||||
Default: ``$NAME`` variable if set, otherwise read from
|
||||
``/etc/passwd``.
|
||||
|
||||
user.other\_email
|
||||
.. nmconfig:: user.other_email
|
||||
|
||||
A list of other email addresses at which you receive email
|
||||
(see also, :ref:`user.primary_email <user.primary_email>`).
|
||||
(see also, :nmconfig:`user.primary_email`)
|
||||
|
||||
Default: not set.
|
||||
|
||||
.. _user.primary_email:
|
||||
.. nmconfig:: user.primary_email
|
||||
|
||||
user.primary\_email
|
||||
Your primary email address.
|
||||
|
||||
Default: ``$EMAIL`` variable if set, otherwise constructed from
|
||||
|
|
|
|||
|
|
@ -14,12 +14,12 @@ DESCRIPTION
|
|||
|
||||
**notmuch insert** reads a message from standard input and delivers it
|
||||
into the maildir directory given by configuration option
|
||||
:ref:`database.mail_root <database.mail_root>`, then incorporates the message into the notmuch
|
||||
:nmconfig:`database.mail_root`, then incorporates the message into the notmuch
|
||||
database. It is an alternative to using a separate tool to deliver the
|
||||
message then running :any:`notmuch-new(1)` afterwards.
|
||||
|
||||
The new message will be tagged with the tags specified by the
|
||||
:ref:`new.tags <new.tags>` configuration option, then by operations specified on the
|
||||
:nmconfig:`new.tags` configuration option, then by operations specified on the
|
||||
command-line: tags prefixed by '+' are added while those prefixed by '-'
|
||||
are removed.
|
||||
|
||||
|
|
@ -38,7 +38,7 @@ Supported options for **insert** include
|
|||
.. option:: --folder=<folder>
|
||||
|
||||
Deliver the message to the specified folder, relative to the
|
||||
top-level directory given by the value of **database.mail_root**. The
|
||||
top-level directory given by the value of :nmconfig:`database.mail_root`. The
|
||||
default is the empty string, which means delivering to the
|
||||
top-level directory.
|
||||
|
||||
|
|
@ -86,16 +86,15 @@ Supported options for **insert** include
|
|||
``--decrypt=nostash`` without considering the security of your
|
||||
index.
|
||||
|
||||
See also :ref:`index.decrypt <index.decrypt>` in :any:`notmuch-config(1)`.
|
||||
See also :nmconfig:`index.decrypt` in :any:`notmuch-config(1)`.
|
||||
|
||||
CONFIGURATION
|
||||
=============
|
||||
|
||||
Indexing is influenced by the configuration options
|
||||
:ref:`index.decrypt <index.decrypt>` and :ref:`index.header
|
||||
<index.header>`. Tagging
|
||||
is controlled by :ref:`new.tags <new.tags>` and
|
||||
:ref:`maildir.synchronize_flags <maildir.synchronize_flags>`. See
|
||||
:nmconfig:`index.decrypt` and :nmconfig:`index.header.\<prefix\>`. Tagging
|
||||
is controlled by options :nmconfig:`new.tags` and
|
||||
:nmconfig:`maildir.synchronize_flags`. See
|
||||
:any:`notmuch-config(1)` for details.
|
||||
|
||||
EXIT STATUS
|
||||
|
|
|
|||
|
|
@ -82,10 +82,10 @@ CONFIGURATION
|
|||
=============
|
||||
|
||||
Indexing is influenced by the configuration options
|
||||
:ref:`index.decrypt <index.decrypt>`, :ref:`index.header
|
||||
<index.header>`, and :ref:`new.ignore <new.ignore>`. Tagging
|
||||
is controlled by :ref:`new.tags <new.tags>` and
|
||||
:ref:`maildir.synchronize_flags <maildir.synchronize_flags>`. See
|
||||
:nmconfig:`index.decrypt`, :nmconfig:`index.header.\<prefix\>`
|
||||
and :nmconfig:`new.ignore`. Tagging
|
||||
is controlled by :nmconfig:`new.tags` and
|
||||
:nmconfig:`maildir.synchronize_flags`. See
|
||||
:any:`notmuch-config(1)` for details.
|
||||
|
||||
EXIT STATUS
|
||||
|
|
|
|||
|
|
@ -225,7 +225,7 @@ CONFIGURATION
|
|||
=============
|
||||
|
||||
Structured output (json / sexp) is influenced by the configuration
|
||||
option :ref:`show.extra_headers <show.extra_headers>`. See
|
||||
option :nmconfig:`show.extra_headers`. See
|
||||
:any:`notmuch-config(1)` for details.
|
||||
|
||||
EXIT STATUS
|
||||
|
|
|
|||
Loading…
Reference in a new issue