[PATCH] doc: clean up manpages
Tomi Ollila
tomi.ollila at iki.fi
Sun Jun 24 07:51:49 PDT 2018
On Tue, Jun 19 2018, Daniel Kahn Gillmor wrote:
> Many of the manpages didn't treat literal text as literal text. I've
> tried to normalize some of the restructured text to make it a bit more
> regular.
>
> several of the synopsis lines are still untouched by this cleanup, but
> i'm not sure what the right way to represent those is in .rst,
> actually.
>
> In particular find that if i rebuild the manpages, sometimes i end up
> with some of the synopsis lines showing – (U+2013 EN DASH) where they
> should have -- (2 × U+002D HYPHEN-MINUS) in the generated nroff
> output, though i have not tracked down the source of this error yet.
Looks OK to me.
Tomi
> ---
> doc/man1/notmuch-address.rst | 12 ++++++------
> doc/man1/notmuch-dump.rst | 2 +-
> doc/man1/notmuch-reply.rst | 2 +-
> doc/man1/notmuch-search.rst | 26 +++++++++++++-------------
> doc/man1/notmuch-show.rst | 14 +++++++-------
> doc/man7/notmuch-search-terms.rst | 4 ++--
> 6 files changed, 30 insertions(+), 30 deletions(-)
>
> diff --git a/doc/man1/notmuch-address.rst b/doc/man1/notmuch-address.rst
> index c00d7d74..12d86e89 100644
> --- a/doc/man1/notmuch-address.rst
> +++ b/doc/man1/notmuch-address.rst
> @@ -32,8 +32,8 @@ Supported options for **address** include
> ``--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
> - given, --output=sender is implied.
> + neither ``--output=sender`` nor ``--output=recipients`` is
> + given, ``--output=sender`` is implied.
>
> **sender**
> Output all addresses from the *From* header.
> @@ -63,19 +63,19 @@ Supported options for **address** include
>
> **no**
> Output all occurrences of addresses in the matching
> - messages. This is not applicable with --output=count.
> + messages. This is not applicable with ``--output=count``.
>
> **mailbox**
> Deduplicate addresses based on the full, case sensitive name
> and email address, or mailbox. This is effectively the same as
> - piping the --deduplicate=no output to **sort | uniq**, except
> + piping the ``--deduplicate=no`` output to **sort | uniq**, except
> for the order of results. This is the default.
>
> **address**
> Deduplicate addresses based on the case insensitive address
> part of the mailbox. Of all the variants (with different name
> or case), print the one occurring most frequently among the
> - matching messages. If --output=count is specified, include all
> + matching messages. If ``--output=count`` is specified, include all
> variants in the count.
>
> ``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
> @@ -86,7 +86,7 @@ Supported options for **address** include
> By default, results will be displayed in reverse chronological
> order, (that is, the newest results will be displayed first).
>
> - However, if either --output=count or --deduplicate=address is
> + However, if either ``--output=count`` or ``--deduplicate=address`` is
> specified, this option is ignored and the order of the results is
> unspecified.
>
> diff --git a/doc/man1/notmuch-dump.rst b/doc/man1/notmuch-dump.rst
> index f8ec4868..ec6335b2 100644
> --- a/doc/man1/notmuch-dump.rst
> +++ b/doc/man1/notmuch-dump.rst
> @@ -21,7 +21,7 @@ incremental backup than the native database files.)
>
> See **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 database will be generated. A ``--`` argument instructs notmuch that
> the remaining arguments are search terms.
>
> Supported options for **dump** include
> diff --git a/doc/man1/notmuch-reply.rst b/doc/man1/notmuch-reply.rst
> index c893ba04..5c64c4a6 100644
> --- a/doc/man1/notmuch-reply.rst
> +++ b/doc/man1/notmuch-reply.rst
> @@ -75,7 +75,7 @@ Supported options for **reply** include
> If ``true``, decrypt any MIME encrypted parts found in the
> selected content (i.e., "multipart/encrypted" parts). Status
> of the decryption will be reported (currently only supported
> - with --format=json and --format=sexp), and on successful
> + with ``--format=json`` and ``--format=sexp``), and on successful
> decryption the multipart/encrypted part will be replaced by
> the decrypted content.
>
> diff --git a/doc/man1/notmuch-search.rst b/doc/man1/notmuch-search.rst
> index e42da2ae..654c5f2c 100644
> --- a/doc/man1/notmuch-search.rst
> +++ b/doc/man1/notmuch-search.rst
> @@ -47,25 +47,25 @@ Supported options for **search** include
>
> **threads**
> Output the thread IDs of all threads with any message matching
> - the search terms, either one per line (--format=text),
> - separated by null characters (--format=text0), as a JSON array
> - (--format=json), or an S-Expression list (--format=sexp).
> + the search terms, either one per line (``--format=text``),
> + separated by null characters (``--format=text0``), as a JSON array
> + (``--format=json``), or an S-Expression list (``--format=sexp``).
>
> **messages**
> Output the message IDs of all messages matching the search
> - terms, either one per line (--format=text), separated by null
> - characters (--format=text0), as a JSON array (--format=json),
> - or as an S-Expression list (--format=sexp).
> + terms, either one per line (``--format=text``), separated by null
> + characters (``--format=text0``), as a JSON array (``--format=json``),
> + or as an S-Expression list (``--format=sexp``).
>
> **files**
> Output the filenames of all messages matching the search
> - terms, either one per line (--format=text), separated by null
> - characters (--format=text0), as a JSON array (--format=json),
> - or as an S-Expression list (--format=sexp).
> + terms, either one per line (``--format=text``), separated by null
> + characters (``--format=text0``), as a JSON array (``--format=json``),
> + or as an S-Expression list (``--format=sexp``).
>
> Note that each message may have multiple filenames associated
> with it. All of them are included in the output (unless
> - limited with the --duplicate=N option). This may be
> + limited with the ``--duplicate=N`` option). This may be
> particularly confusing for **folder:** or **path:** searches
> in a specified directory, as the messages may have duplicates
> in other directories that are included in the output, although
> @@ -73,9 +73,9 @@ Supported options for **search** include
>
> **tags**
> Output all tags that appear on any message matching the search
> - terms, either one per line (--format=text), separated by null
> - characters (--format=text0), as a JSON array (--format=json),
> - or as an S-Expression list (--format=sexp).
> + terms, either one per line (``--format=text``), separated by null
> + characters (``--format=text0``), as a JSON array (``--format=json``),
> + or as an S-Expression list (``--format=sexp``).
>
> ``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
> This option can be used to present results in either chronological
> diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst
> index b2667537..8bfa87c6 100644
> --- a/doc/man1/notmuch-show.rst
> +++ b/doc/man1/notmuch-show.rst
> @@ -71,7 +71,7 @@ Supported options for **show** include
>
> http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
>
> - **raw** (default if --part is given)
> + **raw** (default if ``--part`` is given)
> Write the raw bytes of the given MIME part of a message to
> standard out. For this format, it is an error to specify a
> query that matches more than one message.
> @@ -105,16 +105,16 @@ Supported options for **show** include
>
> ``--verify``
> Compute and report the validity of any MIME cryptographic
> - signatures found in the selected content (ie. "multipart/signed"
> + 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
> + supported with ``--format=json`` and ``--format=sexp``), and the
> multipart/signed part will be replaced by the signed data.
>
> ``--decrypt=(false|auto|true|stash)``
> If ``true``, decrypt any MIME encrypted parts found in the
> - selected content (i.e. "multipart/encrypted" parts). Status of
> + selected content (e.g., "multipart/encrypted" parts). Status of
> the decryption will be reported (currently only supported
> - with --format=json and --format=sexp) and on successful
> + with ``--format=json`` and ``--format=sexp``) and on successful
> decryption the multipart/encrypted part will be replaced by
> the decrypted content.
>
> @@ -166,7 +166,7 @@ Supported options for **show** include
> excluded message will be marked with the exclude flag (except when
> output=mbox when there is nowhere to put the flag).
>
> - If --entire-thread is specified then complete threads are returned
> + If ``--entire-thread`` is specified then complete threads are returned
> regardless (with the excluded flag being set when appropriate) but
> threads that only match in an excluded message are not returned
> when ``--exclude=true.``
> @@ -184,7 +184,7 @@ Supported options for **show** include
>
> ``--include-html``
> Include "text/html" parts as part of the output (currently only
> - supported with --format=json and --format=sexp). By default,
> + supported with ``--format=json`` and ``--format=sexp``). By default,
> unless ``--part=N`` is used to select a specific part or
> ``--include-html`` is used to include all "text/html" parts, no
> part with content type "text/html" is included in the output.
> diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst
> index 8a5eeb18..f7a39ceb 100644
> --- a/doc/man7/notmuch-search-terms.rst
> +++ b/doc/man7/notmuch-search-terms.rst
> @@ -7,7 +7,7 @@ SYNOPSIS
>
> **notmuch** **count** [option ...] <*search-term*> ...
>
> -**notmuch** **dump** [--format=(batch-tag|sup)] [--] [--output=<*file*>] [--] [<*search-term*> ...]
> +**notmuch** **dump** [--gzip] [--format=(batch-tag|sup)] [--output=<*file*>] [--] [<*search-term*> ...]
>
> **notmuch** **reindex** [option ...] <*search-term*> ...
>
> @@ -150,7 +150,7 @@ lastmod:<initial-revision>..<final-revision>
> The **lastmod:** prefix can be used to restrict the result by the
> database revision number of when messages were last modified (tags
> were added/removed or filenames changed). This is usually used in
> - conjunction with the **--uuid** argument to **notmuch search** to
> + conjunction with the ``--uuid`` argument to **notmuch search** to
> find messages that have changed since an earlier query.
>
> query:<name>
> --
> 2.17.1
>
> _______________________________________________
> notmuch mailing list
> notmuch at notmuchmail.org
> https://notmuchmail.org/mailman/listinfo/notmuch
More information about the notmuch
mailing list