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: fix page platform section #2859

Merged
merged 2 commits into from
Apr 1, 2019
Merged

client spec: fix page platform section #2859

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
48c7ac6
client spec: fix page platform section
sbrl Mar 30, 2019
0fac9d7
clieent spec: Add messaage to page resolution section
sbrl Mar 31, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions CLIENT-SPECIFICATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -142,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:

Expand Down