update docs

10 files changed, 199 insertions, 157 deletions

diff --git a/src/abslibre-tools/librerelease b/src/abslibre-tools/librerelease
index 83898af..62ba6b7 100755
--- a/src/abslibre-tools/librerelease
+++ b/src/abslibre-tools/librerelease
@@ -129,6 +129,14 @@ usage() {
   print "Usage: %s [OPTIONS]" "${0##*/}"
   print 'Upload packages in $WORKDIR/staging to the Parabola server'
   echo
+  prose 'By default, `librerelease` expects the runtime-determined `$LIBREUSER`,
+         to match the hackers.git login for which $LIBREUSER has credentials.
+         $LIBREUSER is normally the current local login; but may be
+         over-ridden by setting $SUDO_USER in the environment.
+         If no local logins exist, which match your hackers.git login,
+         you can specify `$REPOUSER` as the remote login for `librerelease`,
+         in the `configuration` section of /usr/lib/libretools/conf.sh,'
+  echo
   print "Options:"
   flag '-c'            'Clean; delete packages in $WORKDIR/staging'
   flag '-l'            "List; list packages but not upload them"
@@ -290,6 +298,7 @@ release_packages() {
   fi
 
   msg "Running db-update on repos"
+  # eg: ssh -p 1863 autobuilder@repo.parabola.nu STAGING='staging/' DBSCRIPTS_CONFIG='/etc/dbscripts/config.local.parabola' db-update
   ssh ${REPODEST_port:+-p "$REPODEST_port"} "${REPODEST_userhost}" "STAGING=${REPODEST_path@Q} DBSCRIPTS_CONFIG=${DBSCRIPTS_CONFIG@Q} db-update"
 
   if [[ -n $HOOKPOSTRELEASE ]]; then
diff --git a/src/chroot-tools/chcleanup.in b/src/chroot-tools/chcleanup.in
index 5655597..f6a08c2 100644
--- a/src/chroot-tools/chcleanup.in
+++ b/src/chroot-tools/chcleanup.in
@@ -1,13 +1,12 @@
 #!/usr/bin/env bash
 set -eE
+
+# Performs chroot cleanup smartly.
+# Removes all and only non-essential packages, leaving a clean base-devel system.
+#
 # Copyright (C) 2011-2012 Nicolás Reynolds <fauno@parabola.nu>
 # Copyright (C) 2012-2013, 2015, 2017-2018 Luke Shumaker <lukeshu@parabola.nu>
 #
-# If you don't see m4_include(...) below, but see function definitions
-# for msg() et al., then this is a generated file, and contains some
-# code from librelib.  See the source distribution for full copyright
-# information.
-#
 # License: GNU GPLv3+
 #
 # This program is free software: you can redistribute it and/or modify
@@ -22,9 +21,13 @@ set -eE
 #
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-# Performs chroot cleanup smartly, it only removes the unneeded packages or
-# leaves you with a clean system
+#
+#
+# License Note:
+# If you don't see m4_include(...) below, but see function definitions
+# for msg() et al., then this is a generated file, and contains some
+# code from librelib.  See the source distribution for full copyright
+# information.
 
 
 ## Library Routines ##
diff --git a/src/chroot-tools/chroot.conf b/src/chroot-tools/chroot.conf
index e9218f4..754c408 100644
--- a/src/chroot-tools/chroot.conf
+++ b/src/chroot-tools/chroot.conf
@@ -2,15 +2,14 @@
 # shellcheck disable=2034
 
 
-# The full path to the chroot is
-#   $CHROOTDIR/$CHROOT/$COPY
-# where $COPY is set at runtime.
+# The full path to the chroot is of the form: $CHROOTDIR/$CHROOT/$COPY,
+#   where $COPY is set at runtime, with $CHROOT as the default.
 # See `librechroot help` for details.
 CHROOTDIR=/var/lib/archbuild
 CHROOT=default
 
-# Extra packages to have installed on the chroot.
-# This is in addition to CHROOTPKG=(base-devel)
+# Extra packages to have installed on the chroot,
+# in addition to CHROOTPKG (standard 'base' + 'base-devel')
 CHROOTEXTRAPKG=()
 #CHROOTEXTRAPKG+=(distcc-nozeroconf socat) # for BUILDENV+=(distcc)
 #CHROOTEXTRAPKG+=(ccache) # for BUILDENV+=(ccache)
diff --git a/src/chroot-tools/librechroot b/src/chroot-tools/librechroot
index f57c2cc..9367ef8 100755
--- a/src/chroot-tools/librechroot
+++ b/src/chroot-tools/librechroot
@@ -210,106 +210,120 @@ mkarchroot() {
 # Main program                                                                 #
 ################################################################################
 
-readonly DEF_PACMANCONF_DIR=/usr/share/pacman/defaults/
+readonly DEF_PACMANCONF_DIR=/usr/share/pacman/defaults
 
 
 usage() {
   eval "$(calculate_directories)"
+
   print "Usage: %s [OPTIONS] COMMAND [ARGS...]" "${0##*/}"
-  print 'Interacts with an archroot (arch chroot).'
-  echo
-  prose 'This is configured with `chroot.conf`, either in
-         `/etc/libretools.d/`, or `$XDG_CONFIG_HOME/libretools/`.
-         The variables you may set are $CHROOTDIR, $CHROOT, and
-         $CHROOTEXTRAPKG.'
   echo
-  prose 'There may be multiple chroots; they are stored in $CHROOTDIR.'
+  print 'Interacts with a libre "archroot" (similarly to `arch-chroot`).'
   echo
-  prose 'Each chroot is named; the default is configured with $CHROOT.'
+  prose 'This is configured with `chroot.conf`,
+         either in `/etc/libretools.d/`, or `$XDG_CONFIG_HOME/libretools/`.
+         The configurable variables are:'
+  bullet   '$CHROOTDIR'
+  bullet   '$CHROOT'
+  bullet   '$CHROOTEXTRAPKG'
   echo
-  prose 'Each named chroot has a master clean copy (named `root`), and any
-         number of other named copies; the copy used by default is the
-         current username (or $SUDO_USER, or `copy` if root).'
+  prose 'Each chroot is named; and there may be multiple chroots; all of which,
+         are stored in $CHROOTDIR, with the default chroot name being: $CHROOT.
+         Each named chroot has a pristine, read-only master system (`root`),
+         which is used as the seed for any number of named working copies,
+         which may be derived from it.
+         If a working copy is not specified, the default is the $LIBREUSER,
+         determined at runtime, per /usr/lib/libretools/conf.sh.
+         $LIBREUSER is normally the current local login; but may be
+         over-ridden by setting $SUDO_USER in the environment.'
   echo
-  prose 'The full path to the chroot copy is "$CHROOTDIR/$CHROOT/$COPY",
-         unless the copy name is manually specified as an absolute path,
-         in which case, that path is used.'
+  prose 'Unless the working copy is manually specified as an absolute path,
+         the path to the working copy ($copydir) will determined at runtime:'
+  print '  $CHROOTDIR/$CHROOT/$COPY'
   echo
   prose 'The current settings for the above variables are:'
-  printf '    CHROOTDIR : %s\n' "${CHROOTDIR:-$(_ 'ERROR: NO SETTING')}"
-  printf '    CHROOT    : %s\n' "${CHROOT:-$(_ 'ERROR: NO SETTING')}"
-  printf '    COPY      : %s\n' "$COPY"
-  printf '    rootdir   : %s\n' "${rootdir:-$(_ 'ERROR')}"
-  printf '    copydir   : %s\n' "${copydir:-$(_ 'ERROR')}"
+  bullet  "\$CHROOTDIR : %s" "${CHROOTDIR:-$(_ 'ERROR: NO SETTING')}"
+  bullet  "\$CHROOT    : %s" "${CHROOT:-$(   _ 'ERROR: NO SETTING')}"
+  bullet  "\$COPY      : %s" "${COPY}"
+  bullet  "\$rootdir   : %s" "${rootdir:-$(  _ 'ERROR'            )}"
+  bullet  "\$copydir   : %s" "${copydir:-$(  _ 'ERROR'            )}"
   echo
-  prose "If the chroot or copy does not exist, it will be created
-         automatically.  A chroot by default contains the packages in the
-         group 'base-devel' and any packages named in \$CHROOTEXTRAPKG.
-         However, for technical reasons, 'fakeroot-tcp' replaces 'fakeroot'
-         in armv7h chroots (BR #2775)."
-  echo
-  prose  'Unless the `-C` or `-M` flags are used, the configuration files
-         that this program installs are the stock versions supplied in the
-         packages, not the versions from your host system.  Other tools
-         (such as libremakepkg) may alter the configuration.'
+  prose 'If the chroot-set or working copy does not exist, it will be created
+         automatically. A chroot by default contains the packages in the
+         `base-devel` group and any packages named in $CHROOTEXTRAPKG.
+         However, for technical reasons, `fakeroot-tcp` replaces `fakeroot`
+         in armv7h chroots (per BR #2775).
+         The packages installed into the chroot, will be those found
+         in the standard Parabola repos: (libre, core, extra, community, pcr),
+         regardless of the pacman/makepkg configuration of the host system.
+         The configuration files in the chroot will also be the standard ones
+         installed by the `pacman` package.
+         These defaults may be over-ridden with the `-C`, `-M`, and `-A` flags;
+         and other tools (such as `libremakepkg`) may over-ride them later.'
   echo
   prose 'This command will make the following configuration changes in the
          chroot:'
   bullet   'overwrite `/etc/libretools.d/chroot.conf`' # libretools/librechroot
   bullet   'overwrite `/etc/pacman.d/mirrorlist`'      # devtools/arch-nspawn
   bullet   'set `CacheDir` in `/etc/pacman.conf`'      # devtools/arch-nspawn
-  prose 'If a new `pacman.conf` is inserted with the `-C` flag, the change
-         is made after the file is copied in; the `-C` flag doesn'"'"'t
-         stop the change from being effective.'
+  prose 'If an over-ride `pacman.conf` is specified with the `-C` flag,
+         the changes above are made after the file is copied in.
+         The `-C` flag will not prevent these modifications.'
   echo
-  prose 'The processor architecture of the chroot is determined
-         by the by `CARCH` variable in the `/etc/makepkg.conf`
-         file inside of the chroot.'
+  prose 'The processor architecture of the chroot is determined by the `$CARCH`
+         variable, in the `/etc/makepkg.conf` file, inside of the chroot.
+         The `-M` flag allows specifying an over-ride of the standard file.'
   echo
-  prose 'The `-A CARCH` flag is *almost* simply an alias for'
-  printf '    %s\n'                                             \
-         "-C \"${DEF_PACMAN_CONF_DIR}pacman.conf.\$CARCH\"  \\" \
-         "-M \"${DEF_PACMAN_CONF_DIR}makepkg.conf.\$CARCH\""
-  prose 'However, before doing that, it actually makes a temporary copy of
-         `pacman.conf`, and modifies it to:'
-  bullet   'set `Architecture` to match the `CARCH` line in `makepkg.conf`'
-  bullet   'comment out any `Include = /etc/pacman.d/*.conf` lines'
+  print 'The `-A <CARCH>` flag sets the -C and -M flags as:'
+  echo    "  -C \"${DEF_PACMANCONF_DIR}/pacman.conf.\$CARCH\"  \\"
+  echo    "  -M \"${DEF_PACMANCONF_DIR}/makepkg.conf.\$CARCH\""
+  prose 'However, `pacman.conf` will be modified to:'
+  bullet   'set `Architecture` to match the `CARCH=` line in `makepkg.conf`'
+  bullet   'comment-out any `Include = /etc/pacman.d/*.conf` lines'
+  bullet   'add special-case build support repos (commented-out)'
+  prose 'The `-A` option is recommended for creating a new `root` seed, e.g.:'
+  echo  '  sudo librechroot -n i686 -A i686 make'
   echo
-  prose 'Creating a copy, deleting a copy, or syncing a copy can be fairly
-         slow; but are very fast if $CHROOTDIR is on a btrfs partition.'
+  prose 'Creating/deleting/synchronizing a copy, can be relatively slow;
+         but can be very fast, if $CHROOTDIR is on a btrfs partition.'
   echo
-  print 'Options:'
-  flag "-n <$(_ CHROOT)>" 'Name of the chroot to use'
-  flag "-l <$(_ COPY)>"   'Name of, or absolute path to, the copy to use'
-  flag '-N'               'Disable networking in the chroot'
-  flag "-C <$(_ FILE)>"   'Copy this file to `$copydir/etc/pacman.conf`'
-  flag "-M <$(_ FILE)>"   'Copy this file to `$copydir/etc/makepkg.conf`'
-  flag "-A <$(_ CARCH)>"  'Set the architecture of the copy; simply an
-                           alias for the `-C` and `-M` flags, see above.'
-  flag "-w <$(_ 'PATH[:INSIDE_PATH[:OPTIONS]]')>" 'Bind mount a file or directory, read/write'
-  flag "-r <$(_ 'PATH[:INSIDE_PATH[:OPTIONS]]')>" 'Bind mount a file or directory, read-only'
+  flag 'Options:'                                                               \
+         "-n <$(_ NAME)>"   'Name of the chroot to use'                         \
+         "-l <$(_ COPY)>"   'Name of, or absolute path to, the copy to use'     \
+         "-C <$(_ FILE)>"   'Copy this file to chroot as: `/etc/pacman.conf`
+                             This option is mutually exclusive with -A.'        \
+         "-M <$(_ FILE)>"   'Copy this file to chroot as: `/etc/makepkg.conf`
+                             This option is mutually exclusive with -A.'        \
+         "-A <$(_ CARCH)>"  'Specify the architecture of a new `root` seed.
+                             This option is mutually exclusive with -C and -M.' \
+         "-N"               'Disable networking in the chroot'                  \
+         "-w <$(_ 'PATH[:INSIDE_PATH[:OPTIONS]]')>" 'Bind mount a file or
+                                                     directory, read/write'     \
+         "-r <$(_ 'PATH[:INSIDE_PATH[:OPTIONS]]')>" 'Bind mount a file or
+                                                     directory, read-only'
   echo
-  print 'Commands:'
-  print ' Create/copy/delete:'
-  flag 'noop|make'       'Do not do anything, but still creates the chroot
-                          copy if it does not exist'
-  flag 'sync'            'Sync the copy with the clean (`root`) copy'
-  flag 'delete'          'Delete the chroot copy'
-  print ' Dealing with packages:'
-  flag "install-file $(_ FILES...)"       'Like `pacman -U FILES...`'
-  flag "install-name $(_ NAMES...)"       'Like `pacman -S NAMES...`'
-  flag 'update'                           'Like `pacman -Syu`'
-  flag 'clean-pkgs'      'Remove all packages from the chroot copy that
-                          are not in base-devel, $CHROOTEXTRAPKG, or named
-                          as a dependency in the file `/startdir/PKGBUILD`
-                          in the chroot copy; and install all packages
-                          that are.'
-  print ' Other:'
-  flag "run $(_ CMD...)" 'Run CMD in the chroot copy'
-  flag 'enter'           'Enter an interactive shell in the chroot copy'
-  flag 'clean-repo'      'Clean /repo in the chroot copy'
-  flag 'help'            'Show this message'
+  flag 'Commands (create/copy/delete):'                      \
+         'make'   'Create a `root` seed and working copy'    \
+         'sync'   'Sync the copy with the clean `root` seed' \
+         'delete' 'Delete the working copy'
+  flag 'Commands (packages):'                                                    \
+         "install-file $(_ FILES...)" 'Like `pacman -U FILES...`'                \
+         "install-name $(_ NAMES...)" 'Like `pacman -S NAMES...`'                \
+         'update'                     'Like `pacman -Syu`'                       \
+         'clean-pkgs'                 'Remove all packages from the working copy
+                                       that are not in `base-devel`,
+                                       $CHROOTEXTRAPKG, or in the depends array
+                                       of the working copy /startdir/PKGBUILD;
+                                       and install all packages that are.
+                                       `libremakepkg` does this implicitly.'
+  flag 'Commands (maintenance):'                                            \
+         "run $(_ CMD...)" 'Run CMD in the working copy'                    \
+         'enter'           'Enter an interactive shell in the working copy' \
+         'clean-repo'      'Clean /repo in the working copy'
+  flag 'Commands (misc):'           \
+         'help' 'Show this message'
 }
+
 readonly commands=(
   noop make sync delete
   install-file install-name update clean-pkgs
@@ -340,20 +354,20 @@ main() {
 
   while getopts 'n:l:NC:M:A:w:r:' opt; do
     case $opt in
-      n  ) CHROOT=$OPTARG                                                     ;;
-      l  ) COPY=$OPTARG                                                       ;;
-      N  ) sysd_nspawn_flags+=(--private-network)                             ;;
+      n  ) CHROOT=$OPTARG                                                      ;;
+      l  ) COPY=$OPTARG                                                        ;;
+      N  ) sysd_nspawn_flags+=(--private-network)                              ;;
       C|M) target_arch=$(detect_chroot_arch "$OPTARG")
