Revamp mkusage backend

 *  Added support for "options", "commands" and plain
    sections.

 *  Changed default for multi-line usage lines to use
    header rather than prefix.

src/include-bash/pretty.sh

@@ -413,16 +413,66 @@ _pretty__echo_help() {
 
 _pretty__echo_usage() {
     #
-    # Print each argument as usage pattern
+    # Compose conventional usage guide
     #
-    local self
+    # The default mode treats each argument as usage pattern
+    # (see below for details).  Additional formatting can be
+    # conveniently achieved by switching to other modes, which
+    # automatically brings necessary headers and indentations
+    # where needed.
+    #
+    #  *  option mode (`-o`) prints "options:" header and 
+    #     indents next arguments,
+    #
+    #  *  command mode (`-c`) prints "commands:" header and
+    #     indents next arguments,
+    #
+    #  *  plain mode (`--`) prints empty line (new paragraph)
+    #     and turns indentations off.
+    #
+    #  *  usage mode (`-u`, active by default), prints
+    #     "usage:" header, indents next arguments and prefixes
+    #     them with name of the script.
+    #
+    #     A special case of usage mode is when only single
+    #     argument is passed to this function; then instead
+    #     of "usage:" header, this usage pattern is prefixed
+    #     with the same string.
+    #
+    # In order to help avoid (rare) conflict between mkusage()
+    # switches and your usage patterns, the very first argument,
+    # and each argument that comes right after one of these
+    # switches are guarranteed not to be interpreted as switch.
+    #
+    local self          # the script name
+    local mode=usage    # mode
+    local esc=1         # escape (take next argument as literal)
+    local arg           # argument to iterate
     case "$SHELLFU_PRETTY_USAGE" in
         subcommand) self="${0##*/}"; self="${self/-/ }" ;;
         *)          self="$caller" ;;
     esac
-    local u
-    for u in "$@";
-    do echo "usage: $self $u"
+    case $# in
+        0)  return 0 ;;
+        1)  echo "usage: $self $1"; return 0 ;;
+    esac
+    echo usage:
+    for arg in "$@";
+    do
+        case $esc:$arg in
+            0:--) shift; mode=plain;  esc=1; echo                ;;
+            0:-c) shift; mode=indent; esc=1; echo; echo commands: ;;
+            0:-i) shift; mode=indent; esc=1; echo                ;;
+            0:-o) shift; mode=indent; esc=1; echo; echo options: ;;
+            0:-u) shift; mode=usage;  esc=1                      ;;
+            *)  esc=0
+                case $mode in
+                    usage)  echo  "  $self $arg" ;;
+                    indent) echo  "  $arg" ;;
+                    plain)  echos "$arg" ;;
+                esac
+                ;;
+        esac
     done
 }
 

tests/pretty_basic/TF_RUN

@@ -42,6 +42,15 @@ tf_enum_subtests() {
     echo "v1_d1_wrap_debug_xmod"
     echo "v1_d1_wrap_die"
     echo "v1_d1_wrap_mkusage"
+    echo "v1_d1_wrap_mkusage_0"
+    echo "v1_d1_wrap_mkusage_1"
+    echo "v1_d1_wrap_mkusage_2"
+    echo "v1_d1_wrap_mkusage_o"
+    echo "v1_d1_wrap_mkusage_p"
+    echo "v1_d1_wrap_mkusage_i"
+    echo "v1_d1_wrap_mkusage_c"
+    echo "v1_d1_wrap_mkusage_all"
+    echo "v1_d1_wrap_mkusage_conflict"
 }
 
 tf_do_subtest() {
@@ -75,7 +84,7 @@ tf_do_subtest() {
         wrap_die)       cmd='bash test/wrap_die foo'; o_es=3 ;;
         wrap_debug)     cmd='bash test/wrap_debug' ;;
         wrap_debug_xmod)cmd='SHELLFU_DEBUG_EXCLUDE=barmod,process,foo,process_job,__do_process_task bash test/wrap_debug' ;;
-        wrap_mkusage)   cmd='bash test/wrap_mkusage'; o_es=2 ;;
+        wrap_mkusage*)  cmd="bash test/$tfun"; o_es=2 ;;
     esac
     tf_testflt -n "$name" -i "$t_in" -S "$o_es" -O "$o_out" -E "$o_err" "$cmd"
 }

tests/pretty_basic/oracle/v0_d0/wrap_mkusage.stderr

@@ -1,2 +1,3 @@
-usage: wrap_mkusage [-d] load [-f file]
-usage: wrap_mkusage [-d] save [-f file]
+usage:
+  wrap_mkusage [-d] load [-f file]
+  wrap_mkusage [-d] save [-f file]

tests/pretty_basic/oracle/v0_d1/wrap_mkusage.stderr

@@ -1,2 +1,3 @@
-usage: wrap_mkusage [-d] load [-f file]
-usage: wrap_mkusage [-d] save [-f file]
+usage:
+  wrap_mkusage [-d] load [-f file]
+  wrap_mkusage [-d] save [-f file]

tests/pretty_basic/oracle/v1_d0/wrap_mkusage.stderr

@@ -1,2 +1,3 @@
-usage: wrap_mkusage [-d] load [-f file]
-usage: wrap_mkusage [-d] save [-f file]
+usage:
+  wrap_mkusage [-d] load [-f file]
+  wrap_mkusage [-d] save [-f file]

tests/pretty_basic/oracle/v1_d1/wrap_mkusage.stderr

