6.2 Programmatic Help Strings

So far, we’ve seen how to use the help function to implement a typical --help option. This is mostly intended for the end-user. There are also times when this function could be useful to you, the application developer. For instance, one could imagine that part of the compilation phase would involve generating the help string in order to include it in the manual. Another idea would be that ‘make install’ creates a REFCARD file in /usr/local/share/doc/my-app/ which contains the help string formatted with the refcard theme, etc..

In such situations, calling the help function might not be directly associated with an end-user level option, or at least not --help, and you might not want to honor the end-user level settings for theme, search path, line-width, or highlighting either (remember that these settings might come from the environment variables associated with --clon-theme, --clon-search-path, --clon-line-width and --clon-highlight).

Because of this, the help function provides additional keys that allow you to override those settings (they are in fact stored in the context object). The keys in question are: :theme, :search-path, :line-width and :highlight.

In addition to that, there is an :output-stream key which defaults to *standard-output* which you could use for instance to write directly to a file. Note that there is no end-user level access to this parameter.