Is there a best practice to documenting a Command Line Interface? [closed] - shell

Question

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 8 years ago.
Improve this question
I have designed a few programs that have a CLI and want to document them as standard as possible. Are there any agreements out there as to the best way to do this?
An example:
Let's say the Program is "sayHello" and it takes in a few parameters: name and message. So a standard call would look like this:
> sayHello "Bob" "You look great"
Okay, so my command usage would look something like this:
sayHello [name] [message]
That may already be a mistake if brackets have a specific meaning in usage commands. But let's go a step farther and say "message" is optional:
sayHello [name] [message (optional)]
And then just one more wrinkle, what if there is a default we want to denote:
sayHello [name] [message (optional: default 'you look good')]
I realize this usage statement looks a little obtuse at this point. I'm really asking if there are somewhat agreed-upon standards on how to write these. I have a sneaking suspicion that the parenthesis and brackets all have specific meanings.

Answer 1

While I am unaware of any official standard, there are some efforts to provide conventions-by-framework. Docopt is one such framework, and may suit your needs here. In their own words:
docopt helps you:
define interface for your command-line app, and
automatically generate parser for it.
There are implementations for many programming languages, including shell.

Answer 2

You might want to look at the manuals for common Unix commands (e.g. man grep) or the help documentation for Windows commands (e.g. find /?) and using them as a general guide. If you picked either of those patterns (or used some elements common to both), you'd at least surprise the fewest number of people.
Apache commons also has some classes in the commons-cli package that will print usage information for your particular set of command-line options.
Options options = new Options();
options.addOption(OptionBuilder.withLongOpt("file")
.withDescription("The file to be processed")
.hasArg()
.withArgName("FILE")
.isRequired()
.create('f'));
options.addOption(OptionBuilder.withLongOpt("version")
.withDescription("Print the version of the application")
.create('v'));
options.addOption(OptionBuilder.withLongOpt("help").create('h'));
String header = "Do something useful with an input file\n\n";
String footer = "\nPlease report issues at http://example.com/issues";
HelpFormatter formatter = new HelpFormatter();
formatter.printHelp("myapp", header, options, footer, true);
Using the above will generate help output that looks like:
usage: myapp -f [-h] [-v]
Do something useful with an input file
-f,--file <FILE> The file to be processed
-h,--help
-v,--version Print the version of the application
Please report issues at http://example.com/issues