Simple shell client shipping with the tldr-pages repo

[sitaramc]

It would be nice to have a very simple shell client (nothing fancy; just 'less' the md file if found, else print a list of pages that start with the argument supplied).

At present I use https://gist.github.com/sitaramc/142c9e3d730583b9271c

And though I hesitate to offer that in a pull request, if someone thinks it looks decent or requires only minor changes to be decent I can do that.

[waldyrious]

+:100: from me, I love the simplicity.

[igorshubovych]

If you want, feel free to add it here in Wiki. There is already one bash client.
Or you can create a PR to add it to README.md.

[waldyrious]

@igorshubovych the proposal was to include this with the repo itself, i.e. as you clone the tldr-pages/tldr repo, you'd have a simple way to query and display the existing pages. It's a different thing than installing a separate, full-fledged client. I think that's a reasonable proposal and would support its inclusion.

[igorshubovych]

Oh, but then I doubt we should do it.

We have some Windows users at the moment, and it will not work for them. They seems like are ok with NodeJS at the moment (seems like Rust client will beat it soon).

If we consider using Bash, i would rather use this one, as it has more features:
https://github.com/raylee/tldr

[waldyrious]

Yeah but that's a full-fledged client and wouldn't make sense to be included in this repo, contrary to a 11 SLOC bash script. The point about Windows is a good one, though. @sitaramc what would you suggest?

[igorshubovych]

what's the difference between 11 SLOC and 250 SLOC?

Are you trying to save some bytes?

[igorshubovych]

Additionally NodeJS client can be added with 1 line in package.json

[waldyrious]

It's subjective, sure, but I don't see the bash script as an actual client, so the separation of implementation (the client repos) and content (tldr-pages) would largely remain in place. It would just be a helper script for convenience instead of cding and lessing by hand.

[sitaramc]

On 29/01/16 23:36, Waldir Pimenta wrote:

It's subjective, sure, but I don't see the bash script as an actual client, so the separation of implementation (the client repos) and content (tldr-pages) would largely remain in place. It would just be a helper script for convenience instead of |cd|ing and |less|ing by hand.

That is precisely what I meant it as.

I'd also like to (re-)say something I say in the code: this is markdown. The whole point of markdown was that it should be readable as-is. I see my simple bash script as saying "here's the base model of your new car; you can fit alloy wheels and colored text by installing other clients".

(did I just go all /. on this by using a car analogy? Shame on me!)

[sitaramc]

re: "The point about Windows is a good one, though. @sitaramc what would you suggest?"

I'm sorry I don't have an answer. My script is merely a POC of sorts -- it even hardcodes Linux, so not just Windows is left out in the cold, even other Unixes are. And though I could fix it for other Unixes, I have no clue about Windows.

The idea is to have something that works off a local clone of the tldr repo so that every query does not go online (my frugal mind rails at that!) And don't miss how it takes just one line of code to say "update this clone in the background, but at most once a day".

