This makes sure each configuration item is cross referenceable without
extra markup, and also adds index entries.
---
doc/conf.py | 7 +
doc/man1/notmuch-config.rst | 60 +++--
doc/man1/notmuch-insert.rst | 15 +-
doc/man1/notmuch-new.rst| 8 ++---
doc/man1/notmuch-show.rst | 2 +-
5 files changed, 50 insertions(+), 42 deletions(-)
diff --git a/doc/conf.py b/doc/conf.py
index e46e1d4e..6afeac06 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -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)
diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst
index acc5ecec..36d48725 100644
--- a/doc/man1/notmuch-config.rst
+++ b/doc/man1/notmuch-config.rst
@@ -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.
+.. nmconfig:: built_with.
+
Compile time feature . 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.
+.. nmconfig:: index.header.
+
Define the query 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.
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.
+.. nmconfig:: query.
+
Expansion for named query called . 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
