[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).

[lrhn]

"Better" means being more readable and understandable to more people.
In this case, I'd consider being closer to similar text that people are familiar with as the guideline.
If people are not used to reading command line usage docs at all, this is not the place to teach them. Doing the same thing as existing comparable tools is the default usability choice.

Being able to copy the example text verbatim onto a command line and not getting an error doesn't feel like an improvement to me.
It's optimistic to assume that using fx " will actually work correctly.

Anyone familiar with command lines will be more likely to recognize that < and > are not meant to be literal since they're well-known redirection operators.
Quotes, on the other hand, are actually part of some command-line syntaxes. (DOS find fx.)

Using no marker, ALL_CAPS or underline will allow copying onto a command line without changing the value. I actually prefer that < and > causes errors if included. (But can potentially overwrite files, which isn't great.)

[incendial]

Being able to copy the example text verbatim onto a command line and not getting an error doesn't feel like an improvement to me.

What's the point of the help example then? Maybe I misunderstand the purpose. Also, do you consider zsh: parse error near \n' as a good actionable error message?

"Better" means being more readable and understandable to more people.

Soooo, there are two groups of people: ones who know the syntax and others who don't. Considering the latter do not understand it and will get an error, changing it to a more newbie-friendly option (e.g., just --option=value) will affect only them, making it more readable and understandable to more people. With that logic, I don't see how keeping angle brackets makes it "better".

Doing the same thing as existing comparable tools is the default usability choice.

Haven't you proved that there are multiple options? " is just an example and not the only available option.

[lrhn]

Haven't you proved that there are multiple options?

There are two other options in common use:

• UPPER_SNAKE_CASE (but usually a single uppercase word like FILE, with no punctuation)
• underline

I've not seen those combined.

The underline only works of the console supports it, meaning that it'll potentially be just nothing if you do prog -- help | more.
Upper-case is harder to automate if the author didn't write the name as such. Not impossible, but it changes what the author wrote, which means it may need an override.
It's easier to provide a flag for removing the angle brackets, and then the author can write whatever they want to see as the name.

So a flag for not writing angle brackets is an option.
So is underlining of the terminal supports it, which it probably should just do.

Adding other options for delimiters doesn't seem like a good idea. That'll be further away from every other program.

Consistency or configurability. Being opinionated or trying to support multiple needs. Design points you can choose between. So far this package has been opinionated on this.