Closed RichardBronosky closed 10 months ago
Hey there, @RichardBronosky! How you test a new page with the tldr command itself is highly client dependent. Some clients support it, and others don't.
However, if you want to lint your page before submission, our style guide documents how you can run the official tldr linter on a page - although this is done automatically by @tldr-bot for you when you open the PR.
I understand how this question would get a "well it depends" answer. However, on line 54 of the README the suggestion is to install via npm install -g tldr
and the next most common way people are going to install is likely to be brew install tldr
as suggested on line 74 (and also here). So, if the documentation explained what to do under those circumstances, most users would be covered. In fact, on line 87 we nearly give the answer I (and most others) needed in the form of docker run --rm -it -v ~/.tldr/:/root/.tldr/ nutellinoit/tldr
. So there we are making an assumption about the user's environment without know what client[s] they prefer.
So, I guess what I am requesting is that instead of having that information on this repo cryptically embedded in the README doc where someone can infer the solution with a "good morning, here's your coffee" clear head, let's also place it on the CONTRIBUTING doc where a strung out developer who finally got a few minutes to write some code for themselves at 2am is likely to Cmd-F for it because they can't get their Aspie eyes to focus on a single sentence because they (being the eyes) keep scanning ahead because "it's got to be here I just can't think of the keyword". [sic run-on for effect]
I just noticed that https://github.com/tldr-pages/tldr-node-client uses ~/.tldrc/cache
and https://github.com/tldr-pages/tldr-c-client uses ~/.tldrc/tldr-master
. So, it is "a little complicated", but not impossible.
I think that there should also be an additional requirement added to https://github.com/tldr-pages/tldr/blob/master/CLIENT-SPECIFICATION.md which states that clients that implement a CLI should report their effective/resolved cache path and/or path heirarchy in order of precedence in a standard script interpretable format. It could be any of:
-h
-c
-v
**** This just made me notice that:
the client specification states:
Option | Required? | Meaning |
---|---|---|
-v, --version | Yes | Shows the current version of the client, and the version of this specification that it implements. |
tldr-node-client uses -V
and --version
for version info and -v
produces an error
tldr-c-client uses only --version
for version info and -v
is documented (in -h
) as being for print verbose output
even though using -v
alone produces the same output as --version
Hey there, @RichardBronosky!
For issues relating to the different clients (e.g. the Node client, the C client, etc), I'd suggest opening issues against their respective repositories.
Great catch about the command-line flags there - I suggest opening separate issues against the respective repositories to notify them and give them a chance to fix it (or even better, open a pull request!). Keeping the scope of each issue limited to a single thing makes it easier for maintainers to handle and manage issues.
If this is documented anywhere, I could not find it.
Many users will install tldr using a package manager at the recommendation of a colleague. Eventually they will find a command/page that is missing and will visit the CONTRIBUTING.md. There they will find lots of information about how to create and submit a new page. They will not find any information about how to test/use their new page with the tldr command prior to submitting and getting it accepted. This is likely to reduce the number of contributors to this project and the quality of submissions. I uncovered the answer to this question by running
sudo dtruss $(which tldr) tar
but in my experience it is very rare that higher level engineers are familiar with these tools (even though they should).Ultimately what I did was
mv ~/.tldrc/tldr-master ~/.tldrc/tldr-master.original; ln -s $PWD ~/.tldrc/tldr-master
from my the directory where I cloned this repo. This could easily be made into a script. If there is an appetite for that I can make a PR for one.