Allow adding usage examples to help text #2477

dbrgn · 2021-05-09T18:30:03Z

dbrgn
May 9, 2021

Please complete the following tasks

I have searched the discussions
I have searched the existing issues

Describe your use case

The tealdeer help text currently includes some invocation examples after the regular help text (using docopt):

Usage:

    tldr [options] <command>...
    tldr [options]

Options:

    -h --help             Show this screen
    -v --version          Show version information
    -l --list             List all commands in the cache
    -f --render <file>    Render a specific markdown file
    -o --os <type>        Override the operating system [linux, osx, sunos, windows]
    -L --language <lang>  Override the language settings
    -u --update           Update the local cache
    -c --clear-cache      Clear the local cache
    -p --pager            Use a pager to page output
    -m --markdown         Display the raw markdown instead of rendering it
    -q --quiet            Suppress informational messages
    --show-paths          Show file and directory paths used by tealdeer
    --config-path         Show config file path (deprecated)
    --seed-config         Create a basic config
    --color <when>        Control when to use color [always, auto, never] [default: auto]

Examples:

    $ tldr tar
    $ tldr --list

To control the cache:

    $ tldr --update
    $ tldr --clear-cache

To render a local file (for testing):

    $ tldr --render /path/to/file.md

I'm currently migrating the codebase to Clap v3. Is there a way to add these "usage examples" to the help text?

Describe the solution you'd like

It might be useful if usage examples could be attached to a CLI, which automatically show up in the help text.

This could be generalized to not just examples, but any additional help text. (Or is this already possible? I searched issues / discussion but could not find anything.)

Note that we'd probably need at least some kind of semantics attached to this "additional help text" data, otherwise help coloring would probably break.