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.

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)

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.<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:
+.. nmconfig:: show.extra_headers
-
-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

doc/man1/notmuch-insert.rst

@@ -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
+:nmconfig:`index.decrypt` and :nmconfig:`index.header.\<prefix\>`.  Tagging
-<index.header>`.  Tagging
+is controlled by options :nmconfig:`new.tags` and
-is controlled by :ref:`new.tags <new.tags>` and
+:nmconfig:`maildir.synchronize_flags`.  See
-:ref:`maildir.synchronize_flags <maildir.synchronize_flags>`.  See
 :any:`notmuch-config(1)` for details.
 
 EXIT STATUS

doc/man1/notmuch-new.rst

@@ -82,10 +82,10 @@ CONFIGURATION
 =============
 
 Indexing is influenced by the configuration options
-:ref:`index.decrypt <index.decrypt>`, :ref:`index.header
+:nmconfig:`index.decrypt`, :nmconfig:`index.header.\<prefix\>`
-<index.header>`, and :ref:`new.ignore <new.ignore>`.  Tagging
+and :nmconfig:`new.ignore`.  Tagging
-is controlled by :ref:`new.tags <new.tags>` and
+is controlled by :nmconfig:`new.tags` and
-:ref:`maildir.synchronize_flags <maildir.synchronize_flags>`.  See
+:nmconfig:`maildir.synchronize_flags`.  See
 :any:`notmuch-config(1)` for details.
 
 EXIT STATUS

doc/man1/notmuch-show.rst

@@ -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