4.1 Output Elements

Let’s look at the output of program --help in a default setting first:

Usage: program [-hdF] [+d] [OPTIONS] FILES...

A clonified program.

  -h, --help                  Print this help and exit.
Runtime options:
  -(+)d, --debug[=yes/no]     Turn debugging on or off.
                              Fallback: yes
                              Environment: DEBUG
                              Default: no
  --simulate=yes/no           Simulate only. Nothing will happen for real,
                              except for log messages.
User identification:
  -f, --first-name=STR        Set the user's first name to STR.
  -F, --family-name[=NAME]    Set the user's family name to NAME.
                              Fallback: unknown

The first line of output is what’s called the synopsis. This synopsis indicates that the program accepts a number of options and also a postfix consisting of file names. The set of available options is not detailed in the synopsis but for convenience, Clon shows the available short and negated packs explicitly.

The next non-empty line is just text. A clonified application is free to put arbitrary text anywhere in its help string. This can be used to describe what the application is about for instance.

Two other lines in the help string look like arbitrary text, but in fact are not: “Runtime options:” and “User identification:”. These are not arbitrary text, but group titles. A group is a way of putting help string items together, for instance because they are related to the same topic. A group has an optional title, and may contain options, arbitrary text or even sub-groups.

In addition to displaying the full help string, a clonified application may display a group’s help string only (in such a case, you don’t get to see the synopsis). This is what happens when you type program --clon-help for instance. Clon’s built-in options belong to a reserved built-in group.

Let’s have a look at the options now. In the first column, you can see that depending on the option, the long, short and negated forms are advertised. Valued options also advertise their argument, enclosed in square brackets when it is optional. In this example, ‘-h’ is a flag, ‘-d’ and ‘--simulate’ are switches with different settings, while ‘-f’ and ‘-F’ are standard valued options.

The second column of the help string provides each option’s description. Descriptions can span across several lines, as in the case of ‘--simulate’. Clon takes care of properly aligning all the material that needs to be displayed.

Finally, you can see that potential fallback values, environment variables and default values are also advertised in that order, when appropriate.