[args] Allow customising options help angle brackets (or change them to double quotes)

[incendial]

Hi,

When passing the valueHelp argument to an option, the printed value is wrapped into angle brackets (< and >), for example:

Usage: dcm check-dependencies [arguments] <directories>
-h, --help                                         Print this usage information.

    --ignored-packages=<my-package,other,...>      Package names that should be ignored.

What I've noticed is that users think these brackets are part of the syntax and try to add them. But this syntax is invalid (at least in the shells I/users have tried it in). Also I'm not aware if that's some common syntax.

It would be great to have double quotes instead as they are actually valid syntax, for example:

Usage: dcm check-dependencies [arguments] <directories>
-h, --help                                         Print this usage information.

    --ignored-packages="my-package,other,..."      Package names that should be ignored.

or at least a way to configure the used character.

[jakemac53]

This is afaik pretty standard syntax (see the git usage text for example https://git-scm.com/docs/git)

[lrhn]

I would personally be more likely to include the "s than the </>s.
(And I wouldn't assume that all platforms treat " as a quote that is removed before the content is passed to the program.)

[incendial]

This is afaik pretty standard syntax (see the git usage text for example https://git-scm.com/docs/git)

Sure, the problem is that there is no good way to communicate to the user that adding <> is not needed - the execution fails on the shell level.

[incendial]

I would personally be more likely to include the "s than the </>s.

Including " is correct when there are multiple comma-separated options (as adding , will also be an error), for example.

[incendial]

And to be on the same page: I'd not add <> as well, but not everyone has good experience with CLIs and sometime people say that they saw and though that this is how it supposed to be passed (because help shows it so).

[jakemac53]

I don't think that diverging from the standard is a net benefit? I can see an argument that " would have been a better standard, but I am not a fan of inventing new standards just because I don't like something about the current one. Unless there is a serious issue, I think it is better to just follow standard practice.

[incendial]

I don't like something about the current one

I think it's an unfair statement which downplays the fact that the help output is simply not helping to use the option correctly. In other words it's a UX issue.

dcm d lib --ignored-packages=<hi>
zsh: parse error near `\n'

Does this look like a meaningful output?

Though I agree with @lrhn's point about ", so please feel free to close this if it's a won't fix (though I'd prefer this to be configurable).

[jakemac53]

I think it's an unfair statement which downplays the fact that the help output is simply not helping to use the option correctly. In other words it's a UX issue.

I am not trying to downplay or even make any statement about what is actually better, just to be clear. What I am saying is that even if we assume the premise of " being more intuitive/better, I still think everybody is ultimately better served by us just following what the most popular CLIs in the ecosystem do. Specifically:

• For users new to CLIs: they get exposure to the standard so they can parse it later on. They almost certainly will be exposed to the git CLI and want to run its --help command.
• For users with experience with CLIs: they will immediately understand our usage text.

Regarding the configuration option, I mostly just worry about configuration creep here, but I also worry about divergence in the experience of Dart command line tools. I would want to hear the opinions of more contributors before just closing the issue though.

[jakemac53]

Also my opinion is based on the premise that <a,b,c> is actually the most standard format, if that is not in fact the case, and I haven't spent a lot of time validating it, then I think my argument holds less weight. Although its still good I think for package:args to be a bit opinionated here so there is standardization across dart command line tools.

[lrhn]

I only know of two "standards" for specifying user-input-goes-here in text docs:

• angle-brackets: <file>
• upper-cased: FILE

And there is apparently also underlining, as used by man man itself. Never noticed the underline, but it is actually there.

And for man pages, Linux man 7 man-pages says

boldface is used for as-is text and italics
are used to indicate replaceable arguments.

That doc itself shows as-is text as normal and arguments as underlined when formatted for a TTY. It's what man formatting does to troff bold/italic, so that makes sense.
So underline is apparently the thing.

I think the upper-cased one may be slightly more common in older tools, and angle brackets more common in newer tools. Some use underline as well, others do not, but underline, and colors, are lost the moment you start piping the output to anything other than a TTY.
Not everyone is being completely consistent, even with themselves. The same tool doesn't always agree between tool --help and man tool.

Examples:

• man man: man -k [apropos options] regexp ... and -L locale, --locale=locale
• man --help: man [OPTION...] [SECTION] PAGE... and -L, --locale=LOCALE
• man ls: ls [OPTION]... [FILE].... ls --help is same without underling.
• man grep and grep --help: grep [OPTION...] PATTERNS [FILE...] and -m NUM, --max-count=NUM
• man git diff/git diff --help: git diff [<options>] [<commit>] [--] [<path>...]. (Angle brackets and underline!)
• man meld: meld [options] FILE and --comparison-file=<file>
• meld --help: meld <file|folder> and --comparison-file=COMPARISON_FILE. (Consistently inconsistent!)

DOS behavior isn't helpful, it just uses plain lower-case words, dir /?:

DIR [drive:][path][filename] [/P] [/W] [/A[[:]attribs]] [/O[[:]sortord]]...

If the args package were to do change here, it would definitely not be using "s.

Converting to UPPER_SNAKE_CASE is an option, but then the user could just write that to begin with.
Having just one choice is better for consistency.
It should be the choice that is most consistent with other command line tools. Which aren't consistent at all.
I'm not sure there is a better choice than angle brackets.

Maybe add underlines if the output terminal supports ANSI?

(Or maybe <ALL_OF_THE_ABOVE>? 👿)

[incendial]

I'm not sure there is a better choice than angle brackets.

Can you please tell what "better" means in your case? Looks like copy-pasting every other option will not give a syntax error, but <> will (which is the main reason for the issue to begin with).