Ability to style help messages

[pickfire]

Closing comment

Rather than embedding a styling API into clap, might I suggest the following issues as a focus point for users and maintainers:

• [modular] Decouple help format from help generation #2914
• Allow styled text in template #1433
• The header for my examples are not colored like the others #3108

---

Make sure you completed the following tasks

• Searched the discussions
• Searched the closes issues

Describe your use case

Configuration to allows styling help messages. It is helpful for example when styling help messages in a way to improves discover-ability of sub-commands or even bold and emphasize command description, or with the use of colors.

Describe the solution you'd like

It may have cross platform terminal support issue so we may need to depend on some other crates to handle styling for this and it is also better to be feature gated.

A snipped in my mind would be to have some terminal escapes to display the color but it may not be cross-platform, this should be open for discussion.

    .subcommand("\e[1mb\e[muild")

But it should be extensible so it could be reused for man page generation or completions later on.

Alternatives, if applicable

Use other crates to get the same feature

Additional context

[pksunkara]

What happens currently if you actually use the ansi escape codes in the usage messages right now?

[pickfire]

@pksunkara Oh, right now the ansi escape codes does not even work.

use clap::{App, SubCommand};

fn main() { Run
    let matches = App::new("app")
        .subcommand(SubCommand::with_name(r"\e[1mt\e[mest"))
        .get_matches();
    dbg!(matches);
}

> cargo r -- -h
   Compiling hello v0.1.0 (/home/ivan/hello)
    Finished dev [unoptimized + debuginfo] target(s) in 0.77s
     Running `target/debug/hello -h`
app

