From 306b7028d2288a3002cdbbcf8fd0973d8d969b84 Mon Sep 17 00:00:00 2001 From: David Bremner Date: Thu, 12 May 2022 08:52:30 -0300 Subject: [PATCH] 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 | 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 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. +.. nmconfig:: squery. + Expansion for named query called , 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 `). + (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 diff --git a/doc/man1/notmuch-insert.rst b/doc/man1/notmuch-insert.rst index fe2bf26b..e05bd0b5 100644 --- a/doc/man1/notmuch-insert.rst +++ b/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 `, 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 ` 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= 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 ` 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 ` and :ref:`index.header -`. Tagging -is controlled by :ref:`new.tags ` and -:ref:`maildir.synchronize_flags `. See +:nmconfig:`index.decrypt` and :nmconfig:`index.header.\`. Tagging +is controlled by options :nmconfig:`new.tags` and +:nmconfig:`maildir.synchronize_flags`. See :any:`notmuch-config(1)` for details. EXIT STATUS diff --git a/doc/man1/notmuch-new.rst b/doc/man1/notmuch-new.rst index 398f8813..f0ed8eb8 100644 --- a/doc/man1/notmuch-new.rst +++ b/doc/man1/notmuch-new.rst @@ -82,10 +82,10 @@ CONFIGURATION ============= Indexing is influenced by the configuration options -:ref:`index.decrypt `, :ref:`index.header -`, and :ref:`new.ignore `. Tagging -is controlled by :ref:`new.tags ` and -:ref:`maildir.synchronize_flags `. See +:nmconfig:`index.decrypt`, :nmconfig:`index.header.\` +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 diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst index 1b02d407..55353921 100644 --- a/doc/man1/notmuch-show.rst +++ b/doc/man1/notmuch-show.rst @@ -225,7 +225,7 @@ CONFIGURATION ============= Structured output (json / sexp) is influenced by the configuration -option :ref:`show.extra_headers `. See +option :nmconfig:`show.extra_headers`. See :any:`notmuch-config(1)` for details. EXIT STATUS -- 2.43.0