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)

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