proposed change: don't spew all --help output for every usage error

proposed change: don't spew all --help output for every usage error

[Jim Meyering]

Any time I misuse an option or use invalid command syntax,
a tool like lvcreate gives a diagnostic saying what went wrong,
and follows it with almost 50 lines of usage information.
That's almost enough to make the important, one-line diagnostic,
scroll beyond the top of my terminal emulator window.

I propose to change this so that upon error, users do still
see the relevant one-line diagnostic (of course), but rather than
the voluminous and obscuring --help output, the tool would simply
output one more line:

  Try `lvcreate --help' for more information.

Also, for all tools, --help output currently goes to stderr.
I will be happy to submit another patch to make the LVM tools
work more like most of the other unix/gnu tools that take --help
as an option: they print --help output to standard output.
That makes it easier for novices to grep through the help output
or to send it through a pager or other pipe.
Besides, when there is no "error", why write to stderr?

FWIW, I've just run into this while writing tests for lvcreate.
I wanted to compare expected error output with actual, but embedding
all 47 "expected" lines in the test script seems excessive.  Also,
when I looked at the actual output, at first I didn't even see the
real diagnostic I'd been expecting, buried amid all the --help output.
So, if *I*, who was expecting a particular diagnostic, nearly miss it,
the average user may not look as hard, and end up having to figure out
the hard way what they did wrong.

So, actually there are two proposals:

  - Print "Try `$cmd --help' for more information." instead of all --help
    output upon bogus command line usage. (still to stderr, of course)

  - Print --help output to stdout, not stderr.

Re: proposed change: don't spew all --help output for every usage error

[Alasdair G Kergon]

On Mon, Sep 17, 2007 at 02:55:42PM +0200, Jim Meyering wrote:
> Any time I misuse an option or use invalid command syntax,
> a tool like lvcreate gives a diagnostic saying what went wrong,
> and follows it with almost 50 lines of usage information.

An approach inherited from LVM1.  Yes, let's change it.

>   Try `lvcreate --help' for more information.
 
'Use' or 'Run' rather than 'Try'?
'more information': currently it's just the command syntax we give.
-h also works.

> as an option: they print --help output to standard output.

stderr is sensible today, because these are error messages.
But if they are only going to appear when you explicitly ask for them
with -h then stdout makes sense.

>   - Print "Try `$cmd --help' for more information." instead of all --help
>     output upon bogus command line usage. (still to stderr, of course)

So yes, but the wording should be improved.
 
>   - Print --help output to stdout, not stderr.

Yes, after the first change.

Alasdair
-- 
agk at redhat.com

revised error output: Run ... --help for more information

[Jim Meyering]

Alasdair G Kergon <agk@redhat.com> wrote:
> On Mon, Sep 17, 2007 at 02:55:42PM +0200, Jim Meyering wrote:
>> Any time I misuse an option or use invalid command syntax,
>> a tool like lvcreate gives a diagnostic saying what went wrong,
>> and follows it with almost 50 lines of usage information.
>
> An approach inherited from LVM1.  Yes, let's change it.
>
>>   Try `lvcreate --help' for more information.
>
> 'Use' or 'Run' rather than 'Try'?
> 'more information': currently it's just the command syntax we give.
> -h also works.
>
>> as an option: they print --help output to standard output.
>
> stderr is sensible today, because these are error messages.
> But if they are only going to appear when you explicitly ask for them
> with -h then stdout makes sense.
>
>>   - Print "Try `$cmd --help' for more information." instead of all --help
>>     output upon bogus command line usage. (still to stderr, of course)
>
> So yes, but the wording should be improved.
>
>>   - Print --help output to stdout, not stderr.
>
> Yes, after the first change.

Good!

I implemented the above (step 1), and now see this:

    $ ./lvchange
      Need 1 or more of -a, -C, -j, -m, -M, -p, -r, --resync, --refresh, --alloc, --addtag, --deltag or --monitor
      lvchange: Run `lvchange --help' for more information.

    [Exit 3]


Note the lack of a command name on the "real" diagnostic line.
And the fact that it appears twice on the Run --help line.

I want to reverse that, so the command name appears where it's more useful
(on the line with the real diagnostic), and not on the Run --help line:

    $ ./lvchange
      lvchange: Need 1 or more of -a, -C, -j, -m, -M, -p, -r, --resync, --refresh, --alloc, --addtag, --deltag or --monitor
      Run `lvchange --help' for more information.

    [Exit 3]

This has two advantages:

  * primarily: when an lvm command fails within a script run by a script
  invoked by another, it's far easier to determine which program emitted any
  given diagnostic when the command's name is right there on the same line.

  * consistency: nearly every other Unix command-line program prints
  diagnostics like this: printf_style ("%s: %s", command_name, diagnostic)

The consistency argument is non-negligible.  I've used tools that
search for diagnostics using a regular expression like /^\w+:/.
They wouldn't detect LVM diagnostics the way they're formatted, now.

revised error output: Run ... --help for more information

[Alasdair G Kergon]

Be aware that this is partly configurable already, but
can still come out looking a bit of a mess.
E.g. In lvm.conf set log { command_names = 1 prefix = ": " }

Alasdair
-- 
agk at redhat.com

revised error output: Run ... --help for more information

[Jim Meyering]

Alasdair G Kergon <agk@redhat.com> wrote:
> Be aware that this is partly configurable already, but
> can still come out looking a bit of a mess.
> E.g. In lvm.conf set log { command_names = 1 prefix = ": " }

Oh!  Thanks.

It'd be nice to make that the default,
but I guess there are reasons.

All the more reason to make the new tests use their own /etc and /dev
directories.

revised error output: Run ... --help for more information

[Alasdair G Kergon]

On Fri, Sep 21, 2007 at 01:30:03PM +0200, Jim Meyering wrote:
>     $ ./lvchange
>       Need 1 or more of -a, -C, -j, -m, -M, -p, -r, --resync, --refresh, --alloc, --addtag, --deltag or --monitor
>       lvchange: Run `lvchange --help' for more information.
 
So we should certainly drop the 'lvchange:' now from the second line of output.

>       lvchange: Need 1 or more of -a, -C, -j, -m, -M, -p, -r, --resync, --refresh, --alloc, --addtag, --deltag or --monitor

So should we add a new option (command_names = 2, perhaps)
that only applies it to messages produced using log_error()
rather than for all output?  [And make this the default setting.]

Or do we only want it (roughly speaking) for EINVALID_CMD_LINE not for
ECMD_FAILED?

Alasdair
-- 
agk at redhat.com

revised error output: Run ... --help for more information

[Jim Meyering]

Alasdair G Kergon <agk@redhat.com> wrote:
> On Fri, Sep 21, 2007 at 01:30:03PM +0200, Jim Meyering wrote:
>>     $ ./lvchange
>>       Need 1 or more of -a, -C, -j, -m, -M, -p, -r, --resync, --refresh, --alloc, --addtag, --deltag or --monitor
>>       lvchange: Run `lvchange --help' for more information.
>
> So we should certainly drop the 'lvchange:' now from the second line of output.

Good.  It's already gone in my current sources.

>>       lvchange: Need 1 or more of -a, -C, -j, -m, -M, -p, -r, --resync, --refresh, --alloc, --addtag, --deltag or --monitor
>
> So should we add a new option (command_names = 2, perhaps)
> that only applies it to messages produced using log_error()
> rather than for all output?  [And make this the default setting.]
>
> Or do we only want it (roughly speaking) for EINVALID_CMD_LINE not for
> ECMD_FAILED?

Personally, I'd like the "command_name: " prefix
on all "real" diagnostic lines -- and that'd be consistent
with what other tools do.  In my experience, the "Run ... --help"
diagnostic is most useful on EINVALID_CMD_LINE failures.