4.5 Help

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.

Function: help [: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…