doc: use program and option directives to document options

Use the program and option directives to document the subcommand
options. This unifies a lot of option documentation throughout.

This also makes it possible to reference options with :option:`--foo`
(within .. program::) or :option:`subcommand --foo` (globally). This
is left for later work.

See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program

Note: There is a lot of indentation change, but intentionally there is
no reflow. Using 'git diff -w' or 'git show -w' to ignore white space
changes makes this a very easy change to review.

doc/man1/notmuch-address.rst

@@ -20,18 +20,23 @@ See :any:`notmuch-search-terms(7)` for details of the supported syntax for
 
 Supported options for **address** include
 
-``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**)
+.. program:: address
+
+.. option:: --format=(json|sexp|text|text0)
+
    Presents the results in either JSON, S-Expressions, newline
    character separated plain-text (default), or null character
    separated plain-text (compatible with :manpage:`xargs(1)` -0
    option where available).
 
-``--format-version=N``
+.. option:: --format-version=N
+
    Use the specified structured output format version. This is
    intended for programs that invoke :any:`notmuch(1)` internally. If
    omitted, the latest supported version will be used.
 
-``--output=(sender|recipients|count|address)``
+.. option:: --output=(sender|recipients|count|address)
+
    Controls which information appears in the output. This option can
    be given multiple times to combine different outputs.  When
    neither ``--output=sender`` nor ``--output=recipients`` is
@@ -60,7 +65,8 @@ Supported options for **address** include
      with names and email addresses. This option has no effect on
      the JSON or S-Expression output formats.
 
-``--deduplicate=(no|mailbox|address)``
+.. option:: --deduplicate=(no|mailbox|address)
+
    Control the deduplication of results.
 
    **no**
@@ -80,7 +86,8 @@ Supported options for **address** include
      matching messages. If ``--output=count`` is specified, include all
      variants in the count.
 
-``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
+.. option:: --sort=(newest-first|oldest-first)
+
    This option can be used to present results in either chronological
    order (**oldest-first**) or reverse chronological order
    (**newest-first**).
@@ -92,7 +99,8 @@ Supported options for **address** include
    specified, this option is ignored and the order of the results is
    unspecified.
 
-``--exclude=(true|false)``
+.. option:: --exclude=(true|false)
+
    A message is called "excluded" if it matches at least one tag in
    search.exclude\_tags that does not appear explicitly in the search
    terms. This option specifies whether to omit excluded messages in

doc/man1/notmuch-compact.rst

@@ -26,13 +26,17 @@ process (which may be quite long) to protect data integrity.
 
 Supported options for **compact** include
 
-``--backup=``\ <directory>
+.. program:: compact
+
+.. option:: --backup=<directory>
+
    Save the current database to the given directory before replacing
    it with the compacted database. The backup directory must not
    exist and it must reside on the same mounted filesystem as the
    current database.
 
-``--quiet``
+.. option:: --quiet
+
    Do not report database compaction progress to stdout.
 
 SEE ALSO

doc/man1/notmuch-config.rst

@@ -19,12 +19,16 @@ DESCRIPTION
 The **config** command can be used to get or set settings in the notmuch
 configuration file and corresponding database.
 
-**get**
+.. program:: config
+
+.. option:: get
+
    The value of the specified configuration item is printed to
    stdout. If the item has multiple values (it is a list), each value
    is separated by a newline character.
 
-**set**
+.. option:: set
+
    The specified configuration item is set to the given value. To
    specify a multiple-value item (a list), provide each value as a
    separate command-line argument.
@@ -36,7 +40,8 @@ configuration file and corresponding database.
    stored in the database, rather than the default (text)
    configuration file.
 
-**list**
+.. option:: list
+
    Every configuration item is printed to stdout, each on a separate
    line of the form::
 

doc/man1/notmuch-count.rst

@@ -24,7 +24,10 @@ See :any:`notmuch-search-terms(7)` for details of the supported syntax for
 
 Supported options for **count** include
 
-``--output=(messages|threads|files)``
+.. program:: count
+
+.. option:: --output=(messages|threads|files)
+
    **messages**
      Output the number of matching messages. This is the default.
 
@@ -37,23 +40,27 @@ Supported options for **count** include
      messages due to duplicates (i.e. multiple files having the
      same message-id).
 
-``--exclude=(true|false)``
+.. option:: --exclude=(true|false)
+
    Specify whether to omit messages matching search.exclude\_tags from
    the count (the default) or not.
 
-``--batch``
+.. option:: --batch
+
    Read queries from a file (stdin by default), one per line, and
    output the number of matching messages (or threads) to stdout, one
    per line. On an empty input line the count of all messages (or
    threads) in the database will be output. This option is not
    compatible with specifying search terms on the command line.
 
-``--lastmod``
+.. option:: --lastmod
+
    Append lastmod (counter for number of database updates) and UUID
    to the output. lastmod values are only comparable between
    databases with the same UUID.
 
-``--input=``\ <filename>
+.. option:: --input=<filename>
+
    Read input from given file, instead of from stdin. Implies
    ``--batch``.
 

doc/man1/notmuch-dump.rst

@@ -28,10 +28,14 @@ the remaining arguments are search terms.
 
 Supported options for **dump** include
 
-``--gzip``
+.. program:: dump
+
+.. option:: --gzip
+
    Compress the output in a format compatible with :manpage:`gzip(1)`.
 
-``--format=(sup|batch-tag)``
+.. option:: --format=(sup|batch-tag)
+
    Notmuch restore supports two plain text dump formats, both with
    one message-id per line, followed by a list of tags.
 
@@ -69,7 +73,8 @@ Supported options for **dump** include
      characters. Note also that tags with spaces will not be
      correctly restored with this format.
 
-``--include=(config|properties|tags)``
+.. option:: --include=(config|properties|tags)
+
    Control what kind of metadata is included in the output.
 
    **config**
@@ -96,7 +101,8 @@ Supported options for **dump** include
 
    where <*included*> is a comma separated list of the above options.
 
-``--output=``\ <filename>
+.. option:: --output=<filename>
+
    Write output to given file instead of stdout.
 
 SEE ALSO

doc/man1/notmuch-emacs-mua.rst

@@ -17,49 +17,63 @@ subject, recipients, and message body, or mailto: URL.
 
 Supported options for **emacs-mua** include
 
-``-h, --help``
+.. program:: emacs-mua
+
+.. option:: -h, --help
+
    Display help.
 
-``-s, --subject=``\ <subject>
+.. option:: -s, --subject=<subject>
+
    Specify the subject of the message.
 
-``--to=``\ <to-address>
+.. option:: --to=<to-address>
+
    Specify a recipient (To).
 
-``-c, --cc=``\ <cc-address>
+.. option:: -c, --cc=<cc-address>
+
    Specify a carbon-copy (Cc) recipient.
 
-``-b, --bcc=``\ <bcc-address>
+.. option:: -b, --bcc=<bcc-address>
+
    Specify a blind-carbon-copy (Bcc) recipient.
 
-``-i, --body=``\ <file>
+.. option:: -i, --body=<file>
+
    Specify a file to include into the body of the message.
 
-``--hello``
+.. option:: --hello
+
    Go to the Notmuch hello screen instead of the message composition
    window if no message composition parameters are given.
 
-``--no-window-system``
+.. option:: --no-window-system
+
    Even if a window system is available, use the current terminal.
 
-``--client``
+.. option:: --client
+
    Use :manpage:`emacsclient(1)`, rather than
    :manpage:`emacs(1)`. For :manpage:`emacsclient(1)` to work, you
    need an already running Emacs with a server, or use
    ``--auto-daemon``.
 
-``--auto-daemon``
+.. option:: --auto-daemon
+
    Automatically start Emacs in daemon mode, if the Emacs server is
    not running. Applicable with ``--client``. Implies
    ``--create-frame``.
 
-``--create-frame``
+.. option:: --create-frame
+
    Create a new frame instead of trying to use the current Emacs
    frame. Applicable with ``--client``. This will be required when
    Emacs is running (or automatically started with ``--auto-daemon``)
    in daemon mode.
 
-``--print``
+.. option:: --print
+
    Output the resulting elisp to stdout instead of evaluating it.
 
 The supported positional parameters and short options are a compatible

doc/man1/notmuch-insert.rst

@@ -33,33 +33,41 @@ more details on hooks.
 Option arguments must appear before any tag operation arguments.
 Supported options for **insert** include
 
