inconsistency in help

[ggzengel]

zfs/cmd/zpool/zpool_main.c

Line 416 in 8f2f6cd

"[-igLpPstvxD] [-T d|u] [pool] ... \n"

The following outputs are different;

#zpool status -h
invalid option 'h'
usage:
	status [--power] [-c [script1,script2,...]] [-igLpPstvxD]  [-T d|u] [pool] ... 
	    [interval [count]]

#zpool help status
zpool status [-DeigLpPstvx] [-T u|d] [-c [SCRIPT1[,SCRIPT2]…]] [pool]… [interval [count]]

In one --power is missing, in the other -e.
Is it possible to have one global text source for this?

@cmharr can you fix this with -e?

@behlendorf Is there some style guide for synopsis, about order of arguments and upper/lower case and ellipses?

[cmharr]

Submitted #16008 to fix the missing '-e' and re-order alphabetically the other 2 letters in that string that aren't right.

[stale]

This issue has been automatically marked as "stale" because it has not had any activity for a while. It will be closed in 90 days if no further activity occurs. Thank you for your contributions.

[ggzengel]

There a still inconsistencies:

    status [-dDegiLpPstvx] [-T u|d] [-c [SCRIPT1[,SCRIPT2]…]] [pool]… [interval [count]]
       [-j [--json-int, --json-flat-vdevs, --json-pool-key-guid]]


    status [--power] [-j [--json-int, --json-flat-vdevs, ...
    --json-pool-key-guid]] [-c [script1,script2,...]] [-dDegiLpPstvx] ...
    [-T d|u] [pool] [interval [count]]

[behlendorf]

The command line help differs slightly from the man pages for some other sub-commands as well. It looks like it's mostly argument ordering but it would be nice to go through an make them all consistent.

[ggzengel]

I asked Perplexity for help. What's about this?

OpenZFS CLI Synopsis and Help Output Rules

These rules ensure consistent, clear, and user-friendly CLI synopsis and help output for OpenZFS commands.

---

1. Single Source of Truth

• Maintain a single, authoritative definition of each command's synopsis and options, used for both CLI --help output and man pages.

---

2. Option Listing and Order

• List all supported options in the synopsis (short and long forms).
• Order all short options (both uppercase and lowercase) alphabetically by their actual case within brackets (e.g., [-DegiLpPstvxT]).
• List long options after short options (e.g., [--power]).
• Group related or mutually exclusive options for clarity, but preserve alphabetical order where possible.

---

3. Argument Formatting

• Required arguments: Use descriptive names in angle brackets or lowercase in brackets (e.g., [pool], <interval>).
• Optional arguments: Enclose in square brackets (e.g., [-e], [-T u|d]).
• Repeatable arguments: Place ellipses directly after the argument with no space (e.g., [pool]...).
• Mutually exclusive/grouped options: Use vertical bars and brackets (e.g., [-T u|d]).

---

4. Ellipses Usage

• Use ellipses (...) directly after the argument or option they apply to, with no space (e.g., [pool]...).
• Only use ellipses for arguments/options that can be repeated.

---

5. Case and Style

• Option flags: Use the actual case as implemented (e.g., both -e and -T).
• Argument placeholders: Use lowercase for generic arguments (e.g., [pool]), uppercase for variables if established (e.g., [SCRIPT1[,SCRIPT2]…]).
• Long options: Use double dashes and lowercase (e.g., --power).

---

6. Option Argument Value Order

• When listing possible values for an option (e.g., -T u|d), use the order from the implementation and documentation.
• If no order is established, list values alphabetically (e.g., -T d|u).

---

7. Consistency Across Outputs

• Ensure the output of --help, -h, and the man page synopsis are identical in terms of option presence, order, and argument notation.

[cmharr]

@behlendorf, perhaps another relevant question is if we should support zpool <cmd> [-h|--help]? Currently both are interpreted as invalid options -- same as giving it nonsense like --banana -- although it does then spit out the command usage. Other commands also lack -h and --help. Is it a conscious choice to only support zpool help <cmd> syntax?

[behlendorf]

There are a couple complications with supporting zpool <cmd> [-h|--help], but nothing to serious.

1. Regarding --help not all of the sub-commands currently support long options. For those that do it's be easy to add. There's also no reason I'm aware of not to go through and add long option support to the commands where it's missing. It's simply that no one has gotten to it yet.
2. As for -h we can't systematically make that change since several of the sub-commands already take -h as an option.

[cmharr]

See PR #17357. This is only for the 'zpool status' command and there are still questions on what style to use, but the two outputs are pretty close. One outstanding question is the CLI usage statement includes ellipses "..." at the end of each line. Do we want to keep those or remove them to match the man page (it doesn't make sense to add them to the man page since line width is controlled by your window size)?