How to write a usage message

The unix/linux "usage" message is in a very specific format, and one which means something to experienced users. You should learn how to write messages in this format, and how to read messages in this format.

The format is the same as the SYNOPSIS section in a man page, without the font changes, and without the loose spacing.
The usage message is output to the standard error.

A usage message begins with the word "usage" (not "Usage"), a colon, and a space.

This is followed by a stylized example command-line. So the next word is the program name. For this you can use either argv[0] ($0 in sh) or a hard-coded program name.

After this, optional items are in square brackets, and "..." means one or more of the previous. So for example,

usage: foo [-x] file

indicates that the "−x" option is optional, but a file name is mandatory (but only one is permitted).

usage: foo file1 file2

indicates that two file names are mandatory. The space between "file1" and "file2" indicates that they are two separate arguments, just as it does in the shell.
The example

usage: foo file ...

means that one or more file names are permitted. To indicate zero or more file names, we combine the syntaxes:

usage: foo [file ...]

Option key letters can be strung together as in man pages. For example, if "foo" takes options "−a", "−b", both, or neither, followed by zero or more file names, we would write

usage: foo [-ab] [file ...]

Where square brackets are used, the entire content of the square brackets can be omitted or present. For example, if you write

usage: foo [-n count] file

that means that you can do "foo −n count file", or "foo file", but not a mixture such as "foo −n file" or "foo count file".

For more complex cases, and only where necessary, a vertical bar can be used to indicate alternatives (contrary to its meaning in the shell — that is to say, a vertical bar here does NOT refer to piping.) Brace brackets can be used for grouping. Example:

usage: cut {-c charnumber | -f fieldnumber} [file ...]

although we don't do this sort of thing too often, as it gets confusing quickly.

Other than the vertical bar and the brace brackets, characters generally are taken to mean what they would mean in the shell. For example, sometimes people use i/o redirection arrows where applicable, although this should be done very sparingly.

Remember that you are not teaching the user how to use the shell, so for example the typical zero-or-more files case would look like this:

usage: foo [file ...]

and NOT like

usage: foo {file ... | <file}