Clap: Ability to style help messages

[pickfire]

Make sure you completed the following tasks

• [x] Searched the discussions
• [x] 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]

@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]

@pickfire sure no issues

[CreepySkeleton]

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

[SirWindfield]

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.

[SirWindfield]

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).

[SirWindfield]

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?

[SirWindfield]

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.