Ability to style help messages #150
Comments
|
What happens currently if you actually use the ansi escape codes in the usage messages right now? |
|
@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);
} |
|
@Dylan-DPC Nope, I will probably not work on this. Maybe I will work on the extra line config #1642. |
|
Sidenote: on Windows < 10 ascii escape codes are not supported AFAIK. Do we care? |
|
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);
} |
|
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. |
|
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. |
|
@pksunkara IIRC currently clap filters out ansi escapes codes like @sirwindfield mentioned. I wonder if there is a reason behind it? |
|
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. |
|
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). |
|
Pasting my own comment from elsewhere
I was thinking along these lines in the context of #1790. Something like or more generally 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. |
|
@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 |
|
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 |
|
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. |
|
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. |
|
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 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? |
|
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. |
|
Hm, I guess what we need is some sort of (optional) fallback: |
|
I like the format that is proposed but I am also vary about adding DSL's to the descriptions. |
|
@pksunkara instead of a DSL, perhaps users can supply |
|
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 Technically I can do this today in clap 2.33 by using the undocumented |
|
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 |
|
My use case is that I'd like to show environment variables in the I'd like a way to highlight the heading and items in this list the same way that clap does for flags and options. |
|
#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. |
Tuesday Apr 07, 2020 at 07:09 GMT
Originally opened as clap-rs/clap#1790
Make sure you completed the following tasks
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.
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
The text was updated successfully, but these errors were encountered: