From 5e63e9ec9bc420da3ba766494d23cc032cf317da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Harry=20M=C3=ADchal?= Date: Mon, 15 Jul 2019 10:23:25 +0200 Subject: [PATCH] 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 | 3 +- doc/meson.build | 1 + doc/toolbox-help.1.md | 31 +++++++++++ doc/toolbox.1.md | 4 ++ toolbox | 113 ++++++++++++++++++++++++++-------------- 5 files changed, 111 insertions(+), 41 deletions(-) create mode 100644 doc/toolbox-help.1.md diff --git a/completion/bash/toolbox b/completion/bash/toolbox index a13c7c4..1a1c7e9 100644 --- a/completion/bash/toolbox +++ b/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" \ diff --git a/doc/meson.build b/doc/meson.build index 1183687..172aee2 100644 --- a/doc/meson.build +++ b/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', diff --git a/doc/toolbox-help.1.md b/doc/toolbox-help.1.md new file mode 100644 index 0000000..684221f --- /dev/null +++ b/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 +``` diff --git a/doc/toolbox.1.md b/doc/toolbox.1.md index 21ca507..1f9755d 100644 --- a/doc/toolbox.1.md +++ b/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. diff --git a/toolbox b/toolbox index a6a4883..931eb78 100755 --- a/toolbox +++ b/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 ]" - echo " [-i | --image ]" - echo " [-r | --release ]" - echo " or: toolbox [-v | --verbose]" - echo " [-y | --assumeyes]" - echo " enter [-c | --container ]" - echo " [-r | --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] [ ...]" - echo " or: toolbox [-y | --assumeyes]" - echo " rmi [-a | --all]" - echo " [-f | --force] [ ...]" - echo " or: toolbox [-v | --verbose]" - echo " [-y | --assumeyes]" - echo " run [-c | --container ]" - echo " [-r | --release ] " - 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"