> Which deviations are you concerned about?

This is the list I came up with the last time I looked at clap:

* Colours - But can be turned off by removing the color feature.

* Plain weird help formatting...:

Example:

$ clap-brightness --help
Adjust sysfs backlight with a log scale

Usage: clap-brightness [OPTIONS] <BACKLIGHT> <ADJUSTMENT>

Arguments:
<BACKLIGHT> Path to sysfs backlight (e.g. /sys/class/backlight/amdgpu_bl0)
<ADJUSTMENT> Percentage adjustment; relative (e.g. +10 or -6.25) or absolute (e.g. 50)

Options:
-m, --min <MIN> Artificially limit maximum brightness (percentage 'n%' or raw value 'n') [default: 0]
-M, --max <MAX> Artificially limit minimum brightness (percentage 'n%' or raw value 'n')
-h, --help Print help

$ argparse-brightness
usage: argparse-brightness [-h] [-m MIN] [-M MAX] backlight adjustment

Adjust sysfs backlight with a log scale

positional arguments:
backlight path to sysfs backlight (e.g. /sys/class/backlight/amdgpu_bl0)
adjustment percentage adjustment (e.g. +10 or -6.25) or absolute value
(e.g. 50)

options:
-h, --help show this help message and exit
-m MIN, --min MIN artificially limit minimum brightness (percentage 'n%' or raw value 'n') [default: 0]
-M MAX, --max MAX artificially limit maximum brightness (percentage 'n%' or raw value 'n')

* Why is the description printed before the usage?

* Why are positional arguments screamed at me? I've genuinely never seen this choice of full caps for positional arguments. I would have been happy with lowercase or <lowercase>.

* Likewise option placeholders are screamed and angle bracketed. I've only ever seen one or the other.

* It refuses to show you what the options are even if there's only 3 of them.

* And then there's the weird error handling decisions:

Example:

$ clap-brightness
error: the following required arguments were not provided:
<BACKLIGHT>
<ADJUSTMENT>

Usage: clap-brightness <BACKLIGHT> <ADJUSTMENT>

For more information, try '--help'.

$ argparse-brightness
usage: argparse-brightness [-h] [-m MIN] [-M MAX] backlight adjustment
argparse-brightness: error: the following arguments are required: backlight, adjustment

* Redacted usage line (why?).

* Instruction to tell me to try '--help'. Maybe useful if it's your first day in a unix environment, a waste of screen space otherwise.

* 2 lines of unnecessary whitespace.

* A newline separated list of required arguments when there are two of them? (If someone's tool takes 20 required arguments they should be punished by having unreadable automatically generated error messages.)

* Error line is formatted as "error: ..." and not "argv[0]: error: ..." which is pretty standard and very useful if you call your program from within a shell script and it dumps an error.

* Usage line isn't printed first, or last, but randomly in the middle (It should be first).

* But it gets worse:

Example:

$ clap-brightness /path a10
error: invalid value 'a10' for '<ADJUSTMENT>': invalid float literal

For more information, try '--help'.

* Usage disappeared entirely? Why?

* And then:

Example:

$ clap-brightness /path -a
error: unexpected argument '-a' found

tip: to pass '-a' as a value, use '-- -a'

Usage: clap-brightness [OPTIONS] <BACKLIGHT> <ADJUSTMENT>

For more information, try '--help'.

* Back to the full usage statement again, but now aside from suggestions to refer to --help, I also get taught how to use --.

From what I can tell, a lot of these things can be cleaned up and changed. But figuring out how to do that and actually doing it seemed like more work than just picking a different option parser.

And yes, a lot of this is nitpicking, but I spend a lot of time in a terminal, I have certain expectations of how things should look and behave, and a lot of these issues are just plain deal breakers.