The other bash client is a proper bash client, colors and all. I have no intention of competing with that (though if you are going to cache stuff anyway, why not just use a local clone? I am sure 'git fetch' is a lot more efficient, especially if you're going to tldr many different commands).

[waldyrious]

I would say it's justifiable to have a Unix-only client, especially since usually people who use command-line git on Windows typically do have a terminal emulator that supports the usual Unix stuff. So if you could get this to work on most Unixes, I'd vote for including the script.

[rubenvereecken]

I still don't really like the idea of delivering even the most lightweight of clients with the repository. It would only be used by contributors and I prefer opening in an editor anyway.

[sitaramc]

On 30/01/16 15:48, Ruben Vereecken wrote:

I still don't really like the idea of delivering even the most lightweight of clients with the repository. It would only be used by contributors and I prefer opening in an editor anyway.

Frankly, I'm more concerned that all the clients seem to be downloading
individual pages on demand than the (arguably) more efficient (and for a
lot of people, definitely faster) mechanism of cloning the repo locally
and using that.

I realise that's subjective but I am also sure I'm not the only one who
is probably doing this for speed, efficiency, whatever.

Which means "only be used by contributors" would not be accurate.

[rubenvereecken]

That means someone would have to download the tldr repo and somehow put the script in PATH manually, more than is comfortable for most. Clients are there to make it easy.

We have tonnes of clients but I've used only a few. Only a few we "officially support". The good ones implement the caching behavior because it's the sane way to go about it.

[igorshubovych]

At least NodeJS, Crystal and Rust clients download zip file with all pages and put it into your ~/.tldr folder.

[hidroh]

tldroid also follows the same approach to cache zip file locally.

[sitaramc]

On 30/01/16 17:22, Igor Shubovych wrote:

At least NodeJS, Crystal and Rust clients download zip file with all pages and put it into your ~/.tldr folder.

good to know; I was clearly wrong (and I certainly did not check all
the clients).

This isn't anywhere near as efficient as a git fetch for updates, but
that's a relatively lesser nit compared to not caching at all.

[waldyrious]

Caching or fetching aside, it's still true that one would need to git clone this repo and install a client separately to use the pages conveniently. As this isn't an actual client (nor it aims to be), we could mention how to add the script to a path, but honestly just being able to do ./tldr page.mdafter cloning the repo sounds like a net positive to me. And to be honest, what's the downside of including this, really?

[rubenvereecken]

Everyone who has tldr cloned first has a tldr client which he uses, then decided he could chip in and clones the tldr repository, not the other way around.

Adding things is easy, removing them is harder.

[igorshubovych]

@waldyrious

And to be honest, what's the downside of including this, really?

• it is not supported on Windows
• as author said, Linux is hardcoded
• it's not full-featured and some other user will soon request a color printing

[igorshubovych]

I actually come up with a better version of this script:

tldrfind () {
  find pages -name "$@.md" -exec cat {} \;
}

Linux is not hardcoded here.

[sitaramc]

On 31/01/16 00:54, Igor Shubovych wrote:

@waldyrious https://github.com/waldyrious

And to be honest, what's the downside of including this, really?

• it is not supported on Windows
• as author said, Linux is hardcoded
• it's not full-featured and some other user will soon request a color printing

1. agreed; I have no clue about Windows, it doesn't exist in my world.
2. It's just a POC; adding at least the other Unixes is trivial
3. that's the point. This is meant to be a starter pack; you need more
   you download one of the "proper" clients.

But it's your baby; I'm done arguing about this. What I have here works
for me. Reducing it even further (like that one-liner someone posted in
another message) loses the self-update, which I consider most essential
(though the bit that lists available commands when given a prefix is
probably debatable).

[waldyrious]

@igorshubovych as I said, if @sitaramc implements support for other Unixes, I'd be in favor of merging, so point 2 is moot.

To the fact that it isn't supported in Windows, I've already responded to that ("usually people who use command-line git on Windows typically do have a terminal emulator that supports the usual Unix stuff"). Do you disagree with that? Even if you do, would we really want to deny Unix users a useful tool just because Windows users can't have it? Could we think of having an equivalent .bat script for them?

Finally, the color stuff it completely out of question IMO -- if we're printing markdown, the token marks already mark the placeholders clearly. And I repeat: this is not meant to be a full-featured client, just a shortcut to view the pages of the repo after cloning it locally.

[leostera]

Hmm...while I see how @waldyrious has some good points, so has @igorshubovych and @rubenvereecken.

My counterproposal to both sides is to add a script in the package.json, as such:

{
  // some other stuff that we already have
  "scripts": {
    "show": "find pages -name \"$@.md\" -exec cat {} \;"
   }
   // even more stuffs of kinds!
}

Very simple one-liner that can be easily used, comes with the repo, requiring no extra setup, and does exactly just that: show a page.

But then again, if I'm editing a page in markdown...don't I already see the full page? Perhaps we don't really need this at all.

[waldyrious]

@sitaramc I tested this in OS X and it didn't work:

~/tldr$ ./tldr.sh cat
./tldr.sh: line 30: realpath: command not found
usage: dirname path
./tldr.sh: line 36: cd: pages: No such file or directory
./tldr.sh: line 44: cd: common: No such file or directory
==> common:
ls: cat*: No such file or directory
./tldr.sh: line 45: cd: ../osx: No such file or directory
==> osx:
ls: cat*: No such file or directory

Any ideas how to address this? Unfortunately I'm afraid I can't help here, as I just recently started using OS X in a work computer.

By the way, I would probably suggest the git update to be dropped, or at least check if the repository is clean, on the master branch, before fetching an update.

[waldyrious]

@Ostera, to make a point already mentioned on gitter (but just so it stays on record here), note that the variants with find / cat you and @igorshubovych proposed above don't address the case where a command has multiple versions per platform. So we can try to go that way, but this issue would need to be addressed. Not sure it can be done in a (reasonably-sized) one-liner though!

[sitaramc]

On 02/02/16 04:44, Waldir Pimenta wrote:

@sitaramc https://github.com/sitaramc I tested this in OS X and it didn't work:

|~/tldr$ ./tldr.sh cat ./tldr.sh: line 30: realpath: command not found usage: dirname path ./tldr.sh: line 36: cd: pages: No such file or directory ./tldr.sh: line 44: cd: common: No such file or directory ==> common: ls: cat_: No such file or directory ./tldr.sh: line 45: cd: ../osx: No such file or directory ==> osx: ls: cat_: No such file or directory |

Any ideas how to address this? Unfortunately I'm afraid I can't help
here, as I just recently started using OS X in a work computer.

As I suspected (and stated in the note there), the "realpath" command
doesn't exist.

Sorry, I have as much access to (and knowledge of) Mac as I do of
Windows; which is to say none. Googling around found me this 1, which
basically says to use "greadlink -f" instead of "realpath".

Even if it were "readlink -f" we could have kept the script from having
to do different things on different OSs.

By the way, I would probably suggest the git update to be dropped, or
at least check if the repository is clean, on the master branch,
before fetching an update.

In any case, if you are dropping the git update this whole thing is moot
as far as I am concerned; I consider that to be quite essential.

Checking if the repo is clean is easy, but that's where we come to a
difference between people who are actively contributing to the tldr
repo, and people who are merely using it. In both cases, we have a
local clone, except in the latter it is guaranteed to be clean.

regards
sitaram

[felixonmars]

cd $(dirname $(realpath $0))
Should be equivalent to
cd $(dirname $(python -c 'import os,sys; print(os.path.realpath(sys.argv[1]))' $0))

I don't have a Mac to test with, but since python should be pre-installed on OS X, it may have a chance to work under OS X.

[igorshubovych]

@sitaramc

We discussed this script internally on Gitter. I will give you my points about it.

I think relying on Git is not for everybody. It is very inconvenient for contributors.

There are several situations, where git pull --rebase can be dangerous:

• you are not on the master branch
• you are in the middle of some work
• you are on your own fork

[zlatanvasovic]

This is stale and probably should be closed. Even though tldr is a knowledge base for shell commands, Shell-format scripting isn't universal to all systems. node, C, go and python clients, among many others, let alone the growing number of web-based clients, already do this job.

[sbrl]

Oh, interesting issue! I wasn't aware of this one.

I think we have quite a few different clients to choose from now, so there should be something for everyone.

I vote to close this too, but we should wait for the opinions from others before doing so.

[andrik]

I agree with you guys and vote to close this one

[sbrl]

Ok, that's 3 votes to close, so I'm going to close this issue. Of course, I'm happy to reopen this if this is a mistake.