improve documentation of configuration options

improve documentation of configuration options

[David Bremner]

I started to edit the documentation for
id:20220205195215.166213-1-david@tethera.net and I realized that
notmuch-config(1) was becoming (had become?) unwieldy. This series
contains some incremental improvements. Eventually I'd like to have
CONFIGURATION sections in the documentation for each command (assuming
there is some relevant configuration).

[PATCH 1/4] doc: alphabetize options in notmuch-config(1)

[David Bremner]

Originally (I think) these were in the order generated by notmuch
setup. As the number of options grows, and several are not in the
initial setup generated file, the original order becomes less useful
for users. This commit alphabetizes the keys to help users
search. There is only one content change, an added cross-reference
from user.other_email to user.primary_email.
---
 doc/man1/notmuch-config.rst | 237 ++++++++++++++++++------------------
 1 file changed, 120 insertions(+), 117 deletions(-)

diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst
index 41e1338b..8ddfc1d6 100644
--- a/doc/man1/notmuch-config.rst
+++ b/doc/man1/notmuch-config.rst
@@ -55,22 +55,19 @@ The available configuration items are described below. Non-absolute
 paths are presumed relative to `$HOME` for items in section
 **database**.
 
-database.path
-    Notmuch will store its database here, (in
-    sub-directory named ``.notmuch`` if **database.mail\_root**
-    is unset).
-
-    Default: see :ref:`database`
+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.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.
+database.autocommit
 
-    History: this configuration value was introduced in notmuch 0.32.
+    How often to commit transactions to disk. `0` means wait until
+    command completes, otherwise an integer `n` specifies to commit to
+    disk after every `n` completed transactions.
 
-    Default: For compatibility with older configurations, the value of
-    database.path is used if **database.mail\_root** is unset.
+    History: this configuration value was introduced in notmuch 0.33.
 
 database.backup_dir
     Directory to store tag dumps when upgrading database.
@@ -88,109 +85,22 @@ database.hook_dir
 
     Default: See HOOKS, below.
 
-database.autocommit
-
-    How often to commit transactions to disk. `0` means wait until
-    command completes, otherwise an integer `n` specifies to commit to
-    disk after every `n` completed transactions.
-
-    History: this configuration value was introduced in notmuch 0.33.
-
-user.name
-    Your full name.
-
-    Default: ``$NAME`` variable if set, otherwise read from
-    ``/etc/passwd``.
-
-user.primary\_email
-    Your primary email address.
-
-    Default: ``$EMAIL`` variable if set, otherwise constructed from
-    the username and hostname of the current machine.
-
-user.other\_email
-    A list of other email addresses at which you receive email.
-
-    Default: not set.
-
-new.tags
-    A list of tags that will be added to all messages incorporated by
-    **notmuch new**.
-
-    Default: ``unread;inbox``.
-
-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:
-
-    A file or a directory name, without path, that will be ignored,
-    regardless of the location in the mail store directory hierarchy.
-
-    Or:
-
-    A regular expression delimited with // that will be matched
-    against the path of the file or directory relative to the database
-    path. Matching files and directories will be ignored. The
-    beginning and end of string must be explicitly anchored. For
-    example, /.*/foo$/ would match "bar/foo" and "bar/baz/foo", but
-    not "foo" or "bar/foobar".
-
-    Default: empty list.
-
-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.
-
-    Default: empty list. Note that :any:`notmuch-setup(1)` puts
-    ``deleted;spam`` here when creating new configuration file.
-
-.. _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:
-    `Subject`, `From`, `To`, `Cc`, `Bcc`, `Reply-To`, `Date`. This
-    option allows the specification of a list of further
-    headers to output.
-
-    History: This configuration value was introduced in notmuch 0.35.
-
-    Default: empty list.
-
-maildir.synchronize\_flags
-    If true, then the following maildir flags (in message filenames)
-    will be synchronized with the corresponding notmuch tags:
+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.
 
