gsu: Improve documentation of gsu_getopts().

[gsu.git] / misc / gsu / subcommand

diff --git a/misc/gsu/subcommand b/misc/gsu/subcommand
index 5ccb3fc54fd309065482522b67a22c6e292934f2..3a1bc6db6697c7a0676a45ae940b930d18ee8901 100644 (file)
--- a/misc/gsu/subcommand
+++ b/misc/gsu/subcommand
@@ -62,7 +62,7 @@ _gsu_print_available_commands()
 
 gsu_complete_options()
 {
-       local opts="$1" cword="$2" cur
+       local opts="$1" cword="$2" cur opt
        local -a words
 
        shift 2
@@ -115,7 +115,7 @@ _com_prefs()
                local name= option_type= default_value= required=
                local description= help_text=
                eval "${gsu_options[$i]}"
-               eval val='"$'${gsu_config_var_prefix}_$name'"'
+               eval val='"${'${gsu_config_var_prefix}_$name:-'}"'
                case "$required" in
                true|yes)
                        printf "# required"
@@ -186,13 +186,7 @@ _com_man()
 
 _gsu_banner_msg()
 {
-       local txt="### $_gsu_self --"
-       if test -z "$gsu_banner_txt"; then
-               txt="$txt set \$gsu_banner_txt to customize this message"
-       else
-               txt="$txt $gsu_banner_txt"
-       fi
-       gsu_short_msg "$txt ###"
+       gsu_short_msg "### $_gsu_self -- ###"
 }
 
 export gsu_help_txt="
@@ -208,11 +202,13 @@ Command line completion.
 
 Usage: complete [<cword> <word>...]
 
-In the first form, the command prints all possible completions to stdout.
-This can be used from the completion function of the shell.
+When executed without argument the command writes bash code to
+stdout. This code is suitable to be evaled from .bashrc to enable
+completion.
 
-Completion code suitable to be evaled is written to stdout if no argument
-was given.
+If at least one argument is given, all possible completions are
+written to stdout. This can be used from the completion function of
+the subcommand.
 "
 
 _com_help()
@@ -312,21 +308,20 @@ complete_help()
        echo "$result"
 }
 
-# Wrapper for bash's getopts.
+# Wrapper for the bash getopts builtin.
 #
 # Aborts on programming errors such as missing or invalid option string.  On
 # success $result contains shell code that can be eval'ed. For each defined
 # option x, the local variable o_x will be created when calling eval "$result".
-# o_x contains true/false for options without an argument or the emtpy string/the
-# given argument, depending on whether this option was contained in the "$@"
-# array.
+# o_x contains true/false for options without argument and either the emtpy
+# string or the given argument for options that take an argument.
 #
 # Example:
 #      gsu_getopts abc:x:y
 #      eval "$result"
-#      [[ $ret -lt 0 ]] && return
+#      (($ret < 0)) && return
 #
-#      [[ "$o_a" = "true ]] && echo "The -a flag was given"
+#      [[ "$o_a" = 'true' ]] && echo 'The -a flag was given'
 #      [[ -n "$o_c" ]] && echo "The -c option was given with arg $o_c"
 gsu_getopts()
 {