10

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)?
  • 2
    @NeilFein Was planning to do so the minute I made the comment. Here:meta.writers.stackexchange.com/questions/1271/… – Mark Baker Mar 1 '17 at 20:03
  • 4
    @NickVolynkin, welcome to Writers and thank you for bringing your question here. I hope you'll continue to ask tech-writing questions here. Check out the tag, too; we have a bunch of other questions you might be interested in. – Monica Cellio Mar 1 '17 at 21:22
9

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
  • 2
    I salute you, sir, for not only making sense of that question but actually coming up with a comprehensible, usable answer. – Lauren Ipsum Mar 1 '17 at 17:40
  • 1
    Note that this is why those other command docs didn't have a "no-args" line where you were looking. – the dark wanderer Mar 2 '17 at 5:42
  • 1
    I do it almost the same. I might say foo with no arguments does ... Another way to address this is to add a defaults to section for optional arguments which gives more details of what foo does without a separate section for it. – Joe Mar 8 '17 at 9:08
5

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.
  • Square braces for [OPTIONS] imply all options are optional – yes, that is exactly what I meant. – Nick Volynkin Mar 1 '17 at 14:57
  • Lots of CLI utilities really display help when called without arguments or with wrong arguments. But in my case the no-args call is not exceptional or erroneous. – Nick Volynkin Mar 1 '17 at 15:00
  • Yes, this. Here's an example of a command with default behavior and a bunch of options. – Monica Cellio Mar 1 '17 at 21:19
  • @MonicaCellio thanks for the example, it is just perfect. Shame on me for not thinking about ls. :) – Nick Volynkin Mar 2 '17 at 8:02
  • 1
    Re-read this answer just now. Thanks for pointing at the difference between standard and exceptional use. It appears quite important. – Nick Volynkin Mar 2 '17 at 8:06
3

I must misunderstand your question, but it seems to me that the function call without argument is already explained in the function description:

enter image description here

  • 2
    The example was oversimplified and real CLI utilities usually have more text before the args table. And what I meant was the description of the overall functionality, related to any of the arguments below. But you're right. That is exactly the place where it is explained, or at least should be explained. – Nick Volynkin Mar 2 '17 at 7:59

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.