Problem

in the corner case where:

1. wp-cli is running on a non-Windows system
2. the PAGER environment variable is not set
3. the command less is not installed
4. the user triggers output of the wp help command:
   • by running that command explicitly
   • by running an invalid wp-cli command

wp-cli crashes, as documented in #5333

An example of an environment without less is many "minimalist" Docker server containers.

Changes

• Fixes Command less not available on the current machine #5333 by removing the assumption that less exists in non-Windows environments when the environment variable $PAGER is not set. Instead, in all environments, invocations of wp help will first check to see if less exists, and use that, before falling back to more. The previous behavior was to pipe output through less -R on non-Windows systems without first checking if less exists.
• Adds a docblock to Help_Command::pass_through_pager()

Alternatives considered

Replacing less -R with cat

This would replace a pager with a non-pager, which seems like a feature regression

Replacing less -R with more in all cases

Ruled out by @mrsdizzie at #6020 (comment), and removed in b88c438

Accurately checking whether less exists

I started a branch with this intent, at benlk@832bb1e , but this approach proved nonviable.

To accurately test whether less exists:

• On Windows, we would need to add a test to wp-cli to determine whether wp-cli is running in cmd.exe or Powershell, as cmd.exe can use where to determine whether a command exists, but Powershell needs to use a different command
• On POSIX systems, where command -v accurately determines whether a command exists, we would also need to check for the existence of an alias, which is a separate can of worms
• In all cases, we would need to perform extensive checks on the return of the check, because proc_close() isn't guaranteed to return the command's exit code

This seemed like way too much scope creep, introducing too much code, requiring too much testing, for a fallback scenario around displaying a help message.

Testing

The existing tests in https://github.com/wp-cli/wp-cli/blob/main/features/help.feature do not care about whether more or less is used.

If additional tests are needed for this change, I'm open to suggestions on what should be tested.

For local testing, on all OS:

1. Set up this branch according to https://make.wordpress.org/cli/handbook/contributions/pull-requests/#working-on-the-project-as-a-whole
2. Run echo $PAGER to check what your local shell's PAGER variable is. If it is set to any value, including an emptystring, run unset PAGER to unset it.
3. Run less to determine whether less exists on your system. If it does, run command -v less (POSIX) or where less (Windows) to determine whether it exists as a binary or as an alias.
4. Run wp without any other commands or options
5. Expect that the output of wp help is displayed. If less exists on your system, it should be paged in less. If less does not exist, but more does exist in your system, the output should be paged in more.