sq - docs

3 files changed, 35 insertions, 29 deletions

diff --git a/HACKING/translations.md b/HACKING/translations.md
index 09de59b..2229d2a 100644
--- a/HACKING/translations.md
+++ b/HACKING/translations.md
@@ -77,19 +77,20 @@ line pair in the `msgmerge` output, with the new text as 'msgid', and an empty
 'msgstr'; but the changes were too significant for the tool to determine the
 correlation. The standard output of `msgmerge` is the raw text for a new
 replacemnt .po file. Next, direct the output to a file, make the corrections
-to the replacemnt .po file, using the `msgmerge` output as a guide. A merge tool
-such as `meld`, is especially helpful for this task. A merge tool should
-highlight the same merge conflicts, shown in the the `msgmerge` output, as a
-side-by-side comparison. You want to merge all of the changes, including line
-numbers (eg: # src/chroot-tools/libremakepkg:42)
+to the replacemnt .po file, using the `msgmerge` output as a guide; then replace
+the failed .po file with the new corrected file.
 
     $ msgmerge po/es/libretools.po po/libretools.pot > po/es/libretools.po-merged
-    $ meld po/es/libretools.po{-merged,}
+    $ mv po/es/libretools.po{-merged,}
 
-Then delete the failed .po file, which is under sorce control, replace it with
-the new corrected file.
+Alternatively, a merge tool such as `meld`, is especially helpful for this task.
+A merge tool should highlight the same merge conflicts, shown in the the
+`msgmerge` output, as a side-by-side comparison, allowing you to merge the
+changes from the generated '-merged' file, into the tracked .po file, in-place.
+In order to minimize the possible merge conflict next time, it is best to merge
+all of the changes, especially the comments with line numbers.
 
-    $ mv po/es/libretools.po{-merged,}
+    $ meld po/es/libretools.po{-merged,}
 
 Once `make clean && make` is able to complete successfully, commit the new .po
 file to the VCS.
diff --git a/src/chroot-tools/librechroot b/src/chroot-tools/librechroot
index 9367ef8..2462f4b 100755
--- a/src/chroot-tools/librechroot
+++ b/src/chroot-tools/librechroot
@@ -216,6 +216,8 @@ readonly DEF_PACMANCONF_DIR=/usr/share/pacman/defaults
 usage() {
   eval "$(calculate_directories)"
 
+  local mount_msg="$(_ 'PATH[:INSIDE_PATH[:OPTIONS]]')"
+
   print "Usage: %s [OPTIONS] COMMAND [ARGS...]" "${0##*/}"
   echo
   print 'Interacts with a libre "archroot" (similarly to `arch-chroot`).'
@@ -287,20 +289,18 @@ usage() {
   prose 'Creating/deleting/synchronizing a copy, can be relatively slow;
          but can be very fast, if $CHROOTDIR is on a btrfs partition.'
   echo
-  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'
+  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 <${mount_msg}>" 'Bind mount a file or directory, read/write'        \
+         "-r <${mount_msg}>" 'Bind mount a file or directory, read-only'
   echo
   flag 'Commands (create/copy/delete):'                      \
          'make'   'Create a `root` seed and working copy'    \
diff --git a/src/lib/messages.sh b/src/lib/messages.sh
index a43533a..b96c637 100644
--- a/src/lib/messages.sh
+++ b/src/lib/messages.sh
@@ -106,15 +106,20 @@ bullet() {
 	printf -- "$mesg" "$@" | fmt -u -w 71 | sed -e '1s/^/  - /' -e '2,$s/^/    /'
 }
 
-# Usage: flag [FLAG DESCRIPTION|HEADING:]...
+# Usage: flag |HEADING:] [FLAG DESCRIPTION [FLAG DESCRIPTION]...]
 #
-# Print a flag and description formatted for --help text.
+# Print formatted for --help text, a heading, to preceed a (possibly empty)
+# list of flags and their description, or a list of flags and descriptions,
+# with an optional heading.
 #
-#   ex: flag '-C <FILE>' 'Use this file instead of pacman.conf'
+#   ex: flag 'Options:' '-C <FILE>' 'Use this file instead of pacman.conf'
+#   ex: flag 'Options:'
+#       flag '-C <FILE>' 'Use this file instead of pacman.conf' \
+#            '-n <NAME>' 'Name of the chroot to use'
 #
-# The descriptions and headings are fed through gettext, the flags ar
-# not, so if part of a flag needs to be translated, you must handle
-# that explicitly, using $(_ <MSGID_STRING>):
+# The headings and descriptions are fed through gettext; but the flags are not.
+# If part of a flag needs to be translated, you must handle that explicitly,
+# using the translation helper directly, of the form $(_ <MSGID_STRING>).
 #
 #   ex: flag "-C <$(_ FILE)>" 'Use this file instead of pacman.conf'
 #