doc: cross-reference notmuch man pages with actual links

Add internal hyperlink targets for man pages and cross-reference them
using the any role reference. There are a number of alternatives to
accomplish this, but this seems like the combination that retains the
man page section number and the same boldface style in the man pages.

As a bonus, we get sanity checking on the links; for example
notmuch-search-terms.rst had a reference to notmuch-properties(1)
i.e. the wrong section.

The obvious semantic follow-up change would be to only have meaningful
"see also" references instead of having them all everywhere.

15 files changed, 286 insertions, 248 deletions

diff --git a/doc/man1/notmuch-address.rst b/doc/man1/notmuch-address.rst
index 9193aefe..9eae65cb 100644
--- a/doc/man1/notmuch-address.rst
+++ b/doc/man1/notmuch-address.rst
@@ -1,3 +1,5 @@
+.. _notmuch-address(1):
+
 ===============
 notmuch-address
 ===============
@@ -13,7 +15,7 @@ DESCRIPTION
 Search for messages matching the given search terms, and display the
 addresses from them. Duplicate addresses are filtered out.
 
-See **notmuch-search-terms(7)** for details of the supported syntax for
+See :any:`notmuch-search-terms(7)` for details of the supported syntax for
 <search-terms>.
 
 Supported options for **address** include
@@ -26,7 +28,7 @@ Supported options for **address** include
 
 ``--format-version=N``
     Use the specified structured output format version. This is
-    intended for programs that invoke **notmuch(1)** internally. If
+    intended for programs that invoke :any:`notmuch(1)` internally. If
     omitted, the latest supported version will be used.
 
 ``--output=(sender|recipients|count|address)``
@@ -116,16 +118,16 @@ This command supports the following special exit status codes
 SEE ALSO
 ========
 
-**notmuch(1)**,
-**notmuch-config(1)**,
-**notmuch-count(1)**,
-**notmuch-dump(1)**,
-**notmuch-hooks(5)**,
-**notmuch-insert(1)**,
-**notmuch-new(1)**,
-**notmuch-reply(1)**,
-**notmuch-restore(1)**,
-**notmuch-search-terms(7)**,
-**notmuch-show(1)**,
-**notmuch-tag(1)**,
-**notmuch-search(1)**
+:any:`notmuch(1)`,
+:any:`notmuch-config(1)`,
+:any:`notmuch-count(1)`,
+:any:`notmuch-dump(1)`,
+:any:`notmuch-hooks(5)`,
+:any:`notmuch-insert(1)`,
+:any:`notmuch-new(1)`,
+:any:`notmuch-reply(1)`,
+:any:`notmuch-restore(1)`,
+:any:`notmuch-search(1)`,
+:any:`notmuch-search-terms(7)`,
+:any:`notmuch-show(1)`,
+:any:`notmuch-tag(1)`
diff --git a/doc/man1/notmuch-compact.rst b/doc/man1/notmuch-compact.rst
index b05593ec..85f611bf 100644
--- a/doc/man1/notmuch-compact.rst
+++ b/doc/man1/notmuch-compact.rst
@@ -1,3 +1,5 @@
+.. _notmuch-compact(1):
+
 ===============
 notmuch-compact
 ===============
@@ -46,15 +48,15 @@ of notmuch.
 SEE ALSO
 ========
 
-**notmuch(1)**,
-**notmuch-count(1)**,
-**notmuch-dump(1)**,
-**notmuch-hooks(5)**,
-**notmuch-insert(1)**,
-**notmuch-new(1)**,
-**notmuch-reply(1)**,
-**notmuch-restore(1)**,
-**notmuch-search(1)**,
-**notmuch-search-terms(7)**,
-**notmuch-show(1)**,
-**notmuch-tag(1)**
+:any:`notmuch(1)`,
+:any:`notmuch-count(1)`,
+:any:`notmuch-dump(1)`,
+:any:`notmuch-hooks(5)`,
+:any:`notmuch-insert(1)`,
+:any:`notmuch-new(1)`,
+:any:`notmuch-reply(1)`,
+:any:`notmuch-restore(1)`,
+:any:`notmuch-search(1)`,
+:any:`notmuch-search-terms(7)`,
+:any:`notmuch-show(1)`,
+:any:`notmuch-tag(1)`
diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst
index 75c59ff9..5c980a8a 100644
--- a/doc/man1/notmuch-config.rst
+++ b/doc/man1/notmuch-config.rst
@@ -1,3 +1,5 @@
+.. _notmuch-config(1):
+
 ==============
 notmuch-config
 ==============
@@ -76,7 +78,7 @@ paths are presumed relative to `$HOME` for items in section
 **database.hook_dir**
 
     Directory containing hooks run by notmuch commands. See
-    **notmuch-hooks(5)**.
+    :any:`notmuch-hooks(5)`.
 
 **user.name**
     Your full name.
