doc: example command-line option reference

[notmuch] / doc / man1 / notmuch-config.rst

diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst
index 5c980a8a4bb80d57cff031594fc0ef6db8708c5b..56f4a1600153517edce62d9094ff37ef1ffb13c1 100644 (file)
--- a/doc/man1/notmuch-config.rst
+++ b/doc/man1/notmuch-config.rst
@@ -19,32 +19,37 @@ DESCRIPTION
 The **config** command can be used to get or set settings in the notmuch
 configuration file and corresponding database.
 
-**get**
-    The value of the specified configuration item is printed to
-    stdout. If the item has multiple values (it is a list), each value
-    is separated by a newline character.
+.. program:: config
 
-**set**
-    The specified configuration item is set to the given value. To
-    specify a multiple-value item (a list), provide each value as a
-    separate command-line argument.
+.. option:: get
 
-    If no values are provided, the specified configuration item will
-    be removed from the configuration file.
+   The value of the specified configuration item is printed to
+   stdout. If the item has multiple values (it is a list), each value
+   is separated by a newline character.
 
-    With the `--database` option, updates configuration metadata
-    stored in the database, rather than the default (text)
-    configuration file.
+.. option:: set
 
-**list**
-    Every configuration item is printed to stdout, each on a separate
-    line of the form::
+   The specified configuration item is set to the given value. To
+   specify a multiple-value item (a list), provide each value as a
+   separate command-line argument.
 
-        section.item=value
+   If no values are provided, the specified configuration item will
+   be removed from the configuration file.
 
-    No additional whitespace surrounds the dot or equals sign
-    characters. In a multiple-value item (a list), the values are
-    separated by semicolon characters.
+   With the `--database` option, updates configuration metadata
+   stored in the database, rather than the default (text)
+   configuration file.
+
+.. option:: list
+
+   Every configuration item is printed to stdout, each on a separate
+   line of the form::
+
+     section.item=value
+
+   No additional whitespace surrounds the dot or equals sign
+   characters. In a multiple-value item (a list), the values are
+   separated by semicolon characters.
 
 The available configuration items are described below. Non-absolute
 paths are presumed relative to `$HOME` for items in section
@@ -235,39 +240,39 @@ paths are presumed relative to `$HOME` for items in section
     :any:`notmuch-search-terms(7)` for more information about named
     queries.
 
-ENVIRONMENT
-===========
-
-The following environment variables can be used to control the behavior
-of notmuch.
-
-**NOTMUCH\_CONFIG**
-    Specifies the location of the notmuch configuration file.
-
-**NOTMUCH_PROFILE**
-    Selects among notmuch configurations.
-
 FILES
 =====
 
 CONFIGURATION
 -------------
 
-If ``NOTMUCH_CONFIG`` is unset, notmuch tries (in order)
+Notmuch configuration file search order:
+
+1. File specified by :option:`notmuch --config` global option; see
+   :any:`notmuch(1)`.
+
+2. File specified by :envvar:`NOTMUCH_CONFIG` environment variable.
 
-- ``$XDG_CONFIG_HOME/notmuch/<profile>/config`` where ``<profile>`` is
-  defined by ``$NOTMUCH_PROFILE`` or "default"
-- ``${HOME}/.notmuch-config<profile>`` where ``<profile>`` is
-  ``.$NOTMUCH_PROFILE`` or ""
+3. ``$XDG_CONFIG_HOME/notmuch/<profile>/config`` where ``<profile>``
+   is defined by :envvar:`NOTMUCH_PROFILE` environment variable if
+   set, ``$XDG_CONFIG_HOME/notmuch/default/config`` otherwise.
+
+4. ``$HOME/.notmuch-config.<profile>`` where ``<profile>`` is defined
+   by :envvar:`NOTMUCH_PROFILE` environment variable if set,
+   ``$HOME/.notmuch-config`` otherwise.
 
 Hooks
 -----
 
-If ``database.hook_dir`` is unset, notmuch tries (in order)
+Notmuch hook directory search order:
+
+1. Directory specified by ``database.hook_dir`` configuration option.
+
+2. ``$XDG_CONFIG_HOME/notmuch/<profile>/hooks`` where ``<profile>``
+   is defined by :envvar:`NOTMUCH_PROFILE` environment variable if
+   set, ``$XDG_CONFIG_HOME/notmuch/default/hooks`` otherwise.
 
-- ``$XDG_CONFIG_HOME/notmuch/<profile>/hooks`` where ``<profile>`` is
-  defined by ``$NOTMUCH_PROFILE`` or "default"
-- ``<database.path>/.notmuch/hooks``
+3. ``<database.path>/.notmuch/hooks``
 
 SEE ALSO
 ========