Documenting the no-args call of a command line program
I am writing the built-in help for a command line program. The exact name is irrelevant, so let's use foo as a placeholder.
This utility can be called with some arguments (like foo -v) or without any arguments at all (just foo).
I'm struggling with describing the no-argument call in the built-in help. (There's a common practice that the -h or --help argument is used to print that help on the screen.)
A common output of -h command looks like this:
$ foo -h
foo [OPTIONS...]
Do FOO in the most awesome way possible
-h --help Show this help
-v --version Show package version
Note the pattern for explaining arguments:
(short) (long) Explanation
The no-argument call doesn't fit in this pattern. All these variants look quite unnatural:
foo Do the FOO
Do the FOO
(no arguments) Do the FOO
In search for examples I've looked at several utilities that have valid no-argument calls (e.g. sh, bash and other shells, systemctl), but none of them describe that in the -h output.
The question: what is the proper way of documenting the no-arguments call in the built-in help?
- Should I write something in the place of
(no arguments)above? - Or should I explain that in a different place (where)?
This post was sourced from https://writers.stackexchange.com/q/26982. It is licensed under CC BY-SA 3.0.
1 answer
Arguments modify the behavior of a program. Running it without arguments means you get is default, unmodified behavior. So the help should describe the default unmodified behavior first, in the body of the description.
$ foo -h
foo [OPTIONS...]
Foo does X. For example:
foo
X happens.
To make foo do Y, use the -y option. For example:
foo -y
X happens with a shot of Y.
Arguments:
-h --help Show this help
-v --version Show package version
-y Make Y happen
0 comment threads
0 comment threads