Sphinx-doc already formats the terms appropriately for a given
backend (bold in html and man). `makeinfo` complains noisily about
formatting inside a @item if we add our own explicit formatting.
This change may change the formatting in the info output. On the other
hand, the existing use of quotes for bold is not that great anyway.
In some places blank lines were removed to preserve the logical
structure of a definition list.
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.
Add internal hyperlink targets for man pages and cross-reference them
using the any role reference. There are a number of alternatives to
accomplish this, but this seems like the combination that retains the
man page section number and the same boldface style in the man pages.
As a bonus, we get sanity checking on the links; for example
notmuch-search-terms.rst had a reference to notmuch-properties(1)
i.e. the wrong section.
The obvious semantic follow-up change would be to only have meaningful
"see also" references instead of having them all everywhere.
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.
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.
Make all parameter descriptions etc. use reStructuredText definition
lists with uniform style and indentation. Remove redundant indentation
from around the lists. Remove blank lines between term lines and
definition blocks. Use four spaces for indentation.
This is almost completely whitespace and paragraph reflow changes.
In most part, our .rst documents are indented with 8 spaces instead
of tabs. Bring the rest of the lines to the same format.
Also, on one (supposedly empty) line, trailing spaces were removed.
The order of the results with --output=count and --deduplicate=address
are unspecified as they're based on a hash table traversal. This being
the case, optimize the query by explicitly requesting unsorted
results. Clarify the documentation accordingly.
When no --output option were given, change default to display senders
only.
When only --count option is given, display senders (in contrary to not
displaying anything).
Document that --count with --sort=**order** is not supported option
combination.
Clean up some whitespace in the documentation.
One test updated to have --output=count without sender nor recipient
output option.
This filters out duplicate addresses from address command output.
It also also adds tests for the address command.
The code here is an extended version of a patch from Jani Nikula.
This moves address-related functionality from search command to the
new address command. The implementation shares almost all code and
some command line options.
Options --offset and --limit were intentionally not included in the
address command, because they refer to messages numbers, which users
do not see in the output. This could confuse users because, for
example, they could see more addresses in the output that what was
specified with --limit. This functionality can be correctly
reimplemented for address subcommand later.
Also useless values of --exclude flag were not included in the address
command.
This was inspired by a patch from Jani Nikula.
