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.
Make man1/notmuch.rst the single point of truth for describing notmuch
environment variables. Use the envvar directive for that, and
reference them with the envvar role.
Drive-by cleanup configuration file and hook directory search order
documentation.
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.
Previously the fact that some configuration options were only stored
in the database (and thus editing the config file had no effect) was a
source of user confusion. This was fixed with the series ending at
d9af0af164.
On the other hand, the underlying partition of config options into
those stored by default in the database and those stored in the config
file remained. This is also confusing, since now some invocations of
"notmuch config set" modify the config file, and others silently
modify the database instead.
With this commit, it is up to the user to decide which configuration
to modify. A new "--database" option is provided for notmuch config to
enable modifying the configuration information in the database;
otherwise the default is to update an external config file.
id:CA+Tk8fzRiqxWpd=r8=DRvEewNZXUZgD7MKyRLB1A=R-LxxGEZw@mail.gmail.com
started a thread of discussion that showed that the cli's current
idiosyncrasies around dealing with boolean options were not
understandable.
This attempts to improve the documentation at least (actual changes to
the API might be better, but have not reached consensus).
Note that no one in the discussion thread identified any other
(non-boolean) command-line options that cannot use space as a
separator. If such an option is identified (or introduced in the
future), it should be added explicitly to this part of the manual.
Signed-off-by: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
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.
Many of the external links found in the notmuch source can be resolved
using https instead of http. This changeset addresses as many as i
could find, without touching the e-mail corpus or expected outputs
found in tests.
The function notmuch_exit_if_unmatched_db_uuid is split from
notmuch_process_shared_options because it needs an open notmuch
database.
There are two exceptional cases in uuid handling.
1) notmuch config and notmuch setup don't currently open the database,
so it doesn't make sense to check the UUID.
2) notmuch compact opens the database inside the library, so we either
need to open the database just to check uuid, or change the API.
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.
This is the output from sphinx-quickstart, massaged a bit, along with
our existing man pages converted to rst.
A skeleton notmuch-emacs manual is also included. It is not suitable
for end user use yet.
