Skip to content

Commit d355b52

Browse files
shadowspawnshadowspawn
authored
More Help documentation (#2282)
1 parent 437e4e3 commit d355b52

File tree

3 files changed

+129
-30
lines changed

3 files changed

+129
-30
lines changed

‎Readme.md

+1-29
Original file line numberDiff line numberDiff line change
@@ -923,35 +923,7 @@ program.helpCommand('assist [command]', 'show assistance');
923923
The built-in help is formatted using the Help class.
924924
You can configure the Help behaviour by modifying data properties and methods using `.configureHelp()`, or by subclassing using `.createHelp()` if you prefer.
925925

926-
The data properties are:
927-
928-
- `helpWidth`: specify the wrap width, useful for unit tests
929-
- `minWidthToWrap`: specify required width to allow wrapping (default 40)
930-
- `sortSubcommands`: sort the subcommands alphabetically
931-
- `sortOptions`: sort the options alphabetically
932-
- `showGlobalOptions`: show a section with the global options from the parent command(s)
933-
934-
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.
935-
936-
Example file: [configure-help.js](./examples/configure-help.js)
937-
938-
```js
939-
program.configureHelp({
940-
sortSubcommands: true,
941-
subcommandTerm: (cmd) => cmd.name() // Just show the name, instead of short usage.
942-
});
943-
```
944-
945-
There are _style_ methods to add color to the help, like `styleTitle` and `styleOptionText`. There is built-in support for respecting
946-
environment variables for `NO_COLOR`, `FORCE_COLOR`, and `CLIFORCE_COLOR`.
947-
948-
Example file: [color-help.mjs](./examples/color-help.mjs)
949-
950-
Other help configuration examples:
951-
- [color-help-replacement.mjs](./examples/color-help-replacement.mjs)
952-
- [help-centered.mjs](./examples/help-centered.mjs)
953-
- [help-subcommands-usage.js](./examples/help-subcommands-usage.js)
954-
- [man-style-help.mjs](./examples/man-style-help.mjs)
926+
For more detail see (./docs/help-in-depth.md)
955927

956928
## Custom event listeners
957929

‎docs/help-in-depth.md

+127
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Help in Depth
2+
3+
The built-in help is formatted using the Help class.
4+
You can configure the Help behaviour by modifying data properties and methods using `.configureHelp()`, or by subclassing using `.createHelp()` if you prefer.
5+
6+
Example file: [configure-help.js](../examples/configure-help.js)
7+
8+
```js
9+
program.configureHelp({
10+
sortSubcommands: true,
11+
subcommandTerm: (cmd) => cmd.name() // Just show the name, instead of short usage.
12+
});
13+
```
14+
15+
- [Help in Depth](#help-in-depth)
16+
- [Data Properties](#data-properties)
17+
- [Stringify and Style](#stringify-and-style)
18+
- [Layout](#layout)
19+
20+
## Data Properties
21+
22+
The data properties are:
23+
24+
- `helpWidth`: specify the wrap width, useful for unit tests
25+
- `minWidthToWrap`: specify required width to allow wrapping (default 40)
26+
- `showGlobalOptions`: show a section with the global options from the parent command(s)
27+
- `sortSubcommands`: sort the subcommands alphabetically
28+
- `sortOptions`: sort the options alphabetically
29+
30+
Example files:
31+
- [configure-help.js](../examples/configure-help.js)
32+
- [global-options-nested.js](../examples/global-options-nested.js)
33+
34+
## Stringify and Style
35+
36+
The `Help` object has narrowly focused methods to allow customising the displayed help.
37+
38+
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:
39+
40+
```js
41+
program.configureHelp({
42+
subcommandTerm: (cmd) => cmd.name() // just show the name instead of usage
43+
});
44+
```
45+
46+
The style routines take just a string. For example to make the titles bold:
47+
48+
```js
49+
import { styleText } from 'node:util';
50+
program.configureHelp({
51+
styleTitle: (str) => styleText('bold', str)
52+
});
53+
```
54+
55+
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()`.
56+
57+
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.
58+
59+
60+
```text
61+
Usage: color-help [options] [command]
62+
<-1--> <-------------2-------------->
63+
<---a----> <---b---> <---c--->
64+
65+
program description
66+
<--------3-------->
67+
68+
Options:
69+
<--1--->
70+
-h, --help display help for command
71+
<---4----> <---------5------------>
72+
73+
Commands:
74+
<---1--->
75+
print [options] <files> print files
76+
<----------6----------> <----7---->
77+
<-b-> <---c---> <--d-->
78+
```
79+
80+
| | stringify(object) | style(string) | default style |
81+
| - | - | - | - |
82+
| 1 | | styleTitle | |
83+
| 2 | commandUsage | styleUsage | a, b, c, d |
84+
| 3 | commandDescription | styleCommandDescription | styleDescriptionText |
85+
| 4 | optionTerm | styleOptionTerm | styleOptionText |
86+
| 5 | optionDescription | styleOptionDescription | styleDescriptionText |
87+
| 6 | subcommandTerm | styleSubcommandTerm | b, c, d |
88+
| 7 | subcommandDescription | styleSubcommandDescription | styleDescriptionText|
89+
| 8 | argumentTerm | styleArgumentTerm | styleArgumentText |
90+
| 9 | argumentDescription | styleArgumentDescription | styleDescriptionText |
91+
| a | | styleCommandText | |
92+
| b | | styleOptionText | |
93+
| c | | styleSubcommandText | |
94+
| d | | styleArgumentText | |
95+
96+
```text
97+
Usage: color-help print [options] <files...>
98+
<-1--> <---------------2------------------->
99+
<---a----> <-c-> <---b---> <---d---->
100+
101+
Arguments:
102+
<---1---->
103+
files files to queue for printing
104+
<-8-> <------------9------------>
105+
...
106+
```
107+
108+
Color example files:
109+
110+
- [color-help.mjs](../examples/color-help.mjs)
111+
- [color-help-replacement.mjs](../examples/color-help-replacement.mjs)
112+
113+
Stringify example files (`subcommandTerm`):
114+
115+
- [help-subcommands-usage.js](../examples/help-subcommands-usage.js)
116+
- [configure-help.js](../examples/configure-help.js)
117+
118+
## Layout
119+
120+
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.
121+
122+
Example files:
123+
124+
- `formatItem`: [help-centered.mjs](../examples/help-centered.mjs)
125+
- `formatItem`: [man-style-help.mjs](../examples/man-style-help.mjs)
126+
- `boxwrap`: [color-help-replacement.mjs](../examples/color-help-replacement.mjs)
127+

‎examples/color-help-replacement.mjs

+1-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ import {
99
import { Command, Help } from 'commander';
1010

1111
// Replace default color and wrapping support with Chalk packages as an example of
12-
// a deep replacement of format and style support.
12+
// a deep replacement of layout and style support.
1313

1414
// This example requires chalk and wrap-ansi and strip-ansi, and won't run
1515
// from a clone of Commander repo without installing them first.

0 commit comments

Comments
 (0)