Improve the help or usage output

A new help command has been added which either shows the toolbox(1)
manual or a manual page for a specific command. The '--help' flag is
now identical to the help command and can be placed after the COMMAND
segment in the list of command line arguments.

Due to a bizarre quirk in less(1) [1], the default pager used to render
manuals on most systems, the man(1) invocations need the standard error
stream to point to the controlling terminal, if any, to work. This
interferes with the global redirection of standard error to /dev/null
in the absence of the '--verbose' flag, and is worked around by
redirecting to standard output instead.

[1] It turns out that less(1) tries to open the controlling terminal
    device /dev/tty to get to the keyboard for accepting input.
    However, it doesn't have a controlling terminal when invoked via
    D-Bus to render a manual on the host. It then strangely falls back
    to using the standard error stream to get to the keyboard.

https://github.com/debarshiray/toolbox/pull/200

completion/bash/toolbox

@@ -13,12 +13,13 @@ __toolbox() {
   local MIN_VERSION=29
   local RAWHIDE_VERSION=31
 
-  local verbose_commands="create enter init-container list run"
+  local verbose_commands="create enter help init-container list run"
   local commands="$verbose_commands rm rmi"
 
   declare -A options
   local options=([create]="--candidate-registry --container --image --release" \
                  [enter]="--container --release" \
+                 [help]="$commands" \
                  [init-container]="--home --home-link --monitor-host --shell --uid --user" \
 		 [list]="--containers --images" \
 		 [rm]="--all --force" \

doc/meson.build

@@ -9,6 +9,7 @@ manuals = [
   'toolbox-create.1',
   'toolbox-enter.1',
   'toolbox-init-container.1',
+  'toolbox-help.1',
   'toolbox-list.1',
   'toolbox-rm.1',
   'toolbox-rmi.1',

doc/toolbox-help.1.md

@@ -0,0 +1,31 @@
+% toolbox-help(1)
+
+## NAME
+toolbox\-help - Display help information about Toolbox
+
+## SYNOPSIS
+**toolbox help** [*COMMAND*]
+
+## DESCRIPTION
+
+When no COMMAND is specified, the `toolbox(1)` manual is shown. If a COMMAND
+is specified, a manual page for that command is brought up.
+
+Note that `toolbox --help ...` is identical to `toolbox help ...` because the
+former is internally converted to the latter.
+
+This page can be displayed with `toolbox help help` or `toolbox help --help`.
+
+## EXAMPLES
+
+### Show the toolbox manual
+
+```
+$ toolbox help
+```
+
+### Show the manual for the create command
+
+```
+$ toolbox help create
+```

doc/toolbox.1.md

@@ -56,6 +56,10 @@ Create a new toolbox container.
 
 Enter a toolbox container for interactive use.
 
+**toolbox-help(1)**
+
+Display help information about Toolbox.
+
 **toolbox-init-container(1)**
 
 Initialize a running container.

toolbox

@@ -1189,6 +1189,18 @@ run()
 )
 
 
+help()
+(
+    to_help_command="$1"
+
+    if [ "$to_help_command" = "" ] 2>&3 || [ "$to_help_command" = "$base_toolbox_command" ] 2>&3; then
+        exec man toolbox 2>&1
+    fi
+
+    exec man toolbox-"$to_help_command" 2>&1
+)
+
+
 list_images()
 (
     output=""
@@ -1677,44 +1689,6 @@ update_container_and_image_names()
 }
 
 
-usage()
-{
-    echo "Usage: toolbox [-v | --verbose]"
-    echo "               [-y | --assumeyes]"
-    echo "               create [--candidate-registry]"
-    echo "                      [-c | --container <name>]"
-    echo "                      [-i | --image <name>]"
-    echo "                      [-r | --release <release>]"
-    echo "   or: toolbox [-v | --verbose]"
-    echo "               [-y | --assumeyes]"
-    echo "               enter [-c | --container <name>]"
-    echo "                     [-r | --release <release>]"
-    echo "   or: toolbox [-v | --verbose]"
-    echo "               [-y | --assumeyes]"
-    echo "               init-container --home"
-    echo "                              --home-link"
-    echo "                              --monitor-host"
-    echo "                              --shell"
-    echo "                              --uid"
-    echo "                              --user"
-    echo "   or: toolbox [-v | --verbose]"
-    echo "               [-y | --assumeyes]"
-    echo "               list [-c | --containers]"
-    echo "                    [-i | --images]"
-    echo "   or: toolbox [-y | --assumeyes]"
-    echo "               rm [-a | --all]"
-    echo "                  [-f | --force] [<container> ...]"
-    echo "   or: toolbox [-y | --assumeyes]"
-    echo "               rmi [-a | --all]"
-    echo "                   [-f | --force] [<image> ...]"
-    echo "   or: toolbox [-v | --verbose]"
-    echo "               [-y | --assumeyes]"
-    echo "               run [-c | --container <name>]"
-    echo "                   [-r | --release <release>] <command>"
-    echo "   or: toolbox --help"
-}
-
-
 arguments=$(save_positional_parameters "$@")
 
 host_id=$(get_host_id)
@@ -1732,7 +1706,18 @@ while has_prefix "$1" -; do
             assume_yes=true
             ;;
         -h | --help )
-            usage
+            if [ -f /run/.containerenv ] 2>&3; then
+                if ! [ -f /run/.toolboxenv ] 2>&3; then
+                    echo "$base_toolbox_command: this is not a toolbox container" >&2
+                    exit 1
+                fi
+
+                # shellcheck disable=SC2119
+                forward_to_host
+                exit
+            fi
+
+            help "$2"
             exit
             ;;
         --sudo )
