Expand help customisation with .addHelpText

[shadowspawn]

Pull Request

Problem

1. can not add a splash screen/title/banner to the help
2. can not add a global epilog
3. event listener is a little clunky and unfamiliar to use
4. help is displayed on stdout even when being displayed as an "error"

See #1225 for collected custom help issues, and #997 for error output.

• beforeAll: Add Support For Title? #46 Option to prefix help with text #578 Question: Is it possible to have a splash screen? #1272
• before: Customize help message for a command #1023

Solution

Add .addHelpText() which takes a position as first parameter, and a string to add or a function returning a string. Position is 'before' or 'after' to affect just this command, and 'beforeAll' or 'afterAll' to affect this command and all its subcommands.

For example:

program.addHelpText('afterAll', '/nSee the web site for more information');

Also:

• .help() and .outputHelp() can be passed { error: true } to write to stderr.
• Deprecate passing callback to .help() and .outputHelp()
• Deprecate .on('--help')

ChangeLog

• use .addHelpText() to add text before or after the built-in help, for just current command or also for all subcommands (Expand help customisation with .addHelpText #1296)
• deprecated callback parameter to .help() and .outputHelp() (removed from README)
• deprecate .on('--help') (removed from README)

[westhom]

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.

[shadowspawn]

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.

[shadowspawn]

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.

[shadowspawn]

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!

[abetomo]

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

[shadowspawn]

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

[shadowspawn]

I have merged develop into release/7.x.

[abetomo]

LGTM 👍

[crystalfp]

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

[shadowspawn]

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.

[crystalfp]

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”.