Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Client spec v1.2: new --language flag, BCP47 to POSIX and other clarifications #3168

Merged
merged 9 commits into from
Aug 23, 2019
Merged

Client spec v1.2: new --language flag, BCP47 to POSIX and other clarifications #3168

Changes from 3 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
4642cd6
client spec: Add new --language flag
sbrl Jul 3, 2019
c3e50b1
client spec: Update --language wording
sbrl Jul 5, 2019
b637d52
client spec: move changelog
sbrl Jul 5, 2019
bd5e8f1
Client spec: reword and reorder language section.
mebeim Jul 31, 2019
84f7b87
Client spec: use POSIX instead of BCP-47 locale tags.
mebeim Jul 31, 2019
461f20f
Client spec: harmonize formatting.
mebeim Jul 31, 2019
7c1222c
Client spec: turn 'Other Considerations' into 'Caching'.
mebeim Jul 31, 2019
1cf1e7b
Client spec: correct use of the term 'argument(s)'.
mebeim Jul 31, 2019
83a7cbe
Client spec: clarify preferred page resolution method.
mebeim Aug 21, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
23 changes: 15 additions & 8 deletions CLIENT-SPECIFICATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,12 @@
# tldr-pages client specification

- **Current Specification Version:** 1.1
- **Current Specification Version:** 1.2

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.
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).


## Changelog
- v1.0 (23rd January 2019)
- Initial release


## Terminology
In order to aid the understanding of this specification document, a number of terms will be defined in this section.

Expand All @@ -38,6 +33,7 @@ Argument | Required? | Meaning
`-p`, `--platform` | Yes | Specifies the platform to be used to perform the action (either listing or searching). 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.
`-l`, `--list` | No | Lists all the pages in the current platform to the standard output. If the special platform `all` is specified a list of all pages in all platforms MUST be displayed.
`-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 MAY NOT implement the long form of an argument (`--update`, `--version`, `--list`, `--platform`).

Expand Down Expand Up @@ -77,6 +73,7 @@ tldr git checkout
tldr --platform osx bash
```


## Directory Structure
This section documents the directory structure that contains the pages themselves.

Expand Down Expand Up @@ -117,7 +114,6 @@ You can check the validity of BCP 47 tags [here](http://schneegans.de/lv/).
The structure inside these translation folders is identical to that of the main `pages` folder.



## 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/), which the exception of the non-standard `{{` and `}}` syntax, which surrounds values in an example that users may edit. Clients MUST NOT break if the page format is changed within the _CommonMark_ specification.

Expand Down Expand Up @@ -160,6 +156,7 @@ https://github.com/tldr-pages/tldr/issues/new?title=page%20request:%20{command_n
#### If multiple versions of a page were found
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
Pages can be written in multiple languages. If a client has access to environment variables, several standard ones exist to specify the language in which a client should operate. 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.).

Expand All @@ -171,9 +168,19 @@ Finally, the [`LANGUAGE` environment variable](https://www.gnu.org/software/gett

If a page is not available in the user's preferred language, then a client MUST respect the user's priority list defined in the `LANGUAGE` variable (if specified), and MAY choose to notify the user that a page in their chosen language couldn't be found (perhaps along with a link to the [translations section of the contributing guide](https://github.com/tldr-pages/tldr/blob/master/CONTRIBUTING.md#translations)).


## Other Considerations
This section contains a number of other items that don't neatly fit into any of the sections defined above.

If appropriate, it is RECOMMENDED that clients implement a cache of pages. If implemented, clients MUST download the _entire_ archive from **https://github.com/tldr-pages/tldr**.

Additionally, clients MAY automatically update the cache on a regular basis.


## Changelog
- [v1.2, July 3rd 2019](https://github.com/tldr-pages/tldr/blob/master/CLIENT-SPECIFICATION.md) (#3168)
- Added new `-L, --language` recommended command-line argument.
- [v1.1, April 1st 2019](https://github.com/tldr-pages/tldr/blob/fbdc06b7425f92cc0d4fc9a5cfc5860ef017251e/CLIENT-SPECIFICATION.md) (#2859)
- Clarified platform section.
- [v1.0, January 23rd 2019](https://github.com/tldr-pages/tldr/blob/f5be8a2614a455288f26e42953efeb8cb3bc50b0/CLIENT-SPECIFICATION.md) (#2706)
- Initial release.