Re: [PATCH] doc: clean up manpages
Daniel Kahn Gillmor 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 ___ notmuch mailing list notmuch@notmuchmail.org https://notmuchmail.org/mailman/listinfo/notmuch
Re: [PATCH] doc: clean up manpages
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 . 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 > -
[PATCH] doc: clean up manpages
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 . 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``), +
