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

[DEPRECATED] Better Help-Text formatting - Align single and double dash flags and options #858

Closed

Conversation

LostInCompilation
Copy link
Contributor

@LostInCompilation LostInCompilation commented Mar 10, 2023

Deprecated

A new PR has been made, see #866.

⚠️ Please ignore everything below. Only the new PR is relevant now.


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 the std::ostream& format_help(...) function directly. EDIT: This is wrong. I'm working on a PR which changes the default formatter and leaves the 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 inside format_help after it got assembled while actually calling format_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:

Description
Usage: myApp [OPTIONS]

Options:
  -h      --help                        Print this help message and exit
  -v      --version                     Display program version information and exit
  -p      --path STRING REQUIRED        Path to start in
  -a, -b  --multiple                    Multiple
          --only-long                   Long
          --hidden, --hide              Show or hide hidden files
  -r      REQUIRED                      Short req.
  -s                                    Short

This is a footer!

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.

@LostInCompilation LostInCompilation changed the title Better Help-Text formatting - Align single and double dash flags and options [DO NOT MERGE] Better Help-Text formatting - Align single and double dash flags and options Mar 10, 2023
@LostInCompilation
Copy link
Contributor Author

This PR has been deprecated. A new and better PR has been made. See #866.

@LostInCompilation LostInCompilation changed the title [DO NOT MERGE] Better Help-Text formatting - Align single and double dash flags and options [DEPRECATED] [DO NOT MERGE] Better Help-Text formatting - Align single and double dash flags and options Mar 19, 2023
@LostInCompilation LostInCompilation changed the title [DEPRECATED] [DO NOT MERGE] Better Help-Text formatting - Align single and double dash flags and options [DEPRECATED] Better Help-Text formatting - Align single and double dash flags and options Mar 19, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant