How to interpret the bash command "usage" syntax?

Question

How exactly do you have to interpret the output of a commands "usage" output, in bash for example.

For example, on my OS X, cp gives me

usage: cp [-R [-H | -L | -P]] [-fi | -n] [-apvX] source_file target_file
       cp [-R [-H | -L | -P]] [-fi | -n] [-apvX] source_file ... target_directory

• What does the nested options, like -H within -R, indicate?
• Does upper and lower case have any meaning?
• When is an argument optional, required?

I need to implement a telnet command line against a program of mine and I would like to get this straight.

Solution 1

For anyone trying to understand what usage output means, the best way is to man man.

seriously :-) Take the time to learn the conventions, it really helps.

   The following conventions apply to the SYNOPSIS section and can be used
   as a guide in other sections.

   bold text          type exactly as shown.
   italic text        replace with appropriate argument.
   [-abc]             any or all arguments within [ ] are optional.
   -a|-b              options delimited by | cannot be used together.
   argument ...       argument is repeatable.
   [expression] ...   entire expression within [ ] is repeatable.

Solution 2

First of all, while there are general conventions, they are not uniformly applied.

• In this case, it's saying that if you use -R (indicating "recursion"), then you can use either -H, -L, or -P. If you don't use -R, then those options are not relevant.
• Yes, case is almost always important. So usually -h and -H do completely different things.
• The square brackets generally indicate that an option or argument is "optional". (The things with hyphens in front of them are "options", the words without hyphens are arguments.) Without brackets the option or argument is generally required. In your example, both "source_file" and "target_directory" are required. The "..." indicates that the previous argument can be repeated.

Other points worth noting:

• The vertical bar indicates "OR". So [-fi | -n] indicates you can use either -f and/or -i but not in combination with -n.
• Grouped options in brackets indicate you can use any of them. So [-apvX] indicates you can use any combination of those options. They don't even need to be smashed together. So -a -v -p would be a valid combination.

Comments

[Warner]

+1 deleting my post as redundant.

[Wildcard]

man man on CentOS 6.6 doesn't have this section; nor does the version of man man on Mac OS X 10.7.4. Where can I find it?

[Wildcard]

Found it, it's man man-pages in CentOS and man manpages on Mac OS X (which uses BSD commands).

[Addison]

This answer, as well as the man man command doesn't seem to cover cases where the input must be one of the items in an enumeration. For example <env> - must be one of [dev | test | uat | perf | prod]