-           arch_nspawn_flags+=(-$opt "$OPTARG")                               ;;
+           arch_nspawn_flags+=(-$opt "$OPTARG")                                ;;
       A  ) target_arch=$OPTARG
-           def_pacmanconf="${DEF_PACMANCONF_DIR}"pacman.conf.${target_arch}
-           def_makepkgconf="${DEF_PACMANCONF_DIR}"makepkg.conf.${target_arch}
+           def_pacmanconf="${DEF_PACMANCONF_DIR}"/pacman.conf.${target_arch}
+           def_makepkgconf="${DEF_PACMANCONF_DIR}"/makepkg.conf.${target_arch}
            arch_nspawn_flags+=( -C "${tmp_pacmanconf}"
                                 -M "${def_makepkgconf}" )
-           has_tmp_pacmanconf=1                                               ;;
-      w  ) sysd_nspawn_flags+=("--bind=$OPTARG")                              ;;
-      r  ) sysd_nspawn_flags+=("--bind-ro=$OPTARG")                           ;;
-      *  ) usage >&2; return $EXIT_INVALIDARGUMENT                            ;;
+           has_tmp_pacmanconf=1                                                ;;
+      w  ) sysd_nspawn_flags+=("--bind=$OPTARG")                               ;;
+      r  ) sysd_nspawn_flags+=("--bind-ro=$OPTARG")                            ;;
+      *  ) usage >&2; return $EXIT_INVALIDARGUMENT                             ;;
     esac
     used_opts[$opt]+=1
   done
