From c8b6db5862e687148b2dc27f4497d31f330bd363 2021-04-09 23:05:42
From: Branko Majic <branko@majic.rs>
Date: 2021-04-09 23:05:42
Subject: [PATCH] Noticket: [TEMPLATE.sh.tpl] Improve help output and tweak quiet/debug option processing:

- Introduce short and long help output. Short help includes only the
  basic usage information, while long help provides full description
  with all options etc.
- Short help includes only the basic usage, and should fit much more
  easily on a single screen of output.
- Long help is only shown when script is invoked with the -h option.
- Output warning messages to stderr instead of stdout.
- Hide info and success messages if quiet output is requested.
- Introduce check for exclusiveness between the debug and quiet
  options.
- Fix some smaller issues reported by shellcheck.

---

diff --git a/templates/TEMPLATE.sh.tpl b/templates/TEMPLATE.sh.tpl
index 4df31c29bc173d2a0dab9b4646346eb258eb075b..a30c70d8a5c6652f5de29c779d6ed12ce9a10e4f 100644
--- a/templates/TEMPLATE.sh.tpl
+++ b/templates/TEMPLATE.sh.tpl
@@ -34,7 +34,22 @@ function usage() {
     cat <<EOF
 \$program \$version, ${2:short description }
 
-Usage: \$program [OPTIONS] ${3:arguments}
+Usage:
+  \$program [OPTIONS] ${3:arguments}
+EOF
+}
+
+function short_help() {
+    cat <<EOF
+\$(usage)
+
+For more details see \$program -h.
+EOF
+}
+
+function long_help() {
+    cat <<EOF
+\$(usage)
 
 \$program ${4:long description}
 
@@ -47,8 +62,7 @@ Usage: \$program [OPTIONS] ${3:arguments}
     -v
         Show script version and licensing information.
     -h
-        Show usage help.
-
+        Show full help.
 
 Please report bugs and send feature requests to <branko@majic.rs>.
 EOF
@@ -81,7 +95,7 @@ EOF
 # Set-up colours for message printing if we're not piping and terminal is
 # capable of outputting the colors.
 _color_terminal=\$(tput colors 2>&1)
-if [[ -t 1 ]] && (( \${_color_terminal} > 0 )); then
+if [[ -t 1 ]] && (( _color_terminal > 0 )); then
     _text_bold=\$(tput bold)
     _text_white=\$(tput setaf 7)
     _text_blue=\$(tput setaf 6)
@@ -107,15 +121,19 @@ function debug() {
 }
 
 function info() {
-    echo "\${_text_bold}\${_text_white}[INFO] \${_text_reset}" "\$@"
+    if [[ $quiet == 0 ]]; then
+        echo "\${_text_bold}\${_text_white}[INFO] \${_text_reset}" "\$@"
+    fi
 }
 
 function success() {
-    echo "\${_text_bold}\${_text_green}[OK]   \${_text_reset}" "\$@"
+    if [[ $quiet == 0 ]]; then
+        echo "\${_text_bold}\${_text_green}[OK]   \${_text_reset}" "\$@"
+    fi
 }
 
 function warning() {
-    echo "\${_text_bold}\${_text_yellow}[WARN] \${_text_reset}" "\$@"
+    echo "\${_text_bold}\${_text_yellow}[WARN] \${_text_reset}" "\$@" >&2
 }
 
 function error() {
@@ -132,7 +150,7 @@ quiet=0
 
 # If no arguments were given, just show usage help.
 if [[ -z \${1-} ]]; then
-    usage
+    short_help
     exit "$SUCCESS"
 fi
 
@@ -143,11 +161,17 @@ while getopts "qdvh" opt; do
 	d) debug=1;;
         v) version
            exit "$SUCCESS";;
-        h) usage
+        h) long_help
            exit "$SUCCESS";;
-        *) usage
+        *) short_help
            exit "$ERROR_ARGUMENTS";;
     esac
 done
 i=\$OPTIND
-shift \$((\$i-1))
+shift \$(( i-1 ))
+
+# Quiet and debug are mutually exclusive.
+if [[ \$quiet != 0 && \$debug != 0 ]]; then
+    error "Quiet and debug options are mutually exclusive."
+    exit "\$ERROR_ARGUMENTS"
+fi