-``--folder=<``\ folder\ **>**
+.. program:: insert
+
+.. option:: --folder=<folder>
+
    Deliver the message to the specified folder, relative to the
    top-level directory given by the value of **database.path**. The
    default is the empty string, which means delivering to the
    top-level directory.
 
-``--create-folder``
+.. option:: --create-folder
+
    Try to create the folder named by the ``--folder`` option, if it
    does not exist. Otherwise the folder must already exist for mail
    delivery to succeed.
 
-``--keep``
+.. option:: --keep
+
    Keep the message file if indexing fails, and keep the message
    indexed if applying tags or maildir flag synchronization
    fails. Ignore these errors and return exit status 0 to indicate
    successful mail delivery.
 
-``--no-hooks``
+.. option:: --no-hooks
+
    Prevent hooks from being run.
 
-``--world-readable``
+.. option:: --world-readable
+
    When writing mail to the mailbox, allow it to be read by users
    other than the current user.  Note that this does not override
    umask.  By default, delivered mail is only readable by the current
    user.
 
-``--decrypt=(true|nostash|auto|false)``
+.. option:: --decrypt=(true|nostash|auto|false)
+
    If ``true`` and the message is encrypted, try to decrypt the
    message while indexing, stashing any session keys discovered.  If
    ``auto``, and notmuch already knows about a session key for the

doc/man1/notmuch-new.rst

@@ -40,17 +40,23 @@ details on hooks.
 
 Supported options for **new** include
 
-``--no-hooks``
+.. program:: new
+
+.. option:: --no-hooks
+
    Prevents hooks from being run.
 
-``--quiet``
+.. option:: --quiet
+
    Do not print progress or results.
 
-``--verbose``
+.. option:: --verbose
+
    Print file names being processed. Ignored when combined with
    ``--quiet``.
 
-``--decrypt=(true|nostash|auto|false)``
+.. option:: --decrypt=(true|nostash|auto|false)
+
    If ``true``, when encountering an encrypted message, try to
    decrypt it while indexing, and stash any discovered session keys.
    If ``auto``, try to use any session key already known to belong to
@@ -66,7 +72,8 @@ Supported options for **new** include
 
    See also ``index.decrypt`` in :any:`notmuch-config(1)`.
 
-``--full-scan``
+.. option:: --full-scan
+
    By default notmuch-new uses directory modification times (mtimes)
    to optimize the scanning of directories for new mail. This option turns
    that optimization off.

doc/man1/notmuch-reindex.rst

@@ -23,7 +23,10 @@ messages using the supplied options.
 
 Supported options for **reindex** include
 
-``--decrypt=(true|nostash|auto|false)``
+.. program:: reindex
+
+.. option:: --decrypt=(true|nostash|auto|false)
+
    If ``true``, when encountering an encrypted message, try to
    decrypt it while reindexing, stashing any session keys discovered.
    If ``auto``, and notmuch already knows about a session key for the

doc/man1/notmuch-reply.rst

@@ -36,7 +36,10 @@ The resulting message template is output to stdout.
 
 Supported options for **reply** include
 
-``--format=``\ (**default**\ \|\ **json**\ \|\ **sexp**\ \|\ **headers-only**)
+.. program:: reply
+
+.. option:: --format=(default|json|sexp|headers-only)
+
    **default**
      Includes subject and quoted message body as an RFC 2822
      message.
@@ -56,12 +59,14 @@ Supported options for **reply** include
      Only produces In-Reply-To, References, To, Cc, and Bcc
      headers.
 
-``--format-version=N``
+.. option:: --format-version=N
+
    Use the specified structured output format version. This is
    intended for programs that invoke :any:`notmuch(1)` internally. If
    omitted, the latest supported version will be used.
 
-``--reply-to=``\ (**all**\ \|\ **sender**)
+.. option:: --reply-to=(all|sender)
+
    **all** (default)
      Replies to all addresses.
 
@@ -72,7 +77,7 @@ Supported options for **reply** include
      order, and copy values from the first that contains something
      other than only the user's addresses.
 
-``--decrypt=(false|auto|true)``
+.. option:: --decrypt=(false|auto|true)
 
    If ``true``, decrypt any MIME encrypted parts found in the
    selected content (i.e., "multipart/encrypted" parts). Status

doc/man1/notmuch-restore.rst

@@ -18,12 +18,16 @@ The input is read from the given filename, if any, or from stdin.
 
 Supported options for **restore** include
 
-``--accumulate``
+.. program:: restore
+
+.. option:: --accumulate
+
    The union of the existing and new tags is applied, instead of
    replacing each message's tags as they are read in from the dump
    file.
 
-``--format=(sup|batch-tag|auto)``
+.. option:: --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 :any:`notmuch-dump(1)`.
@@ -51,7 +55,8 @@ Supported options for **restore** include
      this heuristic, based the fact that batch-tag format contains
      no parentheses, should be accurate.
 
-``--include=(config|properties|tags)``
+.. option:: --include=(config|properties|tags)
+
    Control what kind of metadata is restored.
 
    **config**
@@ -72,7 +77,8 @@ Supported options for **restore** include
    The default is to restore all available types of data. The option
    can be specified multiple times to select some subset.
 
-``--input=``\ <filename>
+.. option:: --input=<filename>
+
    Read input from given file instead of stdin.
 
 GZIPPED INPUT

doc/man1/notmuch-search.rst

@@ -26,18 +26,23 @@ See :any:`notmuch-search-terms(7)` for details of the supported syntax for
 
 Supported options for **search** include
 
-``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**)
+.. program:: search
+
+.. option:: --format=(json|sexp|text|text0)
+
    Presents the results in either JSON, S-Expressions, newline
    character separated plain-text (default), or null character
    separated plain-text (compatible with :manpage:`xargs(1)` -0
    option where available).
 
-``--format-version=N``
+.. option:: --format-version=N
+
    Use the specified structured output format version. This is
    intended for programs that invoke :any:`notmuch(1)` internally. If
    omitted, the latest supported version will be used.
 
-``--output=(summary|threads|messages|files|tags)``
+.. option:: --output=(summary|threads|messages|files|tags)
+
    **summary**
      Output a summary of each thread with any message matching the
      search terms. The summary includes the thread ID, date, the
@@ -79,7 +84,8 @@ Supported options for **search** include
      characters (``--format=text0``), as a JSON array (``--format=json``),
      or as an S-Expression list (``--format=sexp``).
 
-``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
+.. option:: --sort=(newest-first|oldest-first)
+
    This option can be used to present results in either chronological
    order (**oldest-first**) or reverse chronological order
    (**newest-first**).
@@ -93,14 +99,17 @@ Supported options for **search** include
    By default, results will be displayed in reverse chronological
    order, (that is, the newest results will be displayed first).
 
-``--offset=[-]N``
+.. option:: --offset=[-]N
+
    Skip displaying the first N results. With the leading '-', start
    at the Nth result from the end.
 
-``--limit=N``
+.. option:: --limit=N
+
    Limit the number of displayed results to N.
 
-``--exclude=(true|false|all|flag)``
+.. option:: --exclude=(true|false|all|flag)
+
    A message is called "excluded" if it matches at least one tag in
    search.exclude\_tags that does not appear explicitly in the search
    terms. This option specifies whether to omit excluded messages in
@@ -125,7 +134,8 @@ Supported options for **search** include
      number of matching non-excluded messages in the thread, rather
      than the number of matching messages.
 
-``--duplicate=N``
+.. option:: --duplicate=N
+
    For ``--output=files``, output the Nth filename associated with
    each message matching the query (N is 1-based). If N is greater
    than the number of files associated with the message, don't print

doc/man1/notmuch-show.rst

@@ -25,13 +25,17 @@ post-processor (such as the emacs interface to notmuch).
 
 Supported options for **show** include
 
-``--entire-thread=(true|false)``
+.. program:: show
+
+.. option:: --entire-thread=(true|false)
+
    If true, **notmuch show** outputs all messages in the thread of
    any message matching the search terms; if false, it outputs only
    the matching messages. For ``--format=json`` and ``--format=sexp``
    this defaults to true. For other formats, this defaults to false.
 
