[SOLVED] standard for usage statement syntax

hydraMax · 12-25-2011, 05:30 AM

Hi. I'm writing some small command-line programs. Is there some POSIX or GNU standard document somewhere describing what the usage statement syntax is supposed to be?; specifically I am referring to part of the usage statement that describes the command syntax. For example, what symbol should be used to show that an argument is optional (parenthesis, square brackets, angle brackets...); should argument names be capitalized?; how to show if one of two options is mandatory?; and so forth.

I found a GNU coding standards page, but this information doesn't seem to be on it.

Nominal Animal · 12-25-2011, 06:45 AM

First, make sure you use getopt() or the same rules (self-implemented) to parse the options. Getopt() is standardized in IEEE Std 1003.1-2001 (also known as SUSv3, and includes POSIX, also known as IEEE Std 1003.2).

SUSv3/IEEE Std 1003.1 includes a chapter on Utility Conventions, including Utility Argument Syntax and Utility Syntax Guidelines.

The Utility Argument Syntax section describes the format used in IEEE Std 1003.1 exactly, and is used by practically all Linux/POSIX utilities, including the synopses in man pages.

man man and man getopt manpages list the format quite concisely. Here is an abbreviated and simplified list of examples:

Code:

-abc                    short options -a, -b, -c
[-a]                    optional short option
[-abc]                  none, any, or all of optional short options -a, -b, -c
[-d parameter]          short option with a required parameter
argument ...            one or more arguments
[argument] ...          zero or more arguments
-h|--help               alternatives (here, short and long form of the same parameter)
-i|-o|-c                alternatives (one of -i, -o, or -c must be used)
[-i|-o|-c]              alternatives (one of -i, -o, or -c may be used)
[-i file|-o file] ...   short option -i and -o both need a parameter, but can be repeated
--long=value            long option with a parameter
--long value            long option with a parameter
--long[=value]          long option with an optional parameter

Sometimes you see <input file> ... syntax in usages; I've used it to try to make the usage a bit more intuitive. (This derives from BNF syntax used in RFC's, and has nothing to do with the standards and conventions listed above.)

Sometimes you can see extra spaces around [ | ]. These are for readability only, and are strictly not according to the standards and conventions listed above. The main thing is to keep the surprises for the user to a minimum. I don't think small deviations from the rules are significant. I like to use a blind test: Give the script or utility to someone who uses Linux command line tools, and see if they need more than a couple of seconds to look at the usage before correctly using the tool. If they are happy and fast with the tool, I'm happy. If not, it's usually time to edit the options. (Many short options, like -v and -f, are used the same way in a lot of utilities. If more than one tester uses the wrong option, it is usually better to switch the option letters around.)

hydraMax · 12-25-2011, 07:34 PM

Thank you Nominal for a helpful and detailed reply.