global_options: add argument to call silent

FossilOrigin-Name: cab50844d5456d5bb7c10625e3f34038146b84780b93f3abed107c74378cc41f

4 files changed, 51 insertions, 22 deletions

diff --git a/docs/cpt.org b/docs/cpt.org
index 263c547..abdcd62 100644
--- a/docs/cpt.org
+++ b/docs/cpt.org
@@ -871,13 +871,17 @@ inside. Here is the proper way of doing it.
 The =global_options()= function is a simple convenience call to include flags
 that can be used inside most =cpt= tools. It defines the following flags:
 
-| Flag | Long Option   | Calls        |
-|------+---------------+--------------|
-| ~-f~ | ~--force~     | =CPT_FORCE=  |
-| ~-y~ | ~--no-prompt~ | =CPT_PROMPT= |
-|      | ~--root~      | =CPT_ROOT=   |
-| ~-h~ | ~--help~      | =usage()=    |
-| ~-v~ | ~--version~   | =version()=  |
+| Flag | Long Option   | Calls         |
+|------+---------------+---------------|
+| ~-f~ | ~--force~     | =CPT_FORCE=   |
+| ~-y~ | ~--no-prompt~ | =CPT_PROMPT=  |
+|      | ~--root~      | =CPT_ROOT=    |
+| ~-h~ | ~--help~      | =usage()=     |
+| ~-v~ | ~--version~   | =version()=   |
+|      | ~--verbose~   | =CPT_VERBOSE= |
+
+If you don't want these options to be printed on the usage, you can disable it
+by calling ~global_options silent~ instead.
 
 ** Message functions
 :PROPERTIES:
diff --git a/docs/cpt.texi b/docs/cpt.texi
index 7487209..ab1df89 100644
--- a/docs/cpt.texi
+++ b/docs/cpt.texi
@@ -1034,7 +1034,7 @@ parser_definition() @{
 The @samp{global_options()} function is a simple convenience call to include flags
 that can be used inside most @samp{cpt} tools. It defines the following flags:
 
-@multitable {aaaa} {aaaaaaaaaaaaa} {aaaaaaaaaaaa}
+@multitable {aaaa} {aaaaaaaaaaaaa} {aaaaaaaaaaaaa}
 @headitem Flag
 @tab Long Option
 @tab Calls
@@ -1053,8 +1053,14 @@ that can be used inside most @samp{cpt} tools. It defines the following flags:
 @item @code{-v}
 @tab @code{--version}
 @tab @samp{version()}
+@item 
+@tab @code{--verbose}
+@tab @samp{CPT_VERBOSE}
 @end multitable
 
+If you don't want these options to be printed on the usage, you can disable it
+by calling @code{global_options silent} instead.
+
 @node Message functions
 @section Message functions
 
diff --git a/docs/cpt.txt b/docs/cpt.txt
index 8934c15..ab99f4d 100644
--- a/docs/cpt.txt
+++ b/docs/cpt.txt
@@ -924,13 +924,17 @@ development manual for *Carbs Packaging Tools*. For development logs see
   include flags that can be used inside most `cpt' tools. It defines the
   following flags:
 
-   Flag  Long Option    Calls        
-  -----------------------------------
-   `-f'  `--force'      `CPT_FORCE'  
-   `-y'  `--no-prompt'  `CPT_PROMPT' 
-         `--root'       `CPT_ROOT'   
-   `-h'  `--help'       `usage()'    
-   `-v'  `--version'    `version()'  
+   Flag  Long Option    Calls         
+  ------------------------------------
+   `-f'  `--force'      `CPT_FORCE'   
+   `-y'  `--no-prompt'  `CPT_PROMPT'  
+         `--root'       `CPT_ROOT'    
+   `-h'  `--help'       `usage()'     
+   `-v'  `--version'    `version()'   
+         `--verbose'    `CPT_VERBOSE' 
+
+  If you don't want these options to be printed on the usage, you can
+  disable it by calling `global_options silent' instead.
 
 
 8.3 Message functions
diff --git a/src/cpt-lib.in b/src/cpt-lib.in
index c055331..0017fba 100644
--- a/src/cpt-lib.in
+++ b/src/cpt-lib.in
@@ -415,14 +415,29 @@ getoptions_help() {
     echo "}"
 }
 
+# 2086:
+#   The lack of quotes are intentional. We do this so `getoptions()` do not try
+#   to parse the empty string.
+# 2120:
+#   The library does not call this function with any positional arguments, but
+#   that does not mean that other programs will not do it, so this can also be
+#   safely ignored.
+# shellcheck disable=2086,2120
 global_options() {
-    msg -- '' 'Global Options:'
-    flag  CPT_FORCE  -f --force                init:@export -- "Force operation"
-    flag  CPT_PROMPT -y --no-prompt on:0 off:0 init:@export -- "Do not prompt for confirmation"
-    param CPT_ROOT      --root                 init:@export -- "Use an alternate root directory"
-    disp :usage      -h --help                              -- "Show this help message"
-    disp :version    -v --version                           -- "Print version information"
-    flag CPT_VERBOSE    --verbose              init:@export -- "Be more verbose"
+    # These are options that are supported by most utilities. If the optional
+    # argument 'silent' is given, the usage will not print these options, but
+    # the arguments will still be accepted. Sometimes it doesn't make sense to
+    # pollute the screen with options that will be rarely ever used.
+    case $1 in
+        silent) h=hidden:1 ;;
+        *) msg -- '' 'Global Options:'; h=''
+    esac
+    flag  CPT_FORCE  -f --force                $h init:@export -- "Force operation"
+    flag  CPT_PROMPT -y --no-prompt on:0 off:0 $h init:@export -- "Do not prompt for confirmation"
+    param CPT_ROOT      --root                 $h init:@export -- "Use an alternate root directory"
+    disp :usage      -h --help                 $h              -- "Show this help message"
+    disp :version    -v --version              $h              -- "Print version information"
+    flag CPT_VERBOSE    --verbose              $h init:@export -- "Be more verbose"
 }
 
 contains() {