-``--format=(text|json|sexp|mbox|raw)``
+.. option:: --format=(text|json|sexp|mbox|raw)
+
    **text** (default for messages)
      The default plain-text format has all text-content MIME parts
      decoded. Various components in the output, (**message**,
@@ -90,12 +94,14 @@ Supported options for **show** include
      of this may need to implement MIME decoding and similar
      functions.
 
-``--format-version=N``
+.. option:: --format-version=N
+
    Use the specified structured output format version. This is
    intended for programs that invoke :any:`notmuch(1)` internally. If
    omitted, the latest supported version will be used.
 
-``--part=N``
+.. option:: --part=N
+
    Output the single decoded MIME part N of a single message. The
    search terms must match only a single message. Message parts are
    numbered in a depth-first walk of the message MIME structure, and
@@ -105,14 +111,16 @@ Supported options for **show** include
    part still has two MIME parts: part 0 is the whole message
    (headers and body) and part 1 is just the body.
 
-``--verify``
+.. option:: --verify
+
    Compute and report the validity of any MIME cryptographic
    signatures found in the selected content (e.g., "multipart/signed"
    parts). Status of the signature will be reported (currently only
    supported with ``--format=json`` and ``--format=sexp``), and the
    multipart/signed part will be replaced by the signed data.
 
-``--decrypt=(false|auto|true|stash)``
+.. option:: --decrypt=(false|auto|true|stash)
+
    If ``true``, decrypt any MIME encrypted parts found in the
    selected content (e.g., "multipart/encrypted" parts). Status of
    the decryption will be reported (currently only supported
@@ -162,7 +170,8 @@ Supported options for **show** include
 
    Default: ``auto``
 
-``--exclude=(true|false)``
+.. option:: --exclude=(true|false)
+
    Specify whether to omit threads only matching search.exclude\_tags
    from the search results (the default) or not. In either case the
    excluded message will be marked with the exclude flag (except when
@@ -175,7 +184,8 @@ Supported options for **show** include
 
    The default is ``--exclude=true.``
 
-``--body=(true|false)``
+.. option:: --body=(true|false)
+
    If true (the default) **notmuch show** includes the bodies of the
    messages in the output; if false, bodies are omitted.
    ``--body=false`` is only implemented for the text, json and sexp
@@ -184,7 +194,8 @@ Supported options for **show** include
    This is useful if the caller only needs the headers as body-less
    output is much faster and substantially smaller.
 
-``--include-html``
+.. option:: --include-html
+
    Include "text/html" parts as part of the output (currently
    only supported with ``--format=text``, ``--format=json`` and
    ``--format=sexp``). By default, unless ``--part=N`` is used to

doc/man1/notmuch-tag.rst

@@ -34,20 +34,25 @@ the **maildir.synchronize\_flags** configuration option is enabled. See
 
 Supported options for **tag** include
 
-``--remove-all``
+.. program:: tag
+
+.. option:: --remove-all
+
    Remove all tags from each message matching the search terms before
    applying the tag changes appearing on the command line.  This
    means setting the tags of each message to the tags to be added. If
    there are no tags to be added, the messages will have no tags.
 
-``--batch``
+.. option:: --batch
+
    Read batch tagging operations from a file (stdin by default).
    This is more efficient than repeated **notmuch tag**
    invocations. See `TAG FILE FORMAT <#tag_file_format>`__ below for
    the input format. This option is not compatible with specifying
    tagging on the command line.
 
-``--input=``\ <filename>
+.. option:: --input=<filename>
+
    Read input from given file, instead of from stdin. Implies
    ``--batch``.
 

doc/man1/notmuch.rst

@@ -43,20 +43,26 @@ OPTIONS
 
 Supported global options for ``notmuch`` include
 
-``--help`` [command-name]
+.. program:: notmuch
+
+.. option:: --help [command-name]
+
    Print a synopsis of available commands and exit. With an optional
    command name, show the man page for that subcommand.
 
-``--version``
+.. option:: --version
+
    Print the installed version of notmuch, and exit.
 
-``--config=FILE``
+.. option:: --config=FILE
+
    Specify the configuration file to use. This overrides any
    configuration file specified by :envvar:`NOTMUCH_CONFIG`. The empty
    string is a permitted and sometimes useful value of *FILE*, which
    tells ``notmuch`` to use only configuration metadata from the database.
 
-``--uuid=HEX``
+.. option:: --uuid=HEX
+
    Enforce that the database UUID (a unique identifier which persists
    until e.g. the database is compacted) is HEX; exit with an error
    if it is not. This is useful to detect rollover in modification