-    +--------+-----------------------------------------------+
-    | Flag   | Tag                                           |
-    +========+===============================================+
-    | D      | draft                                         |
-    +--------+-----------------------------------------------+
-    | F      | flagged                                       |
-    +--------+-----------------------------------------------+
-    | P      | passed                                        |
-    +--------+-----------------------------------------------+
-    | R      | replied                                       |
-    +--------+-----------------------------------------------+
-    | S      | unread (added when 'S' flag is not present)   |
-    +--------+-----------------------------------------------+
+    History: this configuration value was introduced in notmuch 0.32.
 
-    The :any:`notmuch-new(1)` command will notice flag changes in
-    filenames and update tags, while the :any:`notmuch-tag(1)` and
-    :any:`notmuch-restore(1)` commands will notice tag changes and
-    update flags in filenames.
+    Default: For compatibility with older configurations, the value of
+    database.path is used if **database.mail\_root** is unset.
 
-    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 :any:`notmuch-new(1)` before
-    :any:`notmuch-tag(1)` or :any:`notmuch-restore(1)` 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.
+database.path
+    Notmuch will store its database here, (in
+    sub-directory named ``.notmuch`` if **database.mail\_root**
+    is unset).
 
-    Default: ``true``.
+    Default: see :ref:`database`
 
 index.decrypt
     Policy for decrypting encrypted messages during indexing.  Must be
@@ -254,22 +164,115 @@ index.header.<prefix>
     supported. See :any:`notmuch-search-terms(7)` for a list of existing
     prefixes, and an explanation of probabilistic prefixes.
 
-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.)
+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 :any:`notmuch-new(1)` command will notice flag changes in
+    filenames and update tags, while the :any:`notmuch-tag(1)` and
+    :any:`notmuch-restore(1)` 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 :any:`notmuch-new(1)` before
+    :any:`notmuch-tag(1)` or :any:`notmuch-restore(1)` 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.
+
+    Default: ``true``.
+
+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:
+
+    A file or a directory name, without path, that will be ignored,
+    regardless of the location in the mail store directory hierarchy.
+
+    Or:
+
+    A regular expression delimited with // that will be matched
+    against the path of the file or directory relative to the database
+    path. Matching files and directories will be ignored. The
+    beginning and end of string must be explicitly anchored. For
+    example, /.*/foo$/ would match "bar/foo" and "bar/baz/foo", but
+    not "foo" or "bar/foobar".
+
+    Default: empty list.
+
+new.tags
+    A list of tags that will be added to all messages incorporated by
+    **notmuch new**.
+
+    Default: ``unread;inbox``.
 
 query.<name>
     Expansion for named query called <name>. See
     :any:`notmuch-search-terms(7)` for more information about named
     queries.
 
+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.
+
+    Default: empty list. Note that :any:`notmuch-setup(1)` puts
+    ``deleted;spam`` here when creating new configuration file.
+
+.. _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:
+    `Subject`, `From`, `To`, `Cc`, `Bcc`, `Reply-To`, `Date`. This
+    option allows the specification of a list of further
+    headers to output.
+
+    History: This configuration value was introduced in notmuch 0.35.
+
+    Default: empty list.
+
 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
+    Your full name.
+
+    Default: ``$NAME`` variable if set, otherwise read from
+    ``/etc/passwd``.
+
+user.other\_email
+    A list of other email addresses at which you receive email
+    (see also, :ref:`user.primary_email <user.primary_email>`).
+
+    Default: not set.
+
+.. _user.primary_email:
+
+user.primary\_email
+    Your primary email address.
+
+    Default: ``$EMAIL`` variable if set, otherwise constructed from
+    the username and hostname of the current machine.
+
 FILES
 =====
 
-- 
2.34.1

[PATCH 2/4] doc: add configuration section to notmuch-new(1)

[David Bremner]

Increase discoverability.
---
 doc/man1/notmuch-config.rst | 10 ++++++++++
 doc/man1/notmuch-new.rst    | 10 ++++++++++
 2 files changed, 20 insertions(+)

diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst
index 8ddfc1d6..84a9e023 100644
--- a/doc/man1/notmuch-config.rst
+++ b/doc/man1/notmuch-config.rst
@@ -102,6 +102,8 @@ database.path
 
     Default: see :ref:`database`
 
+.. _index.decrypt:
+
 index.decrypt
     Policy for decrypting encrypted messages during indexing.  Must be
     one of: ``false``, ``auto``, ``nostash``, or ``true``.
@@ -155,6 +157,8 @@ index.decrypt
 
     Default: ``auto``.
 
+.. _index.header:
+
 index.header.<prefix>
     Define the query prefix <prefix>, based on a mail header. For
     example ``index.header.List=List-Id`` will add a probabilistic
@@ -164,6 +168,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:
+
 maildir.synchronize\_flags
     If true, then the following maildir flags (in message filenames)
     will be synchronized with the corresponding notmuch tags:
@@ -197,6 +203,8 @@ maildir.synchronize\_flags
 
     Default: ``true``.
 
+.. _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:
@@ -215,6 +223,8 @@ new.ignore
 
     Default: empty list.
 
+.. _new.tags:
+
 new.tags
     A list of tags that will be added to all messages incorporated by
     **notmuch new**.
diff --git a/doc/man1/notmuch-new.rst b/doc/man1/notmuch-new.rst
index 9cb4a54e..398f8813 100644
--- a/doc/man1/notmuch-new.rst
+++ b/doc/man1/notmuch-new.rst
@@ -78,6 +78,16 @@ Supported options for **new** include
    to optimize the scanning of directories for new mail. This option turns
    that optimization off.
 
+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
+:any:`notmuch-config(1)` for details.
+
 EXIT STATUS
 ===========
 
-- 
2.34.1

[PATCH 3/4] doc: add configuration section to notmuch-insert(1)

[David Bremner]

This is partially redudant given some existing cross references, but
it is useful to have all of the config keys listed in one place, to
help keep track of them if nothing else.
---
 doc/man1/notmuch-insert.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/doc/man1/notmuch-insert.rst b/doc/man1/notmuch-insert.rst
index da9ca791..8d91d62a 100644
--- a/doc/man1/notmuch-insert.rst
+++ b/doc/man1/notmuch-insert.rst
@@ -88,6 +88,16 @@ Supported options for **insert** include
 
    See also ``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
+:any:`notmuch-config(1)` for details.
+
 EXIT STATUS
 ===========
 
-- 
2.34.1

[PATCH 4/4] doc: use hyperlinks for config options in notmuch-insert(1)

[David Bremner]

The tradeoff is no bold/italic in the man pages to get actual
hyperlinks in the html output.
---
 doc/man1/notmuch-config.rst | 2 ++
 doc/man1/notmuch-insert.rst | 6 +++---
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst
index 84a9e023..acc5ecec 100644
--- a/doc/man1/notmuch-config.rst
+++ b/doc/man1/notmuch-config.rst
@@ -85,6 +85,8 @@ database.hook_dir
 
     Default: See HOOKS, below.
 
+.. _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
diff --git a/doc/man1/notmuch-insert.rst b/doc/man1/notmuch-insert.rst
index 8d91d62a..fe2bf26b 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
-**database.mail_root**, then incorporates the message into the notmuch
+:ref:`database.mail_root <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
-**new.tags** configuration option, then by operations specified on the
+:ref:`new.tags <new.tags>` configuration option, then by operations specified on the
 command-line: tags prefixed by '+' are added while those prefixed by '-'
 are removed.
 
@@ -86,7 +86,7 @@ Supported options for **insert** include
    ``--decrypt=nostash`` without considering the security of your
    index.
 
-   See also ``index.decrypt`` in :any:`notmuch-config(1)`.
+   See also :ref:`index.decrypt <index.decrypt>` in :any:`notmuch-config(1)`.
 
 CONFIGURATION
 =============
-- 
2.34.1