Config: revamp the help screen(s)

[jrfnl]

👉🏻 This PR depends on PR #445 .

Description

This PR attempts to make the help information more informative and to improve the readability and findability of options.

This should be seen as a first step to address user concerns about difficulty in finding the options they are looking for and understanding how certain options work, like seen in the recent months in tickets #10/#294/#419, #248, #322, #415 and #434.

The format for the new screens is inspired by similar help screens as currently in use in various other typical CLI tools, like PHPUnit and PHPStan. This includes the choice for the use of colours and which colours to use.

The option descriptions are based on the previously available option descriptions with some improvements where I deemed those appropriate. I've elected to keep the descriptions short though as this is a help screen, not a tutorial.

Notes:

• I've chosen to move the logic to generate the help screen to a separate (internal) class. This new class is fully covered by tests, including various QA tests which function as error-prevention when new options would be added.
• The output, by default, is not coloured, as PHPCS defaults to --no-colors. To get coloured output, either ensure the colors option is saved as 1 in the user-specific configuration using --config-set colors 1 (making PHPCS default to --colors) or pass --colors on the command line. Note: if --colors is passed on the command line _after the -h argument, it will have no effect. This is a symptom of how the CLI argument processing currently works and is considered as out of scope of this issue. See #448.
• The output will respect the report-width setting (which defaults to auto, i.e. width of the current screen), as long as the report-width is 60 columns or more. If the report-width is set to below 60 columns, a width of 60 will be used anyway to allow for displaying the texts.
• colors and report-width settings as saved to a CodeSniffer.conf file via --config-set will be respected when displaying the help screens.
• colors and report-width settings provided via a custom ruleset have no effect on the help screens.

Todo:

• [ ] Update Wiki Usage page before tagging the release which will contain this change.

Suggested changelog entry

The help screens have received a face-lift.

Types of changes

• [x] New feature (non-breaking change which adds functionality)
• [x] Documentation improvement

Testing this PR

To test this PR manually:

• Either check out the PR branch or download the phpcs.phar/phpcbf.phar files generated as build artifacts in the GH Actions workflows (these can be found on the "Summary" page of the latest "Test" workflow run for this PR).
• Run the following commands to see all different outputs:
  • phpcs --colors -h
  • phpcbf --colors -?
  • phpcs --no-colors -h
  • phpcbf --no-colors --help
• Additionally, run the above with variations of --report-width=# (passed on the command-line before the -h).
• Lastly, view the output with different command-line colour schemes.

I'm in particularly looking for feedback on the choices made regarding:

• the categorization of the options
• the (improved) text of the option descriptions
• the colours in regards to how they hold up when different colour schemes are used/against a light background.

Screenshots

New Help screen for PHPCS

New Help screen for PHPCBF

[mbomb007]

The PR changes --colors to be the default, but the help text is wrong regarding that.

[GaryJones]

The PR changes --colors to be the default, but the help text is wrong regarding that.

I don't believe it does. From the original PR description:

The output, by default, is not coloured, as PHPCS default to --no-colors. To get coloured output, either ensure the colors option is saved as 1 in the user-specific configuration using --config-set colors 1 (making PHPCS default to --colors) or pass --colors on the command line.

[mbomb007]

Okay, maybe I misunderstood what the change was when reading the code.

[jrfnl]

At the suggestion of @GaryJones - this is what the "before" looked like:

PHPCS:

PHPCBF:

[jrfnl]

Rebased without (further) changes after the merge of #445 to drop the commits which belonged to #445. Marking as ready for review.

If there is no further feedback I will merge this in a couple of days.

[jrfnl]

Rebased without changes, just squashed the commits together. Merging once the build passes.