Hi there, one thing I badly wanted from commander was the ability to group commands and options in help output, for readability. I implemented it as a quick hack here: https://github.com/westhom/commander.js/compare/c5a5e7b7..86a1980b.

For commands, you can call program.command(...).helpGroup(N), where N is a group index the command belongs to. For options it wasn't as clean, set through a new param: program.option('-k', 'set K', undefined, undefined, N). The help generator methods sort commands/options by their group before formatting the line. By default everything belongs to group 0 and if no other groups exist the help output is normal. Example:

Usage: help-groups [options] [command]

Options:
  -a                 set A
  -b                 set B
  -c                 set C
  
  -q                 set Q
  -r                 set R
  -s                 set S
  
  -h, --help         display help for command

Commands:
  login              log in
  logout             log out
  
  read <process>     read it
  update <process>   update it
  delete <process>   delete it
  refresh <process>  refresh it
  
  publish            publisher
  unpublish          unpublisher
  
  help [command]     display help for command

I was going to open a PR for this but it looks like help is being revamped. It could be nice to have a grouping option like that.

To be safe, the change to use stderr for displaying the help in response to an error makes it a semver major change.

The other changes are backwards compatible, as the --help event and the .help(cb) callback are deprecated but not removed.

I am happier with how this is looking now with an explicit routine which is more readable than an event listener, and leaving the ability to override the built-in help out of this routine.

I deprecated the callbacks to .help() and .outputHelp() as this PR originally included being able to override the built-in help too. That is no longer included, but I would still like to call the callbacks deprecated so can remove them in future!

Could you merge develop into release/7.x?
This includes the 6.1.0 differences.

Oops, will do. I was merging 6.1 into the PR so the diff against develop looked better, missed doing 7.x too.

I have merged develop into release/7.x.

Only a (minor) issue in the new version:

1. .addHelpText("after", "\n") adds two blank lines after help.
2. .addHelpText("after", "") adds nothing after help.
3. .addHelpText("after", " ") adds one blank line after help.

A little confusing. If case 1 should behave as console.log() then case 2 should add one blank line after help. Instead, if the function behaves like write() then case 1 should add one blank line, in my opinion.

Besides this minor issue, the new version is excellent. Thanks!
mario

Case 2 is a special case. If there is an empty string then nothing is output. This is to support a function generating the string deciding that there is nothing to be displayed.

OK, understand. Maybe adding a line to documentation stating this could be useful. Something like this at the end of the Custom help paragraph: “If the string or the output of the function is an empty string, nothing is output, otherwise the string is output followed by a newline”.