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)?
(3)3 Comments
Sorted by latest first Latest Oldest Best
Usually, your first line takes care of that:
Do FOO in the most awesome way possible
Square braces for [OPTIONS] imply all options are optional.
If arguments modify the behavior, give the default behavior in absence of an argument.
-f filename Perform FOO on file given, instead of standard input.
If parameters were not optional, you put them in <>.
foo [OPTIONS] <URL>
Process FOO of the URL in the most awesome way possible.
In this case, if this use is standard, but you may allow exceptional use without the URL, you detail this in the last line, apart from the options:
Called without arguments, foo displays this help, same as -h.
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
I must misunderstand your question, but it seems to me that the function call without argument is already explained in the function description:
Terms of Use Privacy policy Contact About Cancellation policy © freshhoot.com2025 All Rights reserved.