Using manpage role references generates helpful links in html
documentation, while retaining the same boldface style in the man
pages.
The external man page site is configurable. The Debian manpage site
seems like a good fit for Notmuch.
# Despite the name, this actually affects manual pages as well.
html_use_smartypants = False
# Despite the name, this actually affects manual pages as well.
html_use_smartypants = False
+# See:
+# - https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-manpages_url
+# - https://manpages.debian.org/
+manpages_url = 'https://manpages.debian.org/{page}.{section}.html'
+
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**)
Presents the results in either JSON, S-Expressions, newline
character separated plain-text (default), or null character
``--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 **xargs(1)** -0 option where
- available).
+ separated plain-text (compatible with :manpage:`xargs(1)` -0
+ option where available).
``--format-version=N``
Use the specified structured output format version. This is
``--format-version=N``
Use the specified structured output format version. This is
Supported options for **dump** include
``--gzip``
Supported options for **dump** include
``--gzip``
- Compress the output in a format compatible with **gzip(1)**.
+ Compress the output in a format compatible with :manpage:`gzip(1)`.
``--format=(sup|batch-tag)``
Notmuch restore supports two plain text dump formats, both with
``--format=(sup|batch-tag)``
Notmuch restore supports two plain text dump formats, both with
**batch-tag**
The default **batch-tag** dump format is intended to more
robust against malformed message-ids and tags containing
**batch-tag**
The default **batch-tag** dump format is intended to more
robust against malformed message-ids and tags containing
- whitespace or non-\ **ascii(7)** characters. Each line has the
- form::
+ whitespace or non-\ :manpage:`ascii(7)` characters. Each line
+ has the form::
+<*encoded-tag*\ > +<*encoded-tag*\ > ... -- id:<*quoted-message-id*\ >
+<*encoded-tag*\ > +<*encoded-tag*\ > ... -- id:<*quoted-message-id*\ >
**sup**
The **sup** dump file format is specifically chosen to be
**sup**
The **sup** dump file format is specifically chosen to be
- compatible with the format of files produced by sup-dump. 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 them). Each line has the
- following form::
+ 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
+ them). Each line has the following form::
<*message-id*\ > **(** <*tag*\ > ... **)**
<*message-id*\ > **(** <*tag*\ > ... **)**
Even if a window system is available, use the current terminal.
``--client``
Even if a window system is available, use the current terminal.
``--client``
- Use **emacsclient**, rather than **emacs**. For **emacsclient** to
- work, you need an already running Emacs with a server, or use
+ 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``
``--auto-daemon``.
``--auto-daemon``
Output the resulting elisp to stdout instead of evaluating it.
The supported positional parameters and short options are a compatible
Output the resulting elisp to stdout instead of evaluating it.
The supported positional parameters and short options are a compatible
-subset of the **mutt** MUA command-line options. The options and
-positional parameters modifying the message can't be combined with the
-mailto: URL.
+subset of the :manpage:`mutt(1)` MUA command-line options. The options
+and positional parameters modifying the message can't be combined with
+the mailto: URL.
Options may be specified multiple times.
Options may be specified multiple times.
-**notmuch(1)**, **emacsclient(1)**, **mutt(1)**
+**notmuch(1)**,
+:manpage:`emacsclient(1)`,
+:manpage:`mutt(1)`
Use ``false`` to avoid even automatic decryption.
Non-automatic decryption expects a functioning
Use ``false`` to avoid even automatic decryption.
Non-automatic decryption expects a functioning
- **gpg-agent(1)** to provide any needed credentials. Without
+ :manpage:`gpg-agent(1)` to provide any needed credentials. Without
one, the decryption will likely fail.
Default: ``auto``
one, the decryption will likely fail.
Default: ``auto``
=============
\ **notmuch restore** will detect if the input is compressed in
=============
\ **notmuch restore** will detect if the input is compressed in
-**gzip(1)** format and automatically decompress it while reading. This
-detection does not depend on file naming and in particular works for
-standard input.
+:manpage:`gzip(1)` format and automatically decompress it while
+reading. This detection does not depend on file naming and in
+particular works for standard input.
``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**)
Presents the results in either JSON, S-Expressions, newline
character separated plain-text (default), or null character
``--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 **xargs(1)** -0 option where
- available).
+ separated plain-text (compatible with :manpage:`xargs(1)` -0
+ option where available).
``--format-version=N``
Use the specified structured output format version. This is
``--format-version=N``
Use the specified structured output format version. This is
Use ``false`` to avoid even automatic decryption.
Non-automatic decryption (``stash`` or ``true``, in the absence of
Use ``false`` to avoid even automatic decryption.
Non-automatic decryption (``stash`` or ``true``, in the absence of
- a stashed session key) expects a functioning **gpg-agent(1)** to
+ a stashed session key) expects a functioning :manpage:`gpg-agent(1)` to
provide any needed credentials. Without one, the decryption will
fail.
provide any needed credentials. Without one, the decryption will
fail.
Mail storage that uses mbox format, (where one mbox file contains many
messages), will not work with notmuch. If that's how your mail is
currently stored, it is recommended you first convert it to maildir
Mail storage that uses mbox format, (where one mbox file contains many
messages), will not work with notmuch. If that's how your mail is
currently stored, it is recommended you first convert it to maildir
-format with a utility such as mb2md before running **notmuch setup .**
+format with a utility such as :manpage:`mb2md(1)` before running
+**notmuch setup**.
Invoking ``notmuch`` with no command argument will run **setup** if the
setup command has not previously been completed.
Invoking ``notmuch`` with no command argument will run **setup** if the
setup command has not previously been completed.
**NOTMUCH\_TALLOC\_REPORT**
Location to write a talloc memory usage report. See
**NOTMUCH\_TALLOC\_REPORT**
Location to write a talloc memory usage report. See
- **talloc\_enable\_leak\_report\_full** in **talloc(3)** for more
+ **talloc\_enable\_leak\_report\_full** in :manpage:`talloc(3)` for more
information.
**NOTMUCH\_DEBUG\_QUERY**
information.
**NOTMUCH\_DEBUG\_QUERY**
Some of the prefixes with <regex> forms can be also used to restrict
the results to those whose value matches a regular expression (see
Some of the prefixes with <regex> forms can be also used to restrict
the results to those whose value matches a regular expression (see
-**regex(7)**) delimited with //, for example::
+:manpage:`regex(7)`) delimited with //, for example::
notmuch search 'from:"/bob@.*[.]example[.]com/"'
notmuch search 'from:"/bob@.*[.]example[.]com/"'