indicate in help if arguments are optional or repeatable

[koertkuipers]

i do not know if this is of interest to anyone else, but we wanted our users to get more info in the help message. specifically we wanted help to convey is the argument allows empty or is repeatable.

[lefou]

Can you describe how you present the additional information?

[koertkuipers]

Can you describe how you present the additional information?

if something is required it shows up as --x, if its optional it shows up as [--x], if something is repeatable and can be empty it shows up as [--x]*, if something is repeatable but cannot be empty it shows as [--x]+

this makes it easier to understand from help what flags are required, which are optional, which are repeatable, etc.

[lefou]

I think "options" already transport their optional-ity, and having all options in extra brackets makes the list harder to read. Instead, we should denote mandatory argument in the synopsis / usage string. This is also what many linux cli tools do.

[lihaoyi]

Yeah I'm not a fan of putting everything in square brackets. It's not a convention I've seen elsewhere. That begs the question: what is the convention for denoting optional/mandatory flags in a CLI help message? What does everyone else do?

[koertkuipers]

i took the convention of square brackets from linux man pages. e.g.:

NAME
       zip - package and compress (archive) files

SYNOPSIS
       zip [-aABcdDeEfFghjklLmoqrRSTuvVwXyz!@$] [--longoption ...]  [-b path] [-n suffixes] [-t date] [-tt date] [zipfile [file ...]]  [-xi list]

currently ArgSig and TokensReader hold a lot of information that would be useful to any user but that does not show up in --help, like alwaysRepeatable, allowEmpty and default.