`wp help <specific-command>` should be mentioned earlier / more prominent in help index
porg opened this issue · comments
1) A meta question
I wanted to submit a change to the output of purely wp
itself (aka "help index" aka "manpage index"). Which file(s) are used to build this? The content which starts like:
NAME
wp
DESCRIPTION
Manage WordPress through the command-line.
SYNOPSIS
wp <command>
SUBCOMMANDS
...
Did a full text search for Manage WordPress through the command-line
in both https://github.com/wp-cli/handbook and https://github.com/wp-cli/wp-cli but found nothing. I had wanted to submit a change to this as a pull request. But as I was not able to find the source for this, I put my proposal here itself.
2) The change proposal itself
In the section "SUBCOMMANDS" the help command itself is summarized like this:
help Gets help on WP-CLI, or on a specific command.
And only at the very end you have:
Run 'wp help <command>' to get more information on a specific command.
This is not so ideal. I propose to do one of the following:
a) Amend the SYNOPSIS section.
SYNOPSIS
wp <command>
wp help <specific-command>
b) Or in the SUBCOMMANDS section change the help command:
help Gets general help on WP-CLI. What you are currently reading.
help <cmd> Gets help on a specific <cmd> in WP-CLI.
I even would propose to except those from the alphabetical order and put them first, with one empty line inbetween, as they are serve as a quick lookup from more specific help.
Thanks for the suggestion, @porg
- A meta question
Good question, it's definitely not obvious.
All of the help docs are produced by Help_Command
and the functions it calls: https://github.com/wp-cli/wp-cli/blob/d99e2532014d3e0d14999b5f1e4382d9420c8aea/php/commands/src/Help_Command.php
- The change proposal itself
I'm not sure amending the SYNOPSIS is quite the right place. The SYNOPSIS is meant for the command itself.
I agree that the current location of the text is a bit hidden.
We could potentially inject it at the top of the SUBCOMMANDS section:
![image](https://private-user-images.githubusercontent.com/36432/238946173-914be457-a4d6-47ef-abc7-a2dc2a58dd2c.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MTk2MTA1OTAsIm5iZiI6MTcxOTYxMDI5MCwicGF0aCI6Ii8zNjQzMi8yMzg5NDYxNzMtOTE0YmU0NTctYTRkNi00N2VmLWFiYzctYTJkYzJhNThkZDJjLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNDA2MjglMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjQwNjI4VDIxMzEzMFomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTA5N2Q5YTM1OTFjOWRkZmM5NjgxNzVhZWM3MzA3NTY5YzdmNzNhNGQ2YzU1NjMxYWIxYTk2ODFlZGU4Yzc0YzcmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JmFjdG9yX2lkPTAma2V5X2lkPTAmcmVwb19pZD0wIn0.PAHv7EeZJ47F72FsgyrDj69JHjBLrj_vEJY_ckk2ER0)
Or potentially inject a HELP section to this root doc.
It might be useful to see how other popular CLI tools expose their --help
feature.
Ok then
- not in the 1) SYNOPSIS section, I agree with that, had expressed doubts myself.
- but 2) in the SUBCOMMANDS section on the very top. With a blank line after them, to make clear that the other subcommands are then alphabetically ordered.
Best practise for CLI help screens and how they mention help itself
- Just ran
--help
for a random choice of CLI apps, which I recently used - The best practise is very clear from my sample of 5 CLI --help screens:
- Most of them mention help very early on (highlighted in blue,
git
is the exception) - And many of them also give info how to use help command itself (git otherwise the exception, also does this)
- Most of them mention help very early on (highlighted in blue,
Screenshot with 5 CLI --help screens
Those examples are helpful, thank you.
Few more ideas to throw into the mix:
- Include a GETTING STARTED section for
wp
that provides 1-3 paragraphs about WP-CLI with basic usage instructions. - Include a HELP section for
wp
that's more specifically focused on getting help (e.g. runningwp <help>
, asking for help in#cli
on Slack, etc.) - Moving GLOBAL PARAMETERS above SUBCOMMANDS, or somehow highlighting "important" global parameters.
I'd be curious to hear other opinions from @wp-cli/committers
Two thoughts on this:
- We often have a conflict between surfacing as much help as possible and being efficient with screenspace for power users. That's why we have an environment variable to disable the global flags, for example.
- The tail of the output is what remains on the screen if the entire output does not fit. So starting with the help at the beginning would mean it is the first information that gets scrolled out of view.
I'm not against improving on this, just wanted to mention that there are several conflicting goals we're trying to solve for here.