Allow styled text in `template`

[ssokolow]

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

[ssokolow]

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

[danwilliams]

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]

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]

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]

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

[epage]

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