Full help/usage display and modification example (#975)

Example of help modification as documentation supplement.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Philip Top <top1@llnl.gov>
Co-authored-by: Philip Top <phlptp@gmail.com>

examples/help_usage.cpp

@@ -0,0 +1,72 @@
+// Copyright (c) 2017-2023, University of Cincinnati, developed by Henry Schreiner
+// under NSF AWARD 1414736 and by the respective contributors.
+// All rights reserved.
+//
+// SPDX-License-Identifier: BSD-3-Clause
+
+#include <CLI/CLI.hpp>
+#include <string>
+
+int main(int argc, char **argv) {
+    std::string input_file_name, output_file_name;
+    int level, subopt;
+
+    // app caption
+    CLI::App app{"CLI11 help"};
+
+    app.require_subcommand(1);
+    // subcommands options and flags
+    CLI::App *const encode = app.add_subcommand("e", "encode")->ignore_case();  // ignore case
+    encode->add_option("input", input_file_name, "input file")
+        ->option_text(" ")
+        ->required()
+        ->check(CLI::ExistingFile);                                                               // file must exist
+    encode->add_option("output", output_file_name, "output file")->option_text(" ")->required();  // required option
+    encode->add_option("-l, --level", level, "encoding level")
+        ->option_text("[1..9]")
+        ->check(CLI::Range(1, 9))
+        ->default_val(5);                                   // limit parameter range
+    encode->add_flag("-R, --remove", "remove input file");  // no parameter option
+    encode->add_flag("-s, --suboption", subopt, "suboption")->option_text(" ");
+
+    CLI::App *const decode = app.add_subcommand("d", "decode")->ignore_case();
+    decode->add_option("input", input_file_name, "input file")->option_text(" ")->required()->check(CLI::ExistingFile);
+    decode->add_option("output", output_file_name, "output file")->option_text(" ")->required();
+
+    // Usage message modification
+    std::string usage_msg = "Usage: " + std::string(argv[0]) + " <command> [options] <input-file> <output-file>";
+    app.usage(usage_msg);
+    // flag to display full help at once
+    app.set_help_flag("");
+    app.set_help_all_flag("-h, --help");
+
+    CLI11_PARSE(app, argc, argv);
+
+    return 0;
+}
+
+/*
+$ ./help_usage -h
+CLI11 help
+Usage: help_usage <command> [options] <input-file> <output-file>
+
+Options:
+  -h,--help
+
+Subcommands:
+e
+  encode
+  Positionals:
+    input                       input file
+    output                      output file
+  Options:
+    -l,--level [1..9]           encoding level
+    -K,--remove INT             remove input file
+    -s,--suboption              suboption
+
+d
+  decode
+  Positionals:
+    input                       input file
+    output                      output file
+*/