Description
tldr-pages has a client specification to guide how the clients should/must work. I think to accomplish with this specification will help ExTldr to:
- Scale better if tldr-pages changes in the future.
- Standardize how the clients interact with tldr-pages, so if a user begin to use ExTldr after use another client, the transition will be easier.
The next lists are summaries of the requirements specified in the specification, each one, or each group, should have its own issue to document the progress and ease future tasks:
Arguments
- The first argument must be the page name.
- Support the page name with spaces instead of a dash (
-) is not required, but it will be supported by ExTldr. -
-v,--versionoption is required. It must show the current version of the client and the version of the specification. -
-p,--platformoption is required. This one is the one must be used to specify the platform, it must be checked instead of the current platform. -
-u,--updateoption is conditional. It updates the cache of pages and must be implemented if cache is supported. -
-l,--listoption is not required. This option should list all the available pages in the current platform, if another one specified, it shows the pages for the specified platform. -
-L,--languageoption is not required. This specify the language to return the page overriding the language detection. - It should be implemented the long and short version of the options although it isn't required by the specification.
- The standard output is TTY (important to work in Format the markdown of the output #3).
Directory structure
- It is recommended to support future/new platforms, but the system must not break if new platforms are added (relevant Detect automatically the operating system of the user #2).
Translations (#1)
- It is recommended the support for multilingual pages. The format of the directories is
pages.<locale>where is a POSIX Locale Name in the form of<language>_<country>(eg.pages.pt_BR,pages.es). - The language must be determined by the environment variables for language. First should be checked
LC_MESSAGES, thenLANGand finallyLANGUAGE; if no one is available must be show in English. - The client should offer an option to override the language using configuration files or a command line option, as the one described in the "Arguments** group described above.
- It is recommended to check first by platform, then by language.
Caching
- It is recommended to implement a cache of pages. If it is implmented it should download the archive from https://raw.githubusercontent.com/tldr-pages/tldr-pages.github.io/master/assets/tldr.zip.
- If it is implemented, it should be done according to the user's language configuration if there is any to not waste space.
- It should provide an option to update the cache, as the one described in the Arguments group described above.
Many of these are minor changes, but the implementation of the caching system could produce a change in the behavior of the client, so this change will be the last one to implement and it is planned for the v1.0.0.
I will be very thankfully of every feedback given by any users, but specially of the members of the tldr-pages community, the users of tldr-pages and Elixir developers.