New Issue: How should argument parser help and usage message be displayed?

Notifications Issues
1

18687, "arezaii", "How should argument parser help and usage message be displayed?", "2021-11-04T21:55:18Z"

When the argument parser generates and displays help, how should it be formatted?

Depending on feedback, I was thinking of some format similar to this:

<pre-help>

<program name>
<about>
<author>
<version>

<usage>
<arguments>
<options>
<subcommands>

<post help>

Other parsers give you some ability to modify the message format, with Rust having probably the most flexible/generous by way of custom templates. I'm not proposing anything that elegant, and initially the format would be fixed.

For a simple program like the quickstart example, the help output might look like:

USAGE: ArgumentParserQuickstart <POSITIONAL> [-h, --help] [--debug] [--optional <OPTIONAL>]
ARGUMENTS:
        POSITIONAL
OPTIONS:
        -h, --help      Display this message and exit
        --optional <OPTIONAL>
        --debug

There is still work to be done with pretty printing the help output with perfect column alignment and awareness of the screen size, this example is just using dumb tabs.

Usage Messages

For usage messages, I would propose ordering the parts something like this:

USAGE: <binary name> <positional arguments> <flags/options> <subcommand>

Where optional arguments or values are wrapped in [ ] and required ones are wrapped in < >

There is a question of how multiple values should be indicated, and for simplicity I propose using ... to indicate 'or more' values. Some output examples to demonstrate:

  • optional flag with 1 value expected [--flag <VAL>]
  • optional flag with 0 values expected [--flag]
  • optional flag with 1 or more values '' [--flag <VAL ...>]
  • optional flag with 0 or more values '' [--flag [VAL ...]]
  • required versions the same except outer [ ] replaced with < >

It is less clear how to represent arguments which expect a specific range, say 4..10 values, or exactly 8 values.

Other questions:

  1. Should default values for arguments and options be displayed in the help output? In the usage message? If so, how/where? This could be at the end of the help message for an argument/option, but not displayed at all in the case of flags and subcommands.

  2. For flags/options with multiple possible identifiers, should they all be represented in the usage message? e.g. the usage message from the quickstart includes [-h, --help], should it just display [-h] there and the longer version in the help output under OPTIONS:?

  3. For parsers that operate on subcommands, how to give them the whole path from the parent? That is, for a command like mason add -h, how to tell the add subcommand parser that the usage message should append mason? There could be a "parent" property on the argument parser, or that might be a reason to have separate binaryName and program arguments, where binaryName represents the path to the subcommand parser, whose name is represented in program.