Take the 2-minute tour ×
Unix & Linux Stack Exchange is a question and answer site for users of Linux, FreeBSD and other Un*x-like operating systems.. It's 100% free, no registration required.

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?

share|improve this question
add comment

2 Answers

up vote 3 down vote accepted

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. :)

share|improve this answer
add comment

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.

share|improve this answer
1  
For reference, man page conventions are based on Extended Backus-Naur Form. –  ire_and_curses Jan 29 '13 at 17:44
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.