RubyGems - dry-cli-help - Versions diffs - 0.1.0 → 0.5.0 - Mend

dry-cli-help 0.1.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +17 -0
data/README.md +312 -72
data/Rakefile +1 -1
data/lib/dry/cli/help/configuration.rb +80 -47
data/lib/dry/cli/help/formatter.rb +6 -3
data/lib/dry/cli/help/integration.rb +2 -30
data/lib/dry/cli/help/screens/command.rb +6 -6
data/lib/dry/cli/help/screens/listing.rb +2 -2
data/lib/dry/cli/help/version.rb +1 -1
data/lib/dry/cli/help.rb +13 -17
metadata +3 -10
data/SPECIFICATION.md +0 -200

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8756ab593e09c6cdc0e0ab32fe6f3909d05625734a07e7d7c334e3d832ba70ac
-  data.tar.gz: 4477df389d4c4c0d984fe4024f768adf3e254772464694f7acd81609936060a4
+  metadata.gz: 10fb8e86e571ad96c6f523f4807d040b0421ebe1fa65e334738fa785e0212196
+  data.tar.gz: 408f6dd175e32d407f38306c9c61211a9b8e9d7e82f8870cde02ce58cfe64a23
 SHA512:
-  metadata.gz: 6a61174289b02e6a523ba5ccdae1a79cd72241ea7c5bb16de5d543e3aad488a3de9d973644a0297c2c94e0516475241c490470f5d52208f450d7efc243dfd575
-  data.tar.gz: 041553f6adda56086400f208d6bef2ce77613e635581e871ffc58488a3ead1cca4038c3ce4d89f39e79049f529ffaa7cb013dea09bea8701e9c7b5c78ea1d3eb
+  metadata.gz: f42c06e5cb90eae00d6fc11f1fa4cbfed1f789005b4aa6dc0ea27cd60522de63019804c154e818efc4eb4bc52e673765ad638f881f94faa445b0b1a6ce637060
+  data.tar.gz: 9e711ac3f6b30580e1e979f391019de8f1c5d155b9ded6b1c72881e698d79347e337299aca96316b9c9806507d9b1d7022c0f30d9bf715083e60a7a651775c82

data/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,22 @@
 ## [Unreleased]
+## [0.5.0] - Unreleased
+- The `dry-cli` dependency no longer pins a version range; any release satisfies it.
+- `SPECIFICATION.md` moves to `docs/SPECIFICATION.md`, marked as the specification for 0.1.0, and stays out of the YARD documentation.
+- The README documents which sections each screen prints, how groups and nested commands list, the description column and minimum wrap width, `Help.config`, `Help.reset!`, and the `ArgumentError` a bad setting raises.
+## [0.2.1] - 2026-09-15
+- Every setting is made once, in `Dry::CLI::Help.configure`, which now also accepts a block without an argument and runs it against the configuration. The `help` block on registries is removed, along with `Help.config_for` and `Configuration#merge`: the gem adds nothing to dry-cli's registry or command DSL.
+- A `styles` block declares every element's look in one place, replacing `style(element, *names)`. New elements `usage`, `example` and `example_comment`; `comment` is renamed `example_comment` and defaults to bold black.
+- Heading case moves into the heading style: `styles { heading :bold, case: :Capitalize }`, one of `:UPPERCASE`, `:Capitalize`, `:lowercase` or `:as_is`. The `heading_case` setting is removed.
+- `examples/` holds three single-file dry-cli tools that switch this gem on with `--with-dry-cli-help` or `-w`.
+## [0.2.0] - 2026-09-14
+- Documentation, justfile, lefthook and packaging fixes after the conversion. No change to behavior.
 ## [0.1.0] - 2026-09-12
 - Initial release as `dry-cli-help`, converted from `dry-cli-autocomplete`. The shell completion generator is removed; that gem remains the place for it.

data/README.md CHANGED Viewed

