From 48c7ac6c644916f54cc537c267be3a71ea1e0eb7 Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Sat, 30 Mar 2019 19:44:48 +0000 Subject: [PATCH 1/2] client spec: fix page platform section --- CLIENT-SPECIFICATION.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/CLIENT-SPECIFICATION.md b/CLIENT-SPECIFICATION.md index 28ae05c62e657..7f60368fdc3f0 100644 --- a/CLIENT-SPECIFICATION.md +++ b/CLIENT-SPECIFICATION.md @@ -1,6 +1,6 @@ # tldr-pages client specification - - **Current Specification Version:** 1.0 + - **Current Specification Version:** 1.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. @@ -19,7 +19,11 @@ In order to aid the understanding of this specification document, a number of te 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. +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 more than 1 platform. + +If a page is common across multiple platforms, but slightly differently 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. + +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 @@ -29,7 +33,7 @@ This section describes the standardised command-line interface (CLI) for clients A number of arguments MUST be supported (unless otherwise specified) if a CLI is implemented: Argument | 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). 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. From 0fac9d709cdae612b83c9ca89acabd525a83d050 Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Sun, 31 Mar 2019 23:09:42 +0100 Subject: [PATCH 2/2] clieent spec: Add messaage to page resolution section --- CLIENT-SPECIFICATION.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CLIENT-SPECIFICATION.md b/CLIENT-SPECIFICATION.md index 7f60368fdc3f0..66764c8c36d96 100644 --- a/CLIENT-SPECIFICATION.md +++ b/CLIENT-SPECIFICATION.md @@ -146,6 +146,8 @@ For example, a user has a client on windows, and requests the `apt` page. The cl 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. + #### If a page isn't 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: