CLIENT-SPECIFICATION, style-guide: add longform/shortform specifications (#15253)

Co-authored-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
Co-authored-by: Lena <126529524+acuteenvy@users.noreply.github.com>
Co-authored-by: Niklas Mohrin <dev@niklasmohrin.de>

CLIENT-SPECIFICATION.md

@@ -1,7 +1,7 @@
 <!-- markdownlint-disable MD007 MD013 MD024-->
 # tldr-pages client specification
 
-**Current Specification Version:** 2.2
+**Current Specification Version:** Unreleased
 
 This document contains the official specification for tldr-pages clients. It is _not_ a specification of the format of the pages themselves - only a specification of how a user should be able to interface with an official client. For a list of previous versions of the specification, see the [changelog section](#changelog) below.
 
@@ -30,17 +30,19 @@ This section describes the standardised command-line interface (CLI) for clients
 
 ### Arguments
 
-The following command-line options MUST be supported (unless otherwise specified) if a CLI is implemented:
+The following table documents what command-line options MUST be supported and which are optional. If an option is implemented both the short and long versions MUST be available:
 
-Option             | Required?   | Meaning
--------------------|-------------|----------
-`-v`, `--version`  | Yes         | Shows the current version of the client, and the version of this specification that it implements.
-`-p`, `--platform` | Yes         | Specifies the platform to be used to perform the action (either listing or searching) as an argument. If this option is specified, the selected platform MUST be checked first instead of the current platform as described below.
-`-u`, `--update`   | Conditional | Updates the offline cache of pages. MUST be implemented if caching is supported.
-`-l`, `--list`     | No          | Lists all the pages in the current platform to the standard output.
-`-L`, `--language` | No          | Specifies the preferred language for the page returned. Overrides other language detection mechanisms. See the [language section](#language) for more information.
+Option                 | Required?   | Meaning
+-----------------------|-------------|----------
+`-v`, `--version`      | Yes         | Shows the current version of the client, and the version of this specification that it implements.
+`-p`, `--platform`     | Yes         | Specifies the platform to be used to perform the action (either listing or searching) as an argument. If this option is specified, the selected platform MUST be checked first instead of the current platform as described below.
+`-u`, `--update`       | Conditional | Updates the offline cache of pages. MUST be implemented if caching is supported.
+`-l`, `--list`         | No          | Lists all the pages in the current platform to the standard output.
+`-L`, `--language`     | No          | Specifies the preferred language for the page returned. Overrides other language detection mechanisms. See the [language section](#language) for more information.
+`-S`, `--short-options`| No          | If set, will filter examples to show their shortform option when available
+`-E`, `--long-options` | No          | If set, will filter examples to show their longform option when available
 
-Clients MUST implement both the short and long versions of an option.
+By default clients SHOULD display only the longform option when neither `--short-options` or `--long-options` is set by the user. If both are provided, both options should be displayed (see the [Page Structure / Examples](#examples) section for the output format).
 
 Additional decoration MAY be printed if the standard output is a [TTY](https://linusakesson.net/programming/tty/index.php). If not, then the output MUST not contain any additional decorations. For example, a page list MUST be formatted with one page name per line (to enable easy manipulation using standard CLI tools such as `grep` etc.).
 
@@ -113,7 +115,17 @@ The structure inside these translation folders is identical to that of the main
 
 ## Page structure
 
-Although this specification is about the interface that clients must provide, it is also worth noting that pages are written in standard [CommonMark](https://commonmark.org/), with the exception of the non-standard `{{` and `}}` placeholder syntax, which surrounds values in an example that users may edit. Clients MAY highlight the placeholders and MUST remove the surrounding curly braces. Clients MUST NOT treat them as the placeholder syntax if they are escaped using `\` (i.e. `\{\{` and `\}\}`) and MUST instead display literal braces, without backslashes. Placeholder escaping applies only when both braces are escaped (e.g. in `\{` or `\{{`, backslashes MUST be displayed). In cases when a command uses `{}` in its arguments (e.g. `stash@{0}`) **_the outer braces_** mark the placeholder - the braces inside MUST be displayed. Clients MUST NOT break if the page format is changed within the _CommonMark_ specification.
+Although this specification is about the interface that clients must provide, it is also worth noting that pages are written in standard [CommonMark](https://commonmark.org/), with the exceptions:
+- Non-standard `{{`, `}}`, `{{[` and `]}}` placeholder syntax.
+  - `{{` and `}}` surrounds values in an example that indicates editable values.
+  - `{{[` and `]}}` indicate shortform and longform variants of options which are separated by a single `|`. Shortform on the left, longform on the right.
+
+Things to take into account:
+- Clients MAY highlight the placeholders and MUST remove the surrounding curly braces.
+- Clients MUST remove the angle brackets from option placeholders when only short- or longform is shown. 
+- Clients MUST NOT treat them as the placeholder syntax if they are escaped using `\` (i.e. `\{\{` and `\}\}`) and MUST instead display literal braces, without backslashes. Placeholder escaping applies only when both braces are escaped (e.g. in `\{` or `\{{`, backslashes MUST be displayed).
+- In cases when a command uses `{}` in its arguments (e.g. `stash@{0}`) **_the outer braces_** mark the placeholder - the braces inside MUST be displayed.
+- Clients MUST NOT break if the page format is changed within the _CommonMark_ specification.
 
 ### Examples
 
@@ -121,6 +133,7 @@ Although this specification is about the interface that clients must provide, it
 - `docker inspect --format '\{\{range.NetworkSettings.Networks\}\}\{\{.IPAddress\}\}\{\{end\}\}' {{container}}` MUST be rendered as "docker inspect --format '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' container"
 - `mount \\{{computer_name}}\{{share_name}} Z:` MUST be rendered as "mount \\\\computer_name\share_name Z:"
 - `git stash show --patch {{stash@{0}}}` MUST be rendered as "git stash show --patch stash@{0}"
+- `git add {{[-A|--all]}}` MUST be rendered as "git add -A" or "git add --all" when only short or longform is shown. It MUST be rendered as "git add [-A|--all]" when both are requested.
 
 ## Page resolution
 
@@ -236,6 +249,9 @@ the form `vX.Y`) should be done immediately AFTER merging the version bump, as
 the commit hash changes when merging with squash or rebase.
 -->
 
+- Unreleased
+  - Added longform/shortform specifications ([#15253](https://github.com/tldr-pages/tldr/pull/15253))
+
 - [v2.2, March 20th 2024](https://github.com/tldr-pages/tldr/blob/v2.2/CLIENT-SPECIFICATION.md) ([#12452](https://github.com/tldr-pages/tldr/pull/12452))
   - Removed redirect text from the [caching section](#caching) ([#12133](https://github.com/tldr-pages/tldr/pull/12133))
   - Updated asset URLs to use GitHub releases ([#12158](https://github.com/tldr-pages/tldr/pull/12158))

contributing-guides/style-guide.md

@@ -412,7 +412,7 @@ For example, `[d]ownload` in English may be translated into `[d]escargar` in Spa
 ### Option syntax
 
 - For commonly/frequently used commands (e.g. `grep`, `tar`, `etc`), we prefer using short options along with [mnemonics](#short-option-mnemonics) or both inside a placeholder.
-- For highlighting both long and short options in commands (instead of using mnemonics), combine them within a placeholder i.e. `{{-o|--output}}`.
+- For letting the client decide whether to show long or short options in commands, use an option placeholder i.e. `{{[-o|--output]}}`.
 - For user-friendliness, use **GNU-style long options** (like `--help` rather than `-h`) when they are cross-platform compatible (intended to work the same across multiple platforms) for pages in the `common` directory.
 - Prefer using a space instead of the equals sign (`=`) to separate options from their arguments (i.e. use `--opt arg` instead of `--opt=arg`), unless the program does not support it.
 - Likewise prefer separating shortform options from their arguments with a space (i.e. use `-o arg` instead of `-oarg`), unless the program does not support it.