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
Lines in help output can be wider than the terminal width #2065
Comments
One way to solve this would be to buffer the entire help message into a string, then apply wrapping to it all at once. This could have a performance impact (I haven't tried it). A more sophisticated approach could be to buffer the help message in chunks, flushing it to output whenever wrapping occurs (or when an explicit newline is encountered). That could be fairly complex, though. |
Expanding on the second paragraph in my previous comment, here's a sketch of what a "buffer in chunks" wrapping algorithm could look like. This hasn't been tested and there are likely edge cases I've missed:
The Anyway, it's probably worth measuring the performance impact of a "buffer it all" strategy first as it should be much simpler. Or maybe there's a better approach than either of these which I've missed. |
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"). - Many template tags now emit line-wrapped output to match write_default_help. - 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, but if this makes it into 3.0 that's probably reasonable? Note that line-wrapping can have some odd edge cases since it does not account for preceding/trailing characters on the same line as the tag. This is already the case in master, but will affect some additional tags with this changeset. See clap-rs#2065 for details. Closes clap-rs#2002.
If you don't mind, a couple of questions:
That was out of curiosity. For the record, I'd like to see this fixed, not ignored, even if the decided fix will be "don't support width less than N and assert that".
Aha. Word wrap.
No. I don't see any reason why lack of color should imply lack of wrapping.
And this is not-too-far description of my "Refactor" PR. I've done only some preliminary measurements, but they didn't show any significant difference. |
I realized this issue existed while hacking on #2067. At first I thought it was only a problem with custom templates, but then I noticed the default help can also exhibit this behavior (albeit only in pathological cases like the super long binary name). Custom templates can put an arbitrary amount of stuff on a single line which makes this issue more pronounced (it can affect all tag(s), not just binary name & version).
The tiny width was just to make the example short. I don't set an explicit width in any of my real uses of clap. |
I agree. I think the variant names are throwing me off; since it's |
@mkantor I think this has been fixed with the recent changes to master. Do you think you can look into the test cases? |
@pksunkara I rebased the tests and they still fail, so it appears this issue hasn't been fixed. |
|
So it looks like we are wrapping individual fields in places (e.g. bin name, version, etc) rather than wrapping the result. Part of this comes from the fact that we are processing a template. Resolving this would take some work in balancing how to wrap the aggregation of fields without interfering with areas that might not want wrapping. |
Code
Steps to reproduce the issue
cargo run
This string is 34 characters long. v12.34.56
) is wider than the desired width (35), even though there are places where it could have been wrapped.See this diff for additional test cases.
Version
rustc 1.45.2 (d3fb005a3 2020-07-31)
master
Actual Behavior Summary
When getting help output that has been line-wrapped to fit the terminal width the output can be wider than the terminal, even if there are places where wrapping could have been applied.
Expected Behavior Summary
Lines should never be wider than specified terminal width unless they contain no word breaks.
Additional context
Wrapping is currently applied to individual bits and pieces of the overall help message without taking into account their context. For example, as demonstrated above the version number and binary name are displayed on the same line by default, but the binary name is always wrapped as if its last character is at the end of the line. Similarly, some template tags have their output wrapped, but without preceding/trailing characters being accounted for.
The text was updated successfully, but these errors were encountered: