Skip to content

Commit 862f4c9

Browse files
kbdharunacuteenvysbrlsebastiaanspeck
authored
CLIENT-SPECIFICATION: add automatic platform detection suggestion, fix Markdown syntax (#11523)
* CLIENT-SPECIFICATION: add platform suggestion Signed-off-by: K.B.Dharun Krishna <[email protected]> * CLIENT-SPECIFICATION: minor fixes Co-authored-by: Lena <[email protected]> * CLIENT-SPECIFICATION: fix typo * CLIENT-SPECIFICATION: minor fixes Co-authored-by: Lena <[email protected]> * CLIENT-SPECIFICATION: remove usage suggestion * CLIENT-SPECIFICATION: update page Co-authored-by: Starbeamrainbowlabs <[email protected]> * CLIENT-SPECIFICATION: minor fixes Co-authored-by: Starbeamrainbowlabs <[email protected]> * Update CLIENT-SPECIFICATION.md Co-authored-by: Sebastiaan Speck <[email protected]> * CLIENT-SPECIFICATION: update changelog Signed-off-by: K.B.Dharun Krishna <[email protected]> * CLIENT-SPECIFICATION: fix description in changelog Co-authored-by: Lena <[email protected]> --------- Signed-off-by: K.B.Dharun Krishna <[email protected]> Co-authored-by: Lena <[email protected]> Co-authored-by: Starbeamrainbowlabs <[email protected]> Co-authored-by: Sebastiaan Speck <[email protected]>
1 parent 1e1cc4d commit 862f4c9

File tree

1 file changed

+64
-61
lines changed

1 file changed

+64
-61
lines changed

‎CLIENT-SPECIFICATION.md

+64-61
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,11 @@
11
# tldr-pages client specification
22

3-
**Current Specification Version:** 2.0
3+
**Current Specification Version:** 2.1
44

5-
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.
5+
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.
66

77
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
88

9-
109
## Terminology
1110

1211
This section defines key terms that are relevant for understanding this specification document.
@@ -24,7 +23,6 @@ If a page is common across multiple platforms, but slightly different on a given
2423

2524
For example, if the command `foo` is common to `mac`, `windows`, and `linux` but functions differently on `windows`, then the main page will be stored in `common`, and a copy will be placed in `windows` that's altered to match the different functionality.
2625

27-
2826
## Command-line interface
2927

3028
This section describes the standardised command-line interface (CLI) for clients implementing one. Clients that do not provide a CLI can ignore this section.
@@ -78,12 +76,12 @@ This section documents the directory structure that contains the pages themselve
7876

7977
The main version of every page is stored inside (but not directly) the `pages` directory. Inside this directory, there is a folder for each platform - for example `windows`, `linux`, and the special `common` platform:
8078

81-
- `pages/`
82-
- `common/`
83-
- `linux/`
84-
- `windows/`
85-
- `osx/`
86-
- ...etc.
79+
- `pages/`
80+
- `common/`
81+
- `linux/`
82+
- `windows/`
83+
- `osx/`
84+
- ...etc.
8785

8886
It is RECOMMENDED that clients support `macos` as an alias for `osx`.
8987

@@ -97,23 +95,21 @@ Command name | Mapped name | Filename
9795
`git checkout` | `git-checkout` | `git-checkout.md`
9896
`tar` | `tar` | `tar.md`
9997

100-
10198
### Translations
10299

103100
Other directories sit alongside the main `pages` directory, and contain translations of the main versions of every page - though pages MAY NOT have a translation available for a given language yet. Furthermore, a given language MAY NOT have a folder yet either. The format of these directories is `pages.<locale>`, where `<locale>` is a [POSIX Locale Name](https://www.gnu.org/software/gettext/manual/html_node/Locale-Names.html#Locale-Names) in the form of `<language>_<country>`, where:
104101

105-
- `<language>` is the shortest [ISO 639](https://en.wikipedia.org/wiki/ISO_639) language code for the chosen language (see [here](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) for a complete list).
106-
- `<country>` is the two-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code for the chosen region (see [here](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) for a complete list).
102+
- `<language>` is the shortest [ISO 639](https://en.wikipedia.org/wiki/ISO_639) language code for the chosen language (see [here](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) for a complete list).
103+
- `<country>` is the two-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code for the chosen region (see [here](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) for a complete list).
107104

108105
Some examples:
109106

110-
- Chinese (Taiwan): `pages.zh_TW`.
111-
- Portuguese (Brazil): `pages.pt_BR`.
112-
- Italian: `pages.it`.
107+
- Chinese (Taiwan): `pages.zh_TW`.
108+
- Portuguese (Brazil): `pages.pt_BR`.
109+
- Italian: `pages.it`.
113110

114111
The structure inside these translation folders is identical to that of the main `pages` folder.
115112

116-
117113
## Page structure
118114

119115
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). Clients MUST NOT break if the page format is changed within the _CommonMark_ specification.
@@ -122,21 +118,21 @@ Although this specification is about the interface that clients must provide, it
122118

123119
- `ping {{example.com}}` MUST be rendered as "ping example.com"
124120
- `docker inspect --format '\{\{range.NetworkSettings.Networks\}\}\{\{.IPAddress\}\}\{\{end\}\}' {{container}}` MUST be rendered as "docker inspect --format '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' container"
125-
- `mount \\{{computer_name}}\{{share_name}} Z:` MUST be rendered as "mount \\computer_name\share_name Z:"
126-
121+
- `mount \\{{computer_name}}\{{share_name}} Z:` MUST be rendered as "mount \\\\computer_name\share_name Z:"
127122

128123
## Page resolution
129124

130125
This section defines the algorithm by which a client can decide which page a user has requested.
131126

132127
After transparently replacing spaces (` `) with dashes (`-`) and lowercasing the name, clients have several decisions to make:
133128

134-
- The language of a page to display to a client
135-
- The platform to display a page from
129+
- The language of a page to display to a client
130+
- The platform to display a page from
136131

137132
### Platform
138133

139134
Clients MUST default to displaying the page associated with the platform on which the client is running.
135+
140136
For example, a client running on _Windows 11_ will default to displaying pages from the `windows` platform.
141137
Clients MAY provide a user-configurable option to override this behaviour, however.
142138

@@ -155,6 +151,8 @@ Steps #3 and #4 may be done in either order.
155151

156152
It is possible that due to this page resolution logic, the client may show a page which does not belong to the host platform because a page can reside in `common`, and not be present on the host platform. Clients must not assume that a given command is always executable on the host platform.
157153

154+
It is RECOMMENDED that clients detect new platforms added to the relevant `pages` directory automatically.
155+
158156
#### If a page is not found
159157

160158
If a page cannot be found in _any_ platform, then it is RECOMMENDED that clients display an error message with a link to create a new issue against the `tldr-pages/tldr` GitHub repository. Said link might take the following form:
@@ -169,7 +167,6 @@ where `{command_name}` is the name of the command that was not found. Clients th
169167

170168
If multiple versions of a page were found for different platforms, then a client MAY choose to display a notice to the user notifying them of this.
171169

172-
173170
## Language
174171

175172
Pages can be written in multiple languages. If a client has access to environment variables, it MUST use them to derive the preferred user language as described in the next paragraphs. If not, then clients MUST make reasonable assumptions based on the information provided by the environment in which they operate (e.g. consulting `navigator.languages` in a browser, etc.).
@@ -205,20 +202,21 @@ The [`LC_MESSAGES` environment variable](https://www.gnu.org/software/gettext/ma
205202
206203
Here's an example of how the lookup should be done on `linux` having set `LANG=it` and `LANGUAGE="it:fr:en"`:
207204

208-
1. pages.it/linux/some-page.md -> does not exist
209-
2. pages.fr/linux/some-page.md -> does not exist
210-
3. pages/linux/some-page.md -> does not exist
211-
4. pages.it/common/some-page.md -> does not exist
212-
5. pages.fr/common/some-page.md -> does not exist
213-
6. pages/common/some-page.md -> FOUND!
205+
Step | Path checked | Outcome
206+
------|--------------------------------|-----------------------
207+
1 | pages.it/linux/some-page.md | does not exist
208+
2 | pages.fr/linux/some-page.md | does not exist
209+
3 | pages/linux/some-page.md | does not exist
210+
4 | pages.it/common/some-page.md | does not exist
211+
5 | pages.fr/common/some-page.md | does not exist
212+
6 | pages/common/some-page.md | FOUND!
214213

215214
## Caching
216215

217216
If appropriate, it is RECOMMENDED that clients implement a cache of pages. If implemented, clients MUST download the entire archive either as a whole from **[https://tldr.sh/assets/tldr.zip](https://tldr.sh/assets/tldr.zip)** (Which redirects to [https://raw.githubusercontent.com/tldr-pages/tldr-pages.github.io/main/assets/tldr.zip](https://raw.githubusercontent.com/tldr-pages/tldr-pages.github.io/main/assets/tldr.zip)) or download language-specific translation archives in the format `https://tldr.sh/assets/tldr-pages.{{language-code}}.zip` (Which redirects to [https://raw.githubusercontent.com/tldr-pages/tldr-pages.github.io/main/assets/tldr-pages.{{language-code}}.zip](https://raw.githubusercontent.com/tldr-pages/tldr-pages.github.io/main/assets)), along with the archive for English from **[https://tldr.sh/assets/tldr-pages.zip](https://tldr.sh/assets/tldr-pages.zip)** (It redirects to [https://raw.githubusercontent.com/tldr-pages/tldr-pages.github.io/main/assets/tldr-pages.zip](https://raw.githubusercontent.com/tldr-pages/tldr-pages.github.io/main/assets/tldr-pages.zip)).
218217

219218
Caching SHOULD be done according to the user's language configuration (if any), to not waste unneeded space for unused languages. Additionally, clients MAY automatically update the cache regularly.
220219

221-
222220
## Changelog
223221

224222
<!--
@@ -232,35 +230,40 @@ including the changes. NOTE: tagging of the commit with a new version tag (in
232230
the form `vX.Y`) should be done immediately AFTER merging the version bump, as
233231
the commit hash changes when merging with squash or rebase.
234232
-->
235-
- Unreleased
236-
237-
- [v2.0, September 10th 2023](https://github.com/tldr-pages/tldr/blob/v2.0/CLIENT-SPECIFICATION.md) ([#10148](https://github.com/tldr-pages/tldr/pull/10148))
238-
- Add recommendation to support `macos` alias for `osx` ([#7514](https://github.com/tldr-pages/tldr/pull/7514))
239-
- Drop the special "all" platform from the `--list` flag ([#7561](https://github.com/tldr-pages/tldr/pull/7561))
240-
- Drop the `master` branch from the assets link. ([#9668](https://github.com/tldr-pages/tldr/pull/9668))
241-
- Require support for long options ([#9651](https://github.com/tldr-pages/tldr/pull/9651))
242-
- Add recommendation to support caching individual translation archives ([#10148](https://github.com/tldr-pages/tldr/pull/10148))
243-
244-
- [v1.5, March 17th 2021](https://github.com/tldr-pages/tldr/blob/v1.5/CLIENT-SPECIFICATION.md) ([#5428](https://github.com/tldr-pages/tldr/pull/5428))
245-
- Add requirement for converting command names to lowercase before running the page resolution algorithm.
246-
- Use HTTPS for archive links.
247-
248-
- [v1.4, August 13th 2020](https://github.com/tldr-pages/tldr/blob/v1.4/CLIENT-SPECIFICATION.md) ([#4246](https://github.com/tldr-pages/tldr/pull/4246))
249-
- Add requirement for CLI clients to use non-zero exit code on failing to find a page.
250-
251-
- [v1.3, June 11th 2020](https://github.com/tldr-pages/tldr/blob/v1.3/CLIENT-SPECIFICATION.md) ([#4101](https://github.com/tldr-pages/tldr/pull/4101))
252-
- Clarified fallback to English in the language resolution algorithm.
253-
- Update the `LANG` and `LANGUAGE` environment variables to conform to the GNU spec.
254-
255-
- [v1.2, July 3rd 2019](https://github.com/tldr-pages/tldr/blob/v1.2/CLIENT-SPECIFICATION.md) ([#3168](https://github.com/tldr-pages/tldr/pull/3168))
256-
- Addition of a new `-L, --language` recommended command-line option.
257-
- Rewording of the language section, also encouraging the use of configuration files for language.
258-
- Shift from BCP-47 to POSIX style locale tags, with consequent **deprecation of previous versions of the spec**.
259-
- Clearer clarification about the recommended caching functionality.
260-
- Correction of the usage of the term "arguments" in the homonym section.
261-
262-
- [v1.1, April 1st 2019](https://github.com/tldr-pages/tldr/blob/v1.1/CLIENT-SPECIFICATION.md) (deprecated) ([#2859](https://github.com/tldr-pages/tldr/pull/2859))
263-
- Clarified platform section.
264-
265-
- [v1.0, January 23rd 2019](https://github.com/tldr-pages/tldr/blob/v1.0/CLIENT-SPECIFICATION.md) (deprecated) ([#2706](https://github.com/tldr-pages/tldr/pull/2706))
266-
- Initial release.
233+
234+
- Unreleased
235+
236+
- [v2.1, November 30th 2023](https://github.com/tldr-pages/tldr/blob/v2.1/CLIENT-SPECIFICATION.md) ([#11523](https://github.com/tldr-pages/tldr/pull/11523))
237+
- Add requirement to support escaping the placeholder syntax in certain pages ([#10730](https://github.com/tldr-pages/tldr/pull/10730))
238+
- Add suggestion to detect new platforms added to the relevant `pages` directory automatically ([#11523](https://github.com/tldr-pages/tldr/pull/11523))
239+
240+
- [v2.0, September 10th 2023](https://github.com/tldr-pages/tldr/blob/v2.0/CLIENT-SPECIFICATION.md) ([#10148](https://github.com/tldr-pages/tldr/pull/10148))
241+
- Add recommendation to support `macos` alias for `osx` ([#7514](https://github.com/tldr-pages/tldr/pull/7514))
242+
- Drop the special "all" platform from the `--list` flag ([#7561](https://github.com/tldr-pages/tldr/pull/7561))
243+
- Drop the `master` branch from the assets link. ([#9668](https://github.com/tldr-pages/tldr/pull/9668))
244+
- Require support for long options ([#9651](https://github.com/tldr-pages/tldr/pull/9651))
245+
- Add recommendation to support caching individual translation archives ([#10148](https://github.com/tldr-pages/tldr/pull/10148))
246+
247+
- [v1.5, March 17th 2021](https://github.com/tldr-pages/tldr/blob/v1.5/CLIENT-SPECIFICATION.md) ([#5428](https://github.com/tldr-pages/tldr/pull/5428))
248+
- Add requirement for converting command names to lowercase before running the page resolution algorithm.
249+
- Use HTTPS for archive links.
250+
251+
- [v1.4, August 13th 2020](https://github.com/tldr-pages/tldr/blob/v1.4/CLIENT-SPECIFICATION.md) ([#4246](https://github.com/tldr-pages/tldr/pull/4246))
252+
- Add requirement for CLI clients to use non-zero exit code on failing to find a page.
253+
254+
- [v1.3, June 11th 2020](https://github.com/tldr-pages/tldr/blob/v1.3/CLIENT-SPECIFICATION.md) ([#4101](https://github.com/tldr-pages/tldr/pull/4101))
255+
- Clarified fallback to English in the language resolution algorithm.
256+
- Update the `LANG` and `LANGUAGE` environment variables to conform to the GNU spec.
257+
258+
- [v1.2, July 3rd 2019](https://github.com/tldr-pages/tldr/blob/v1.2/CLIENT-SPECIFICATION.md) ([#3168](https://github.com/tldr-pages/tldr/pull/3168))
259+
- Addition of a new `-L, --language` recommended command-line option.
260+
- Rewording of the language section, also encouraging the use of configuration files for language.
261+
- Shift from BCP-47 to POSIX style locale tags, with consequent **deprecation of previous versions of the spec**.
262+
- Clearer clarification about the recommended caching functionality.
263+
- Correction of the usage of the term "arguments" in the homonym section.
264+
265+
- [v1.1, April 1st 2019](https://github.com/tldr-pages/tldr/blob/v1.1/CLIENT-SPECIFICATION.md) (deprecated) ([#2859](https://github.com/tldr-pages/tldr/pull/2859))
266+
- Clarified platform section.
267+
268+
- [v1.0, January 23rd 2019](https://github.com/tldr-pages/tldr/blob/v1.0/CLIENT-SPECIFICATION.md) (deprecated) ([#2706](https://github.com/tldr-pages/tldr/pull/2706))
269+
- Initial release.

0 commit comments

Comments
 (0)