@@ -103,7 +105,7 @@ paths are presumed relative to `$HOME` for items in section
 
 **new.ignore**
     A list to specify files and directories that will not be searched
-    for messages by **notmuch new**. Each entry in the list is either:
+    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.
@@ -124,7 +126,7 @@ paths are presumed relative to `$HOME` for items in section
     default. Using an excluded tag in a query will override that
     exclusion.
 
-    Default: empty list. Note that **notmuch-setup(1)** puts
+    Default: empty list. Note that :any:`notmuch-setup(1)` puts
     ``deleted;spam`` here when creating new configuration file.
 
 **maildir.synchronize\_flags**
@@ -145,16 +147,18 @@ paths are presumed relative to `$HOME` for items in section
     | S      | unread (added when 'S' flag is not present)   |
     +--------+-----------------------------------------------+
 
-    The **notmuch new** command will notice flag changes in filenames
-    and update tags, while the **notmuch tag** and **notmuch restore**
-    commands will notice tag changes and update flags in filenames.
+    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 **notmuch new** before **notmuch tag** or
-    **notmuch restore** 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.
+    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``.
 
@@ -174,8 +178,8 @@ paths are presumed relative to `$HOME` for items in section
     ``nostash`` is the same as ``true`` except that it will not stash
     newly-discovered session keys in the database.
 
-    From the command line (i.e. during **notmuch-new(1)**,
-    **notmuch-insert(1)**, or **notmuch-reindex(1)**), the user can
+    From the command line (i.e. during :any:`notmuch-new(1)`,
+    :any:`notmuch-insert(1)`, or :any:`notmuch-reindex(1)`), the user can
     override the database's stored decryption policy with the
     ``--decrypt=`` option.
 
@@ -199,7 +203,7 @@ paths are presumed relative to `$HOME` for items in section
 
     Stashed session keys are kept in the database as properties
     associated with the message.  See ``session-key`` in
