Update and improve usage-related docstrings

src/include-bash/pretty.sh

@@ -37,7 +37,13 @@ PRETTY_VERBOSE=${PRETTY_VERBOSE:-false}
 PRETTY=${PRETTY:-plain}
 
 #
-# Usage mode -- set to 'subcommand' to remove first dash
+# Usage display mode
+#
+# How to determine program name for purposes of usage messages.
+#
+# If empty, use basename of "$0".  Set to 'subcommand' to remove first
+# dash (so that `path/to/foo-bar becomes `foo bar` which may make more
+# sense in meta-command scenrarios).  Set to self=NAME to force NAME.
 #
 PRETTY_USAGE=${PRETTY_USAGE:-}
 
@@ -131,12 +137,6 @@ mkusage() {
     #
     # Use "--" to delimit end of arguments processed by mkusage.
     #
-    # Setting PRETTY_USAGE to 'subcommand' has effect that
-    # in each call, first hyphen in the script's "own" name is
-    # replaced by space; this is used for git-like sub-commands,
-    # where the actual binary name is e.g. "git-add" for
-    # "git add".
-    #
     # Recommended usage is to define usage() in your script and
     # use this in its body.  That way you only need to define
     # usage patterns once and skip to them from any place where
@@ -456,7 +456,7 @@ _pretty__echo_usage() {
     #
     #  *  usage mode (`-u`, active by default), prints
     #     "usage:" header, indents next arguments and prefixes
-    #     them with name of the script.
+    #     them with name of the script.  See also $PRETTY_USAGE.
     #
     #     A special case of usage mode is when only single
     #     argument is passed to this function; then instead