USAGE:
    hello [SUBCOMMAND]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    \e[1mt\e[mest
    help             Prints this message or the help of the given subcommand(s)

[Dylan-DPC-zz]

@pickfire hey, thanks for reporting this. do you want to work on this issue? feel free to submit a PR :)

[pickfire]

@Dylan-DPC Nope, I will probably not work on this. Maybe I will work on the extra line config #1642.

[Dylan-DPC-zz]

@pickfire sure no issues

[CreepySkeleton]

Sidenote: on Windows < 10 ascii escape codes are not supported AFAIK. Do we care?

[mainrs]

Wouldn't an API be better that can be passed to items. This would allow for noop implementations on unsupported platforms. There are enough crates out there that already do that, there would just be the need to create an API around it. Maybe something like this?

use clap::{App, SubCommand, Style};

fn main() { Run
    let style = Style::default()
        .fg(Color::Red)
        .bg(Color::Orange)
        .underline();

    let matches = App::new("app")
        .subcommand(SubCommand::with_name("test").style(style))
        .get_matches();
    dbg!(matches);
}

[pickfire]

But how does this API works with some more advanced? Like command description where one needs to change the style of some text partially? I bet it would be complicated.

[mainrs]

I mean there are already solutions for that. For example https://github.com/mackwic/colored allows to color strings how you'd like. And you can just compose them using the format macros.

Given the example above it wasn't clear that a need arised in having everything colorable. And I kind of doubt the usefulness of that one.

Not sure what clap does under the hood to be honest, but I just tested it using a simple example and clap does filter out the ANSI. I did some fast digging but couldn't find the part where it does that. You guys probably know more though.

use clap::{Arg, App};
use colored::Colorize;

fn main() {
    println!("{}", "hello world".red());
    let matches = App::new("test")
        .arg(Arg::with_name("arg")
            .about("some longer description".cyan().as_ref()))
        .get_matches();
}

I expected the above to print the help in cyan, but the control codes get filtered out for some reason. The hello world is red though.

[pickfire]

@pksunkara IIRC currently clap filters out ansi escapes codes like @sirwindfield mentioned. I wonder if there is a reason behind it?

[pksunkara]

I am not sure if we filter or remove it. I would need to check. But the current behavior you are describing is intentional. Having non display chars was messing with the help message indentation.

[pickfire]

But these escape codes for coloring are not adding any spaces or changing the indentation, maybe we can explicitly whitelist the escape codes for coloring (except those that mess with the cursors).

[CreepySkeleton]

Pasting my own comment from elsewhere

---

That said, what I'd suggest is some kind of placeholder that resolves to either changing the colour if colourization is enabled or nothing if it's disabled.

I was thinking along these lines in the context of #1790. Something like

{color:yellow:USAGE}

or more generally

{color:color_name-bold:text}
 ----- ---------- ---- ----
 |        |         |
 keyword  |       optional bold switch
       the color

And maintain the list of supported colors.

I don't want to support any RGB-or-something notations because Windows CMD has only a set of predefined colors and implementing the RGB code => winapi color mapping is something I very much like to avoid.

[pickfire]

@CreepySkeleton Does windows support for coloring and codes similar to the one in linux? I wonder if it would be good to do it this way, the API looks interesting but I think it may be a bit limited for linux where people cannot use something special like blinking cursors (I rarely see people using it but it could be done). Or maybe should we still allow an API to let people paste raw text for different platforms or we could pair it with some kind of #[cfg(platform?)] for it?

[CreepySkeleton]

Wait, we were talking about coloring and bolding and italicizing arbitrary parts of the template and then we somehow ended up talking about blinking cursors??? How on earth does this stuff relate to help messages?

As for the question, yes, windows has support for text coloring. Specifically, we use termocolor for cross-platform handing of all this insanity, so I'd say this enum is all you can count on (except Ansi and Rgb, see the reason above).

[mainrs]

That doesn't hold true for all Windows versions. Windows 10 does support RGB values the same as Linux does. I did find and use a crate that had support for it, not sure what it's name was though.

[pickfire]

Wait, we were talking about coloring and bolding and italicizing arbitrary parts of the template and then we somehow ended up talking about blinking cursors??? How on earth does this stuff relate to help messages?

Yes, we are talking about coloring, bolding and italicizing (or maybe underline too). I just wanted to talk about the extensibility which probably we won't need because we are limited to cross platform support but I am just wondering if there is a possibility that we are able allow that.

[CreepySkeleton]

That's all nice and dandy, but let's imagine you're on Windows 7 or 8 or pre-escapes-supported win 10 (was about 35% of market share last time I looked) and you're trying to set the RGB color, say {color:#ef432a:TEXT}. What is clap supposed to do? What can clap do? Only ignore the setting - there's no sane way to map an RGB code to one of the 16 colors and make it look good.

If we implemented RGB handling in the way described above (and I see no others), then we're up to answering questions like, "I (developer) made use of the brand new feature and now my Win 7 users complain they're left staring at black-and-white wall of text, all retro! You claimed support for win 7; is RGB broken?".

This is the reason I'm not excited about RGB: I don't want to roll features that sometimes work and sometimes don't.

Although, I admit I'm not dead set against it, but I'm going to need some further persuasion about why this is useful. Are the 16 colors not enough for help messages?

[mainrs]

I do get your point, but what is wrong with having the developer decide if they want to map the RGB colors back to the 16 if needs arises due to platform restrictions? I guess for a first implementation RGB can be ignored for sure. But I don't see why this couldn't even be an optional feature people can opt in to.

[CreepySkeleton]

Hm, I guess what we need is some sort of (optional) fallback: {color:#ef432a(yellow):TEXT} which means "if the platform does not support rgb, set it to yellow". If no fallback specified, you're out of luck and colors.

[pksunkara]

I like the format that is proposed but I am also vary about adding DSL's to the descriptions.

[ajeetdsouza]

@pksunkara instead of a DSL, perhaps users can supply after_help_pieces: Vec<(String, Option<Color>)>? That way, you can just pass it to the Colorizer the same way other strings in clap are passed.

[lilyball]

I want color in messages, but primarily I want to be able to just match clap's existing colors rather than specifying a particular one. My use case is when writing a help message for an option with possible/default values. Clap will include these possible/default values in the help string with colors, but if I'm referencing a possible value in the string itself, I want to use the same color. Similarly if I hide the default/possible values I want to be able to reproduce them in the help string.

Basically, what I want is to be able to write arg.hide_default_value(true).hide_possible_values(true).help(…) and still be able to replicate precisely the same output clap does by default. The goal of course is to then modify that, but if I can replicate it, then that means I have the tools to do what I need.

Technically I can do this today in clap 2.33 by using the undocumented clap::Format, but I'm assuming it's undocumented for a reason and a cursory look at clap 3.0 suggests it's no longer available there.

[lilyball]

To expand on that, I would really like 3.0 to at least have the ability to apply the same coloration used for the default/possible values, regardless of any support for a full DSL for coloration. At the moment I am going ahead and using clap::Format in my code, with the expectation that I'll have to adapt once clap 3.0 is out and we switch to it, and I'd really love to have some solution that doesn't involve reimporting atty and ansi_term myself.

[ajeetdsouza]

My use case is that I'd like to show environment variables in the --help menu.

ENVIRONMENT VARIABLES:
    SAMPLE_FOO    This does foo thing.
    SAMPLE_BAR    This does bar thing.

I'd like a way to highlight the heading and items in this list the same way that clap does for flags and options.

[epage]

#2914 is another way of resolving some of the care-abouts mentioned this thread.

Personally, this thread sounds like its pulling into claps' API a terminal styling API, directly or through a template language. There are enough care-abouts and concerns with those APIs, I'm concerned having a bespoke styling API is a bigger concern than we should take on. We could adopt an existing one but those tend to have their own cadence for breaking changes, I'm unsure how much we want to tie ourselves to them in that way.

See also

• Allow styled text in template #1433
• The header for my examples are not colored like the others #3108

[epage]

Rather than embedding a styling API into clap, might I suggest the following issues as a focus point for users and maintainers:

• [modular] Decouple help format from help generation #2914
• Allow styled text in template #1433
• The header for my examples are not colored like the others #3108

I'm going to go ahead and close this out in favor of those issues. If there are any concerns with the plan of relying on those issues, please let us know!

[pksunkara]

I think this issue was kept separate to #1433 because this would allow users to show different colors for their different subcommands. I am not sure if #2914 would cover that case?

[epage]

So, to a degree, we'll need to expose Colorizer to allow code-genned help after #2914. Having that exposed in the whole API and allowing custom styling is what I'm most concerned about in this issue (especially when if a subcommand needs a separate display name from actual name for styling).

With the custom formatting allowed by #2914, a user could match on the subcommand names and do a lookup for how they would want to format it, so I do see that being a solution for this.