My perspective on the rationale for splitting short/long help is that optimizing for the reader's time is a reasonable thing to do. Often I just need a refresher of what options are available. But sometimes I need a deeper understanding of what each option controls and how. (Yes I understand that this should be in man pages). There needs to be a reasonable way to control the verbosity of the help output from the command line however.

I agree with your point that most flags should generally treat short versions as exact aliases to long flags, but I just think that a convention that treats -h and --help as concise vs long is 100% reasonable. The distinction is often breadth vs depth.

That would be a perfectly reasonable convention, except it's already a convention that they do the same thing.

Having them be different could cause someone to look at -h, and not even know about --help. Or if someone writes a script parsing the output of -h for some reason, someone else might come along and change it to --help expecting it to be the same thing.

The rust crate clap which is one of the more well known crates for command line parsing gets about 2M downloads a day and has this convention built in.

This convention existed before clap came into being, but I don't recall when I first saw it. I have been using the command line for just shy of 40 years across various operating systems.

100% agree, not sure where this idea came from but I'm not a fan.

You can just make a `--help-all` (or whatever word you want to use), imo the `--help-all` command doesn't need a short equivalent because it's not something you'd frequently use.