debian/notmuch
1
0
Fork 0
mirror of https://git.notmuchmail.org/git/notmuch synced 2024-11-21 18:38:08 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: use program and option directives to document options

Browse source 
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.
This commit is contained in:
Jani Nikula 2021-05-21 23:44:12 +03:00 committed by David Bremner
parent 574b2436ee
commit f2e2f2aa96
15 changed files with 740 additions and 635 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
doc/man1/notmuch-address.rst
View file

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

8
doc/man1/notmuch-compact.rst
View file

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

11
doc/man1/notmuch-config.rst
View file

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

17
doc/man1/notmuch-count.rst
View file

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

14
doc/man1/notmuch-dump.rst
View file

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

38
doc/man1/notmuch-emacs-mua.rst
View file

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

20
doc/man1/notmuch-insert.rst
View file

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

17
doc/man1/notmuch-new.rst
View file

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

5
doc/man1/notmuch-reindex.rst
View file

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

13
doc/man1/notmuch-reply.rst
View file

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

14
doc/man1/notmuch-restore.rst
View file

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

26
doc/man1/notmuch-search.rst
View file

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

29
doc/man1/notmuch-show.rst
View file

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

11
doc/man1/notmuch-tag.rst
View file

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

14
doc/man1/notmuch.rst
View file

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