Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Documenting the no-args call of a command line program

+0
−0

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)?
History
Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

This post was sourced from https://writers.stackexchange.com/q/26982. It is licensed under CC BY-SA 3.0.

0 comment threads

1 answer

+0
−0

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
History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

Sign up to answer this question »