Difference between revisions of "usage statement syntax"

Latest revision as of 15:23, 17 July 2024

== Usage Statements The usage statement is generated by commands when at least one flag that is not valid has been included in the command line. The usage statement must not be used if only the data associated with a flag is missing or incorrect. If this occurs, an error message unique to the problem is used.

Show the command syntax in the usage statement. For example, a possible usage statement for the del command reads:

Usage: del {File ...|-} Clauses defining the purpose of a command are to be removed.

Capitalize the first letter of such words (parameters) as File, Directory, String, Number, and so on only when used in a usage statement.

Do not abbreviate parameters on the command line. It may be perfectly obvious to experienced users that Num means Number, but spell it out to ensure correct translation.

Use only the following delimiters in usage statements:

Delimiter

[ ]   Parameter is optional. 
{ }   There is more than one parameter choice, but one of the parameters is required. (See the following text.) 
|     Choose one parameter only. [a|b] indicates that you can choose a or b or neither a nor b. {a|b} indicates that you must choose either a or b.
..    Parameter can be repeated on the command line. (Note that there is a space before the ellipsis.) 
-     Standard input. 

A usage statement parameter does not require square brackets or braces if it is required and is the only choice, as in the following:

banner String

In usage statements, put a space between flags that must be separated on the command line. For example:

unget [-n] [-rSID] [-s] {File|-}

If flags can be used together without a separating space, do not separate them with a space on the command line. For example:

wc [-cwl] {File ...|-}

When the order of flags on the command line does not make a difference, put them in alphabetical order. If the case is mixed, put lowercase versions first:

get -aAijlmM

Some usage statements can be long and involved. Use your best judgment to determine where you should end lines in the usage statement. The following example shows an old-style usage statement for the get command:

Usage: get [-e|-k] [-cCutoff] [-iList] [-rSID] [-wString] [xList] [-b] [-gmnpst] [-l[p]] File ...

Retrieves a specified version of a Source Code Control System (SCCS) file.