Allow styled text in template

[epage]

Issue by ssokolow
Tuesday Mar 19, 2019 at 00:17 GMT
Originally opened as clap-rs/clap#1433

---

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:

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:

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

[epage]

Comment by ssokolow
Tuesday Mar 19, 2019 at 00:33 GMT

---

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

[epage]

Comment by danwilliams
Sunday May 05, 2019 at 13:45 GMT

---

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.

[epage]

Comment by ssokolow
Monday May 06, 2019 at 02:03 GMT

---

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.

[epage]

Comment by CreepySkeleton
Thursday Jul 09, 2020 at 13:10 GMT

---

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 clap-rs/clap#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.

[epage]

Comment by pksunkara
Monday Oct 26, 2020 at 08:21 GMT

---

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