Change main client to tldr-cpp-client

[Leandros]

The tldr c client is now in the homebrew core available, and can simply be installed via

brew install tldr

without any taps required.

What's your opinion on promoting it more?

[waldyrious]

Is it available on major Linux distros' package repositories? If not, would you be willing to set that up and ensure it's updated? or perhaps offer an in-app update feature, if that's at all possible (similar to evergreen browsers' auto-update mechanisms)?

[waldyrious]

To be clear, I'm fine with promoting the C++ client more, as I mentioned in #1057, but I wouldn't make it the main client for the tldr project unless it was easily installable using a package manager in the main unix-y platforms.

[Leandros]

Good point. It's probably quite impossible to get tldr into the Linux distros main repositories, it's to niche for that.

Still, I think it's a huge bonus to promote a native client, which can be installed without the huge dependencies npm and nodejs bring to the table (I for one would turn away, when someone told me to install a cli tool via npm, and I know a whole bunch of people who think similarly).

[agnivade]

Agree with @waldyrious here. I am fine with promoting native clients without dependencies, but unless we have a platform independent solution to it, I wouldn't prefer it.

[Leandros]

We could provide binary builds for both Windows and Linux. Requiring npm is a pretty huge dependency, presumably, lot's of people do not have installed and / or do not want to have it installed.

[waldyrious]

it's to niche for that

I beg to disagree! The only people (using unix-y systems) for whom this is too niche are those who haven't heard of it :P seriously, I'd put this at the level of manpages in terms of relevance for the day-to-day CLI usage.

If you would like, we can certainly offer to maintain the packages in the distros' repositories, but I'd ask you to at least initiate the process to set that up. It's fine if you'd rather not, but in that case I'm afraid it just isn't fair to change our primary client from an easy-to-install-anywhere (albeit bulky) node.js-based tool, to something that requires downloading and installing a custom binary, or building from source -- especially for a project so keen to remain friendly to beginners.

[Leandros]

Yes, while you might think it's important, others might not (others will probably include all Linux Distro maintainers).

From my past interactions with the package maintainers on famous Linux distros, this is way too tiny to be in there main repositories. Keep in mind, that even Node.JS is still not in the main repositories.

What I could simply do is create a PPA for Debian/Ubuntu/Mint (or whatever distro using apt-get).
Another PPA for use on CentOS / RHEL would also be required.
Getting tldr into the Arch-Linux repos might actually be possible, they are quite open. Otherwise I could simply do a AUR (if it doesn't exist yet).

I will try to get tldr into the repositories.
Keep in mind that Windows will always require a binary which you would have to download and place somewhere in your path. (which is still a lot less trouble than installing npm)

Edit: They actually added node.js recently, but it's 0.10. That's why the official node site is still recommending the use of there own repository.

[waldyrious]

even Node.JS is still not in the main repositories.

Whoa, I would never guess. It would be nice to be able to verify this sort of thing automatically. I guess this would be a good opportunity to resurrect my unix-manifests project :P

What you propose sounds reasonable, so please go ahead. In the meantime, I'll mark this issue with the "waiting" label until we get some progress in that front.

As for Windows, I believe Chocolatey would be a nice counterpart to Homebrew on OS X :)

[Leandros]

Just found this by accident: http://linuxbrew.sh/

Might be an easy way for Linux users to get tldr.

[waldyrious]

Nice :) that still requires ruby (I believe python is now included by default in most repos), but it's a good alternative. of course, the usual channels (the package repositories or at least PPA-like workarounds to them would be preferable, if possible.

[agnivade]

at least PPA-like workarounds to them would be preferable

Absolutely yes. I would love it if someone can create a PPA and maintain a debian package for tldr !

[Leandros]

My comment, copied over from #1115:

There is a proposal to create a spec for clients (#1065). Wouldn't it be easier to simply remove the already way to many clients?

We already have to many "official" clients, my proposal is to have one reference client which is maintained by the organization and every other client can be maintained by the community.

This client should satisfy the following constraints:

• mature
• bug free
• no third-party dependency
• distributable via one binary
• multi-platform

This can easily be satisfied by the following clients:

• official tldr c client
• unofficial go client
• unofficial go client

If decide to pick the c client, I would have to invest some time to fix a few bugs on windows and make sure it runs on linux (and submit it to the packages on different distros). I'm happy to accept any help and opinion.

I still believe we should reduce the general amount of clients, changing the default client to an easy to install multiplatform client is only the first step.

[leostera]

I come here to say that I agree with @Leandros, and it's got nothing to do with his github username being equal* to my first name.

npm is itself not a big issue, but the node client relies on a humongous tree of dependencies.

A golang client could be easily crosscompiled to work without any dependencies in all major platforms, and all that could be done with Travis (they have a Github Releases hook IIRC) – sample release: https://github.com/ostera/watch/releases/tag/0.3.2 and release script: https://github.com/ostera/watch/blob/0.3.2/release.sh

From then on we could automate the maintenance of the PPA and things should be fairly smooth.
_{* Okay, it's got a Levenshtein distance of 1!}

[Leandros]

Travis (they have a Github Releases hook IIRC)

That sounds neat! I'll look into this and set it up for tldr-cpp-client. This will provide an easy way to get OS X / Linux builds. I'll look into a solution for Windows.

[waldyrious]

I approve of the idea of portable code without huge dependencies, but just to be sure: are we talking about "installing" by downloading a binary and manually placing it in the search path? If so, I'm not sure that's a good user experience. The tool should be easily installable (easy from the perspective of a beginner to the command-line world!), even if we by means of a two- or three-command one-liner that downloads, marks as executable and copies the binary into the proper place.

Additionally, we need the tool to be easily updatable. There are two options for this:

• Make the tool be available in a well-known package manager for each system (Homebrew for OS X, Chocolatey for Windows, and maybe as a Snap for Linux distros?)
• Implement a self-updating (with the user's approval) feature within the app.

Finally, the tool's source code should be readable and well documented, so as to make it easily hackable and encouraging contributions from its users (this is one of the points in favor of tools built using higher-level languages such as javascript or python).

What are your thoughts/plans regarding these points, @Leandros?

[Leandros]

Those are some very good points and a great client should satisfy all of those.

Easily Installable

Isn't tldr target to more tech-savvy and already existing command line users? Where possible, the native package manager[1] can easily be used to distribute a binary build while also providing those as a simple download via the Github repository for easy self-installation (if preferred). Windows could be served via a dedicated installer, but I believe this is absolutely and totally overkill, since it would only install one single binary. Most developers would probably prefer a single binary in a zip which they can put in the path on their own. To still serve lazy or less tech-savvy people we could bundle the download with a .bat file which will automate all the steps for you, while being a lot lighter than an installer.

Easily Updatable

Should not be of concern to the client, since this will be handled by the package manager (where possible, see [1]). It'll be some kind of an issue for Windows users, though. Implementing a self-updater isn't exactly super complicated (if kept really simple), but since only Windows users will be affected, a simple, polite message telling that an update is available should be more than enough.

Regarding Chocolatey: How does this solve our issue? I think it's horrible user experience if we would require the user to install some big third-party program just to put a 5kb executable somewhere?

Easily Hackable

C is a widely used and well understood language, I don't think that should create any issues.
In comparison to JavaScript, C is not a domain specific language and should have a wider audience of developers.

[1]: apt-get on debian based Linux, Pacman / yaourt on Arch based Linux, Yum on CentOS based Linux, brew on macOS

[leostera]

I'd love a dockerized version as well, sometimes people just want to run things.

[Leandros]

Docker? For a single executable? Don't you think that's a tiny bit overkill?

(Apart from that, I'll not support Docker in any way for ethical reasons)

[waldyrious]

Isn't tldr target to more tech-savvy and already existing command line users?

Not really. From CONTRIBUTING.md: "When in doubt, keep new command-line users in mind. Err on the side of clarity rather than terseness.". Arguably, documentation (especially clear and concise as tldr-pages aims to be) is much more valuable to beginners than to experts, who can figure their way around man pages and other sources of information.

Where possible, the native package manager[1] can easily be used to distribute a binary build while also providing those as a simple download via the Github repository for easy self-installation (if preferred).

I thought you had said that getting an app included in the native package managers was quite hard? How do we handle this? My suggestion to use Snap, Homebrew and Chocolatey was precisely to bypass the default package managers' stricter app inclusion / updating procedures.

Windows could be served via a dedicated installer, but I believe this is absolutely and totally overkill, since it would only install one single binary.

For a command-line tool (which wouldn't e.g. be called in a stand-alone GUI or custom shell by clicking on an icon or Start menu entry), this makes sense.

Most developers would probably prefer a single binary in a zip which they can put in the path on their own.

Agree with the first part, but I think it's important to use the platform's standard package installation infrastructure -- e.g. place the binary in a folder in C:/Program Files, or wherever binaries need to be placed to be accessible in the command line. The latter may be something to be set by editing the PATH instead of changing the location of the binary -- I'm not very acquainted with this type of deployment on Windows -- but in any case I wouldn't want to put the burden of this setup on the users by default (expert users can always do it manually if they prefer).

To still serve lazy or less tech-savvy people we could bundle the download with a .bat file which will automate all the steps for you, while being a lot lighter than an installer.

Fine by me, as long as it follows the platform's infrastructure as mentioned above.

[Easily Updatable] Should not be of concern to the client, since this will be handled by the package manager (where possible, see [1]).

Agreed, but will we actually be able to use those channels?

It'll be some kind of an issue for Windows users, though. Implementing a self-updater isn't exactly super complicated (if kept really simple), but since only Windows users will be affected, a simple, polite message telling that an update is available should be more than enough.

Agreed, but if we can't use the other system's package managers, it would make sense to include the self-updater in the tool itself so that all platforms could benefit from it.

Regarding Chocolatey: How does this solve our issue? I think it's horrible user experience if we would require the user to install some big third-party program just to put a 5kb executable somewhere?

They would always have the option of copying the binary manually. The idea is that if they already had Chocolatey set up, they could use it to install/upgrade tldr. The other option is to provide the self-updating mechanism.

C is a widely used and well understood language

So is Javascript and perhaps to a lesser extent Python, so I don't think this factor makes much of a difference.

In comparison to JavaScript, C is not a domain specific language and should have a wider audience of developers.

Are you saying that by being domain-specific, JavaScript is less accessible than C? I think most people would say the fact that JS is a higher-level language has more bearing on its accessibility than its original purpose as a web scripting language. Node.js is pretty generic and used for a wide range of non-web tools (tldr-node-client being a case-in-point).

My focus with the "easily hackable" was not so much on the language itself, but on the readability and documentation of the code.

ps - Although I am disagreeing with some of the things you say, I want to make sure my words aren't taken as discouragement. I fully support moving to a leaner default client, just not at the expense of the user experience.

[Leandros]

I thought you had said that getting an app included in the native package managers was quite hard? How do we handle this? My suggestion to use Snap, Homebrew and Chocolatey was precisely to bypass the default package managers' stricter app inclusion / updating procedures.

This is correct, but as far as I know, any of these have some way to add custom repositories (like we used to do with homebrew).
My point still holds, we probably won't be included in Debians default repository (my prime example being Node.js, which wasn't in their repositories until mid 2015, and is still on version 0.10.x). I have no experience with Arch Linux, CentOS, or Ubuntu. We might be able to get in their default repositories, but I wouldn't bet on it.

Fine by me, as long as it follows the platform's infrastructure as mentioned above.

I agree, we should stay true to the platform. I'm not big of a Windows users myself, but as far as I know, most command line tools are installed by putting them into some directory of their (or users) choice and amending the path. Some do this via installers, some via .bat, some expect the user to do it on their own.
I'll look into writing a .bat to automate the process.

Are you saying that by being domain-specific, JavaScript is less accessible than C?

No, but I expect the intersection of developers interested in working on a native client and people knowing C is bigger than people knowing JavaScript, and Node.js and are interesting in client development.

Node.js is pretty generic and used for a wide range of non-web tools (tldr-node-client being a case-in-point).

Is it? I've never seen or used a non-web based Node.js tool before. Good to know!

I fully support moving to a leaner default client, just not at the expense of the user experience.

I probably misunderstood you, but how can the user experience get worse than with the current client? Requiring the user to install node.js, npm to install tldr is the worse it can get in my opinion.

Node.js 6.7.0: 3,669 files, 40.8M
tldr-node-client: 1,147 files, 7.8M

vs

tldr-c-client: 1 file, 36K

That is a difference of 4815 files and 48.3M.

[leostera]

EDIT: I realize this might counter some of my previous comments, but it's just dawning on me that we haven't really defined the UX we want for the tool other than this conversation

I really just want a client that

1. Installs instantly and to the right places
2. It's self-updating (both client and content)
3. works exactly the same every. fucking. where.

This would mean:

1. a single very small client installable from my distro/os package manager of choice
2. a single client that relies heavily on git for the content (and for it's own source)
3. a single client

I don't care what it's built in or on as long as I can get this flow:

$ one-step-install tldr
done <-- in under 5 seconds
$ tldr tar
...
# 30 days later
$ tldr tar
(...background fetch of new content)
new page

BUT we need to understand some things, good and bad:

1. currently a clean npm -g i tldr took 26 seconds under a 1GBit internet connection – we can do far better than throwing dependencies at a problem
2. a compiled C client would be very small, but it would involve so much more development effort to build upon for new features (forget searching through pages, or any interesting string manipulation) specially now that we are redefining the UX, and
3. a go/rust client would be fairly small and would require no external dependencies, while still maintaining extensibility to, well, to some extent...BUT
4. the most relevant part here is that the core maintainers[0] of tldr are (for the most) part fluent in Javascript, since they will be the ones burdened by whatever is the outcome of this debate

Considering this, I suggest we take a good look at ourselves (tm), in particular how we wrote the node client, and figure out how to strip it down to the bare minimum code necessary. IMO we can build it using node's stdlib, and keep itself updated through npm/git.

Once we've migrated to a git based content management flow, and properly defined an experience that we'd like to detach from it's biggest dependency (node/npm), then let's talk about making a binary build.

Too much shit to deal with at once 😅

(Skip if you don't care about docker) Side-note: docker is just an abstraction on top of cgroups and namespaces, which are just kernel features. So a containerized version, while seemingly overkill, and definitely not what I'm proposing as our main official client, could easily be sized in under 8mb in total, and be completely isolated and run anywhere with a modern linux kernel. Not proposing it, just stating that it's not crazy to treat tldr as a namespaced, cgroups, copy-on-write, sandboxed process (better known as container). After all even when you're not in a container, you are in a container. 😆

[0] for the lack of a better label, and because "the people who invest their into making these tools what they are, for good and bad" was quite a mouthful

[Leandros]

forget searching through pages, or any interesting string manipulation

Pardon? A semi-fast and portable string search is easy to build. We don't have to build the next grep/ack/ag, that obviously requires a lot more effort.
Searchable pages aren't particularly hard either. We pre-build a simple index and search through it.

IMO we can build it using node's stdlib, and keep itself updated through npm/git.

Just keeping the node dependency is way to much, in my opinion. I suggested tldr to a handful of friends over the past year. Guess how many installed it by just going to the landing-page? Zero. Not a single friend of mine wanted to install Node.js for a simple command line utility. That's 60MB of glorified junk. Few settled for a client installable via brew, some used python, many simply used the web client once and forgot about it.

EDIT: I realize this might counter some of my previous comments, but it's just dawning on me that we haven't really defined the UX we want for the tool other than this conversation

You literally suggested the only feature which requires, one way or the other, the use of a c library: libgit2. Adding this to the node client adds another layer of dependency: a working c compiler.

I don't see a single point speaking in favor of a Node.js client. (keep in mind I'm also not suggesting the client would have to be written in C. C++, Fortran, Go or whatever language can use C libraries and be compiled to a binary).

[agnivade]

the most relevant part here is that the core maintainers[0] of tldr are (for the most) part fluent in Javascript,

I am pretty comfortable in Go. Now I feel that I should have taken ownership of the Go client instead of the node client 😞

Guess how many installed it by just going to the landing-page? Zero. Not a single friend of mine wanted to install Node.js for a simple command line utility. That's 60MB of glorified junk.

That is really interesting. That means none of your friends had node and npm already installed on their system. In which case, its certainly a big step to overcome and install the node client. But then again, lot of people are part of the npm ecosystem and for them an npm install is a breeze. I would love to see some statistics in this regard.

The libgit2 thing is also concerning. Given that there is no native JS client for git(atleast I haven't found any), this is gonna be ugly. @Ostera - any pointers on that ?

All that being said and done, I have no qualms with a native client. As long as they fulfill the "easy install" and "easy update" criteria mentioned above. I would like the emphasize that copying the binary and placing it in the system path is NOT an option and will easily put off beginners(Heck, even I don't like untaring the go distribution every time, they release a new version). We need it to be available through a client mechanism, either through "brew for linux" or "snap".

Just my 2 cents 😄

[leostera]

Again, we don't need no platform specific git client. We can access git like everyone else: system calls calling the git executable.

[Leandros]

What? Git is definitely not a syscall.
You mean calling the git executable, right?

[leostera]

Yup. Calling the git executable directly.

[waldyrious]

I will comment later with more time, but I am wondering why do we have to choose/provide a single official client at all? If we ensure all clients featured in our documentation follow the UX/features spec we define (#1065), then we can let each user pick the (endorsed) client that is most compatible with their environment/experience/preferences, without imposing any particular prerequisites setup.

On a related note, let's keep in mind that the node client wasn't specifically elected to be the official client; it merely was the first one included by @rprieto himself when he first created the tldr-pages project. In fact, by adopting several clients under the organization (the python one, the cpp one, the elixir one), I believe we can interpret his original intent as not endorsing the node client as the main one to the detriment of the others. (This probably means that to be consistent, we should remove the "default" installation instructions in the README to not refer to a specific tool (as suggested by @ericbn in #1057 (comment)).

[agnivade]

We need not provide an official client. But we should point users towards the most mature and actively maintained client(s). Otherwise how is the user going to know which client to install given there are so many options ? Obviously, not all of them equally support all of the requirements that we define.

[Leandros]

I am wondering why do we have to choose/provide a single official client at all?

There doesn't have to be just a single client, but it's pretty common to have one reference implementation which is then "ported" by the community to different languages / environments.

The issue is, we're currently "suggesting" way to many clients on the landing page.
We should direct users to the reference implementation. This is a clear call to action and will make it simple for users to get started, if they want to try something new they can come back and try other clients.

Examples for projects having one reference implementations and many "ports":

• lz4
• xxhash
• scrypt

Those were just the projects I could come up while writing, there are obviously many more.

[agnivade]

Hey, I myself have a port of scrypt in golang 😄 !

[waldyrious]

we should point users towards the most mature and actively maintained client(s). Otherwise how is the user going to know which client to install given there are so many options ? Obviously, not all of them equally support all of the requirements that we define.

Hence the proposal to only feature in our documentation those clients that do support all the requirements that we define. We can consider those "the most mature clients", and do so with a concrete, objective measure.

The issue is, we're currently "suggesting" way to many clients on the landing page.

Agreed. Defining the spec and removing those that don't follow it should address this issue.

We should direct users to the reference implementation.

Well, if we have several clients following the same spec, then users can refer to any of them to start a new project. Or they can simply refer to the spec itself. This has the benefit of allowing people to pick a reference implementation in a language (programming or natural) they're already comfortable/familiar with.

[Leandros]

Hence the proposal to only feature in our documentation those clients that do support all the requirements that we define. We can consider those "the most mature clients", and do so with a concrete, objective measure.

That won't solve the problem, it'll simply reduce it.

[waldyrious]

I came across this nifty visualization of node packages' dependencies, and thought it could be interesting to share here tldr-node-client's tree.

Interactive version: http://npm.anvaka.com/#/view/2d/tldr

Screenshot:

requests and unzip2 seem to be the main culprits. I'm not sure anything can be done to curtail those, though. That's a topic for another discussion anyway.

[rprieto]

Hi everyone! Sorry I haven't been active in a long time for many different reasons :( I was pinged above so I'll explain my initial reasoning on having a single client :)

I don't know if lz4 or scrypt are comparable. They are algorithms or libraries that need implementations in many languages, because users are developers who will integrate with them in several languages.

I'd say TLDR is a tool for which the end users probably don't mind what technology is used. To me it would be similar to Git providing command line tools called cpp-git, go-git, ruby-git. I think promoting a single official client (e.g. tldr-cpp-client) would be great for users, potentially listing other alternate clients as "other clients people can try". I'm perfectly fine if the Node client isn't the main official client!

[pepa65]

I see no mention of bash here, but it is very platform independent, has only one dependency (bash) that is likely available everywhere people are interested in using tldr as a commandline client, and the single 'binary' is very small.

That said, I don't see the advantage of trying to push one client over others.

[zlatanvasovic]

Is this issue resolved yet? I think @pepa65's response sums everything up nicely.

That said, I don't see the advantage of trying to push one client over others.

[agnivade]

There has been no consensus so far. It is one of those issues which is stuck in limbo.

[Leandros]

The cpp client hasn't been touched in years. Partially because I stopped seeing a reason of developing it as one of many. I'm still under the impression that it's actively harmful to have so many clients. They should've all been consolidated into a single client (whichever that would've been).

[sbrl]

In that case @Leandros, I'm not sure that it's worth keeping this issue open.

While I don't exactly agree that consolidating into a single client is the right answer here, either way you look at this I'd suggest that would be a separate issue.

To that end, I propose we close this issue.

[zlatanvasovic]

It's a waste of resources to focus on developing multiple clients when neither the project's core nor the most used client (node) are completely developed.

I agree with @sbrl this should be closed.

[Leandros]

It's a waste of resources to focus on developing multiple clients when neither the project's core nor the most used client (node) aren't completely developed.

Agreed.

[waldyrious]

Just to set the record clear, there seem to be two separate issues discussed in the last few comments:

1. whether we should promote a single client as the main one (no consensus)
2. whether we should consolidate clients into a single one (no consensus)

Neither is the reason this issue is being closed (which makes sense because there's no decision either way); it's closed because it proposes applying (1) to this client, but that's not an option as it is no longer being developed due to (2) currently defaulting towards keeping multiple clients, by virtue of that being the status quo, with no consensus to change that. (Is that a fair assessment, @sbrl?)

[sbrl]

Yep, that's a pretty accurate way of putting it.

Those issues there should really have their own issues for discussion purposes. IIRC, we do have some a related issue: #1410 (move everything into 1 repo; personally I'm against that). I can't find one about multiple client though (which I'm also against).

Edit: To clarify I'm against having a single client.

[Leandros]

I'm still in favor of having a single client which works on all platforms and removing the promotion of multiple clients.

[pepa65]

I'm still in favor of having a single client which works on all platforms

:-D Preferably one binary then..!

[zlatanvasovic]

@Leandros Are you still in favor of it being the C client? It seems user consensus is on Node / Python due to the popularity of those technologies.

[Leandros]

@zdroid Not really. Use the most mature and most portable client. Although the C client is probably the most portable one, it's by no means the most mature one.

[sbrl]

How would a single client work in your terminal, in a web browser, on Android and iOS phones, and via a smart speaker all at the same time @Leandros?

Also edited my previous comment to clarify that I'm against having a single client.

[zlatanvasovic]

Do we have a client for a smart speaker? If not, we definitely need one! 😉

Now that I see @sbrl's comment, I have to say my mind is on her side aswell. We could focus on one CLI-based platform, but that's the most we can do. Developing portable clients is community's job, and the community has been doing it great.

[sbrl]

(@zdroid: I hope you don't mind, but I've edited your comment to correct my pronouns)

[zlatanvasovic]

@sbrl I don't mind of course. 😉

---

Just an idea on top of my head: perhaps a web(site) client could be the default one?

[Leandros]

@sbrl I don't really see the need for a tldr client on a smartphone, to be honest. But, if you want to be completely pedantic, C runs on all the platforms you mentioned ;)

[sbrl]

Neither do I, but I'm sure some people would find it useful - potentially if you're working with an air-gapped machine?

It should perhaps be noted that the output medium is completely different for a smart speaker, the web, and the terminal though.

Speaking of smart speakers, I've seen mycroft.ai but haven't yet played around with it. Perhaps that would be a good candidate for developing a tldr-pages plugin? :P

tldr-pages everywhere