-    **notmuch-properties(7)** for more details about how they can be
+    :any:`notmuch-properties(7)` for more details about how they can be
     useful.
 
     Be aware that the notmuch index is likely sufficient (and a
@@ -217,7 +221,7 @@ paths are presumed relative to `$HOME` for items in section
     prefix ``List:`` that searches the ``List-Id`` field.  User
     defined prefixes must not start with 'a'...'z'; in particular
     adding a prefix with same name as a predefined prefix is not
-    supported. See **notmuch-search-terms(7)** for a list of existing
+    supported. See :any:`notmuch-search-terms(7)` for a list of existing
     prefixes, and an explanation of probabilistic prefixes.
 
 **built_with.<name>**
@@ -228,7 +232,7 @@ paths are presumed relative to `$HOME` for items in section
 
 **query.<name>**
     Expansion for named query called <name>. See
-    **notmuch-search-terms(7)** for more information about named
+    :any:`notmuch-search-terms(7)` for more information about named
     queries.
 
 ENVIRONMENT
@@ -268,16 +272,16 @@ If ``database.hook_dir`` is unset, notmuch tries (in order)
 SEE ALSO
 ========
 
-**notmuch(1)**,
-**notmuch-count(1)**,
-**notmuch-dump(1)**,
-**notmuch-hooks(5)**,
-**notmuch-insert(1)**,
-**notmuch-new(1)**,
-**notmuch-reply(1)**,
-**notmuch-restore(1)**,
-**notmuch-search(1)**,
-**notmuch-search-terms(7)**,
-**notmuch-properties(7)**,
-**notmuch-show(1)**,
-**notmuch-tag(1)**
+:any:`notmuch(1)`,
+:any:`notmuch-count(1)`,
+:any:`notmuch-dump(1)`,
+:any:`notmuch-hooks(5)`,
+:any:`notmuch-insert(1)`,
+:any:`notmuch-new(1)`,
+:any:`notmuch-properties(7)`,
+:any:`notmuch-reply(1)`,
+:any:`notmuch-restore(1)`,
+:any:`notmuch-search(1)`,
+:any:`notmuch-search-terms(7)`,
+:any:`notmuch-show(1)`,
+:any:`notmuch-tag(1)`
diff --git a/doc/man1/notmuch-count.rst b/doc/man1/notmuch-count.rst
index 0eac5dbe..61686d35 100644
--- a/doc/man1/notmuch-count.rst
+++ b/doc/man1/notmuch-count.rst
@@ -1,3 +1,5 @@
+.. _notmuch-count(1):
+
 =============
 notmuch-count
 =============
@@ -17,7 +19,7 @@ The number of matching messages (or threads) is output to stdout.
 With no search terms, a count of all messages (or threads) in the
 database will be displayed.
 
-See **notmuch-search-terms(7)** for details of the supported syntax for
+See :any:`notmuch-search-terms(7)` for details of the supported syntax for
 <search-terms>.
 
 Supported options for **count** include
@@ -58,15 +60,15 @@ Supported options for **count** include
 SEE ALSO
 ========
 
-**notmuch(1)**,
-**notmuch-config(1)**,
-**notmuch-dump(1)**,
-**notmuch-hooks(5)**,
-**notmuch-insert(1)**,
-**notmuch-new(1)**,
-**notmuch-reply(1)**,
-**notmuch-restore(1)**,
-**notmuch-search(1)**,
-**notmuch-search-terms(7)**,
-**notmuch-show(1)**,
-**notmuch-tag(1)**
+:any:`notmuch(1)`,
+:any:`notmuch-config(1)`,
+:any:`notmuch-dump(1)`,
+:any:`notmuch-hooks(5)`,
+:any:`notmuch-insert(1)`,
+:any:`notmuch-new(1)`,
+:any:`notmuch-reply(1)`,
+:any:`notmuch-restore(1)`,
+:any:`notmuch-search(1)`,
+:any:`notmuch-search-terms(7)`,
+:any:`notmuch-show(1)`,
+:any:`notmuch-tag(1)`
diff --git a/doc/man1/notmuch-dump.rst b/doc/man1/notmuch-dump.rst
index 0a7a2387..57c46297 100644
--- a/doc/man1/notmuch-dump.rst
+++ b/doc/man1/notmuch-dump.rst
@@ -1,3 +1,5 @@
+.. _notmuch-dump(1):
+
 ============
 notmuch-dump
 ============
@@ -19,7 +21,7 @@ recreated from the messages themselves. The output of notmuch dump is
 therefore the only critical thing to backup (and much more friendly to
 incremental backup than the native database files.)
 
-See **notmuch-search-terms(7)** for details of the supported syntax
+See :any:`notmuch-search-terms(7)` for details of the supported syntax
 for <search-terms>. With no search terms, a dump of all messages in
 the database will be generated. A ``--`` argument instructs notmuch that
 the remaining arguments are search terms.
@@ -49,15 +51,15 @@ Supported options for **dump** include
         quote, it must be enclosed in double quotes and double quotes
         inside the ID must be doubled. The astute reader will notice
         this is a special case of the batch input format for
-        **notmuch-tag(1)**; note that the single message-id query is
-        mandatory for **notmuch-restore(1)**.
+        :any:`notmuch-tag(1)`; note that the single message-id query is
+        mandatory for :any:`notmuch-restore(1)`.
 
     **sup**
         The **sup** dump file format is specifically chosen to be
         compatible with the format of files produced by
         :manpage:`sup-dump(1)`. So if you've previously been using sup
-        for mail, then the **notmuch restore** command provides you a
-        way to import all of your tags (or labels as sup calls
+        for mail, then the :any:`notmuch-restore(1)` command provides
+        you a way to import all of your tags (or labels as sup calls
         them). Each line has the following form::
 
           <*message-id*\ > **(** <*tag*\ > ... **)**
@@ -79,7 +81,7 @@ Supported options for **dump** include
         Output per-message (key,value) metadata.  Each line starts
         with "#= ", followed by a message id, and a space separated
         list of key=value pairs.  Ids, keys and values are hex encoded
-        if needed.  See **notmuch-properties(7)** for more details.
+        if needed.  See :any:`notmuch-properties(7)` for more details.
 
     **tags**
         Output per-message boolean metadata, namely tags. See *format* above
@@ -100,16 +102,16 @@ Supported options for **dump** include
 SEE ALSO
 ========
 
-**notmuch(1)**,
-**notmuch-config(1)**,
-**notmuch-count(1)**,
-**notmuch-hooks(5)**,
-**notmuch-insert(1)**,
-**notmuch-new(1)**,
-**notmuch-properties(7)**,
-**notmuch-reply(1)**,
-**notmuch-restore(1)**,
-**notmuch-search(1)**,
-**notmuch-search-terms(7)**,
-**notmuch-show(1)**,
-**notmuch-tag(1)**
+:any:`notmuch(1)`,
+:any:`notmuch-config(1)`,
+:any:`notmuch-count(1)`,
+:any:`notmuch-hooks(5)`,
+:any:`notmuch-insert(1)`,
+:any:`notmuch-new(1)`,
+:any:`notmuch-properties(7)`,
+:any:`notmuch-reply(1)`,
+:any:`notmuch-restore(1)`,
+:any:`notmuch-search(1)`,
+:any:`notmuch-search-terms(7)`,
+:any:`notmuch-show(1)`,
+:any:`notmuch-tag(1)`
diff --git a/doc/man1/notmuch-emacs-mua.rst b/doc/man1/notmuch-emacs-mua.rst
index a1e65edd..a599b6eb 100644
--- a/doc/man1/notmuch-emacs-mua.rst
+++ b/doc/man1/notmuch-emacs-mua.rst
@@ -1,3 +1,5 @@
+.. _notmuch-emacs-mua(1):
+
 =================
 notmuch-emacs-mua
 =================
@@ -79,6 +81,6 @@ ENVIRONMENT VARIABLES
 SEE ALSO
 ========
 
-**notmuch(1)**,
+:any:`notmuch(1)`,
 :manpage:`emacsclient(1)`,
 :manpage:`mutt(1)`
diff --git a/doc/man1/notmuch-insert.rst b/doc/man1/notmuch-insert.rst
index 86e2f567..67adf225 100644
--- a/doc/man1/notmuch-insert.rst
+++ b/doc/man1/notmuch-insert.rst
@@ -1,3 +1,5 @@
+.. _notmuch-insert(1):
+
 ==============
 notmuch-insert
 ==============
@@ -14,7 +16,7 @@ DESCRIPTION
 into the maildir directory given by configuration option
 **database.path**, then incorporates the message into the notmuch
 database. It is an alternative to using a separate tool to deliver the
-message then running **notmuch new** afterwards.
+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
@@ -25,7 +27,7 @@ If the new message is a duplicate of an existing message in the database
 (it has same Message-ID), it will be added to the maildir folder and
 notmuch database, but the tags will not be changed.
 
-The **insert** command supports hooks. See **notmuch-hooks(5)** for
+The **insert** command supports hooks. See :any:`notmuch-hooks(5)` for
 more details on hooks.
 
 Option arguments must appear before any tag operation arguments.
@@ -76,7 +78,7 @@ Supported options for **insert** include
     ``--decrypt=nostash`` without considering the security of your
     index.
 
-    See also ``index.decrypt`` in **notmuch-config(1)**.
+    See also ``index.decrypt`` in :any:`notmuch-config(1)`.
 
 EXIT STATUS
 ===========
@@ -101,14 +103,14 @@ status of the **insert** command.
 SEE ALSO
 ========
 
-**notmuch(1)**,
-**notmuch-config(1)**,
-**notmuch-count(1)**,
-**notmuch-dump(1)**,
-**notmuch-hooks(5)**,
-**notmuch-reply(1)**,
-**notmuch-restore(1)**,
-**notmuch-search(1)**,
-**notmuch-search-terms(7)**,
-**notmuch-show(1)**,
-**notmuch-tag(1)**
+:any:`notmuch(1)`,
+:any:`notmuch-config(1)`,
+:any:`notmuch-count(1)`,
+:any:`notmuch-dump(1)`,
+:any:`notmuch-hooks(5)`,
+:any:`notmuch-reply(1)`,
+:any:`notmuch-restore(1)`,
+:any:`notmuch-search(1)`,
+:any:`notmuch-search-terms(7)`,
+:any:`notmuch-show(1)`,
+:any:`notmuch-tag(1)`
diff --git a/doc/man1/notmuch-new.rst b/doc/man1/notmuch-new.rst
index 20a1103b..1044d1cd 100644
--- a/doc/man1/notmuch-new.rst
+++ b/doc/man1/notmuch-new.rst
@@ -1,3 +1,5 @@
+.. _notmuch-new(1):
+
 ===========
 notmuch-new
 ===========
@@ -17,22 +19,23 @@ performing full-text indexing on new messages that are found. Each new
 message will automatically be tagged with both the **inbox** and
 **unread** tags.
 
-You should run **notmuch new** once after first running **notmuch
-setup** to create the initial database. The first run may take a long
-time if you have a significant amount of mail (several hundred thousand
-messages or more). Subsequently, you should run **notmuch new** whenever
-new mail is delivered and you wish to incorporate it into the database.
-These subsequent runs will be much quicker than the initial run.
+You should run **notmuch new** once after first running
+:any:`notmuch-setup(1)` to create the initial database. The first run
+may take a long time if you have a significant amount of mail (several
+hundred thousand messages or more). Subsequently, you should run
+**notmuch new** whenever new mail is delivered and you wish to
+incorporate it into the database.  These subsequent runs will be much
+quicker than the initial run.
 
 Invoking ``notmuch`` with no command argument will run **new** if
-**notmuch setup** has previously been completed, but **notmuch new** has
-not previously been run.
+:any:`notmuch-setup(1)` has previously been completed, but **notmuch
+new** has not previously been run.
 
 **notmuch new** updates tags according to maildir flag changes if the
 **maildir.synchronize\_flags** configuration option is enabled. See
-**notmuch-config(1)** for details.
+:any:`notmuch-config(1)` for details.
 
-The **new** command supports hooks. See **notmuch-hooks(5)** for more
+The **new** command supports hooks. See :any:`notmuch-hooks(5)` for more
 details on hooks.
 
 Supported options for **new** include
@@ -61,7 +64,7 @@ Supported options for **new** include
     ``--decrypt=nostash`` without considering the security of your
     index.
 
-    See also ``index.decrypt`` in **notmuch-config(1)**.
+    See also ``index.decrypt`` in :any:`notmuch-config(1)`.
 
 ``--full-scan``
     By default notmuch-new uses directory modification times (mtimes)
@@ -79,15 +82,15 @@ This command supports the following special exit status code
 SEE ALSO
 ========
 
-**notmuch(1)**,
-**notmuch-config(1)**,
-**notmuch-count(1)**,
-**notmuch-dump(1)**,
-**notmuch-hooks(5)**,
-**notmuch-insert(1)**,
-**notmuch-reply(1)**,
-**notmuch-restore(1)**,
-**notmuch-search(1)**,
-**notmuch-search-terms(7)**,
-**notmuch-show(1)**,
-**notmuch-tag(1)**
+:any:`notmuch(1)`,
+:any:`notmuch-config(1)`,
+:any:`notmuch-count(1)`,
+:any:`notmuch-dump(1)`,
+:any:`notmuch-hooks(5)`,
+:any:`notmuch-insert(1)`,
+:any:`notmuch-reply(1)`,
+:any:`notmuch-restore(1)`,
+:any:`notmuch-search(1)`,
+:any:`notmuch-search-terms(7)`,
+:any:`notmuch-show(1)`,
+:any:`notmuch-tag(1)`
diff --git a/doc/man1/notmuch-reindex.rst b/doc/man1/notmuch-reindex.rst
index cd7c91a0..359def7e 100644
--- a/doc/man1/notmuch-reindex.rst
+++ b/doc/man1/notmuch-reindex.rst
@@ -1,3 +1,5 @@
+.. _notmuch-reindex(1):
+
 ===============
 notmuch-reindex
 ===============
@@ -12,7 +14,7 @@ DESCRIPTION
 
 Re-index all messages matching the search terms.
 
-See **notmuch-search-terms(7)** for details of the supported syntax for
+See :any:`notmuch-search-terms(7)` for details of the supported syntax for
 <*search-term*\ >.
 
 The **reindex** command searches for all messages matching the
@@ -42,7 +44,7 @@ Supported options for **reindex** include
     ``--decrypt=nostash`` without considering the security of your
     index.
 
-    See also ``index.decrypt`` in **notmuch-config(1)**.
+    See also ``index.decrypt`` in :any:`notmuch-config(1)`.
 
 EXAMPLES
 ========
@@ -84,17 +86,17 @@ https://trac.xapian.org/ticket/742:
 SEE ALSO
 ========
 
-**notmuch(1)**,
-**notmuch-compact(1)**,
-**notmuch-config(1)**,
-**notmuch-count(1)**,
-**notmuch-dump(1)**,
-**notmuch-hooks(5)**,
-**notmuch-insert(1)**,
-**notmuch-new(1)**,
-**notmuch-reply(1)**,
-**notmuch-restore(1)**,
-**notmuch-search(1)**,
-**notmuch-search-terms(7)**,
-**notmuch-show(1)**,
-**notmuch-tag(1)**
+:any:`notmuch(1)`,
+:any:`notmuch-compact(1)`,
+:any:`notmuch-config(1)`,
+:any:`notmuch-count(1)`,
+:any:`notmuch-dump(1)`,
+:any:`notmuch-hooks(5)`,
+:any:`notmuch-insert(1)`,
+:any:`notmuch-new(1)`,
+:any:`notmuch-reply(1)`,
+:any:`notmuch-restore(1)`,
+:any:`notmuch-search(1)`,
+:any:`notmuch-search-terms(7)`,
+:any:`notmuch-show(1)`,
+:any:`notmuch-tag(1)`
diff --git a/doc/man1/notmuch-reply.rst b/doc/man1/notmuch-reply.rst
index b1c3590b..168c399c 100644
--- a/doc/man1/notmuch-reply.rst
+++ b/doc/man1/notmuch-reply.rst
@@ -1,3 +1,5 @@
+.. _notmuch-reply(1):
+
 =============
 notmuch-reply
 =============
@@ -56,7 +58,7 @@ Supported options for **reply** include
 
 ``--format-version=N``
     Use the specified structured output format version. This is
-    intended for programs that invoke **notmuch(1)** internally. If
+    intended for programs that invoke :any:`notmuch(1)` internally. If
     omitted, the latest supported version will be used.
 
 ``--reply-to=``\ (**all**\ \|\ **sender**)
@@ -91,7 +93,7 @@ Supported options for **reply** include
 
     Default: ``auto``
 
-See **notmuch-search-terms(7)** for details of the supported syntax for
+See :any:`notmuch-search-terms(7)` for details of the supported syntax for
 <search-terms>.
 
 Note: It is most common to use **notmuch reply** with a search string
@@ -116,15 +118,15 @@ This command supports the following special exit status codes
 SEE ALSO
 ========
 
-**notmuch(1)**,
-**notmuch-config(1)**,
-**notmuch-count(1)**,
-**notmuch-dump(1)**,
-**notmuch-hooks(5)**,
-**notmuch-insert(1)**,
-**notmuch-new(1)**,
-**notmuch-restore(1)**,
-**notmuch-search(1)**,
-**notmuch-search-terms(7)**,
-**notmuch-show(1)**,
-**notmuch-tag(1)**
+:any:`notmuch(1)`,
+:any:`notmuch-config(1)`,
+:any:`notmuch-count(1)`,
+:any:`notmuch-dump(1)`,
+:any:`notmuch-hooks(5)`,
+:any:`notmuch-insert(1)`,
+:any:`notmuch-new(1)`,
+:any:`notmuch-restore(1)`,
+:any:`notmuch-search(1)`,
+:any:`notmuch-search-terms(7)`,
+:any:`notmuch-show(1)`,
+:any:`notmuch-tag(1)`
diff --git a/doc/man1/notmuch-restore.rst b/doc/man1/notmuch-restore.rst
index e7d68c08..7be34854 100644
--- a/doc/man1/notmuch-restore.rst
+++ b/doc/man1/notmuch-restore.rst
@@ -1,3 +1,5 @@
+.. _notmuch-restore(1):
+
 ===============
 notmuch-restore
 ===============
@@ -10,7 +12,7 @@ SYNOPSIS
 DESCRIPTION
 ===========
 
-Restores the tags from the given file (see **notmuch dump**).
+Restores the tags from the given file (see :any:`notmuch-dump(1)`).
 
 The input is read from the given filename, if any, or from stdin.
 
@@ -24,7 +26,7 @@ Supported options for **restore** include
 ``--format=(sup|batch-tag|auto)``
     Notmuch restore supports two plain text dump formats, with each
     line specifying a message-id and a set of tags. For details of the
-    actual formats, see **notmuch-dump(1)**.
+    actual formats, see :any:`notmuch-dump(1)`.
 
     **sup**
         The **sup** dump file format is specifically chosen to be
@@ -36,12 +38,12 @@ Supported options for **restore** include
     **batch-tag**
         The **batch-tag** dump format is intended to more robust
         against malformed message-ids and tags containing whitespace
-        or non-\ **ascii(7)** characters. See **notmuch-dump(1)** for
+        or non-\ **ascii(7)** characters. See :any:`notmuch-dump(1)` for
         details on this format.
 
         **notmuch restore** updates the maildir flags according to tag
         changes if the **maildir.synchronize\_flags** configuration
-        option is enabled. See **notmuch-config(1)** for details.
+        option is enabled. See :any:`notmuch-config(1)` for details.
 
     **auto**
         This option (the default) tries to guess the format from the
@@ -61,7 +63,7 @@ Supported options for **restore** include
         Restore per-message (key,value) metadata.  Each line starts
         with "#= ", followed by a message id, and a space separated
         list of key=value pairs.  Ids, keys and values are hex encoded
-        if needed.  See **notmuch-properties(7)** for more details.
+        if needed.  See :any:`notmuch-properties(7)` for more details.
 
     **tags**
         Restore per-message metadata, namely tags. See *format* above
@@ -84,16 +86,16 @@ particular works for standard input.
 SEE ALSO
 ========
 
-**notmuch(1)**,
-**notmuch-config(1)**,
-**notmuch-count(1)**,
-**notmuch-dump(1)**,
-**notmuch-hooks(5)**,
-**notmuch-insert(1)**,
-**notmuch-new(1)**,
-**notmuch-properties(7)**,
-**notmuch-reply(1)**,
-**notmuch-search(1)**,
-**notmuch-search-terms(7)**,
-**notmuch-show(1)**,
-**notmuch-tag(1)**
+:any:`notmuch(1)`,
+:any:`notmuch-config(1)`,
+:any:`notmuch-count(1)`,
+:any:`notmuch-dump(1)`,
+:any:`notmuch-hooks(5)`,
+:any:`notmuch-insert(1)`,
+:any:`notmuch-new(1)`,
+:any:`notmuch-properties(7)`,
+:any:`notmuch-reply(1)`,
+:any:`notmuch-search(1)`,
+:any:`notmuch-search-terms(7)`,
+:any:`notmuch-show(1)`,
+:any:`notmuch-tag(1)`
diff --git a/doc/man1/notmuch-search.rst b/doc/man1/notmuch-search.rst
index ee9d4118..689f027a 100644
--- a/doc/man1/notmuch-search.rst
+++ b/doc/man1/notmuch-search.rst
@@ -1,3 +1,5 @@
+.. _notmuch-search(1):
+
 ==============
 notmuch-search
 ==============
@@ -19,7 +21,7 @@ in the thread, the number of matched messages and total messages in the
 thread, the names of all participants in the thread, and the subject of
 the newest (or oldest) message.
 
-See **notmuch-search-terms(7)** for details of the supported syntax for
+See :any:`notmuch-search-terms(7)` for details of the supported syntax for
 <search-terms>.
 
 Supported options for **search** include
@@ -32,7 +34,7 @@ Supported options for **search** include
 
 ``--format-version=N``
     Use the specified structured output format version. This is
-    intended for programs that invoke **notmuch(1)** internally. If
+    intended for programs that invoke :any:`notmuch(1)` internally. If
     omitted, the latest supported version will be used.
 
 ``--output=(summary|threads|messages|files|tags)``
@@ -164,16 +166,16 @@ This command supports the following special exit status codes
 SEE ALSO
 ========
 
-**notmuch(1)**,
-**notmuch-config(1)**,
-**notmuch-count(1)**,
-**notmuch-dump(1)**,
-**notmuch-hooks(5)**,
-**notmuch-insert(1)**,
-**notmuch-new(1)**,
-**notmuch-reply(1)**,
-**notmuch-restore(1)**,
-**notmuch-search-terms(7)**,
-**notmuch-show(1)**,
-**notmuch-tag(1)**
-**notmuch-address(1)**
+:any:`notmuch(1)`,
+:any:`notmuch-address(1)`
+:any:`notmuch-config(1)`,
+:any:`notmuch-count(1)`,
+:any:`notmuch-dump(1)`,
+:any:`notmuch-hooks(5)`,
+:any:`notmuch-insert(1)`,
+:any:`notmuch-new(1)`,
+:any:`notmuch-reply(1)`,
+:any:`notmuch-restore(1)`,
+:any:`notmuch-search-terms(7)`,
+:any:`notmuch-show(1)`,
+:any:`notmuch-tag(1)`
diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst
index c2130e47..1291884f 100644
--- a/doc/man1/notmuch-show.rst
+++ b/doc/man1/notmuch-show.rst
@@ -1,3 +1,5 @@
+.. _notmuch-show(1):
+
 ============
 notmuch-show
 ============
@@ -12,7 +14,7 @@ DESCRIPTION
 
 Shows all messages matching the search terms.
 
-See **notmuch-search-terms(7)** for details of the supported syntax for
+See :any:`notmuch-search-terms(7)` for details of the supported syntax for
 <search-terms>.
 
 The messages will be grouped and sorted based on the threading (all
@@ -90,7 +92,7 @@ Supported options for **show** include
 
 ``--format-version=N``
     Use the specified structured output format version. This is
-    intended for programs that invoke **notmuch(1)** internally. If
+    intended for programs that invoke :any:`notmuch(1)` internally. If
     omitted, the latest supported version will be used.
 
 ``--part=N``
@@ -190,9 +192,10 @@ Supported options for **show** include
     "text/html" parts, no part with content type "text/html" is included
     in the output.
 
-A common use of **notmuch show** is to display a single thread of email
-messages. For this, use a search term of "thread:<thread-id>" as can be
-seen in the first column of output from the **notmuch search** command.
+A common use of **notmuch show** is to display a single thread of
+email messages. For this, use a search term of "thread:<thread-id>" as
+can be seen in the first column of output from the
+:any:`notmuch-search(1)` command.
 
 EXIT STATUS
 ===========
@@ -208,15 +211,15 @@ This command supports the following special exit status codes
 SEE ALSO
 ========
 
-**notmuch(1)**,
-**notmuch-config(1)**,
-**notmuch-count(1)**,
-**notmuch-dump(1)**,
-**notmuch-hooks(5)**,
-**notmuch-insert(1)**,
-**notmuch-new(1)**,
-**notmuch-reply(1)**,
-**notmuch-restore(1)**,
-**notmuch-search(1)**,
-**notmuch-search-terms(7)**,
-**notmuch-tag(1)**
+:any:`notmuch(1)`,
+:any:`notmuch-config(1)`,
+:any:`notmuch-count(1)`,
+:any:`notmuch-dump(1)`,
+:any:`notmuch-hooks(5)`,
+:any:`notmuch-insert(1)`,
+:any:`notmuch-new(1)`,
+:any:`notmuch-reply(1)`,
+:any:`notmuch-restore(1)`,
+:any:`notmuch-search(1)`,
+:any:`notmuch-search-terms(7)`,
+:any:`notmuch-tag(1)`
diff --git a/doc/man1/notmuch-tag.rst b/doc/man1/notmuch-tag.rst
index c2324f5a..1da876c5 100644
--- a/doc/man1/notmuch-tag.rst
+++ b/doc/man1/notmuch-tag.rst
@@ -1,3 +1,5 @@
+.. _notmuch-tag(1):
+
 ===========
 notmuch-tag
 ===========
@@ -14,7 +16,7 @@ DESCRIPTION
 
 Add/remove tags for all messages matching the search terms.
 
-See **notmuch-search-terms(7)** for details of the supported syntax for
+See :any:`notmuch-search-terms(7)` for details of the supported syntax for
 <*search-term*\ >.
 
 Tags prefixed by '+' are added while those prefixed by '-' are removed.
@@ -28,7 +30,7 @@ beginning with '+' or '-' is provided by allowing the user to specify a
 
 **notmuch tag** updates the maildir flags according to tag changes if
 the **maildir.synchronize\_flags** configuration option is enabled. See
-**notmuch-config(1)** for details.
+:any:`notmuch-config(1)` for details.
 
 Supported options for **tag** include
 
@@ -100,15 +102,15 @@ of the tag **space in tags**
 SEE ALSO
 ========
 
-**notmuch(1)**,
-**notmuch-config(1)**,
-**notmuch-count(1)**,
-**notmuch-dump(1)**,
-**notmuch-hooks(5)**,
-**notmuch-insert(1)**,
-**notmuch-new(1)**,
-**notmuch-reply(1)**,
-**notmuch-restore(1)**,
-**notmuch-search(1)**,
-**notmuch-search-terms(7)**,
-**notmuch-show(1)**,
+:any:`notmuch(1)`,
+:any:`notmuch-config(1)`,
+:any:`notmuch-count(1)`,
+:any:`notmuch-dump(1)`,
+:any:`notmuch-hooks(5)`,
+:any:`notmuch-insert(1)`,
+:any:`notmuch-new(1)`,
+:any:`notmuch-reply(1)`,
+:any:`notmuch-restore(1)`,
+:any:`notmuch-search(1)`,
+:any:`notmuch-search-terms(7)`,
+:any:`notmuch-show(1)`,
diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst
index 7fdcc9dd..7b84ef44 100644
--- a/doc/man1/notmuch.rst
+++ b/doc/man1/notmuch.rst
@@ -1,3 +1,6 @@
+.. _notmuch(1):
+.. _notmuch-setup(1):
+
 =======
 notmuch
 =======
@@ -15,8 +18,9 @@ reading, and tagging large collections of email messages.
 
 This page describes how to get started using notmuch from the command
 line, and gives a brief overview of the commands available. For more
-information on e.g. **notmuch show** consult the **notmuch-show(1)** man
-page, also accessible via **notmuch help show**
+information on e.g. **notmuch show** consult the
+:any:`notmuch-show(1)` man page, also accessible via **notmuch help
+show**
 
 The quickest way to get started with Notmuch is to simply invoke the
 ``notmuch`` command with no arguments, which will interactively guide
@@ -100,23 +104,25 @@ OTHER COMMANDS
 --------------
 
 Several of the notmuch commands accept search terms with a common
-syntax. See **notmuch-search-terms**\ (7) for more details on the
+syntax. See :any:`notmuch-search-terms(7)` for more details on the
 supported syntax.
 
-The **search**, **show**, **address** and **count** commands are used
-to query the email database.
+The :any:`notmuch-search(1)`, :any:`notmuch-show(1)`,
+:any:`notmuch-address(1)` and :any:`notmuch-count(1)` commands are
+used to query the email database.
 
-The **reply** command is useful for preparing a template for an email
-reply.
+The :any:`notmuch-reply(1)` command is useful for preparing a template
+for an email reply.
 
-The **tag** command is the only command available for manipulating
-database contents.
+The :any:`notmuch-tag(1)` command is the only command available for
+manipulating database contents.
 
-The **dump** and **restore** commands can be used to create a textual
-dump of email tags for backup purposes, and to restore from that dump.
+The :any:`notmuch-dump(1)` and :any:`notmuch-restore(1)` commands can
+be used to create a textual dump of email tags for backup purposes,
+and to restore from that dump.
 
-The **config** command can be used to get or set settings in the notmuch
-configuration file.
+The :any:`notmuch-config(1)` command can be used to get or set
+settings in the notmuch configuration file.
 
 CUSTOM COMMANDS
 ---------------
@@ -163,22 +169,22 @@ of notmuch.
 SEE ALSO
 ========
 
-**notmuch-address(1)**,
-**notmuch-compact(1)**,
-**notmuch-config(1)**,
-**notmuch-count(1)**,
-**notmuch-dump(1)**,
-**notmuch-hooks(5)**,
-**notmuch-insert(1)**,
-**notmuch-new(1)**,
-**notmuch-properties(7)**,
-**notmuch-reindex(1)**,
-**notmuch-reply(1)**,
-**notmuch-restore(1)**,
-**notmuch-search(1)**,
-**notmuch-search-terms(7)**,
-**notmuch-show(1)**,
-**notmuch-tag(1)**
+:any:`notmuch-address(1)`,
+:any:`notmuch-compact(1)`,
+:any:`notmuch-config(1)`,
+:any:`notmuch-count(1)`,
+:any:`notmuch-dump(1)`,
+:any:`notmuch-hooks(5)`,
+:any:`notmuch-insert(1)`,
+:any:`notmuch-new(1)`,
+:any:`notmuch-properties(7)`,
+:any:`notmuch-reindex(1)`,
+:any:`notmuch-reply(1)`,
+:any:`notmuch-restore(1)`,
+:any:`notmuch-search(1)`,
+:any:`notmuch-search-terms(7)`,
+:any:`notmuch-show(1)`,
+:any:`notmuch-tag(1)`
 
 The notmuch website: **https://notmuchmail.org**