<commit_before># tldr-pages client specification

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

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 (18th December 2018)
	 - Initial draft
 - v1.1 (18th December 2018)
	 - Refined bullet points according to comments
	 - Ensure the spec specifies the _interface_, not the workings
 - v2.0 (12th January 2019)
	 - Expanded notes into full sentences
 - v2.1 (23rd January 2019)
   - Removed optional parts of specification


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

### Page
tldr-pages consists of multiple _pages_ - each of which describes a specific command.

### Platform
Pages are grouped by platform. A platform is an operating system. For example, `windows`, `linux`, `osx`. The special platform `common` contains pages for commands that work identically across all platforms.


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

### Arguments
A number of arguments MUST be supported (unless otherwise specified if a CLI is implemented:

Argument		       | Meaning
-------------------|--------------------
`--update`         | Updates the offline cache of pages. MUST be implemented if cache is supported.
`--version`, `-v`  | Shows the current version of the client, and the version of this specification that it implements.
`--list`, `-l`     | 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.
`--platform`, `-p` | Specifies the platform that should be used for resolving page names. If specified, the named platform MUST be checked first instead of the host platform as described below.

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

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

Here are some examples invocations using the above flags:

```bash
tldr --update
tldr --version
tldr -l
```

### Page Names
The first argument that does not start with a dash (`-`) MUST be considered the page name.

In addition, page names MAY contain spaces (e.g. `git status`) - such page names MUST be transparently concatenated with dashes (`-`). For example, the page name:

```<commit_msg>Show short arguments first<commit_after># tldr-pages client specification

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

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 (18th December 2018)
	 - Initial draft
 - v1.1 (18th December 2018)
	 - Refined bullet points according to comments
	 - Ensure the spec specifies the _interface_, not the workings
 - v2.0 (12th January 2019)
	 - Expanded notes into full sentences
 - v2.1 (23rd January 2019)
   - Removed optional parts of specification


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

### Page
tldr-pages consists of multiple _pages_ - each of which describes a specific command.

### Platform
Pages are grouped by platform. A platform is an operating system. For example, `windows`, `linux`, `osx`. The special platform `common` contains pages for commands that work identically across all platforms.


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

### Arguments
A number of arguments MUST be supported (unless otherwise specified if a CLI is implemented:

Argument		       | Meaning
-------------------|--------------------
`-u`, `--update`   | Updates the offline cache of pages. MUST be implemented if cache is supported.
`-v`, `--version`  | Shows the current version of the client, and the version of this specification that it implements.
`-l`, `--list`     | 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.
`-p`, `--platform` | Specifies the platform that should be used for resolving page names. If specified, the named platform MUST be checked first instead of the host platform as described below.

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

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

Here are some examples invocations using the above flags:

```bash
tldr --update
tldr --version
tldr -l
```

### Page Names
The first argument that does not start with a dash (`-`) MUST be considered the page name.

In addition, page names MAY contain spaces (e.g. `git status`) - such page names MUST be transparently concatenated with dashes (`-`). For example, the page name:

```
{'fraction_non_alphanumeric': 0.08626452331688683, 'fraction_numerical': 0.013687728791978354, 'mean_word_length': 3.8713178294573645, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1742952', 'n_tokens_mistral': 1730, 'n_tokens_neox': 1567, 'n_words': 878}