CLIENT-SPECIFICATION: add longform/shortform specifications

[Managor]

See these for more information:
#13556
tldr-pages/tldr-python-client#259

• The page(s) are in the correct platform directories: common, linux, osx, windows, sunos, android, etc.
• The page(s) have at most 8 examples.
• The page description(s) have links to documentation or a homepage.
• The page(s) follow the content guidelines.
• The page(s) follow the style guide.
• The PR title conforms to the recommended templates.
• Version of the command being documented (if known):

[Managor]

For now, I'm looking for feedback before opening for review.

[sebastiaanspeck]

LGTM!

[acuteenvy]

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?

[Managor]

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 -s|--longform plastered everywhere is very newbie friendly.