search

tldr-pages / tldr

📚 Collaborative cheatsheets for console commands
https://tldr.sh
Other
51.03k stars 4.2k forks source link

Document how to use the tldr command against a local git repo #4986

Closed RichardBronosky closed 10 months ago

RichardBronosky commented 3 years ago

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.

sbrl commented 3 years 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.

RichardBronosky commented 3 years ago

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]

RichardBronosky commented 3 years ago

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:

** This just made me notice that:

sbrl commented 3 years ago

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.