Skip to content

Commit

Permalink
CLIENT-SPECIFICATION (2.0): document removal of master branch, additi…
Browse files Browse the repository at this point in the history 
…on of support for individual translation archives (#10148)

* CLIENT-SPECIFICATION: bump version to 2.0, fix typos

* client-specification-v2.0: update changelog

* Apply suggestions from code review

Co-authored-by: Waldir Pimenta <[email protected]>

* CLIENT-SPECIFICATION: add back unreleased placeholder

* CLIENT-SPECIFICATION: update Caching section

* CLIENT-SPECIFICATION: prepare for release

---------

Co-authored-by: Waldir Pimenta <[email protected]>
  • Loading branch information
@kbdharun @waldyrious
kbdharun and waldyrious committed Sep 10, 2023
1 parent 99ecf78 commit ebd4b32
Showing 1 changed file with 27 additions and 24 deletions.
51 changes: 27 additions & 24 deletions CLIENT-SPECIFICATION.md
View file
@@ -1,6 +1,6 @@
# tldr-pages client specification

**Current Specification Version:** 1.5
**Current Specification Version:** 2.0

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.

Expand All @@ -9,7 +9,7 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SH

## Terminology

In order to aid the understanding of this specification document, a number of terms will be defined in this section.
This section defines key terms that are relevant for understanding this specification document.

### Page

Expand All @@ -20,7 +20,7 @@ tldr-pages consists of multiple _pages_ - each of which describes a specific com
Pages are grouped by platform, i.e. operating systems — for example, `windows`, `linux`, `osx`.
The special platform `common` contains pages for commands that work identically across more than one platform.

If a page is common across multiple platforms, but slightly different on a given platform, then the page is still stored in `common`, but a copy tailored for the differing platform is placed in that platform's specific folder.
If a page is common across multiple platforms, but slightly different on a given platform, then the page is still stored in the `common` directory, but a copy tailored for the differing platform is placed in that platform's specific folder.

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.

Expand All @@ -31,23 +31,23 @@ This section describes the standardised command-line interface (CLI) for clients

### Arguments

A number of command-line options MUST be supported (unless otherwise specified) if a CLI is implemented:
The following command-line options MUST be supported (unless otherwise specified) if a CLI is implemented:

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 cache is supported.
`-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.

Clients MUST implement both the short and long version of an option.
Clients MUST implement both the short and long versions of an option.

Additional decoration MAY be printed if the standard output is a [TTY](http://www.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 1 page name per line (to enable easy manipulation using standard CLI tools such as `grep` etc.).
Additional decoration MAY be printed if the standard output is a [TTY](http://www.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.).

Clients MAY support additional custom arguments and syntax not documented here.

Here are some examples invocations using the above flags:
Here are some examples of invocations using the above flags:

```bash
tldr --update
Expand Down Expand Up @@ -131,14 +131,14 @@ After transparently replacing spaces (` `) with dashes (`-`) and lowercasing the
### Platform

Clients MUST default to displaying the page associated with the platform on which the client is running.
For example, a client running on _Windows 10_ 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.

If a page is not available for the host platform, clients MUST fallback to the special `common` platform.
If a page is not available for the host platform, clients MUST fall back to the special `common` platform.

If a page is not available for either the host platform or the `common` platform, then clients SHOULD search other platforms and display a page from there - along with a warning message.

For example, a user has a client on windows, and requests the `apt` page. The client consults the platforms in the following order:
For example, a user has a client on Windows and requests the `apt` page. The client consults the platforms in the following order:

1. `windows` - Not available
2. `common` - Not available
Expand All @@ -157,7 +157,7 @@ If a page cannot be found in _any_ platform, then it is RECOMMENDED that clients
https://github.com/tldr-pages/tldr/issues/new?title=page%20request:%20{command_name}
```

where `{command_name}` is the name of the command that was not found. Clients that have control over their exit code on the command-line (i.e. clients that provide a CLI) MUST exit with a non-zero exit code in addition to showing the above message.
where `{command_name}` is the name of the command that was not found. Clients that have control over their exit code on the command line (i.e. clients that provide a CLI) MUST exit with a non-zero exit code in addition to showing the above message.

#### If multiple versions of a page were found

Expand All @@ -166,11 +166,11 @@ If multiple versions of a page were found for different platforms, then a client

## Language

Pages can be written in multiple languages. If a client has access to environment variables, it MUST use them 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.).

The [`LANG` environment variable](https://www.gnu.org/software/gettext/manual/html_node/Locale-Environment-Variables.html) specifies the user preferred locale (in the form `ll[_CC][.encoding]`). The [`LANGUAGE` environment variable](https://www.gnu.org/software/gettext/manual/html_node/The-LANGUAGE-variable.html) specifies a priority list of locales (in the form `l1:l2:...`) that can be used if the locale defined by `LANG` is not available. Both `LANG` and `LANGUAGE` may contain the values `C` or `POSIX`, which should be ignored.
The [`LANG` environment variable](https://www.gnu.org/software/gettext/manual/html_node/Locale-Environment-Variables.html) specifies the user's preferred locale (in the form `ll[_CC][.encoding]`). The [`LANGUAGE` environment variable](https://www.gnu.org/software/gettext/manual/html_node/The-LANGUAGE-variable.html) specifies a priority list of locales (in the form `l1:l2:...`) that can be used if the locale defined by `LANG` is not available. Both `LANG` and `LANGUAGE` may contain the values `C` or `POSIX`, which should be ignored.

In order to determine the display language, a client MUST:
To determine the display language, a client MUST:

1. Check the value of `LANG`. If not set, then skip to step 5.
2. Extract the priority list from `LANGUAGE`. If not set, start with an empty priority list.
Expand All @@ -188,11 +188,11 @@ Examples:
unset |`it:cz` | `en`
unset |unset | `en`

Regardless of the language determined through the environment, clients MUST always attempt to fallback to English if the page does not exist in the user preferred language. Clients MAY notify the user when a page in their preferred language cannot be found (optionally including a link to the [translations section of the contributing guide](https://github.com/tldr-pages/tldr/blob/main/CONTRIBUTING.md#translations)).
Regardless of the language determined through the environment, clients MUST always attempt to fall back to English if the page does not exist in the user's preferred language. Clients MAY notify the user when a page in their preferred language cannot be found (optionally including a link to the [translations section of the contributing guide](https://github.com/tldr-pages/tldr/blob/main/CONTRIBUTING.md#translations)).

It is also RECOMMENDED to make the language configurable, as to not only rely on the environment. Clients SHOULD offer options to configure or override the language using configuration files or even command-line options (like `-L, --language` as suggested in the [arguments section](#arguments) above). If such a command-line option is specified, a client must strictly adhere to its value, and MUST NOT show pages in a different language, failing with an appropriate error message instead.
It is also RECOMMENDED to make the language configurable, to not only rely on the environment. Clients SHOULD offer options to configure or override the language using configuration files or even command-line options (like `-L, --language` as suggested in the [arguments section](#arguments) above). If such a command-line option is specified, a client must strictly adhere to its value, and MUST NOT show pages in a different language, failing with an appropriate error message instead.

The [`LC_MESSAGES` environment variable](https://www.gnu.org/software/gettext/manual/html_node/Locale-Environment-Variables.html) MAY be present. If the client itself is localized and this environment variable is present, it MUST use its value in order to determine the language in which interface text is shown (separately from the language used for pages). In absence of `LC_MESSAGES`, then `LANG` and `LANGUAGE` MUST be used for this purpose instead.
The [`LC_MESSAGES` environment variable](https://www.gnu.org/software/gettext/manual/html_node/Locale-Environment-Variables.html) MAY be present. If the client itself is localized and this environment variable is present, it MUST use its value to determine the language in which interface text is shown (separately from the language used for pages). In the absence of `LC_MESSAGES`, then `LANG` and `LANGUAGE` MUST be used for this purpose instead.

**Note that** for page lookup it is highly RECOMMENDED to give precedence to the platform over the language. In other words, look for a platform under each language, before checking the next preferred language. This ensures a meaningful and correct page resolution.

Expand All @@ -207,9 +207,9 @@ Here's an example of how the lookup should be done on `linux` having set `LANG=i

## Caching

If appropriate, it is RECOMMENDED that clients implement a cache of pages. If implemented, clients MUST download the archive either from **[https://tldr.sh/assets/tldr.zip](https://tldr.sh/assets/tldr.zip)** or [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) (which is pointed to by the first link).
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)).

