From d355b52d2013def008e7874c14f97d4fd96ed26f Mon Sep 17 00:00:00 2001 From: John Gee Date: Wed, 27 Nov 2024 08:40:18 +1300 Subject: [PATCH] More Help documentation (#2282) --- Readme.md | 30 +------ docs/help-in-depth.md | 127 ++++++++++++++++++++++++++++ examples/color-help-replacement.mjs | 2 +- 3 files changed, 129 insertions(+), 30 deletions(-) create mode 100644 docs/help-in-depth.md diff --git a/Readme.md b/Readme.md index 4cc70c207..38cc824ae 100644 --- a/Readme.md +++ b/Readme.md @@ -923,35 +923,7 @@ program.helpCommand('assist [command]', 'show assistance'); The built-in help is formatted using the Help class. You can configure the Help behaviour by modifying data properties and methods using `.configureHelp()`, or by subclassing using `.createHelp()` if you prefer. -The data properties are: - -- `helpWidth`: specify the wrap width, useful for unit tests -- `minWidthToWrap`: specify required width to allow wrapping (default 40) -- `sortSubcommands`: sort the subcommands alphabetically -- `sortOptions`: sort the options alphabetically -- `showGlobalOptions`: show a section with the global options from the parent command(s) - -You can override any method on the [Help](./lib/help.js) class. There are methods getting the visible lists of arguments, options, and subcommands. There are methods for formatting the items in the lists, with each item having a _term_ and _description_. Take a look at `.formatHelp()` to see how they are used. - -Example file: [configure-help.js](./examples/configure-help.js) - -```js -program.configureHelp({ - sortSubcommands: true, - subcommandTerm: (cmd) => cmd.name() // Just show the name, instead of short usage. -}); -``` - -There are _style_ methods to add color to the help, like `styleTitle` and `styleOptionText`. There is built-in support for respecting -environment variables for `NO_COLOR`, `FORCE_COLOR`, and `CLIFORCE_COLOR`. - -Example file: [color-help.mjs](./examples/color-help.mjs) - -Other help configuration examples: -- [color-help-replacement.mjs](./examples/color-help-replacement.mjs) -- [help-centered.mjs](./examples/help-centered.mjs) -- [help-subcommands-usage.js](./examples/help-subcommands-usage.js) -- [man-style-help.mjs](./examples/man-style-help.mjs) +For more detail see (./docs/help-in-depth.md) ## Custom event listeners diff --git a/docs/help-in-depth.md b/docs/help-in-depth.md new file mode 100644 index 000000000..b50f9e25e --- /dev/null +++ b/docs/help-in-depth.md @@ -0,0 +1,127 @@ +# Help in Depth + +The built-in help is formatted using the Help class. +You can configure the Help behaviour by modifying data properties and methods using `.configureHelp()`, or by subclassing using `.createHelp()` if you prefer. + +Example file: [configure-help.js](../examples/configure-help.js) + +```js +program.configureHelp({ + sortSubcommands: true, + subcommandTerm: (cmd) => cmd.name() // Just show the name, instead of short usage. +}); +``` + +- [Help in Depth](#help-in-depth) + - [Data Properties](#data-properties) + - [Stringify and Style](#stringify-and-style) + - [Layout](#layout) + +## Data Properties + +The data properties are: + +- `helpWidth`: specify the wrap width, useful for unit tests +- `minWidthToWrap`: specify required width to allow wrapping (default 40) +- `showGlobalOptions`: show a section with the global options from the parent command(s) +- `sortSubcommands`: sort the subcommands alphabetically +- `sortOptions`: sort the options alphabetically + +Example files: +- [configure-help.js](../examples/configure-help.js) +- [global-options-nested.js](../examples/global-options-nested.js) + +## Stringify and Style + +The `Help` object has narrowly focused methods to allow customising the displayed help. + +The stringify routines take an object (`Command` or `Option` or `Argument`) and produce a string. For example you could change the way subcommands are listed: + +```js +program.configureHelp({ + subcommandTerm: (cmd) => cmd.name() // just show the name instead of usage +}); +``` + +The style routines take just a string. For example to make the titles bold: + +```js +import { styleText } from 'node:util'; +program.configureHelp({ + styleTitle: (str) => styleText('bold', str) +}); +``` + +There is built-in support for detecting whether the output has colors, and respecting environment variables for `NO_COLOR`, `FORCE_COLOR`, and `CLIFORCE_COLOR`. The style routines always get called and color is stripped afterwards if needed using `Command.configureOutput().stripColor()`. + +This annotated help output shows where the stringify and style routines are used. The first output is for a program with subcommands, and the second output is for a subcommand with arguments. + + +```text +Usage: color-help [options] [command] +<-1--> <-------------2--------------> + <---a----> <---b---> <---c---> + +program description +<--------3--------> + +Options: +<--1---> + -h, --help display help for command + <---4----> <---------5------------> + +Commands: +<---1---> + print [options] print files + <----------6----------> <----7----> + <-b-> <---c---> <--d--> +``` + +| | stringify(object) | style(string) | default style | +| - | - | - | - | +| 1 | | styleTitle | | +| 2 | commandUsage | styleUsage | a, b, c, d | +| 3 | commandDescription | styleCommandDescription | styleDescriptionText | +| 4 | optionTerm | styleOptionTerm | styleOptionText | +| 5 | optionDescription | styleOptionDescription | styleDescriptionText | +| 6 | subcommandTerm | styleSubcommandTerm | b, c, d | +| 7 | subcommandDescription | styleSubcommandDescription | styleDescriptionText| +| 8 | argumentTerm | styleArgumentTerm | styleArgumentText | +| 9 | argumentDescription | styleArgumentDescription | styleDescriptionText | +| a | | styleCommandText | | +| b | | styleOptionText | | +| c | | styleSubcommandText | | +| d | | styleArgumentText | | + +```text +Usage: color-help print [options] +<-1--> <---------------2-------------------> + <---a----> <-c-> <---b---> <---d----> + +Arguments: +<---1----> + files files to queue for printing + <-8-> <------------9------------> +... +``` + +Color example files: + +- [color-help.mjs](../examples/color-help.mjs) +- [color-help-replacement.mjs](../examples/color-help-replacement.mjs) + +Stringify example files (`subcommandTerm`): + +- [help-subcommands-usage.js](../examples/help-subcommands-usage.js) +- [configure-help.js](../examples/configure-help.js) + +## Layout + +Utility methods which control the layout include `padWidth`, `boxWrap`, and `formatItem`. These can be overridden to change the layout or replace with an alternative implementation. + +Example files: + +- `formatItem`: [help-centered.mjs](../examples/help-centered.mjs) +- `formatItem`: [man-style-help.mjs](../examples/man-style-help.mjs) +- `boxwrap`: [color-help-replacement.mjs](../examples/color-help-replacement.mjs) + diff --git a/examples/color-help-replacement.mjs b/examples/color-help-replacement.mjs index c53bd2e1f..51e1d6527 100644 --- a/examples/color-help-replacement.mjs +++ b/examples/color-help-replacement.mjs @@ -9,7 +9,7 @@ import { import { Command, Help } from 'commander'; // Replace default color and wrapping support with Chalk packages as an example of -// a deep replacement of format and style support. +// a deep replacement of layout and style support. // This example requires chalk and wrap-ansi and strip-ansi, and won't run // from a clone of Commander repo without installing them first.