CLIENT-SPECIFICATION, style-guide: add longform/shortform specifications #15253
Conversation
Managor
requested review from
sbrl,
kbdharun and
sebastiaanspeck
as code owners
github-actions
bot
added
the
documentation
|
For now, I'm looking for feedback before opening for review. |
There was a problem hiding this comment.
The current syntax (i.e. {{-s|--long}}) doesn't work for programs that don't follow this convention for options (e.g. nuclei - example short|long option placeholder: {{-l|-list}}, and now there's no way for a client to distinguish this from an ordinary choice placeholder). If we standardize this, it's going to be hard to change it to support different option conventions in the future, hence I'd like to propose an alternative syntax.
#5092 was a proposal to use {[ ... ]} for option selection. That is not backwards compatible, because it uses a single curly brace, which makes it not a placeholder by the current specification.
What if we combine the two (i.e. use {{[-s|--long]}})? Current clients will display [-s|--long] with placeholder styling, which still looks like a choice, and on top of that a short option doesn't need to start with a single hyphen, and a long option doesn't need to start with two hyphens. As long as the square brackets are included, an option can be whatever we want it to be, allowing even for subcommand short forms (e.g. cargo {{[b|build]}}).
What do you think about this?
|
After mulling it over, I've come to accept the idea. There needs to be flexibility to add arbitrary shortform/longform arguments. Do you think it would be good to make the expected default behavior to only show the longform options? It would remove clutter for new users. I don't think having |
|
Is there any way to disable github actions for this pull request?. It's getting in the way of reading what has changed. |
No it can't, but IMO it does not distract from the real changes. |
Managor
changed the title
| `-o`, `--shortform`| No | If set, will filter examples to show their shortform option when available | ||
| `-O`, `--longform` | No | If set, will filter examples to show their longform option when available |
There was a problem hiding this comment.
Before we merge this, I would like to ask everyone for their opinion on these short options, because changing them in all clients later on will be very hard to do. Which ones do you think are better?
@kbdharun @sebastiaanspeck @spageektti
-Sfor short,-Vfor long options (original proposal)-ofor short,-Ofor long options (current)
discussed in CLIENT-SPECIFICATION, style-guide: add longform/shortform specifications #15253 (comment)- maybe something else entirely?
I personally like the original options more.
There was a problem hiding this comment.
+1 for -S for short, -V for long options (original proposal)
There was a problem hiding this comment.
I prefer the first proposition, but why do we use V and not L?
There was a problem hiding this comment.
Because -L is already in use.
There was a problem hiding this comment.
A lot of support for the original proposal. I'll ask the question again based on the suggestion sbrl made:
-Sfor short,-Vfor long options (original proposal)-sfor short,-efor long options (alternative idea) (e for expanded)
@acuteenvy @sebastiaanspeck @spageektti @sbrl
I personally like the alternative idea since it wouldn't involve uppercase characters.
See these for more information:
#13556
tldr-pages/tldr-python-client#259
common,linux,osx,windows,sunos,android, etc.