@@ -5,20 +5,20 @@
 Configurable, wrapped, colored help screens for [dry-cli](https://github.com/dry-rb/dry-cli) applications.
 > [!NOTE]
-> The design, the settings and every decision behind them are in [SPECIFICATION.md](SPECIFICATION.md).
+> The original design, the settings and the decisions behind them are in [docs/SPECIFICATION.md](docs/SPECIFICATION.md), written for version 0.1.0.
 dry-cli prints help as it finds it: no title, no description of the program, no color, one line per description however long, and commands sorted alphabetically. This gem keeps the command structure you already declared and changes only what the user reads before a command runs. Progress bars, spinners and error panels belong in `dry-cli-ui`.
 ## Before and after
-`taxlibris compile -h` with dry-cli alone:
+`my-cli compile -h` with dry-cli alone:
 ```text
 Command:
-  taxlibris compile
+  my-cli compile
 Usage:
-  taxlibris compile RULES [OUTPUT]
+  my-cli compile RULES [OUTPUT]
 Description:
   Compile tax rules
@@ -37,7 +37,7 @@ With `require "dry/cli/help"`:
 ```text
 USAGE
-  taxlibris compile RULES [OUTPUT] [OPTIONS]
+  my-cli compile RULES [OUTPUT] [OPTIONS]
 DESCRIPTION
   Compile tax rules
@@ -54,6 +54,13 @@ OPTIONS
 Headings are bold and yellow, commands green, options and arguments cyan, and every description wraps to the terminal with a hanging indent.
+The same comparison as screenshots, taken from `examples/rbcheck`:
+| Standard dry-cli Help Screen                    | Require `dry/cli/help`                   |
+| :---------------------------------------------- | :--------------------------------------- |
+| ![original](docs/img/without-dry-cli-help.avif) | ![with](docs/img/with-dry-cli-help.avif) |
+|                                                 |                                          |
 ## Installation
 ```bash
@@ -62,6 +69,8 @@ gem install dry-cli-help
 Or add `gem "dry-cli-help"` to your `Gemfile`.
+It requires Ruby 4.0 or newer, and depends on `dry-cli` and `pastel`.
 ## Usage
 Require it after dry-cli. That alone changes every help screen in the process.
@@ -71,44 +80,44 @@ require "dry/cli"
 require "dry/cli/help"
 ```
-Describe the program in the registry:
+Then make every setting once, in one block, before the CLI runs. Your registry, commands and options stay plain dry-cli: the gem adds nothing to them, so you can add or remove it without touching a command.
 ```ruby
-module Taxlibris
-  module CLI
-    extend Dry::CLI::Registry
+Dry::CLI::Help.configure do
+  title "MyCLI"
-    help do
-      title "Taxlibris"
+  description <<~TEXT
+    Compile, validate, and evaluate rules.
+  TEXT
-      description <<~TEXT
-        Compile, validate, and evaluate tax rules.
-      TEXT
+  epilogue "Documentation: https://example.com/my-cli"
-      epilogue "Documentation: https://example.com/taxlibris"
+  color :auto
+  width :terminal
+  wrap true
+end
-      color :auto
-      width :terminal
-      wrap true
-    end
+module My
+  module CLI
+    extend Dry::CLI::Registry
-    register "compile", Compile
+    register "compile",  Compile
     register "validate", Validate
     register "evaluate", Evaluate
-    register "version", Version, aliases: ["--version", "-v"]
+    register "version",  Version, aliases: ["--version", "-v"]
   end
 end
 ```
-`taxlibris -h` then prints:
+`my-cli -h` then prints:
 ```text
-Taxlibris
+MyCLI
-Compile, validate, and evaluate tax rules.
+Compile, validate, and evaluate rules.
 USAGE
-  taxlibris COMMAND [OPTIONS]
+  my-cli COMMAND [OPTIONS]
 COMMANDS
   compile        Compile tax rules
@@ -120,12 +129,12 @@ OPTIONS
   -h, --help     Show help
   -v, --version  Show version
-Documentation: https://example.com/taxlibris
+Documentation: https://example.com/my-cli
 ```
-A command reachable as `--version` lists under Options by its dashed names.
+A command reachable as `--version` lists under Options by its dashed names. Commands marked `hidden: true` in the registry stay out of every list, and a non-dashed alias prints next to its command, as in `build, b`.
-Settings for the whole process go through `configure`. A registry's `help` block overrides them:
+A block that takes an argument receives the configuration instead of running against it:
 ```ruby
 Dry::CLI::Help.configure do |config|
@@ -134,34 +143,202 @@ Dry::CLI::Help.configure do |config|
 end
 ```
-A `help` block that takes an argument receives the configuration instead, so `help { |h| h.title = "Taxlibris" }` works too.
+Every setting validates its value and raises `ArgumentError` on one it cannot use. `Dry::CLI::Help.config` returns the current settings, and `Dry::CLI::Help.reset!` forgets them all, which is handy between tests.
+## Examples
+The [`examples`](examples) folder holds three single-file tools built on dry-cli. Each one loads and configures this gem only when you pass `--with-dry-cli-help`, or `-w` for short, so you can run the same command both ways and compare:
+```bash
+examples/rbcheck -h                      # dry-cli's own help
+examples/rbcheck -h --with-dry-cli-help  # the same help, through this gem
+```
+`examples/rbcheck` has two commands, `version` and `check-ruby-syntax [DIR]`. Condensed:
+```ruby
+#!/usr/bin/env ruby
+require "dry/cli"
+if [ARGV.delete("--with-dry-cli-help"), ARGV.delete("-w")].any?
+  require "dry/cli/help"
+  Dry::CLI::Help.configure do
+    title "rbcheck"
+    description "Small checks for Ruby projects."
+    epilogue "Report bugs at https://example.com/rbcheck/issues"
+  end
+end
+module Rbcheck
+  extend Dry::CLI::Registry
+  class Version < Dry::CLI::Command
+    desc "Print the version"
+    def call(**) = puts("rbcheck 1.0.0")
+  end
+  class CheckRubySyntax < Dry::CLI::Command
+    desc "Check every Ruby file under a directory for syntax errors, and report "\
+         "each file that fails to parse with its line number"
+    argument :dir, desc: "Directory to scan", default: "."
+    option :exclude, type: :array, desc: "Glob patterns to skip, such as vendor/**"
+    option :quiet, type: :boolean, default: false, aliases: ["-q"],
+           desc: "Print only the files that fail"
+    example ["lib # check one directory", "--exclude=vendor/** # skip vendored gems"]
+    def call(dir:, quiet:, exclude: [], **)
+      # ... parses every file under dir with Prism ...
+    end
+  end
+  register "version", Version, aliases: ["--version", "-v"]
+  register "check-ruby-syntax", CheckRubySyntax
+end
+Dry::CLI.new(Rbcheck).call
+```
+Every screen below comes from running it in an 80-column terminal.
+### `rbcheck -h`
+dry-cli alone prints a list of commands to stderr and exits 1, and does not wrap the long description.
+```text
+Commands:
+  rbcheck check-ruby-syntax [DIR]                 # Check every Ruby file under a directory for syntax errors, and report each file that fails to parse with its line number
+  rbcheck version                                 # Print the version
+```
+With this gem, `rbcheck -h` prints the help below to stdout and exits 0.
+> [!NOTE]
+> Whether a CLI run with no arguments should exit 1 or 0 is debatable. dry-cli exits 1, and so does this gem by default: plain `rbcheck` prints the same screen to stderr and exits 1. Set [`exit_code_without_arguments`](#dsl-based-configuration-api) to `0` to treat it like `-h` instead.
+```text
+rbcheck
+Small checks for Ruby projects.
+USAGE
+  rbcheck COMMAND [OPTIONS]
+COMMANDS
+  version            Print the version
+  check-ruby-syntax  Check every Ruby file under a directory for syntax errors,
+                     and report each file that fails to parse with its line
+                     number
+OPTIONS
+  -h, --help         Show help
+  -v, --version      Print the version
+Report bugs at https://example.com/rbcheck/issues
+```
+- The title, description and epilogue come from the `configure` block.
+- Commands list in the order they were registered, not alphabetically.
+- The long description wraps to the terminal under its own column.
+- `version` is also reachable as `--version` and `-v`, so it lists under Options too. dry-cli never shows those aliases.
+### `rbcheck check-ruby-syntax -h`
+dry-cli alone:
+```text
+Command:
+  rbcheck check-ruby-syntax
+Usage:
+  rbcheck check-ruby-syntax [DIR]
+Description:
+  Check every Ruby file under a directory for syntax errors, and report each file that fails to parse with its line number
+Arguments:
+  DIR                               # Directory to scan
+Options:
+  --exclude=VALUE1,VALUE2,..        # Glob patterns to skip, such as vendor/**
+  --[no-]quiet, -q                  # Print only the files that fail, default: false
+  --help, -h                        # Print this help
+Examples:
+  rbcheck check-ruby-syntax lib # check one directory
+  rbcheck check-ruby-syntax --exclude=vendor/** # skip vendored gems
+```
+With this gem:
+```text
+USAGE
+  rbcheck check-ruby-syntax [DIR] [OPTIONS]
+DESCRIPTION
+  Check every Ruby file under a directory for syntax errors, and report each
+  file that fails to parse with its line number
-## Settings
+ARGUMENTS
+  DIR                         Directory to scan (default: ".")
+OPTIONS
+  --exclude=VALUE1,VALUE2,..  Glob patterns to skip, such as vendor/**
+  -q, --[no-]quiet            Print only the files that fail (default: false)
+  -h, --help                  Show help
+EXAMPLES
+  rbcheck check-ruby-syntax lib             check one directory
+  rbcheck check-ruby-syntax --exclude=vendor/**
+                                            skip vendored gems
+```
-| Setting                       | Values                            | Default         |
-| ----------------------------- | --------------------------------- | --------------- |
-| `title`                       | String                            | none            |
-| `description`                 | String                            | none            |
-| `epilogue`                    | String                            | none            |
-| `color`                       | `true`, `false`, `:auto`          | `:auto`         |
-| `wrap`                        | `true`, `false`                   | `true`          |
-| `width`                       | `:terminal`, Integer              | `:terminal`     |
-| `margin`                      | Integer                           | `0`             |
-| `exit_code_without_arguments` | 0 to 255                          | `1`             |
-| `banner_on_subcommands`       | `true`, `false`                   | `false`         |
-| `heading_case`                | `:upcase`, `:capitalize`, `:none` | `:upcase`       |
-| `command_order`               | `:registration`, `:alphabetical`  | `:registration` |
+- The `Command:` section repeats the usage line, so it is gone, and the usage line shows that the command takes options.
+- The argument's default of `"."` shows up; dry-cli leaves it out.
+- Short aliases come first (`-q, --[no-]quiet`), and every description lines up in one column instead of trailing a `#`.
+- Each example's comment moves into a column of its own. An example longer than that column puts its comment on the next line.
+In a terminal the headings print bold yellow, usage lines, commands and examples green, arguments and options cyan, and example comments bold black.
+`examples/todo` shows nested commands, custom headings and a `styles` block. `examples/deploy` shows a fixed width, a banner above command help, reordered sections and help without a command exiting 0. [`examples/README.md`](examples/README.md) lists what each one demonstrates.
+## DSL-based Configuration API
+The gem offers a compact DSL in the general spirit of Ruby and `dry-rb` in particular, and makes the following methods available within the `configure` block.
+| Setting                       | Values                           | Default         | What it does                                                                                                              |
+| ----------------------------- | -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `title`                       | String                           | none            | Prints the first line of the banner, above the top-level help                                                             |
+| `description`                 | String                           | none            | Prints paragraphs under the title, reflowed to the wrap width                                                             |
+| `epilogue`                    | String                           | none            | Prints paragraphs at the very end of the top-level help                                                                   |
+| `color`                       | `true`, `false`, `:auto`         | `:auto`         | Paints headings, commands, arguments and options; `:auto` paints only a terminal                                          |
+| `wrap`                        | `true`, `false`                  | `true`          | Wraps descriptions with a hanging indent; `false` prints each one on a single line as written                             |
+| `width`                       | `:terminal`, Integer             | `:terminal`     | Sets the column text wraps at; `:terminal` follows the terminal's width                                                   |
+| `margin`                      | Integer                          | `0`             | Keeps that many columns free at the right edge when `width` is `:terminal`                                                |
+| `exit_code_without_arguments` | 0 to 255                         | `1`             | Sets the exit status of `my-cli` or `my-cli db` run with no command; `0` also prints the help to stdout instead of stderr |
+| `banner_on_subcommands`       | `true`, `false`                  | `false`         | Prints the title and description above command help and group listings too, not only above the top-level help             |
+| `command_order`               | `:registration`, `:alphabetical` | `:registration` | Lists commands in the order you registered them, or sorted by name as dry-cli does                                        |
 `color :auto` colors a terminal and honors [`NO_COLOR`](https://no-color.org). `width :terminal` reads `COLUMNS`, then the console, then falls back to 80, and `margin` keeps columns free at the right edge.
-Running the program with no command prints the top-level help and exits 1, as dry-cli does. `exit_code_without_arguments 0` prints it to stdout and exits 0 instead. `-h` and `--help` always exit 0.
+Running the program, or a group such as `my-cli db`, with no command prints its help to stderr and exits 1, as dry-cli does. With
+```ruby
+exit_code_without_arguments 0
+```
+it prints to stdout and exits 0 instead. `-h` and `--help` always print to stdout and exit 0. A mistyped command prints dry-cli's suggestion, then the help, to stderr and exits 1.
+The banner (title and description) and the epilogue print on the top-level help. A CLI built from a single command, `Dry::CLI.new(Deploy)`, counts as top level, so its command help gets both.
 ### Headings, sections and groups
 ```ruby
-help do
+Dry::CLI::Help.configure do
   heading :commands, "Available commands"
-  heading_case :capitalize
   group "Rules", "compile", "validate"
   group "Returns", "evaluate"
@@ -171,22 +348,58 @@ help do
 end
 ```
-- `heading` replaces one section's heading text.
-- `group` lists commands under a heading of their own, in the order given. Ungrouped commands stay under Commands. A group inside a group names the full path, such as `"db migrate"`.
+- `heading` replaces one section's heading text. It takes `:usage`, `:description`, `:commands`, `:subcommands`, `:arguments`, `:options` or `:examples`; `banner` and `epilogue` have no heading. How headings are cased belongs to their style, below.
+- `group` lists commands under a heading of their own, in the order given. Ungrouped commands stay under Commands, and groups print below them in the order declared. A group with no commands raises `ArgumentError`; a group whose commands a screen does not list prints no heading there. A nested command is named by its full path, such as `"db migrate"`, and its group shows on `my-cli db -h`.
 - `sections` sets the order; a section left out is hidden. `hide` hides sections without restating the order.
-The sections are `banner`, `usage`, `description`, `commands`, `subcommands`, `arguments`, `options`, `examples` and `epilogue`. Each screen prints the ones that apply to it.
+The sections are `banner`, `usage`, `description`, `commands`, `subcommands`, `arguments`, `options`, `examples` and `epilogue`. Each screen prints the ones that apply to it:
+| Screen                                        | Sections it can print                                                                           |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| A listing: `my-cli`, `my-cli -h`, `my-cli db` | `banner`, `usage`, `commands`, `options`, `epilogue`                                            |
+| A command: `my-cli compile -h`                | `banner`, `usage`, `description`, `subcommands`, `arguments`, `options`, `examples`, `epilogue` |
+A few details of those screens:
+- A command that also has subcommands gets a second usage line, `my-cli db COMMAND [OPTIONS]`, and a Subcommands section.
+- A group registered without a command of its own describes itself by what it holds, as in `Subcommands: add, remove`.
+- An array argument prints as `FILES...`.
+- Every definition list on a screen shares one description column, never wider than half the wrap width. A term longer than that column puts its description on the next line.
+- Text never wraps narrower than 20 columns, however small the terminal.
 ### Styles
+Every element's look is declared together, in one `styles` block inside `configure`:
 ```ruby
-help do
-  style :heading, :bold, :bright_blue
-  style :comment            # no styles: print it plain
+Dry::CLI::Help.configure do
+  styles do
+    title           :bold
+    heading         :bold, :yellow, case: :UPPERCASE
+    usage           :green
+    command         :green
+    argument        :cyan
+    option          :cyan
+    example         :green
+    example_comment :bold, :black
+  end
 end
 ```
-The styled elements are `title`, `heading`, `command`, `argument`, `option` and `comment`, the last being the part of an example after the first `#` surrounded by spaces, as in `"rules.form # compile one file"`.
+Those are the defaults. Name only the elements you want to change; a line with no styles, such as `example_comment`, prints that element plain.
+| Element           | Applies to                                                                                           |
+| ----------------- | ---------------------------------------------------------------------------------------------------- |
+| `title`           | The banner title                                                                                     |
+| `heading`         | Every section and group heading                                                                      |
+| `usage`           | Every usage line, whole                                                                              |
+| `command`         | Command names in a list                                                                              |
+| `argument`        | Argument names                                                                                       |
+| `option`          | Option names                                                                                         |
+| `example`         | The command line of an example                                                                       |
+| `example_comment` | The part of an example after the first `#` surrounded by spaces, as in `"lib # check one directory"` |
+`heading` alone takes `case:`, one of `:UPPERCASE`, `:Capitalize`, `:lowercase` or `:as_is`, each written the way it cases. `:Capitalize` raises only the first letter. `heading case: :as_is` with no styles changes the case and keeps the colors.
 ### The Colors module
@@ -203,23 +416,33 @@ class Deploy < Dry::CLI::Command
 end
 ```
-The methods are the eight colors `black red green yellow blue magenta cyan white`, their `bright_` forms, the `on_` and `on_bright_` backgrounds, and `clear bold dim italic underline inverse hidden strikethrough`. `Dry::CLI::Help::Colors.enabled = false` turns them all off.
+The methods are the eight colors `black red green yellow blue magenta cyan white`, their `bright_` forms, the `on_` and `on_bright_` backgrounds, and `clear bold dim italic underline inverse hidden strikethrough`. `Dry::CLI::Help::Colors.enabled` takes `true`, `false` or `:auto` (the default, which colors only a terminal and honors `NO_COLOR`). Help screens ignore that switch and follow the `color` setting.
 ## How it works
 The gem prepends one module to `Dry::CLI`, overriding the two private methods dry-cli prints help from. It does not replace `Dry::CLI::Banner` or `Dry::CLI::Usage`.
 ```mermaid
-flowchart LR
-  argv[ARGV] --> call["Dry::CLI#call"]
-  call -->|"command found, -h given"| help["#help"]
-  call -->|"no command, a group, -h at a level, a typo"| spell["#spell_checker"]
-  help --> command[Screens::Command]
-  spell --> listing[Screens::Listing]
-  command --> formatter[Formatter]
-  listing --> formatter
-  config["Help.configure + registry help block"] --> formatter
-  formatter --> out[stdout or stderr]
+---
+config:
+  layout: elk
+  theme: forest
+---
+flowchart TB
+    argv["ARGV"] --> cli_call["Dry::CLI#call"]
+    cli_call -->|"command found, --help given"| help_method["#help"]
+    cli_call -->|"no command, a group, -h at a level, a typo"| spell_checker["#spell_checker"]
+    help_method --> command_screen["Screens::Command"]
+    spell_checker --> listing_screen["Screens::Listing"]
+    command_screen --> formatter["Formatter"]
+    listing_screen --> formatter
+    help_config["Help.configure"] --> formatter
+    formatter --> output["stdout or stderr"]
 ```
 Both methods are `@api private` in dry-cli. `spec/dry/cli/help/dry_cli_contract_spec.rb` asserts every internal the gem reads, so a dry-cli release that moves one fails this suite, naming what moved.
@@ -227,13 +450,16 @@ Both methods are `@api private` in dry-cli. `spec/dry/cli/help/dry_cli_contract_
 ## Development
 ```bash
-just install     # bundle install
-just test        # the suite; a full run enforces 100% line and branch coverage
-just lint        # rubocop
-just ci          # both
-just lefthook    # every pre-commit hook against every file
-just format      # rubocop -a, then mdformat --wrap no on every Markdown file
-bin/console      # IRB with the gem loaded
+just install        # bundle install
+just test           # the suite; a full run enforces 100% line and branch coverage
+just test-coverage  # measure coverage even for a partial run
+just lint           # rubocop
+just ci             # rubocop, then the suite with coverage
+just lefthook       # every pre-commit hook against every file
+just format         # mdformat --wrap no on every Markdown file, then rubocop -a
+just doc            # YARD documentation
+just build          # build the .gem into pkg/
+bin/console         # IRB with the gem loaded
 ```
 ## Contributing
@@ -241,7 +467,21 @@ bin/console      # IRB with the gem loaded
 Bug reports and pull requests are welcome at <https://github.com/kigster/dry-cli-help>.
 > [!WARNING]
-> The `dry-` prefix and the `Dry::CLI::Help` namespace do not imply endorsement by dry-rb. This is an independent gem that extends theirs.
+> The `dry-` prefix and the `Dry::CLI::Help` namespace do not imply endorsement by dry-rb.
+>
+> This is an independent and opinionated gem that extends theirs.
+## Note to Dry-Rb Maintainers
+First — hats off to all of you who tirelessly built out one of the most valuable collections of libraries in the Ruby ecosystem.
+While I admire and would be willing to contribute any or all of the extension gem's code to the original gem, I feel that creating plugins and extensions allows the author to fully express their needs and wants, and then, if the authors of `dry-cli` become interested in any of them, I would be honored to submit a PR to `dry-cli` itself.
+This method offered a very open road to extensibility and experimentation. If the code quality or design is not up to the level required for direct contributions to `dry-rb`, then let it be known that:
+1. We would be very happy to receive any feedback and improve, refactor, and update the gem assuming it improves it
+1. Roll any part of the codebase as a PR to the `dry-cli` core.
+1. We hold the authors of `dry-rb` in high regard, and generally would love to collaborate, as long as the feedback loop/cycle is not so long that the context of the changes gets lost in time, as with so many contributions made to other gems in the past.
 ## License

data/Rakefile CHANGED Viewed

@@ -28,7 +28,7 @@ end
 task build: :permissions
 YARD::Rake::YardocTask.new(:doc) do |t|
-  t.files = %w[lib/**/*.rb - README.md LICENSE.txt CHANGELOG.md SPECIFICATION.md]
+  t.files = %w[lib/**/*.rb - README.md LICENSE.txt CHANGELOG.md]
   t.options.unshift("--title", '"dry-cli-help: configurable help screens for dry-cli"')
   t.after = -> { exec("open doc/index.html") } if RUBY_PLATFORM =~ /darwin/
 end

data/lib/dry/cli/help/configuration.rb CHANGED Viewed

@@ -3,19 +3,18 @@
 module Dry
   class CLI
     module Help
-      # Help settings, readable and writable two ways:
+      # Every help setting, made once for the whole process, two ways:
       #
-      #   help do
-      #     title "Taxlibris"            # inside a registry's help block
+      #   Dry::CLI::Help.configure do
+      #     title "MyCLI"            # as a DSL
       #   end
       #
       #   Dry::CLI::Help.configure do |config|
-      #     config.title = "Taxlibris"   # on the yielded object
+      #     config.title = "MyCLI"   # on the yielded object
       #   end
       #
-      # An instance stores only what was set on it. Everything else reads from
-      # {DEFAULTS}, which is what lets a registry's settings sit over the
-      # process-wide ones through {#merge} without either copying the other.
+      # Every element's look is declared in one {#styles} block. Anything not
+      # set reads from {DEFAULTS}, {HEADINGS} or {STYLES}.
       class Configuration
         # Every section, in default order.
         SECTIONS = %i[
@@ -37,13 +36,18 @@ module Dry
         STYLES = {
           title: %i[bold],
           heading: %i[bold yellow],
+          usage: %i[green],
           command: %i[green],
           argument: %i[cyan],
           option: %i[cyan],
-          comment: %i[bright_black]
+          example: %i[green],
+          example_comment: %i[bold black]
         }.freeze
-        HEADING_CASES = %i[upcase capitalize none].freeze
+        # How headings can be cased; each name is written the way it cases.
+        # `:Capitalize` raises only the first letter.
+        HEADING_CASES = %i[UPPERCASE Capitalize lowercase as_is].freeze
+        DEFAULT_HEADING_CASE = :UPPERCASE
         COMMAND_ORDERS = %i[registration alphabetical].freeze
         # Narrowest column text wraps at, however small the terminal.
@@ -63,7 +67,6 @@ module Dry
           margin: ->(value) { value.is_a?(Integer) && !value.negative? },
           exit_code_without_arguments: ->(value) { value.is_a?(Integer) && value.between?(0, 255) },
           banner_on_subcommands: BOOLEAN,
-          heading_case: ->(value) { HEADING_CASES.include?(value) },
           command_order: ->(value) { COMMAND_ORDERS.include?(value) }
         }.freeze
@@ -77,7 +80,6 @@ module Dry
           margin: 0,
           exit_code_without_arguments: 1,
           banner_on_subcommands: false,
-          heading_case: :upcase,
           command_order: :registration
         }.freeze
@@ -122,26 +124,36 @@ module Dry
           HEADINGS.merge(@values.fetch(:headings, {}))
         end
-        # Replace the styles of one element. No styles prints it plain.
+        # Declare how elements look, all in one place. Each line names an
+        # element from {STYLES} and its styles from {Colors::STYLES}; no styles
+        # prints it plain. Elements left out keep their defaults. `heading` also
+        # takes `case:`, one of {HEADING_CASES}. A block taking an argument
+        # receives the declarations instead.
+        #
+        # @example
+        #   styles do
+        #     heading :bold, :blue, case: :Capitalize
+        #     example_comment              # plain
+        #   end
         #
-        # @param element [Symbol] a key of {STYLES}
-        # @param names [Array<Symbol>] names from {Colors::STYLES}
-        # @return [Array<Symbol>]
-        def style(element, *names)
-          raise ArgumentError, "#{element.inspect} is not a styled element" unless STYLES.key?(element)
-          unknown = names - Colors::STYLES
-          raise ArgumentError, "unknown styles: #{unknown.inspect}" unless unknown.empty?
-          @values[:styles] = @values.fetch(:styles, {}).merge(element => names.freeze)
-          names
-        end
         # @return [Hash{Symbol => Array<Symbol>}] every element's styles
-        def styles
+        def styles(&block)
+          if block
+            sheet = StyleSheet.new
+            block.arity == 1 ? yield(sheet) : sheet.instance_eval(&block)
+            @values[:styles] = @values.fetch(:styles, {}).merge(sheet.styles)
+            @values[:heading_case] = sheet.heading_case if sheet.heading_case
+          end
           STYLES.merge(@values.fetch(:styles, {}))
         end
+        # How every heading is cased, set by `heading ..., case:` in {#styles}.
+        #
+        # @return [Symbol] one of {HEADING_CASES}
+        def heading_case
+          @values.fetch(:heading_case, DEFAULT_HEADING_CASE)
+        end
         # List commands under a heading of their own, in the order given.
         # Groups print in the order they are declared, after ungrouped commands.
         #
@@ -206,27 +218,6 @@ module Dry
           [columns, MIN_WIDTH].max
         end
-        # These settings with another instance's laid over them. Headings and
-        # styles merge key by key, hidden sections add up, and any other setting
-        # the other instance made replaces this one's.
-        #
-        # @param other [Configuration]
-        # @return [Configuration] a new instance
-        def merge(other)
-          combined = @values.merge(other.values) do |key, mine, theirs|
-            case key
-            when :headings, :styles then mine.merge(theirs)
-            when :hidden then mine | theirs
-            else theirs
-            end
-          end
-          self.class.new(combined)
-        end
-        protected
-        attr_reader :values
         private
         def validate_sections(names)
@@ -235,6 +226,48 @@ module Dry
           names.freeze
         end
+        # What a {Configuration#styles} block runs against: one method per
+        # element, each validating what it is given.
+        class StyleSheet
+          # @return [Hash{Symbol => Array<Symbol>}] the elements declared
+          attr_reader :styles
+          # @return [Symbol, nil] the heading case, when declared
+          attr_reader :heading_case
+          def initialize
+            @styles = {}
+          end
+          STYLES.each_key do |element|
+            define_method(element) do |*names, **options|
+              declare(element, names.flatten, options)
+            end
+          end
+          private
+          def declare(element, names, options)
+            unknown = names - Colors::STYLES
+            raise ArgumentError, "unknown styles for #{element}: #{unknown.inspect}" unless unknown.empty?
+            @heading_case = letter_case(element, options) unless options.empty?
+            # `heading case: :as_is` alone changes the case and keeps the styles.
+            @styles[element] = names.freeze unless names.empty? && !options.empty?
+          end
+          def letter_case(element, options)
+            unless element == :heading && options.keys == [:case]
+              raise ArgumentError, "#{element} takes no #{options.keys.map { "#{it}:" }.join(', ')}"
+            end
+            value = options.fetch(:case)
+            return value if HEADING_CASES.include?(value)
+            raise ArgumentError, "case cannot be #{value.inspect}; use one of #{HEADING_CASES.inspect}"
+          end
+        end
       end
     end
   end

data/lib/dry/cli/help/formatter.rb CHANGED Viewed

@@ -49,12 +49,15 @@ module Dry
           title(config.headings.fetch(section))
         end
-        # A heading with the configured case and style, for any text.
+        # A heading in the configured case and style, for any text.
+        #
+        # @param text [String]
         # @return [String]
         def title(text)
           cased = case config.heading_case
-                  when :upcase then text.upcase
-                  when :capitalize then text.sub(/\A\p{Ll}/, &:upcase)
+                  when :UPPERCASE then text.upcase
+                  when :lowercase then text.downcase
+                  when :Capitalize then text.sub(/\A\p{Ll}/, &:upcase)
                   else text
                   end
           paint(cased, :heading)

data/lib/dry/cli/help/integration.rb CHANGED Viewed

@@ -20,7 +20,7 @@ module Dry
           def help(command, prog_name)
             screen = Screens::Command.new(
               command:, prog_name:, top_level: !kommand.nil?,
-              config: Help.config_for(registry), io: out
+              config: Help.config, io: out
             )
             out.puts screen.render
             exit(0)
@@ -30,7 +30,7 @@ module Dry
           # all, a group without a command of its own, `-h` or `--help` at a
           # registry level, or a typo.
           def spell_checker(result, arguments)
-            config = Help.config_for(registry)
+            config = Help.config
             unmatched = arguments.drop(result.names.length)
             if unmatched.empty?
@@ -50,34 +50,6 @@ module Dry
             exit(status)
           end
         end
-        # Included into Dry::CLI::Registry, so every registry can describe itself.
-        module RegistryMethods
-          # Configure this registry's help. A block taking an argument receives
-          # the configuration; any other block runs against it.
-          #
-          # @example
-          #   help do
-          #     title "Taxlibris"
-          #     width 100
-          #   end
-          #
-          # @return [Configuration] this registry's settings
-          def help(&block)
-            @help_config ||= Configuration.new
-            if block&.arity == 1
-              yield @help_config
-            elsif block
-              @help_config.instance_eval(&block)
-            end
-            @help_config
-          end
-          # @return [Configuration, nil] nil until {#help} is called
-          def help_config
-            @help_config
-          end
-        end
       end
     end
   end

data/lib/dry/cli/help/screens/command.rb CHANGED Viewed

@@ -32,10 +32,9 @@ module Dry
           end
           def render_usage
-            program = format.paint(prog_name, :command)
-            lines = ["#{INDENT}#{program}#{usage_arguments} [OPTIONS]"]
-            lines << "#{INDENT}#{program} COMMAND [OPTIONS]" if subcommand_rows.any?
-            section(:usage, lines)
+            lines = ["#{prog_name}#{usage_arguments} [OPTIONS]"]
+            lines << "#{prog_name} COMMAND [OPTIONS]" if subcommand_rows.any?
+            section(:usage, lines.map { INDENT + format.paint(it, :usage) })
           end
           def render_description
@@ -59,7 +58,8 @@ module Dry
           def render_examples
             rows = command.examples.map do |example|
               line, comment = example.split(" # ", 2)
-              Row.new(term: "#{prog_name} #{line.strip}", text: comment&.strip, text_style: :comment)
+              Row.new(term: "#{prog_name} #{line.strip}", text: comment&.strip,
+                      term_style: :example, text_style: :example_comment)
             end
             section(:examples, format.definitions(rows, format.column_for(rows)))
           end
@@ -72,7 +72,7 @@ module Dry
             required = command.required_arguments.map { argument_name(it) }
             optional = command.optional_arguments.map { "[#{argument_name(it)}]" }
             names = [*required, *optional]
-            " #{format.paint(names.join(' '), :argument)}" unless names.empty?
+            " #{names.join(' ')}" unless names.empty?
           end
           def subcommand_rows

data/lib/dry/cli/help/screens/listing.rb CHANGED Viewed

@@ -32,8 +32,8 @@ module Dry
           end
           def render_usage
-            program = format.paint(ProgramName.call(result.names), :command)
-            section(:usage, ["#{INDENT}#{program} COMMAND [OPTIONS]"])
+            usage = format.paint("#{ProgramName.call(result.names)} COMMAND [OPTIONS]", :usage)
+            section(:usage, ["#{INDENT}#{usage}"])
           end
           def render_commands

data/lib/dry/cli/help/version.rb CHANGED Viewed

@@ -9,7 +9,7 @@ module Dry
   # inherits from Object, so an empty reopening is compatible either way.
   class CLI
     module Help
-      VERSION = "0.1.0"
+      VERSION = "0.5.0"
     end
   end
 end

data/lib/dry/cli/help.rb CHANGED Viewed

@@ -19,14 +19,22 @@ module Dry
     # Configurable, wrapped and colored help screens for dry-cli.
     #
     # Requiring this file changes the help every Dry::CLI in the process prints.
-    # Settings come from {.configure} for the whole process, and from a
-    # registry's `help` block for that registry.
+    # Every setting is made once, in {.configure}, so the way dry-cli declares
+    # registries, commands and options stays exactly as dry-cli ships it.
     module Help
       class << self
-        # @yieldparam config [Configuration] the process-wide settings
+        # Make every setting. A block taking an argument receives the
+        # configuration; any other block runs against it.
+        #
+        # @example
+        #   Dry::CLI::Help.configure do
+        #     title "MyCLI"
+        #     styles { heading :bold, :blue }
+        #   end
+        #
         # @return [Configuration]
-        def configure
-          yield config
+        def configure(&block)
+          block.arity == 1 ? yield(config) : config.instance_eval(&block)
           config
         end
@@ -40,21 +48,9 @@ module Dry
         def reset!
           @config = nil
         end
-        # The settings a registry renders with: its own `help` block over the
-        # process-wide settings. A single command passed to Dry::CLI.new has no
-        # `help` block, so it renders with the process-wide settings alone.
-        #
-        # @param registry [Module, Class, Dry::CLI::Command, nil]
-        # @return [Configuration]
-        def config_for(registry)
-          own = registry.help_config if registry.respond_to?(:help_config)
-          own ? config.merge(own) : config
-        end
       end
     end
   end
 end
 Dry::CLI.prepend(Dry::CLI::Help::Integration::CLIMethods)
-Dry::CLI::Registry.include(Dry::CLI::Help::Integration::RegistryMethods)

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dry-cli-help
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -15,20 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.1.1
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '2'
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.1.1
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '2'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: pastel
   requirement: !ruby/object:Gem::Requirement
@@ -56,7 +50,6 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- SPECIFICATION.md
 - lib/dry-cli-help.rb
 - lib/dry/cli/help.rb
 - lib/dry/cli/help/colors.rb

data/SPECIFICATION.md DELETED Viewed

@@ -1,200 +0,0 @@
-# dry-cli-help
-Enhanced help presentation for [`dry-cli`](https://github.com/dry-rb/dry-cli).
-## Purpose
-`dry-cli-help` improves the **static, human-facing documentation** generated by `dry-cli`.
-It does not replace `dry-cli` or introduce another command framework. It takes the command structure already defined through `dry-cli` and provides richer, more configurable help output.
-## Responsibilities
-- Top-level application title and description
-- Command descriptions
-- Automatic line wrapping based on terminal width
-- ANSI color and styling
-- Configurable headings
-- Improved spacing and indentation
-- Usage formatting
-- Arguments and options formatting
-- Examples
-- Epilogues
-- Command grouping
-- Section ordering
-- Hiding or customizing sections
-- Consistent formatting across commands
-## Example
-```ruby
-require "dry/cli"
-require "dry/cli/help"
-Dry::CLI::Help.configure do |config|
-  config.width = :terminal
-  config.wrap = true
-  config.color = true
-end
-```
-An application could provide richer top-level help:
-```ruby
-class CLI
-  extend Dry::CLI::Registry
-  help do
-    title "Taxlibris"
-    description <<~TEXT
-      Compile, validate, and evaluate tax rules.
-    TEXT
-    color true
-    width :terminal
-    wrap true
-  end
-end
-```
-Result:
-```text
-Taxlibris
-Compile, validate, and evaluate tax rules.
-USAGE
-  taxlibris COMMAND [OPTIONS]
-COMMANDS
-  compile       Compile tax rules
-  validate      Validate the rule corpus
-  evaluate      Evaluate a tax return
-OPTIONS
-  --help        Show help
-  --version     Show version
-```
-## Design Principle
-`dry-cli-help` owns what the user sees **before a command runs**.
-It should remain focused on documentation and presentation rather than runtime command UI.
-Runtime features such as progress bars, spinners, status displays, and error panels belong in `dry-cli-ui`.
-## Relationship
-```text
-dry-cli
-    │
-    └── dry-cli-help
-          │
-          ├── descriptions
-          ├── usage
-          ├── wrapping
-          ├── headings
-          ├── colors
-          ├── arguments/options
-          └── examples
-```
-## Requirements carried from the first draft
-1. **Exit status without arguments.** dry-cli prints the command list and exits 1 when run with no command. The status is configurable. Asking for help with `-h` or `--help` always exits 0.
-1. **Banner.** The title and description print above the command list for `mycli`, `mycli -h` and `mycli --help`. A separate setting decides whether they also print for `mycli subcommand -h`.
-1. **Wrapping.** Three modes: no wrapping (dry-cli's behavior), wrapping at a fixed column such as 80 or 100, and wrapping at the terminal's width minus an optional margin.
-1. **Colors.** Built on `pastel`. A `Colors` module, when included, makes each style below available as a method: `red("text")` returns decorated text, and `red.bold("text")` chains.
-   - Foreground: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, and the `bright_` form of each.
-   - Background: `on_black`, `on_red`, `on_green`, `on_yellow`, `on_blue`, `on_magenta`, `on_cyan`, `on_white`, and the `on_bright_` form of each.
-   - Styles: `clear`, `bold`, `dim`, `italic`, `underline`, `inverse`, `hidden`, `strikethrough`.
-## Decisions
-### Integration
-Requiring `dry/cli/help` changes help output for every `Dry::CLI` in the process. It does not replace `Dry::CLI::Banner` or `Dry::CLI::Usage`. It prepends one module to `Dry::CLI` that overrides two private methods, the only two places dry-cli prints help:
-| dry-cli method                         | When dry-cli calls it                                      |
-| -------------------------------------- | ---------------------------------------------------------- |
-| `Dry::CLI#help(command, prog_name)`    | `mycli deploy -h`, for any command with a class            |
-| `Dry::CLI#spell_checker(result, argv)` | `mycli`, `mycli -h`, `mycli db` for a group, `mycli bogus` |
-Both are `@api private` in dry-cli 1.4.1. A spec asserts they exist, so a dry-cli release that renames them fails this gem's suite rather than a host's help screen. `Dry::CLI::Help::Integration` holds the override.
-`help` is added to `Dry::CLI::Registry`, so any module or class that extends a registry can call it.
-### Configuration
-Two levels, one vocabulary. `Dry::CLI::Help.configure` sets process-wide values. A registry's `help` block overrides them for that registry. A setting neither level sets takes the default below.
-Every setting reads and writes both ways: `title "Taxlibris"` inside a `help` block, and `config.title = "Taxlibris"` on the yielded object. A `help` block taking one argument receives the configuration instead of being evaluated against it.
-| Setting                       | Values                               | Default         | Effect                                                                 |
-| ----------------------------- | ------------------------------------ | --------------- | ---------------------------------------------------------------------- |
-| `title`                       | String                               | none            | First line of the banner                                               |
-| `description`                 | String                               | none            | Paragraphs under the title, wrapped                                    |
-| `epilogue`                    | String                               | none            | Paragraphs at the end of the top-level help                            |
-| `color`                       | `true`, `false`, `:auto`             | `:auto`         | `:auto` colors a terminal and honors `NO_COLOR`                        |
-| `wrap`                        | `true`, `false`                      | `true`          | `false` prints descriptions as written                                 |
-| `width`                       | `:terminal`, Integer                 | `:terminal`     | The column text wraps at                                               |
-| `margin`                      | Integer                              | `0`             | Columns kept free at the right edge when `width` is `:terminal`        |
-| `exit_code_without_arguments` | Integer, 0 to 255                    | `1`             | Status for `mycli` or `mycli group` with no command                    |
-| `banner_on_subcommands`       | `true`, `false`                      | `false`         | Print the title and description above `mycli command -h`               |
-| `heading_case`                | `:upcase`, `:capitalize`, `:none`    | `:upcase`       | How every heading is cased; `:capitalize` raises only the first letter |
-| `command_order`               | `:registration`, `:alphabetical`     | `:registration` | Order commands list in; dry-cli sorts alphabetically                   |
-| `heading(section, text)`      | Section name, String                 | see below       | Replaces one heading's text                                            |
-| `style(element, *styles)`     | Element name, `Colors::STYLES` names | see below       | Replaces one element's styles                                          |
-| `group(name, *commands)`      | String, command paths                | none            | Lists those commands under their own heading, in declaration order     |
-| `sections(*names)`            | Section names                        | all             | Order of sections; a section left out is hidden                        |
-| `hide(*names)`                | Section names                        | none            | Hides sections without restating the order                             |
-Terminal width comes from `COLUMNS`, then the console, then 80. A resolved wrap width never falls below 20 columns.
-### Sections
-In default order, with default headings:
-| Section       | Heading     | Top-level help | Command help                        |
-| ------------- | ----------- | -------------- | ----------------------------------- |
-| `banner`      | none        | yes            | when `banner_on_subcommands` is set |
-| `usage`       | Usage       | yes            | yes                                 |
-| `description` | Description | no             | yes                                 |
-| `commands`    | Commands    | yes            | no                                  |
-| `subcommands` | Subcommands | no             | when the command has children       |
-| `arguments`   | Arguments   | no             | yes                                 |
-| `options`     | Options     | yes            | yes                                 |
-| `examples`    | Examples    | no             | yes                                 |
-| `epilogue`    | none        | yes            | only for a single command           |
-A single command passed to `Dry::CLI.new(SomeCommand)` is the whole program, so its command help prints the banner and the epilogue too. It has no registry, so it renders with the process-wide settings alone.
-A group listing, `mycli db` where `db` has no command of its own, renders as top-level help scoped to the group, with the banner only when `banner_on_subcommands` is set, and no epilogue.
-Every Options section starts with `-h, --help  Show help`, because both spellings work at every level. The example above shows `--help` alone; `spec/dry/cli/help/integration_spec.rb` holds the exact output.
-At any level, a command registered under a name or alias starting with `-`, such as `register "version", Version, aliases: ["--version"]`, lists under Options rather than Commands.
-### Styled elements
-| Element    | Default styles   | Applies to                             |
-| ---------- | ---------------- | -------------------------------------- |
-| `title`    | `bold`           | The banner title                       |
-| `heading`  | `bold`, `yellow` | Every section heading                  |
-| `command`  | `green`          | Command names and the program in usage |
-| `argument` | `cyan`           | Argument names                         |
-| `option`   | `cyan`           | Option names                           |
-| `comment`  | `bright_black`   | The comment half of an example         |
-### Layout
-- Every section after the first starts after one blank line. Section bodies indent two columns.
-- A definition list (commands, arguments, options) aligns its descriptions in one column across the whole screen, two columns past the longest term that has a description. The column never passes half the wrap width, and a term longer than the column puts its description on the next line.
-- Examples align among themselves. A full command line is longer than any option, and sharing its column would push every other description to the right.
-- A group registered without a command has no description of its own, so it lists as `Subcommands: a, b`.
-- An argument or option description ends with what a reader needs to supply it: `(required; one of: json, yaml; default: "json")`. An array argument reads `NAME...`.
-- Descriptions wrap with a hanging indent under the description column. Paragraphs split on blank lines and reflow; a line starting with whitespace prints verbatim.
-- An example written `"prod # ship to production"` renders the part after the first `#` surrounded by spaces as its description.