Improve layout of help output, and autogenerated help for custom commands #8852
Description
Related problem
Current help output is pretty comprehensive (for built-ins, at least), but the order of sections and layout of info could be reworked to improve scannability and readability.
Also, could add a --verbose flag (default false), to hide metadata like category...
Here's a current help text (with editorial comments in [[]])
〉help table
Render the table.
[[ usage, parameters and flags should go here]]
[[ move the following sentence lower down, it's a special case usage note]]
If the table contains a column called 'index', this column is used as the table index instead of the usual continuous index.
[[move search and category lower down, these are not the first thing I need to know about this command]]
Search terms: display, render
Category: viewers
[[ reformat to take up less vertical space. ]]
This command:
- does not create a scope.
- is a built-in command.
- is not a subcommand.
- is not part of a plugin.
- is not a custom command.
- is not a keyword.
Usage:
> table {flags}
Flags:
-h, --help - Display the help message for this command
-n, --start-number <int> - row number to start viewing from
-l, --list - list available table modes/themes
-w, --width <int> - number of terminal columns wide (not output columns)
-e, --expand - expand the table structure in a light mode
-d, --expand-deep <int> - an expand limit of recursion which will take place
-, --flatten-separator <string> - sets a separator when 'flatten' used
-c, --collapse - expand the table structure in collapse mode.
Be aware collapse mode currently doesn't support width control
Signatures:
<any> | table -> <any>
Examples:
List the files in current directory, with indexes starting from 1.
> ls | table -n 1
Render data in table view
> [[a b]; [1 2] [3 4]] | table
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ 4 │
╰───┴───┴───╯
Render data in table view (expanded)
> [[a b]; [1 2] [2 [4 4]]] | table --expand
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ 4 │
╰───┴───┴───╯
Render data in table view (collapsed)
> [[a b]; [1 2] [2 [4 4]]] | table --collapse
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ 4 │
╰───┴───┴───╯
Describe the solution you'd like
My SWAG at an improvement, interested to hear what others think.
- Help should have a --verbose flag, and
category,search termsandthis commandshould only display if it is set - Good help text often is too long, such that all-important usage text scrolls off the top of the screen. Consider adding an
--examplesflag to control rendering of examples section (default false). Or consider rendering help in a pager, likeman, (which really gets it right, IMHO).
〉help table
Render the table.
Usage:
<any> | table {flags} -> <any>
Flags:
-h, --help - Display the help message for this command
-n, --start-number <int> - row number to start viewing from
-l, --list - list available table modes/themes
-w, --width <int> - number of terminal columns wide (not output columns)
-e, --expand - expand the table structure in a light mode
-d, --expand-deep <int> - an expand limit of recursion which will take place
-, --flatten-separator <string> - sets a separator when 'flatten' used
-c, --collapse - expand the table structure in collapse mode.
Be aware collapse mode currently doesn't support width control
If the table contains a column called 'index', this column is used as the table index instead of the usual continuous index.
[[ command parameters would go here... ]]
Examples:
List the files in current directory, with indexes starting from 1.
> ls | table -n 1
Render data in table view
> [[a b]; [1 2] [3 4]] | table
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ 4 │
╰───┴───┴───╯
Render data in table view (expanded)
> [[a b]; [1 2] [2 [4 4]]] | table --expand
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ 4 │
╰───┴───┴───╯
Render data in table view (collapsed)
> [[a b]; [1 2] [2 [4 4]]] | table --collapse
╭───┬───┬───╮
│ # │ a │ b │
├───┼───┼───┤
│ 0 │ 1 │ 2 │
│ 1 │ 3 │ 4 │
╰───┴───┴───╯
[[ the rest of this metadata only shown if `help --verbose` ]]
Search terms: display, render
Category: viewers
This command:
- does not create a scope.
- is a built-in command.
- is not a subcommand.
- is not part of a plugin.
- is not a custom command.
- is not a keyword.
Describe alternatives you've considered
No response
Additional context and details
A task under #8813, though the proposal here is to implement a divergence from built-in help.