Caching SHOULD be done according to the user's language configuration (if any), as to not waste unneeded space for unused languages. Additionally, clients MAY automatically update the cache on a regular basis.
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
Expand All @@ -225,11 +225,14 @@ 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 commit hash changes when merging with squash or rebase.
-->

- Unreleased

- [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))
- Drop the special "all" platform from `--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))
- Drop the `master` branch from the assets link. ([#9668](https://github.com/tldr-pages/tldr/pull/9668))
- Require support for long options ([#9651](https://github.com/tldr-pages/tldr/pull/9651))
- Add recommendation to support caching individual translation archives ([#10148](https://github.com/tldr-pages/tldr/pull/10148))

- [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))
- Add requirement for converting command names to lowercase before running the page resolution algorithm.
Expand All @@ -240,11 +243,11 @@ the commit hash changes when merging with squash or rebase.

- [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))
- Clarified fallback to English in the language resolution algorithm.
- Update `LANG` and `LANGUAGE` environment variable to conform to the GNU spec.
- Update the `LANG` and `LANGUAGE` environment variables to conform to the GNU spec.

- [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))
- Addition of a new `-L, --language` recommended command-line option.
- Rewording of the language section also encouraging the use of configuration files for language.
- Rewording of the language section, also encouraging the use of configuration files for language.
- Shift from BCP-47 to POSIX style locale tags, with consequent **deprecation of previous versions of the spec**.
- Clearer clarification about the recommended caching functionality.
- Correction of the usage of the term "arguments" in the homonym section.
Expand Down

0 comments on commit ebd4b32

Please sign in to comment.