3

This is a follow up to a previous question, where Silverrocker suggested a nice way to display a help message similar to commands like ls or du.

program --help

Usage: program [<options>][<arguments> ...]

Options:
--help         show this message, then exit
--something    after some spaces for alignment, an explenation follows.

I really like this approach but I can only guess how to produce such a help message. Are there any GNU/whatever documents/standards on how to produce something like this?

Community
  • 1
helpermethod
  • 1,952
  • 2
  • 19
  • 25

2 Answers2

3

In ls and du, the --help output is plain and simple hardcoded into the program.

In scripting languages such as Python there may be an option parsing library that does it automatically for you.

As for standards, the only thing I could find was this:

http://www.gnu.org/prep/standards/html_node/_002d_002dhelp.html#g_t_002d_002dhelp

or more specific to ls, du (coreutils):

http://www.gnu.org/software/coreutils/manual/html_node/Common-options.html#Common-options

which is entirely unhelpful.

I guess it's up to you to format it nicely. :)

frostschutz
  • 47,228
  • 5
  • 112
  • 159
2

When writing a command line utility I create a usage() function that spits out information in that form, and when I add or change something in the getopt (or whatever) code I update the usage function to reflect this. Of course, the problem with that system is that if you are lazy, you can end up with a inaccurate usage message, but that is not such a hard problem to avoid or rectify.

As for guidelines, the principle "usage:" line can follow man page conventions, eg:

Usage: mycommand -h | [-x|y|z] [-a] [-b arg] required_param [optional_param]

Where a pipe | indicates or (so you can use one of x or y or z) and brackets optional bits. This might be simplified, as per ls, to

Usage: mycommand [options] required_param [optional_param]

Then go through the options alphabetically, etc.

"Usage" fires if a dud option is parsed, -h or --help is used, a required argument is missing, etc.

goldilocks
  • 86,451
  • 30
  • 200
  • 258
  • 1
    For reference, man page conventions are based on [Extended Backus-Naur Form](http://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form). – ire_and_curses Jan 29 '13 at 17:44