@@ -435,7 +449,7 @@ main() {
   if (( has_tmp_pacmanconf ))                               && \
      ! [[ -f "${def_pacmanconf}" && -f "${def_makepkgconf}" ]]; then
     error 'Unsupported architecture: %s' "${target_arch}"
-    plain 'See the files in %q for valid architectures.' "${DEF_PACMANCONF_DIR}"
+    plain 'See the files in %q for valid architectures.' "${DEF_PACMANCONF_DIR}/"
     return $EXIT_INVALIDARGUMENT;
   fi
 
diff --git a/src/chroot-tools/libremakepkg b/src/chroot-tools/libremakepkg
index 41aa74e..20fcb6a 100755
--- a/src/chroot-tools/libremakepkg
+++ b/src/chroot-tools/libremakepkg
@@ -142,21 +142,26 @@ build() (
 # The main program #############################################################
 
 usage() {
+  local mount_msg="$(_ 'PATH[:INSIDE_PATH[:OPTIONS]]')"
+
   print "Usage: %s [options]" "${0##*/}"
   print 'This program will build your package.'
   echo
   prose 'If run from outside of a chroot, this command will make the
          following configuration changes in the chroot:'
-  bullet 'whatever changes `librechroot` makes.'
+  bullet 'whatever changes `librechroot` makes'
   bullet 'set `{PKG,SRC,SRCPKG,LOG}DEST` in `/etc/makepkg.conf`'
   bullet 'set `MAKEFLAGS` and `PACKAGER` in `/etc/makepkg.conf` to reflect
-          the value outside of the chroot.'
-  bullet 'create a `builduser` with the same numeric UID as the
-          invoking $SUDO_USER.'
-  bullet 'let this `builduser` call `sudo pacman` without a password.'
+          the value outside of the chroot'
+  bullet 'create a `builduser` with the same numeric UID as $LIBREUSER'
+  bullet 'let this `builduser` call `sudo pacman` without a password'
   bullet 'set `keyserver-options` in `~builduser/.gnupg/gpg.conf`'
-  bullet "copy the user's GnuPG pubring to be the \`builduser\`'s pubring"
+  bullet 'copy the GPG pubring of the host $LIBREUSER,
+          as the GPG pubring of the chroot `builduser`'
   bullet 'add a pacman repositoriy of locally built packages'
+  prose '$LIBREUSER is determined at runtime, per /usr/lib/libretools/conf.sh.
+         $LIBREUSER is normally the local login of the invoking user;
+          but may be over-ridden by setting $SUDO_USER in the environment.'
   echo
   prose 'This command is configured both with `chroot.conf` (either in
          `/etc/libretools.d/` or `$XDG_CONFIG_HOME/libretools/`), and with
@@ -164,24 +169,22 @@ usage() {
          environment variables for {SRC,SRCPKG,PKG,LOG}DEST, MAKEFLAGS and
          PACKAGER override the settings in makepkg.conf(5).'
   echo
-  prose 'The `-n` and `-l` options behave identically to librechroot, see
-         the documentation there.'
+  prose 'The `-n` and `-l` options behave identically to librechroot (see
+         the librechroot documentation).'
   echo
-  print 'Options:'
-  flag 'librechroot options:' \
-       "-n <$(_ CHROOT)>"                          'Name of the chroot to use' \
-       "-l <$(_ COPY)>"                            'Name of, or absolute path to, the chroot copy to use' \
-       "-w <$(_ 'PATH[:INSIDE_PATH[:OPTIONS]]')>"  'Bind mount a file or directory, read/write' \
-       "-r <$(_ 'PATH[:INSIDE_PATH[:OPTIONS]]')>"  'Bind mount a file or directory, read-only'
-  flag 'libremakepkg options:' \
-       '-N'                   "Don't disable networking during prepare(),
-                               build(), and package().  PLEASE don't use
-                               this unless you have a special reason, its
-                               use is a violation of Parabola policy." \
-       '-R'                   'Repackage contents of the package without
-                               rebuilding' \
-       "-S <$(_ SRCPKGFILE)>" 'Use an existing --allsource source-package' \
-       '-h'                   'Show this message'
+  flag 'Options (librechroot):'                                                   \
+       "-n <$(_ NAME)>"    'Name of the chroot to use'                            \
+       "-l <$(_ COPY)>"    'Name of, or absolute path to, the chroot copy to use' \
+       "-w <${mount_msg}>" 'Bind mount a file or directory, read/write'           \
+       "-r <${mount_msg}>" 'Bind mount a file or directory, read-only'
+  flag 'Options (libremakepkg):'                                               \
+       '-N'             "Don't disable networking during prepare(),
+                         build(), and package().  PLEASE don't use
+                         this unless you have a special reason, its
+                         use is a violation of Parabola policy."               \
+       '-R'             'Repackage contents of the package without rebuilding' \
+       "-S <$(_ FILE)>" 'Use an existing --allsource source-package'           \
+       '-h'             'Show this message'
 }
 
 # Convenience method for use in option parsing
diff --git a/src/lib/messages.sh b/src/lib/messages.sh
index 283102d..a43533a 100644
--- a/src/lib/messages.sh
+++ b/src/lib/messages.sh
@@ -113,8 +113,8 @@ bullet() {
 #   ex: flag '-C <FILE>' 'Use this file instead of pacman.conf'
 #
 # The descriptions and headings are fed through gettext, the flags ar
-# not, so if part of a flag needs to be translated, you must do that
-# yourself:
+# not, so if part of a flag needs to be translated, you must handle
+# that explicitly, using $(_ <MSGID_STRING>):
 #
 #   ex: flag "-C <$(_ FILE)>" 'Use this file instead of pacman.conf'
 #
diff --git a/src/librefetch/librefetch b/src/librefetch/librefetch
index e91e58a..bc9d57d 100755
--- a/src/librefetch/librefetch
+++ b/src/librefetch/librefetch
@@ -65,7 +65,7 @@ usage() {
   prose "In create mode, it either looks at a build script and uses that
          to create the source tarball, or it uses GPG to create a
          signature (if OUTPUT_FILE ends with \`.sig\` or \`.sig.part\`).
-         If it is using GPG to create a signature, but the file that it is
+         If it is using GPG to create a signature, but the file which it is
          trying to sign doesn't exist yet, it recurses on itself to first
          create that file.  SOURCE_URL is ignored, except that it is used
          to set the default value of OUTPUT_FILE, and that it may be used
@@ -80,18 +80,17 @@ usage() {
   print "Example usage:"
   print '  $ %s https://repo.parabola.nu/other/mypackage/mypackage-1.0.tar.gz' "$cmd"
   echo
-  print "Options:"
-  flag 'Settings:' \
-       "-C"               "Force create mode (don't download)" \
-       "-D"               "Force download mode (don't create)" \
+  flag 'Options (behavior):'                                               \
+       "-C"               "Force create mode (don't download)"             \
+       "-D"               "Force download mode (don't create)"             \
        "-p <$(_ FILE)>"   "Use an alternate build script (instead of
                            'PKGBUILD').  If an SRCBUILD exists in the same
-                           directory, it is used instead" \
-       'Alternate modes:' \
-       "-g, --geninteg"   "Generate integrity checks for source files" \
-       "-S, --srcbuild"   "Print the effective build script (SRCBUILD)" \
+                           directory, it is used instead"
+  flag 'Options (reports):'                                                \
+       "-g, --geninteg"   "Generate integrity checks for source files"     \
+       "-S, --srcbuild"   "Print the effective build script (SRCBUILD)"    \
        "-M, --makepkg"    "Generate and print the location of the
-                           effective makepkg script" \
+                           effective makepkg script"                       \
        "-h, --help"       "Show this message"
 }
 
@@ -399,7 +398,6 @@ create_signature() {
 
   gpg --detach-sign --use-agent "${SIGNWITHKEY[@]}" --no-armor "$filename" &>/dev/null || ret=$EXIT_FAILURE
 
-
   if (( ! ret )); then
     msg2 "Created signature file %s." "$filename.sig"
   else
diff --git a/src/librefetch/librefetch-install b/src/librefetch/librefetch-install
index 5f4fd82..a582b43 100755
--- a/src/librefetch/librefetch-install
+++ b/src/librefetch/librefetch-install
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
-# lirefetch-install: (un)install librefetch to /etc/makepkg.conf
+#
+# lirefetch-install: uninstall librefetch from /etc/makepkg.conf
 #
 # Copyright (C) 2013-2015, 2017 Luke Shumaker <lukeshu@parabola.nu>
 #
@@ -19,6 +20,23 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Parabola. If not, see <http://www.gnu.org/licenses/>.
+#
+#
+# NOTE: primarily, this is called by the libretools.install hooks
+#
+# NOTE: this script originally accepted an 'install' option to munge makepkg.conf in place
+#         by the libretools.install hooks
+#       that behavior was replaced by the runtime script: /etc/makepkg.d/librefetch.conf
+#         (source: libretools::src/librefetch/makepkg-librefetch.conf.in),
+#         which must be sourced by makepkg.conf in order to enable mksource() handling
+#         (see `man librefetch`)
+#
+#       note that this is not the 'librefetch.conf' sourced by librefetch and librestage
+#         (see `man 5 librefetch.conf`)
+#       that one is: /etc/libretools.d/librefetch.conf
+#         (source: libretools::src/librefetch/librefetch.conf)
+#       TODO: one of those should be renamed, to avoid the name collision/confusion
+
 
 
 set -ueE
diff --git a/src/pkgbuild-summarize-nonfree b/src/pkgbuild-summarize-nonfree
index dd063bc..d622cf6 100755
--- a/src/pkgbuild-summarize-nonfree
+++ b/src/pkgbuild-summarize-nonfree
@@ -32,7 +32,7 @@ declare -ri _E_PKG_NONFREE=32
 
 usage() {
   print "Usage: %s [OPTIONS] STATUS" "${0##*/}"
-  print "Summarizes a status code from pkgbuild-check-nonfree"
+  print 'Summarizes a freedom-status code from `pkgbuild-check-nonfree`'
   echo
   prose 'It thresholds the issues it finds, only failing for error-level
          issues, and ignoring warnings.  Unless `-q` is specified, it also
@@ -90,13 +90,13 @@ parse() {
         $_E_LIC_NOGPL)
           warning "This PKGBUILD has a GPL-incompatible license";;
         $_E_LIC_NONFREE)
-          error "This PKGBUILD has a known nonfree license"
+          error "This PKGBUILD has a non-free license"
           ret=$EXIT_FAILURE;;
         $_E_DEP_NONFREE)
-          error "This PKGBUILD depends on known nonfree packages"
+          error "This PKGBUILD depends on blacklisted package(s)"
           ret=$EXIT_FAILURE;;
         $_E_PKG_NONFREE)
-          error "This PKGBUILD is for a known nonfree package"
+          error "This PKGBUILD is for a blacklisted package"
           ret=$EXIT_FAILURE;;
       esac
     fi
diff --git a/src/toru/toru-path b/src/toru/toru-path
index 0d3fc70..92a4566 100755
--- a/src/toru/toru-path
+++ b/src/toru/toru-path
@@ -30,27 +30,25 @@ usage() {
   print 'Create/update the `$TORUPATH/paths.tch` database.'
   echo
   prose 'The file `%s` is a Tokyo Cabinet database a mapping between paths
-         to PKGBUILD files and `pkgname`s and `pkgbase`s.  PKGBUILD files
-         are scanned for in `$ABSROOT` in each of `$REPOS`.' \
-           '$TORUPATH/paths.tch'
+         to PKGBUILD files and `pkgname`s and `pkgbase`s.  PKGBUILD files are
+         scanned for in `$ABSROOT` in each of `$REPOS`.' '$TORUPATH/paths.tch'
   echo
   prose 'Additionally, it creates a timestamp file at `%s`, so that skip
          PKGBUILD files that have not changed since the previous
-         invocation.' \
-           '$TORUPATH/lastsync.paths'
+         invocation.' '$TORUPATH/lastsync.paths'
   echo
-  print 'Configuration:'
-  flag \
-    'libretools.conf : TORUPATH' 'Where to store `paths.tch`' \
-    'libretools.conf : REPOS'    'Which repositories to consider from `$ABSROOT`' \
-    'abs.conf : ABSROOT'         'Where to find PKGBUILD files'
+  flag 'Configuration:'                                                             \
+       'libretools.conf::TORUPATH' 'Where to store `paths.tch`'                     \
+       'libretools.conf::REPOS'    'Which repositories to consider from `$ABSROOT`' \
+       'abs.conf::ABSROOT'         'Where to find PKGBUILD files'
   echo
-  print 'Options:'
-  flag \
-    'T=$TORUPATH' 'Override libretools.conf:TORUPATH' \
-    'V=true'      'Be verbose' \
-    'F=true'      'Ignore timestamps; force re-scan all PKGBUILDs' \
-    '-h'          'Show this message'
+  flag 'Environment:'                                    \
+       'T=$TORUPATH' 'Override libretools.conf:TORUPATH' \
+       'V=true'      'Be verbose'                        \
+       'F=true'      'Ignore timestamps; force re-scan all PKGBUILDs'
+  echo
+  flag 'Options:'               \
+       '-h' 'Show this message'
 }
 
 main() {