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

Use a default template instead of separate code path in Help::write_help #2002

Closed
CreepySkeleton opened this issue Jul 6, 2020 · 1 comment · Fixed by #2067
Closed

Use a default template instead of separate code path in Help::write_help #2002

CreepySkeleton opened this issue Jul 6, 2020 · 1 comment · Fixed by #2067
Labels
A-help Area: documentation, including docs.rs, readme, examples, etc... E-help-wanted Call for participation: Help is requested to fix this issue. E-medium Call for participation: Experience needed to fix: Medium / intermediate
Milestone

Comments

@CreepySkeleton
Copy link
Contributor

As @kitlith noticed in #1986 (comment),:

Using a template vs not using a template go through two somewhat different code-paths, right? You don't internally use a template unless the user provides one.

In other words, instead of using some sort of hardcoded template, we use a separate function that acts like a hardcoded template.

I think that it worth exploring simply using a hardcoded template instead of a separate code path. We may also export this template as pub static: &str DEFAULT_TEMPLATE, but I'm opposed to considering precise contents of the default template as an API contract as we may (and probably will) tweak it here and there.

Related code:

clap/src/output/help.rs

Lines 110 to 115 in 9fc8ec9

if let Some(h) = self.parser.app.help_str {
self.none(h).map_err(Error::from)?;
} else if let Some(tmpl) = self.parser.app.template {
self.write_templated_help(tmpl)?;
} else {
self.write_default_help()?;

The function in question:

pub(crate) fn write_default_help(&mut self) -> ClapResult<()> {

@CreepySkeleton CreepySkeleton added P2: need to have A-help Area: documentation, including docs.rs, readme, examples, etc... E-medium Call for participation: Experience needed to fix: Medium / intermediate E-help-wanted Call for participation: Help is requested to fix this issue. labels Jul 6, 2020
@CreepySkeleton CreepySkeleton added this to the 3.1 milestone Jul 6, 2020
@kitlith
Copy link
Contributor

kitlith commented Jul 6, 2020

I agree. The precise contents of that template should be able to change. The guarantee I was going for is not "this is the template that will always produce the default output" but "this is the template that produces the default output for this version".

mkantor added a commit to mkantor/clap that referenced this issue Aug 12, 2020
mkantor added a commit to mkantor/clap that referenced this issue Aug 12, 2020
This makes some changes to the template system:

- Template tags for optional items (like {author}) now expand to
  nothing when the value is unset instead of a default string (like
  "unknown author").
- Items are now line-wrapped TODO doc why where when
- Items with long variants now expand to the appropriate thing for -h
  vs --help.
- The now-obsolete {long-about} tag has been removed.
- A few new tags have been added.

These are externally-visible changes that might require adjustment,
but since the next release will be a major bump anyway that's probably
reasonable?

Closes clap-rs#2002.
@bors bors bot closed this as completed in a87320a Aug 15, 2020
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... E-help-wanted Call for participation: Help is requested to fix this issue. E-medium Call for participation: Experience needed to fix: Medium / intermediate
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants