[PATCH] doc: clean up manpages

[PATCH] doc: clean up manpages

[Daniel Kahn Gillmor]

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

Re: [PATCH] doc: clean up manpages

[Tomi Ollila]

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@notmuchmail.org
> https://notmuchmail.org/mailman/listinfo/notmuch

Re: [PATCH] doc: clean up manpages

[David Bremner]

Daniel Kahn Gillmor <dkg@fifthhorseman.net> writes:

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

pushed.

d