CLIENT-SPECIFICATION, style-guide: add longform/shortform specifications

CLIENT-SPECIFICATION.md

@@ -1,7 +1,7 @@
 <!-- markdownlint-disable MD007 MD013 MD024-->
 # tldr-pages client specification
 
-**Current Specification Version:** 2.2
+**Current Specification Version:** 2.3
 
 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,7 +30,7 @@ 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
 -------------------|-------------|----------
@@ -39,8 +39,10 @@ Option             | Required?   | Meaning
 `-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.
+`-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
 
-Clients MUST implement both the short and long versions of an option.
+By default clients SHOULD display only the longform option when neither `--shortform` or `--longform` is set by the user. If both are provided, both patterns should be displayed.
 
 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.).
 
@@ -54,6 +56,17 @@ tldr --version
 tldr -l
 ```
 
+### Environment variables
+
+The following environment variables MAY be supported by the client to alter its behavior:
+
+Environment variable | Meaning
+---------------------|----------
+TLDR_PLATFORM        | Specify the platform to be used by tldr
+TLDR_LANGUAGE        | Specify which language to prefer
+TLDR_SHORTFORM       | Specify whether to show shortform options
+TLDR_LONGFORM        | Specify whether to show longform options
+
 ### Page names
 
 The first argument that does not start with a dash (`-`), MUST be considered the page name.
@@ -113,14 +126,26 @@ 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 and MAY remove them when both are shown depending whether it's clear where the the option placeholder starts and ends (for example when underlining placeholders).
+- 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
 
 - `ping {{example.com}}` MUST be rendered as "ping example.com"
 - `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 may be rendered as "git add [-A|--all]" or "git add -A|--all" when both are requested.
+- `rsync {{[-zvhP|--compress --verbose --human-readable --partial --progress]}} {{path/to/source}} {{path/to/destination}}` is an example where it's not clear when the option placeholder ends. Rendering it as "rsync [-zvhP|--compress --verbose --human-readable --partial --progress] path/to/source path/to/destination" can help. Client side formatting like underlines can allow for dropping the angle brackets.
 
 ## Page resolution
 

contributing-guides/style-guide.md

@@ -363,7 +363,7 @@
 Short option mnemonics are optional hints that can be added to help users understand the meaning of these short options. The assigned mnemonics should match with the ones in the command's official documentation (e.g. from `man` or `Get-Help`). For example:
 
 ```md
 - [d]isplay the ins[t]allation [i]D for the current device. Useful for offline license activation:
 
 `slmgr.vbs /dti`
 
@@ -375,11 +375,11 @@
 Note that, in the first example, the `[d]`, `[t]`, and `[i]` characters are enclosed with square brackets to indicate that the `/dti` option of the command is a combination of "display", "installation", and "ID", respectively. 
 Group consecutive mnemonic characters under the same square brackets, for example: `e[xp]i[r]ation` instead of `e[x][p]i[r]ation`.
 
 **Mnemonic characters must be written in a case-sensitive manner**, even when it is placed as the first character of the sentence (i.e. use `[d]isplay` instead of `[D]isplay`).
 This is to avoid conflicts with GNU-style command options which may interpret uppercase options differently than the lowercase ones, such as `-v` for displaying the command's `[v]ersion` number and `-V` to run the command in `[V]erbose` mode.
 
 Option mnemonics may also be used in translations as long as the highlighted word contains similar meanings to the language (commonly English) which the command is written for.
 For example, `[d]ownload` in English may be translated into `[d]escargar` in Spanish, `[i]nstall` in English may be translated to `[i]nstallieren` in German, and `[a]pp` in English may be translated into `[a]plikasi` in Indonesian and Malay.
 
 - Optionally, mnemonics and their enclosed terms can be separated with brackets from the rest of the description (i.e. `([a]ll)`) in translations and specific pages to provide additional context or mention a word not present in the description.
 
@@ -392,7 +392,7 @@
 ### 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.
 
@@ -500,11 +500,11 @@
 - For instances of degree and percentage, use `50°C` and `50%` rather than `50 °C` and `50 %`.
 
 3. No additional spaces before/after full-width punctuations.
 
 - For example, use `开启 shell，进入交互模式` rather than `开启 shell ，进入交互模式`
 
 4. Use full-width punctuations except for long Latin clauses.
 
 - For example, use `嗨，你好。` rather than `嗨, 你好.`
 
 5. Use half-width punctuation to end a sentence when the last character is half-width.
@@ -564,7 +564,7 @@
 | Initialize, Reinitialize | Inisialisasikan, Inisialisasikan Ulang | The word [`inisialisasi`](https://kbbi.kemdikbud.go.id/entri/inisialisasi) is officially considered as noun. Requires a `-kan` suffix to convert into a verb. |
 | Interpreter | Interpreter | Preferred over [`penerjemah`](https://kbbi.kemdikbud.go.id/entri/penerjemah) which is also commonly used to describe `translator`. |
 | Install, Reinstall | Pasang, Pasang Ulang | Preferred over `instal` [which is not considered a standard word](https://kbbi.kemdikbud.go.id/entri/instal). |
 | Load, Reload | Muat, Muat ulang | These words are the same for `boot` and `reboot`. See notes in the bottom section. |
 | Options / Preferences (macOS) / Settings | Pengaturan | Preferred over [`opsi`](https://kbbi.kemdikbud.go.id/entri/opsi). |
 | Server | Server | Preferred over [`peladen`](https://kbbi.kemdikbud.go.id/entri/peladen) or [`pelayan`](https://kbbi.kemdikbud.go.id/entri/pelayan), which are less common when used in computing contexts. |
 | Service | Layanan | The Indonesian standard word is acceptable here. |
@@ -585,7 +585,7 @@
 Add detailed contexts to remove ambiguity (notice the highlighted word):
 
 > Muat konfigurasi dari file yang ditentukan setelah **pengguna** memuat ulang **sistem operasi**
 
 Similarly, for the word `start` / `mulai`
 
 > Mulai proses server web