tldr-pages / extldr Goto Github PK

The best option to integrate HTTPoison is to develop the own ExTldr HTTP client from the HTTPoison behavior. It will ease the future development and the necessary tests.

Further reading

• Typespecs and behaviours
• How to mock HTTPoison in Elixir

After @owenvoke and me thinks that #15 was solved, I merged it. Now it stills returning errors. But now I think this might be due it is necessary to reconfigure ExCoveralls. I am going to review the ExCoveralls configuration for GitHub Actions, modify it and then propose a PR with the change.

Specify mix coveralls.github as the build script in the GitHub action YML file and explicitly set the MIX_ENV environment to test and add GITHUB_TOKEN with the value of {{ secrets.GITHUB_TOKEN }}, this is required because is used internaly by coveralls.io to check the action and add statuses.

I am going to change the build script to mix coveralls.github and add the GITHUB_TOKEN with the value specified.

Although it isn't a priority and markdown review might be disabled in Codacy, I think it would be interesting to keep an uniform markdown style. So keep the markdown linting might be better.

There are issues on:

• .github/ISSUE_TEMPLATE/*
• CHANGELOG.md
• README.md

It should be interesting to develop a mechanism to upgrade ExTldr, at least the script. One idea might be to compare the version of ExTldr used by the user with the latest release available in GitHub. If the release would be newer, it will upgrade the ExTldr, but if the release is pre-release, an alpha version, ¿or beta?, should ask the user if he still wants to upgrade ExTldr.

There should be no calls to IO.inspect/1 (lib/ex_tldr.ex). Codacy report:

While calls to IO.inspect might appear in some parts of production code, most calls to this function are added during debugging sessions.

To address this issue I am going to raise two different exceptions when:

• There isn't internet connection.
• The error is unexpected. If the error is unexpected, encourage the user to report it in this repository.

As it is indicated in #6, the tldr-pages client specification recommends to develop a cache system. Quoted from the mentioned issue:

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

Probably this will consists a major change, so it is assigned to the milestone v1.0.0.

Due this repository has been transferred to @tldr-pages, it is necessary to perform some changes:

• Change references to ivanhercaz/extldr in the badges of the README.
• Check if Travis CI and another tools continuos to work fine with this repository after change the old reference, if not, it should be fixed. It is possible that for this I will need to be administrator of this repository.
• Change links to the old reference of the repository to this new one to avoid redirects.

Although this is not exactly a documentation issue, I think this one is the best one to organize this issue. If someone have a suggestion, it would be awesome if you apply it or discuss about it.

Is your feature request related to a problem? Please describe.
It is a bit uncomfortable to read the output of a page in markdown format in the same terminal.

Describe the solution you'd like
Develop a module (¿Format?) to format the output. The module could use ANSI code to perform the replacements.

Describe alternatives you've considered
Another alternative is to search an existent package on Hex.pm and apply it.

Additional context
This module should be able to:

• Transform heading 1 (#).
• Transform code (code between `)
• Transform quote (>.
• It could be interesting to test if it is a good idea to use bold text with the arguments between curly brackets ({{command}}).

This issue is just a reminder of what it is pending to do after the merge of #21 and the development of the HTTP client of ExTldr with the HTTPoison behaviour described in #22.

When the behavior of HTTPoison will be integrated in ExTldr it will be useful to develop the tests to cover the working of these lines of code. I label this issue as priority:low because it is important but not explicitly necessary to the good working of ExTldr, it is more an idea to keep the code well-documented and clean, easing the future participation of possible collaborators.

Before to work on this it is important to check the test already writtent, but commented, in test/ex_tldr_test.exs, review again #21 and check the saved readings about mocking in Elixir, behaviors and a long etcetera of useful stuff for this issue.

Is your feature request related to a problem? Please describe.
tldr-pages is a community driven project, so it is important to encourage another users to request or create nonexistent command pages.

Describe the solution you'd like
Add a link to open an issue (<https://github.com/tldr-pages/tldr/issues/new>) if the command page doesn't exist.

tldr-pages is a multilingual project so the clients should have multilingual support, this one too! I will try to include it in ExTldr.

ExTldr should be able to detect automatically the operating system of the user, so if the users execute extldr linux_command in a Linux distribution or extldr windows_command in Windows, it should be check first the pages for Linux or Windows respectively without the necessity to use extldr linux linux_command or extldr windows windows_command.

This issue is just to track the enhancements of ExTldr, due it is already developed and it will be soon in the next release

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, --version option is required. It must show the current version of the client and the version of the specification.
• -p, --platform option is required. This one is the one must be used to specify the platform, it must be checked instead of the current platform.
• -u, --update option is conditional. It updates the cache of pages and must be implemented if cache is supported.
• -l, --list option 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, --language option 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 #3).

Directory structure

• It is recommended to support future/new platforms, but the system must not break if new platforms are added (relevant #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, then LANG and finally LANGUAGE; 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.

I think contributing guidelines could help another interested persons in participate in ExTldr development or in its documentation.