diff --git a/CLIENT-SPECIFICATION.md b/CLIENT-SPECIFICATION.md index eba17aa62b73e..2c6e8550f475c 100644 --- a/CLIENT-SPECIFICATION.md +++ b/CLIENT-SPECIFICATION.md @@ -112,13 +112,14 @@ The structure inside these translation folders is identical to that of the main ## 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). In cases when a command uses `{}` in its arguments (e.g. `stash@{0}`) ***the outer braces*** mark the placeholder - the braces inside MUST be displayed. Clients MUST NOT break if the page format is changed within the _CommonMark_ specification. ### Examples - `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" - `mount \\{{computer_name}}\{{share_name}} Z:` MUST be rendered as "mount \\\\computer_name\share_name Z:" +- `git stash show --patch {{stash@{0}}}` MUST be rendered as "git stash show --patch stash@{0}" ## Page resolution @@ -213,7 +214,7 @@ Step | Path checked | Outcome ## Caching -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)). +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 **** or download language-specific archives in the format `https://github.com/tldr-pages/tldr/releases/latest/download/tldr-pages.{{language-code}}.zip` (e.g. ****). The English archive is also available from ****. 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.