Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow styled text in template #1433

Closed
ssokolow opened this issue Mar 19, 2019 · 6 comments · Fixed by #4765
Closed

Allow styled text in template #1433

ssokolow opened this issue Mar 19, 2019 · 6 comments · Fixed by #4765
Labels
A-help Area: documentation, including docs.rs, readme, examples, etc... C-enhancement Category: Raise on the bar on expectations S-blocked Status: Blocked on something else such as an RFC or other implementation work.
Milestone

Comments

@ssokolow
Copy link

Rust Version

rustc 1.32.0 (9fda7c223 2019-01-16)

Affected Version of clap

2.32.0

Bug or Feature Request Summary

When using a custom template to work around papercuts in Clap (#1432) and StructOpt (TeXitoi/structopt#172) which break help2man, i can find no documented way to apply AppSettings::ColoredHelp to the "USAGE:" header, though I've managed to reconstruct the desired bits of all of the rest of the default template.

Expected Behavior Summary

I should have some means of reintroducing the conditionally and portably colored USAGE: header, like this:

desired

NOTE: Image created as a composite of two screenshots.

Actual Behavior Summary

I was able to recreate every desired element of the default template except the coloring on the USAGE: header:

actual

Steps to Reproduce the issue

  1. Copy the example from the README into a new project
  2. Use the following custom template in concert with AppSettings::ColoredHelp:
const HELP_TEMPLATE: &str = "{bin} {version}

{about}

USAGE:
    {usage}

{all-args}
";

Sample Code or Link to Sample Code

https://gist.github.com/ssokolow/9df8c92b24d94116c5eb57fccad2b1a2

@ssokolow
Copy link
Author

...and, aesthetics aside, having a USAGE: header is necessary for help2man to recognize the usage line.

@danwilliams
Copy link

Equally, if you use, as a guideline, the "full help template" that can be found here:

https://github.com/clap-rs/clap/blob/master/tests/example1_tmpl_full.txt

...there is no way to apply the ColoredHelp formatting to the various other headings if, for instance, you wish to change their order or rename them (e.g. for language translations).

Unsure at this point of the best approach to getting coloured help output when using custom help templates.

@ssokolow
Copy link
Author

ssokolow commented May 6, 2019

EDIT: Sorry if you saw the original form of this via e-mail notification. I initially misunderstood the intent of your response.

True, but, In my testing, aside from the USAGE: header not being colourized, the template I gave is equivalent to removing the author placeholder from the default template and inserting a newline before {about} so help2man understands it properly.

example1_tmpl_full.txt has the additional problem of not replicating the "hide headers for empty sections" behaviour of the default template.

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.

@CreepySkeleton CreepySkeleton added C: colorizing A-help Area: documentation, including docs.rs, readme, examples, etc... C-enhancement Category: Raise on the bar on expectations labels Feb 1, 2020
@pksunkara pksunkara added this to the 3.1 milestone Apr 9, 2020
@CreepySkeleton
Copy link
Contributor

CreepySkeleton commented Jul 9, 2020

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.

@pksunkara pksunkara changed the title No template placeholder for colorized "USAGE:" header Allow styled text in template Oct 26, 2020
@pksunkara
Copy link
Member

The original usage issue is fixed in #2131. I am repurposing this issue for general styled text in templates.

@epage
Copy link
Member

epage commented Aug 18, 2022

My plan is for the API to accept ANSI colored strings. When we output, we use a special stdout/stderr that adapt the ANSI color codes to the capabilities of the terminal.

Blocked on https://github.com/epage/anstyle/issues/5

@epage epage added S-blocked Status: Blocked on something else such as an RFC or other implementation work. and removed S-waiting-on-design Status: Waiting on user-facing design to be resolved before implementing labels Aug 18, 2022
@epage epage added this to the 4.x milestone Aug 30, 2022
epage added a commit to epage/clap that referenced this issue Mar 17, 2023
epage added a commit to epage/clap that referenced this issue Mar 17, 2023
epage added a commit to epage/clap that referenced this issue Mar 18, 2023
epage added a commit to epage/clap that referenced this issue Mar 18, 2023
epage added a commit to epage/clap that referenced this issue Mar 18, 2023
epage added a commit to epage/clap that referenced this issue Mar 18, 2023
epage added a commit to epage/clap that referenced this issue Mar 28, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-help Area: documentation, including docs.rs, readme, examples, etc... C-enhancement Category: Raise on the bar on expectations S-blocked Status: Blocked on something else such as an RFC or other implementation work.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants