proposal: flag: add SetHelpOutput to specify the destination for help explicitly

[Songmu]

I was pleased to see the exit code set to 0 when -h/--help was explicitly specified with Go 1.15 or later. ref. #37533.

I have one more request for -h/--help. It is that I want to be able to output usage to Stdout instead of Stderr only when the help flag is explicitly specified. This is useful when we want to pipe the output to a pager such as less.

I've made the following changes to allow us to specify the output destination for help. How about it?

cbb8882

[mvdan]

Personally, I'm not sure that this is a convincing argument. Lots of programs print their help text to stderr, so if you want to use a pager, you have to know how to handle stderr anyway.

In any POSIX-compatible shell, you can just do foo -h 2>&1 | less. Bash also has a shortcut for this, foo -h |& less.

Finally, if you really do care about this detail, you could always just set your own usage func to print to stdout.

[ianlancetaylor]

There were objections to the change in exit status; see #37533 (comment) and the following discussion. I think there would be even stronger objections to changing from standard error to standard output.

I agree that using standard output would make sense and would be consistent with the GNU coding standards (https://www.gnu.org/prep/standards/html_node/_002d_002dhelp.html). But I don't think we can change it now.

[Songmu]

Yes, I also don't want to put in a breaking change. I just want to be able to specify a destination optionally only for --help is specified explicitly. For example, fs.SetHelpOutput(os.Stdout).

Also, I only want to change the output destination when --help is explicitly specified. Although a usage is also output on flag parse errors, I want to unify the output to fs.Output, which is generally Stderr. This behavior cannot be achieved by simply changing fs.Usage.

[rsc]

Note that SetHelpOutput would be inappropriate when --help is not specified, that is, when Usage is being called because of an unknown command-line flag. Even the GNU tools print to standard error in that case.

I would suggest that if you really want to implement -help, add that as a flag using the new flag.Func, and then it's easy to do:

os.Stderr = os.Stdout

at the top of your implementation.

[Songmu]

I also think that if --help is not explicitly specified, then STDERR is appropriate.

As you suggested, defining --help flag explicitly is certainly better and clearer idea. I close this issue that it satisfy my requirement.