docs: further usage updates and clarifications

[skip ci]

Author: tomeon

USAGE.md

@@ -31,17 +31,19 @@ and responsiveness.
 
 # SETUP
 
-`/etc/asd.conf` contains all user-managed settings.  The configuration file
-location can be overridden by specifying a pathname in the `ASDCONF`
-environment variable.  For instance, to load `asd` settings from
+The `asd` configuration file contains all user-managed settings.  See the entry
+on `ASDCONF` in the [`ENVIRONMENT VARIABLES`](#environment-variables) section
+for information on the default `asd` configuration file location.  The
+configuration file location can be overridden by specifying a pathname in the
+`ASDCONF` environment variable.  For instance, to load `asd` settings from
 `/here/for/some/reason/lives/asd.conf`:
 
 ```shell-session
 $ ASDCONF=/here/for/some/reason/lives/asd.conf asd <subcommand>
 ```
 
-**Note** that edits made to `/etc/asd.conf` while `asd` is running will be
-applied only after `asd` has been restarted.
+**Note** that edits made to the `asd` configuration file while `asd` is running
+will be applied only after `asd` has been restarted.
 
 In the `asd` configuration file, you may define the following variables:
 
@@ -56,8 +58,10 @@ In the `asd` configuration file, you may define the following variables:
 
 : A path that lives on a tmpfs or zram mount.  This is where `asd` will store
   the data eventually synchronized back to the physical disk.  By default,
-  `asd` sets `VOLATILE=/tmp`.  **Note** that it is a fatal error to set
-  `VOLATILE` to a path that does not live on a tmpfs or zram mount.
+  when running as `root` and `ASDNOV1PATHS` is unset or set to a false value,
+  `asd` sets `VOLATILE=/tmp`.  Otherwise, `VOLATILE` defaults to `ASDRUNDIR`.
+  **Note** that it is a fatal error to set `VOLATILE` to a path that does not
+  live on a tmpfs or zram mount.
 
 `USE_OVERLAYFS`
 
@@ -79,12 +83,12 @@ In the `asd` configuration file, you may define the following variables:
 
 : A boolean variable controlling whether to issue debugging output.
 
-**Note** that the default value of `/tmp` should work just fine for the
-`VOLATILE` setting.  If using [`bleachbit`][BleachBit], do NOT invoke it with
-the `--clean system.tmp` switch or you will remove a key dot file (`.foo`) from
-`/tmp` that `asd` needs to keep track of sync status.  Also note that using a
-value of `/dev/shm` can cause problems with systemd's `NAMESPACE` spawning only
-when users enable the OverlayFS option.
+**Note** that the default values of `/tmp`/`ASDRUNDIR` should work just fine
+for the `VOLATILE` setting.  If using [`bleachbit`][BleachBit], do NOT invoke
+it with the `--clean system.tmp` switch or you will remove a key dot file
+(`.foo`) from `/tmp` that `asd` needs to keep track of sync status.  Also note
+that using a value of `/dev/shm` can cause problems with systemd's `NAMESPACE`
+spawning only when users enable the OverlayFS option.
 
 Example:
 
@@ -110,33 +114,38 @@ WHATTOSYNC=(
 
 `ASDCONF`
 
-: Path to the `asd` configuration file.  Defaults to `/etc/asd.conf` when
-  `ASDNOV1PATHS` is disabled; otherwise, defaults to `${ASDCONFDIR}/asd.conf`.
+: Path to the `asd` configuration file.  Defaults to `/etc/asd.conf` when `asd`
+  is running as `root` and `ASDNOV1PATHS` is unset or set to a false value;
+  otherwise, defaults to `${ASDCONFDIR}/asd.conf`.
 
 `ASDNOV1PATHS`
 
 : A boolean variable controlling whether to use "version 1" paths or not.  When
   set to a false value, `asd` will use old-style defaults for its daemon file
-  (`/run/asd`), lock file (`/run/asd-lock`), configuration file
-  (`/etc/asd.conf`)  .  **NOTE** that this variable is
-  ignored when `asd` is running as a non-`root` user.  Defaults to disabled
-  (effectively, `ASDNOV1PATHS=0`).
+  (`/run/asd`), lock file (`/run/asd-lock`), and configuration file
+  (`/etc/asd.conf`).  **NOTE** that this variable is ignored when `asd` is
+  running as a non-`root` user.  Defaults to disabled (effectively,
+  `ASDNOV1PATHS=0`).
 
 `ASDCONFDIR`
 
 : Parent directory of `asd.conf` if `ASDCONF` is not defined.  Ignored when
   running as `root` and `ASDNOV1PATHS` is unset or set to a false value.
-  Otherwise, defaults to `CONFIGURATION_DIRECTORY` (which is set when `asd`
-  runs under systemd), falling back to `/etc/asd` when running as `root` and
-  `${XDG_CONFIG_DIR}/asd` when running as a non-`root` user.
+  Otherwise, defaults to the first (leftmost) of the colon-separated paths in
+  the `CONFIGURATION_DIRECTORY` environment variable (which is set when `asd`
+  runs under systemd and the `asd.service` unit defines at least one
+  `ConfigurationDirectory` entry), falling back to `/etc/asd` when running as
+  `root` and `${XDG_CONFIG_DIR}/asd` when running as a non-`root` user.
 
 `ASDRUNDIR`
 
 : Directory where `asd` should store runtime state.  Ignored when running as
   `root` and `ASDNOV1PATHS` is unset or set to a false value.  Otherwise,
-  defaults to `RUNTIME_DIRECTORY` (which is set when `asd` runs under systemd),
-  falling back to `/run/asd` when running as `root` and
-  `${XDG_RUNTIME_DIR}/asd` when running as a non-`root` user.
+  defaults to the first (leftmost) of the colon-separated paths in the
+  `RUNTIME_DIRECTORY` (which is set when `asd` runs under systemd and the
+  `asd.service` unit defines at least one `RuntimeDirectory` entry), falling
+  back to `/run/asd` when running as `root` and `${XDG_RUNTIME_DIR}/asd` when
+  running as a non-`root` user.
 
 `ASDCONFTIMEOUT`
 
@@ -360,6 +369,11 @@ Discover a bug? Please open an issue on the project page linked below.
 - Project page: https://github.com/graysky2/anything-sync-daemon
 - Wiki page: https://wiki.archlinux.org/index.php/Anything-sync-daemon
 
+# SEE ALSO
+
+`bash`(1), `cron`(8), `crontab`(1), `crontab`(5), `mount`(5),
+`systemd.exec`(5), `systemd.service`(5), `systemd.timer`(5), `systemd.unit`(5)
+
 # AUTHOR
 
 graysky (graysky AT archlinux DOT us)

doc/asd.1

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 2.19.2
+.\" Automatically generated by Pandoc 3.1.6
 .\"
 .\" Define V font for inline verbatim, using C font in formats
 .\" that render this, and otherwise B font.
@@ -45,7 +45,10 @@ is redirected from the physical disc to RAM, reducing wear to the
 physical disc and improving speed and responsiveness.
 .SH SETUP
 .PP
-\f[V]/etc/asd.conf\f[R] contains all user-managed settings.
+The \f[V]asd\f[R] configuration file contains all user-managed settings.
+See the entry on \f[V]ASDCONF\f[R] in the
+\f[V]ENVIRONMENT VARIABLES\f[R] section for information on the default
+\f[V]asd\f[R] configuration file location.
 The configuration file location can be overridden by specifying a
 pathname in the \f[V]ASDCONF\f[R] environment variable.
 For instance, to load \f[V]asd\f[R] settings from
@@ -57,9 +60,9 @@ $ ASDCONF=/here/for/some/reason/lives/asd.conf asd <subcommand>
 \f[R]
 .fi
 .PP
-\f[B]Note\f[R] that edits made to \f[V]/etc/asd.conf\f[R] while
-\f[V]asd\f[R] is running will be applied only after \f[V]asd\f[R] has
-been restarted.
+\f[B]Note\f[R] that edits made to the \f[V]asd\f[R] configuration file
+while \f[V]asd\f[R] is running will be applied only after \f[V]asd\f[R]
+has been restarted.
 .PP
 In the \f[V]asd\f[R] configuration file, you may define the following
 variables:
@@ -75,7 +78,10 @@ list, \f[V]asd\f[R] will complain and bail out.
 A path that lives on a tmpfs or zram mount.
 This is where \f[V]asd\f[R] will store the data eventually synchronized
 back to the physical disk.
-By default, \f[V]asd\f[R] sets \f[V]VOLATILE=/tmp\f[R].
+By default, when running as \f[V]root\f[R] and \f[V]ASDNOV1PATHS\f[R] is
+unset or set to a false value, \f[V]asd\f[R] sets
+\f[V]VOLATILE=/tmp\f[R].
+Otherwise, \f[V]VOLATILE\f[R] defaults to \f[V]ASDRUNDIR\f[R].
 \f[B]Note\f[R] that it is a fatal error to set \f[V]VOLATILE\f[R] to a
 path that does not live on a tmpfs or zram mount.
 .TP
@@ -97,8 +103,9 @@ keep.
 \f[V]DEBUG\f[R]
 A boolean variable controlling whether to issue debugging output.
 .PP
-\f[B]Note\f[R] that the default value of \f[V]/tmp\f[R] should work just
-fine for the \f[V]VOLATILE\f[R] setting.
+\f[B]Note\f[R] that the default values of
+\f[V]/tmp\f[R]/\f[V]ASDRUNDIR\f[R] should work just fine for the
+\f[V]VOLATILE\f[R] setting.
 If using \f[V]bleachbit\f[R] (https://www.bleachbit.org/), do NOT invoke
 it with the \f[V]--clean system.tmp\f[R] switch or you will remove a key
 dot file (\f[V].foo\f[R]) from \f[V]/tmp\f[R] that \f[V]asd\f[R] needs
@@ -133,34 +140,42 @@ WHATTOSYNC=(
 .TP
 \f[V]ASDCONF\f[R]
 Path to the \f[V]asd\f[R] configuration file.
-Defaults to \f[V]/etc/asd.conf\f[R] when \f[V]ASDNOV1PATHS\f[R] is
-disabled; otherwise, defaults to \f[V]${ASDCONFDIR}/asd.conf\f[R].
+Defaults to \f[V]/etc/asd.conf\f[R] when \f[V]asd\f[R] is running as
+\f[V]root\f[R] and \f[V]ASDNOV1PATHS\f[R] is unset or set to a false
+value; otherwise, defaults to \f[V]${ASDCONFDIR}/asd.conf\f[R].
 .TP
 \f[V]ASDNOV1PATHS\f[R]
 A boolean variable controlling whether to use \[lq]version 1\[rq] paths
 or not.
-When set to a false value, \f[B]FIXME\f[R].
+When set to a false value, \f[V]asd\f[R] will use old-style defaults for
+its daemon file (\f[V]/run/asd\f[R]), lock file
+(\f[V]/run/asd-lock\f[R]), and configuration file
+(\f[V]/etc/asd.conf\f[R]).
 \f[B]NOTE\f[R] that this variable is ignored when \f[V]asd\f[R] is
 running as a non-\f[V]root\f[R] user.
 Defaults to disabled (effectively, \f[V]ASDNOV1PATHS=0\f[R]).
 .TP
 \f[V]ASDCONFDIR\f[R]
 Parent directory of \f[V]asd.conf\f[R] if \f[V]ASDCONF\f[R] is not
 defined.
-Ignored when running as \f[V]root\f[R] and \f[V]ASDNOV1PATHS\f[R] is set
-to a false value.
-Otherwise, defaults to \f[V]CONFIGURATION_DIRECTORY\f[R] (which is set
-when \f[V]asd\f[R] runs under systemd), falling back to
-\f[V]/etc/asd\f[R] when running as \f[V]root\f[R] and
+Ignored when running as \f[V]root\f[R] and \f[V]ASDNOV1PATHS\f[R] is
+unset or set to a false value.
+Otherwise, defaults to the first (leftmost) of the colon-separated paths
+in the \f[V]CONFIGURATION_DIRECTORY\f[R] environment variable (which is
+set when \f[V]asd\f[R] runs under systemd and the \f[V]asd.service\f[R]
+unit defines at least one \f[V]ConfigurationDirectory\f[R] entry),
+falling back to \f[V]/etc/asd\f[R] when running as \f[V]root\f[R] and
 \f[V]${XDG_CONFIG_DIR}/asd\f[R] when running as a non-\f[V]root\f[R]
 user.
 .TP
 \f[V]ASDRUNDIR\f[R]
 Directory where \f[V]asd\f[R] should store runtime state.
-Ignored when running as \f[V]root\f[R] and \f[V]ASDNOV1PATHS\f[R] is set
-to a false value.
-Otherwise, defaults to \f[V]RUNTIME_DIRECTORY\f[R] (which is set when
-\f[V]asd\f[R] runs under systemd), falling back to \f[V]/run/asd\f[R]
+Ignored when running as \f[V]root\f[R] and \f[V]ASDNOV1PATHS\f[R] is
+unset or set to a false value.
+Otherwise, defaults to the first (leftmost) of the colon-separated paths
+in the \f[V]RUNTIME_DIRECTORY\f[R] (which is set when \f[V]asd\f[R] runs
+under systemd and the \f[V]asd.service\f[R] unit defines at least one
+\f[V]RuntimeDirectory\f[R] entry), falling back to \f[V]/run/asd\f[R]
 when running as \f[V]root\f[R] and \f[V]${XDG_RUNTIME_DIR}/asd\f[R] when
 running as a non-\f[V]root\f[R] user.
 .TP
@@ -403,6 +418,12 @@ if a hung process has something open there, it can be messy.
 Project page: https://github.com/graysky2/anything-sync-daemon
 .IP \[bu] 2
 Wiki page: https://wiki.archlinux.org/index.php/Anything-sync-daemon
+.SH SEE ALSO
+.PP
+\f[V]bash\f[R](1), \f[V]cron\f[R](8), \f[V]crontab\f[R](1),
+\f[V]crontab\f[R](5), \f[V]mount\f[R](5), \f[V]systemd.exec\f[R](5),
+\f[V]systemd.service\f[R](5), \f[V]systemd.timer\f[R](5),
+\f[V]systemd.unit\f[R](5)
 .SH AUTHOR
 .PP
 graysky (graysky AT archlinux DOT us)