How to denote that a command line argument is optional when printing usage

Question

Assume that I have a script that can be run in either of the following ways.

./foo arg1 arg2
./foo

Is there a generally accepted way to denote that arg1 and arg2 aren't mandatory arguments when printing the correct usage of the command?

I've sometimes noticed usage printed with the arguments wrapped in brackets like in the following usage printout.

Usage: ./foo [arg1] [arg2]

Do these brackets mean that the argument is optional or is there another generally accepted way to denote that an argument is optional?

Solution 1

I personally have not seen a 'standard' that denotes that a switch is optional (like how there's a standard that defines how certain languages are written for example), as it really is personal choice, but according to IBM's docs and the Wiki, along with numerous shell scripts I've personally seen (and command line options from various programs), and the IEEE, the 'defacto' is to treat square bracketed ([]) parameters as optional parameters. Example from Linux:

ping (output trimmed...)

usage: ping [-c count] [-t ttl] host

where [-c count] and [-t ttl] are optional parameters but host is not (as defined in the help).

I personally follow the defacto as well by using [] to mean they are optional parameters and make sure to note that in the usage of that script/program.

I should note that a computer standard should define how something happens and its failure paths (either true fail or undefined behavior). Something along the lines of the command line interpreter _shall_ treat arguments as optional when enclosed in square brackets, and _shall_ treat X as Y when Z, etc.. Much like the ISO C standard says how a function shall be formed for it to be valid (otherwise it fails). Given that there are no command line interpreters, from ASH to ZSH and everything in between, that fail a script for treating [] as anything but optional, one could say there is not a true standard.

Solution 2

Yes, the square brackets indicate optional arguments in Unix man pages.

From "man man":

[-abc] any or all arguments within [ ] are optional.