@@ -1,2 +1,3 @@
-usage: wrap_mkusage [-d] load [-f file]
-usage: wrap_mkusage [-d] save [-f file]
+usage:
+  wrap_mkusage [-d] load [-f file]
+  wrap_mkusage [-d] save [-f file]

tests/pretty_basic/oracle/v1_d1/wrap_mkusage_1.stderr

@@ -0,0 +1 @@
+usage: wrap_mkusage_1 [-d] load [-f file]

tests/pretty_basic/oracle/v1_d1/wrap_mkusage_2.stderr

@@ -0,0 +1,3 @@
+usage:
+  wrap_mkusage_2 [-d] load [-f file]
+  wrap_mkusage_2 [-d] save [-f file]

tests/pretty_basic/oracle/v1_d1/wrap_mkusage_all.stderr

@@ -0,0 +1,19 @@
+usage:
+  wrap_mkusage_all [-d] load [-f file]
+  wrap_mkusage_all [-d] save [-f file]
+
+options:
+  -d         debug
+  -f file    some file
+
+commands:
+  load - load a file or something
+  save - save a file or something
+
+here is some data
+
+  data1
+  data2
+  data3
+
+and that's all folks!

tests/pretty_basic/oracle/v1_d1/wrap_mkusage_c.stderr

@@ -0,0 +1,7 @@
+usage:
+  wrap_mkusage_c [-d] load [-f file]
+  wrap_mkusage_c [-d] save [-f file]
+
+commands:
+  load - load a file or something
+  save - save a file or something

tests/pretty_basic/oracle/v1_d1/wrap_mkusage_conflict.stderr

@@ -0,0 +1,4 @@
+usage:
+  wrap_mkusage_conflict -o
+  wrap_mkusage_conflict [-d] load [-f file]
+  wrap_mkusage_conflict [-d] save [-f file]

tests/pretty_basic/oracle/v1_d1/wrap_mkusage_i.stderr

@@ -0,0 +1,7 @@
+usage:
+  wrap_mkusage_i [-d] load [-f file]
+  wrap_mkusage_i [-d] save [-f file]
+
+  data1
+  data2
+  data3

tests/pretty_basic/oracle/v1_d1/wrap_mkusage_o.stderr

@@ -0,0 +1,7 @@
+usage:
+  wrap_mkusage_o [-d] load [-f file]
+  wrap_mkusage_o [-d] save [-f file]
+
+options:
+  -d         debug
+  -f file    some file

tests/pretty_basic/oracle/v1_d1/wrap_mkusage_p.stderr

@@ -0,0 +1,5 @@
+usage:
+  wrap_mkusage_p [-d] load [-f file]
+  wrap_mkusage_p [-d] save [-f file]
+
+Author: chucky

tests/pretty_basic/test/wrap_mkusage_0

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+. "$(shellfu-get path)"
+
+shellfu import pretty
+
+usage() {
+    mkusage
+}
+
+usage

tests/pretty_basic/test/wrap_mkusage_1

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+. "$(shellfu-get path)"
+
+shellfu import pretty
+
+usage() {
+    mkusage "[-d] load [-f file]"
+}
+
+usage

tests/pretty_basic/test/wrap_mkusage_2

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+. "$(shellfu-get path)"
+
+shellfu import pretty
+
+usage() {
+    mkusage "[-d] load [-f file]" \
+            "[-d] save [-f file]"
+}
+
+usage

tests/pretty_basic/test/wrap_mkusage_all

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+. "$(shellfu-get path)"
+
+shellfu import pretty
+
+usage() {
+    mkusage "[-d] load [-f file]" \
+            "[-d] save [-f file]" \
+         -o "-d         debug" \
+            "-f file    some file" \
+         -c "load - load a file or something" \
+            "save - save a file or something" \
+         -- "here is some data" \
+         -i "data1" "data2" "data3" \
+         -- "and that's all folks!"
+}
+
+usage

tests/pretty_basic/test/wrap_mkusage_c

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+. "$(shellfu-get path)"
+
+shellfu import pretty
+
+usage() {
+    mkusage "[-d] load [-f file]" \
+            "[-d] save [-f file]" \
+         -c "load - load a file or something" \
+            "save - save a file or something"
+}
+
+usage

tests/pretty_basic/test/wrap_mkusage_conflict

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+. "$(shellfu-get path)"
+
+shellfu import pretty
+
+usage() {
+    mkusage -o "[-d] load [-f file]" \
+            "[-d] save [-f file]"
+}
+
+usage

tests/pretty_basic/test/wrap_mkusage_i

@@ -0,0 +1,13 @@
+#!/bin/bash
+
+. "$(shellfu-get path)"
+
+shellfu import pretty
+
+usage() {
+    mkusage "[-d] load [-f file]" \
+            "[-d] save [-f file]" \
+         -i "data1" "data2" "data3"
+}
+
+usage

tests/pretty_basic/test/wrap_mkusage_o

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+. "$(shellfu-get path)"
+
+shellfu import pretty
+
+usage() {
+    mkusage "[-d] load [-f file]" \
+            "[-d] save [-f file]" \
+         -o "-d         debug" \
+            "-f file    some file"
+}
+
+usage

tests/pretty_basic/test/wrap_mkusage_p

@@ -0,0 +1,13 @@
+#!/bin/bash
+
+. "$(shellfu-get path)"
+
+shellfu import pretty
+
+usage() {
+    mkusage "[-d] load [-f file]" \
+            "[-d] save [-f file]" \
+         -- "Author: chucky"
+}
+
+usage