[DEPRECATED] Better Help-Text formatting - Align single and double dash flags and options #858
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Deprecated
A new PR has been made, see #866.
EDIT: I found a way to implement this PR nicely into the default
Formatter
, instead of the ugly way like it is now. I'm currently working on that and some additional features for better help formatting, like paragraphs with correct line wrapping for long descriptions.Please ignore the text below, do not merge this PR, and please leave it open for now until I sorted things out. I'll take care of everything.
EDIT 2: Still on it, almost done. Should be completed this weekend.
This PR is mainly based on #353 and indirectly on #856. It adds a new and better help text formatting by aligning single and double dash flags and options nicely.
A bit about the background:
As far as I understood the source code (and wrote in #856) there is no good way to reliable format all combinations for flags and options using a custom formatter (or by modifying the default formatter). This PR therefore changes theEDIT: This is wrong. I'm working on a PR which changes the default formatter and leaves thestd::ostream& format_help(...)
function directly.format_help
function in it's original state.A goal was not needing to modify any function signatures or otherwise spread-out changes to the codebase. Because of that, the code for this PR seems a bit more verbose since, for example, we need to split up the parameter
std::string name
insideformat_help
after it got assembled while actually callingformat_help
. But as I said, I wanted to avoid changing function signatures or spread the changes across more files than necessary. I added a lot of comments to explain what is going on. The code also supports setting a custom column size. Single dash flags occupy 25% of the column width, double dash flags and options (like REQUIRED) 75%.I thoroughly testes this code and so far it worked without a problem with all examples and custom tests made by me.
I'm currently testing with CLI11 tests.EDIT: The failed tests are failing because they expect the old help text format. So all Tests seem to "pass". However there is no guarantee (yet) that it is fully bug free. The code is only manipulating singe and double dash flags and options (-f or --file). Subcommands and positionals are formatted like before, no changes are made to them.Here's an example of the new help text formatting:
The alignment is like suggested in #353 and also looks more UNIX standard.
I think I'll make some improvements tomorrow or simplify some code, fix some spelling and code style issues. But there shouldn't be any major changes. I'll appreciate some feedback and am looking forward to possibly see the new formatting in CLI11. If this is completely the wrong way and such changes are only allowed using custom formatters, let me know.