Should the usage message be printed out in all cases when an error is reported?

[ndokos]

This issue arose in pbench-register-tool-set and pbench-register-tool: they both issue a (sometimes long) usage message after an error is encountered that causes the program to exit. The worry is that the error message is easy to miss.

We might want to come up with criteria about when to output the usage message: maybe if the error is an error in the command line invocation itself (e.g. a wrong option or an unrecognized value for an option) then we show the usage message. If however, the error is "deeper" (i.e. the command line would be fine with other values of options, but something in the current values causes an error that aborts the run) then maybe the usage message is not needed.

WDYT?

[dbutenhof]

One option is to have separate long and brief usage messages; maybe syntactical issues should be reported with a brief usage, but any "full usage" message that goes over 1/4 screen or so might be reserved for an explicit --help invocation.

As we move towards click groups and subcommands ... a separate help subcommand for "documentation" on a command might be a good way to move forward, with the error "usage" reminder being a small summary showing the options but without much (if any) description, that would fit in a few lines and not be quite so distracting when you just made a minor typo or something of that nature.

[webbnh]

I agree with both of you: if there is nothing wrong with the syntax of the command line, then the usage message (long or short) is unlikely to be useful -- what is needed is a description of the problem, without obscuring it with extra, pointless text; however, I also think it would be handy to have long and short usage messages (this is quite common among other utilities) -- we can print the short one in association with command line syntax errors and print the long one when requested by --help.