ctome
/
tldr
mirror of https://github.com/CrimsonTome/tldr.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

CLIENT-SPECIFICATION: add automatic platform detection suggestion, fix Markdown syntax (#11523) 

* CLIENT-SPECIFICATION: add platform suggestion

Signed-off-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>

* CLIENT-SPECIFICATION: minor fixes

Co-authored-by: Lena <126529524+acuteenvy@users.noreply.github.com>

* CLIENT-SPECIFICATION: fix typo

* CLIENT-SPECIFICATION: minor fixes

Co-authored-by: Lena <126529524+acuteenvy@users.noreply.github.com>

* CLIENT-SPECIFICATION: remove usage suggestion

* CLIENT-SPECIFICATION: update page

Co-authored-by: Starbeamrainbowlabs <sbrl@starbeamrainbowlabs.com>

* CLIENT-SPECIFICATION: minor fixes

Co-authored-by: Starbeamrainbowlabs <sbrl@starbeamrainbowlabs.com>

* Update CLIENT-SPECIFICATION.md

Co-authored-by: Sebastiaan Speck <12570668+sebastiaanspeck@users.noreply.github.com>

* CLIENT-SPECIFICATION: update changelog

Signed-off-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>

* CLIENT-SPECIFICATION: fix description in changelog

Co-authored-by: Lena <126529524+acuteenvy@users.noreply.github.com>

---------

Signed-off-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
Co-authored-by: Lena <126529524+acuteenvy@users.noreply.github.com>
Co-authored-by: Starbeamrainbowlabs <sbrl@starbeamrainbowlabs.com>
Co-authored-by: Sebastiaan Speck <12570668+sebastiaanspeck@users.noreply.github.com>
pull/23/head
K.B.Dharun Krishna 2023-11-30 23:31:27 +05:30 committed by GitHub
parent 1e1cc4df3b
commit 862f4c9fa0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 57 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
CLIENT-SPECIFICATION.md
View File

@ -1,12 +1,11 @@
# tldr-pages client specification # tldr-pages client specification
**Current Specification Version:** 2.0 **Current Specification Version:** 2.1
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. 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.
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). 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).
## Terminology ## Terminology
This section defines key terms that are relevant for understanding this specification document. 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
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. 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.
## Command-line interface ## Command-line interface
This section describes the standardised command-line interface (CLI) for clients implementing one. Clients that do not provide a CLI can ignore this section. This section describes the standardised command-line interface (CLI) for clients implementing one. Clients that do not provide a CLI can ignore this section.
@ -97,7 +95,6 @@ Command name | Mapped name | Filename
`git checkout` | `git-checkout` | `git-checkout.md` `git checkout` | `git-checkout` | `git-checkout.md`
`tar` | `tar` | `tar.md` `tar` | `tar` | `tar.md`
### Translations ### Translations
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: 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:
@ -113,7 +110,6 @@ Some examples:
The structure inside these translation folders is identical to that of the main `pages` folder. The structure inside these translation folders is identical to that of the main `pages` folder.
## Page structure ## 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). 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 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,8 +118,7 @@ Although this specification is about the interface that clients must provide, it
- `ping {{example.com}}` MUST be rendered as "ping example.com" - `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" - `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:" - `mount \\{{computer_name}}\{{share_name}} Z:` MUST be rendered as "mount \\\\computer_name\share_name Z:"
## Page resolution ## Page resolution
@ -137,6 +132,7 @@ After transparently replacing spaces (` `) with dashes (`-`) and lowercasing the
### Platform ### Platform
Clients MUST default to displaying the page associated with the platform on which the client is running. Clients MUST default to displaying the page associated with the platform on which the client is running.
For example, a client running on _Windows 11_ will default to displaying pages from the `windows` platform. For example, a client running on _Windows 11_ will default to displaying pages from the `windows` platform.
Clients MAY provide a user-configurable option to override this behaviour, however. Clients MAY provide a user-configurable option to override this behaviour, however.
@ -155,6 +151,8 @@ Steps #3 and #4 may be done in either order.
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. 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.
It is RECOMMENDED that clients detect new platforms added to the relevant `pages` directory automatically.
#### If a page is not found #### If a page is not found
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: 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
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. 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.
## Language ## Language
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.). 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,12 +202,14 @@ The [`LC_MESSAGES` environment variable](https://www.gnu.org/software/gettext/ma
Here's an example of how the lookup should be done on `linux` having set `LANG=it` and `LANGUAGE="it:fr:en"`: Here's an example of how the lookup should be done on `linux` having set `LANG=it` and `LANGUAGE="it:fr:en"`:
1. pages.it/linux/some-page.md -> does not exist Step | Path checked | Outcome
2. pages.fr/linux/some-page.md -> does not exist ------|--------------------------------|-----------------------
3. pages/linux/some-page.md -> does not exist 1 | pages.it/linux/some-page.md | does not exist
4. pages.it/common/some-page.md -> does not exist 2 | pages.fr/linux/some-page.md | does not exist
5. pages.fr/common/some-page.md -> does not exist 3 | pages/linux/some-page.md | does not exist
6. pages/common/some-page.md -> FOUND! 4 | pages.it/common/some-page.md | does not exist
5 | pages.fr/common/some-page.md | does not exist
6 | pages/common/some-page.md | FOUND!
## Caching ## Caching
@ -218,7 +217,6 @@ If appropriate, it is RECOMMENDED that clients implement a cache of pages. If im
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. 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.
## Changelog ## Changelog
<!-- <!--
@ -232,8 +230,13 @@ including the changes. NOTE: tagging of the commit with a new version tag (in
the form `vX.Y`) should be done immediately AFTER merging the version bump, as the form `vX.Y`) should be done immediately AFTER merging the version bump, as
the commit hash changes when merging with squash or rebase. the commit hash changes when merging with squash or rebase.
--> -->
- Unreleased - Unreleased
- [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))
- Add requirement to support escaping the placeholder syntax in certain pages ([#10730](https://github.com/tldr-pages/tldr/pull/10730))
- Add suggestion to detect new platforms added to the relevant `pages` directory automatically ([#11523](https://github.com/tldr-pages/tldr/pull/11523))
- [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)) - [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))
- Add recommendation to support `macos` alias for `osx` ([#7514](https://github.com/tldr-pages/tldr/pull/7514)) - Add recommendation to support `macos` alias for `osx` ([#7514](https://github.com/tldr-pages/tldr/pull/7514))
- Drop the special "all" platform from the `--list` flag ([#7561](https://github.com/tldr-pages/tldr/pull/7561)) - Drop the special "all" platform from the `--list` flag ([#7561](https://github.com/tldr-pages/tldr/pull/7561))