@@ -1794,7 +1779,7 @@ shift
 
 if [ -f /run/.containerenv ] 2>&3; then
     case $op in
-        create | enter | list | rm | rmi | run )
+        create | enter | list | rm | rmi | run | help )
             if ! [ -f /run/.toolboxenv ] 2>&3; then
                 echo "$base_toolbox_command: this is not a toolbox container" >&2
                 exit 1
@@ -1809,6 +1794,11 @@ if [ -f /run/.containerenv ] 2>&3; then
             init_container_monitor_host=false
             while has_prefix "$1" -; do
                 case $1 in
+                    -h | --help )
+                        # shellcheck disable=SC2119
+                        forward_to_host
+                        exit
+                        ;;
                     --home )
                         shift
                         exit_if_missing_argument --home "$1"
@@ -1880,6 +1870,10 @@ case $op in
                     fi
                     toolbox_container="$arg"
                     ;;
+                -h | --help )
+                    help "$op"
+                    exit
+                    ;;
                 -i | --image )
                     shift
                     exit_if_missing_argument --image "$1"
@@ -1914,6 +1908,10 @@ case $op in
                     exit_if_missing_argument --container "$1"
                     toolbox_container=$1
                     ;;
+                -h | --help )
+                    help "$op"
+                    exit
+                    ;;
                 -r | --release )
                     shift
                     exit_if_missing_argument --release "$1"
@@ -1933,7 +1931,30 @@ case $op in
         enter
         exit
         ;;
+    help )
+        while has_prefix "$1" -; do
+            case $1 in
+                -h | --help )
+                    help "$op"
+                    exit
+                    ;;
+                * )
+                    exit_if_unrecognized_option "$1"
+            esac
+            shift
+        done
+        help "$1"
+        exit
+        ;;
     init-container )
+        while has_prefix "$1" -; do
+            case $1 in
+                -h | --help )
+                    help "$op"
+                    exit
+            esac
+            shift
+        done
         echo "$base_toolbox_command: The 'init-container' command can only be used inside containers" >&2
         echo "Try '$base_toolbox_command --help' for more information." >&2
         exit 1
@@ -1946,6 +1967,10 @@ case $op in
                 -c | --containers )
                     ls_containers=true
                     ;;
+                -h | --help )
+                    help "$op"
+                    exit
+                    ;;
                 -i | --images )
                     ls_images=true
                     ;;
@@ -1988,6 +2013,10 @@ case $op in
                 -f | --force )
                     rm_force=true
                     ;;
+                -h | --help )
+                    help "$op"
+                    exit
+                    ;;
                 * )
                     exit_if_unrecognized_option "$1"
             esac
@@ -2022,6 +2051,10 @@ case $op in
                     exit_if_missing_argument --container "$1"
                     toolbox_container=$1
                     ;;
+                -h | --help )
+                    help "$op"
+                    exit
+                    ;;
                 -r | --release )
                     shift
                     exit_if_missing_argument --release "$1"