One of the first motivations in the design of Clon was to automate
the generation of the help string, which is a very boring maintenance
task to do by hand. The application’s synopsis contains all the
necessary information to do so. In order to print your application’s
help string, use the help function.
:item ITEM] ¶Print the application’s help string. Printing honors the search path, theme, line width and highlight settings provided by the corresponding built-in options (see Theme Mechanism in The Clon End-User Manual).
By default, help prints the whole application help string,
excluding hidden items. However, if you have kept a reference to any
synopsis item (option, text, group), you can pass it as the value of the
:item key, and Clon will only print the help string for that
particular item. In this case however, it will be displayed even if was
declared as hidden (this exception does not extend to its sub-items, though,
and they will not be displayed if themselves declared hidden).
For instance, the Clon built-in group is normally hidden, so it
doesn’t show up in the global help string, but the --clon-help
option uses the help function on it explicitely, so it discards
its hidden state.
Here is a potentially useful application of hidden groups in conjunction
with the :item key. Look at ImageMagick’s convert
program’s help string for instance: it is 276 lines long. Gosh. The help
string is decomposed into several categories: image settings, image
operators, misc options etc.. If I were to implement this program, I
would rather have the --help option display an overview of the
program, advertise --version and a couple of others, and I
would then implement --help as an enumeration for listing every
option category individually (they would normally be stored in hidden
groups). The user could then use --help=settings,
--help=operators and so on to display only the category she’s
interested in.
Finally, here is potentially useful application of hidden options that are never ever displayed in any help string whatsoever, and I mean, like, ever. This is the perfect tool for backdoor’ing a program. For instance, if you ever need to implement a --discard-all-security-measures-and-blow-the-nuke option, then you’d better have it hidden…