Collaborate with bropages/cheat?

[waldyrious]

(Note for context: this issue was created with the title "Collaborate with bropages?")

It's quite unfortunate that there are two projects splitting the mindshare of easily approachable, community-maintained quick reference documents for console commands: tldr and bropages.

I didn't find signs of any past discussion, so I'd thought I'd mention the possibility and call the maintainers @rprieto and @hubsmoke (and all interested parties, of course) to go over the possibilities.

To kick things off, it might be worth discussing:

• the merits of the friendlier submission mechanism of bropages and the possibilities of tldr adopting such a workflow
• the many-competing-versions model of bropages versus the more wiki-like single-canonical-document model of tldr
• the possibility of developing a Ruby-based tldr client (done since #288)
• whether a web-based client like tldr.js connecting to both databases could be a nice first step towards greater integration

What do you guys think?

[leostera]

Warning: Off the top of my head.

the merits of the friendlier submission mechanism of bropages and the possibilities of tldr adopting such a workflow

While the cli is friendlier than submitting PR's and allows everyone to collaborate easily, tldr wouldn't be able to guarantee that the pages are actually useful. I fear this: https://github.com/hubsmoke/bro/issues/47 and this https://github.com/hubsmoke/bro/issues/23 – this are features that would need to be developed that otherwise are available already in form of PR's.

And a bit of trouble goes a long way in keeping trolls away.

Idea: Perhaps we could anonymously track the commands that are being searched, and thus easily know which ones people want but are not yet available? This way we could suggest which pages people could collaborate with, and even have them sorted by priority.

whether a web-based client like tldr.js connecting to both databases could be a nice first step towards greater integration

This I could, but I'd rather do not. Mostly because of the format of their documents. Sample: http://bropages.org/man.json – I'm not saying it can't be worked with, I'm saying it's heavily redundant.

But if tldr-pages was to entertain the idea of one API that would make client-side page-caching easy, one API to rebuild the pages index by a mere GitHub Webhook, one API to rule all clients and to HTTP bind them...

Then I will take the API to Mordor.

[waldyrious]

For the record, I too prefer the collaborative, single-document model, rather than the competitive, many-versions one (though that may be a biased opinion coming from a long-time wikipedian!) but you've got a good point that the merge & editing features come from free with a PR model (which isn't all that trouble, really -- doing stuff in github's web interface can actually be more user friendly than using the command line at times).

[jcrben]

Right now these pages mostly list commands, but I can see the two projects serving different purposes. Bro offers a list of useful and community-upvoted commands while using GH pages makes it easier to craft a modern manpage which doesn't have a lot of the cruft so pithily demonstrated with the tar example in the README. It also makes it easier to drop in links - for example if I'm looking at the sed page, it's probably a good idea to link to Bruce Barnett's tutorial for further details.

[waldyrious]

using GH pages

Um, did you mean tldr-pages, or am I missing something here?

Anyway, I'd argue that tldr is primarily, to use your words, "a list of useful commands". The possibility of a nice formatted document to summarize/replace the bulkier manpages is definitely a bonus, but at their heart I'd still categorize these two projects (tldr & bropages) within the same class.

[rprieto]

I still believe both tools share the same idea (list of usage example), the main difference being what @jcrben pointed out: Bropages is based on submissions and voting and tldr is based on curated content.

I didn't really see tldr as an alternative to man pages, e.g. supporting any arbitrary Markdown. That'd be an interesting idea, but the ship's sailed on too many tldr clients that expect a list of examples. The question was definitely raised at the beginning: "why not just contribute to the official pages"? Which is a fair point... hence tldr focusing on concrete examples.

But nice pages using Markdown, easy to contribute too, supporting links and being more example-driven could be a handy man-page sidekick.... so maybe that's a tldr V2 type of thing? The downsides of not being man-pages stay the same, obviously, e.g. how do you handle different versions? (quick answer: we probably don't :smile:).

[waldyrious]

Just so the discussion doesn't veer too far away from the original topic, I'd really like to hear your thoughts (@rprieto) about a simpler way to contribute. Maybe using hub? It would be great if we could replicate a workflow similar (but even simpler) to this.

[jcrben]

@rprieto well, if this is just going to be a duplicate of bro with a list of commands, I doubt I'll reach for it very often, as I'm mostly using bro for quick command examples. I'd rather see sane explanations of the switches and context. Contributing to the official pages is sort of interesting, but not really realistic - many of these pages are effectively frozen in time and maintained by single individuals who are often inactive.

But yeah, maybe someday. Handling multiple versions is not an insurmountable problem.

[rprieto]

@jcrben if you're interested in kicking off the conversations / suggesting ideas about a potential tldr v2, please do! I agree there could be value in really simple man pages similar to the "simple English" version of Wikipedia. We'd need strong guidelines about what should be in/out and a decent format to handle platforms/versions.

Otherwise about tldr v1 being a duplicate... for what it's worth it was created about 1 month before bro pages was announced. I guess it means we have 2 tools doing similar jobs, to each their own :) I like having Markdown pages that can easily be edited but are still relatively stable, but I understand that some people like bro pages better, that's the beauty of open source!

[jcrben]

How would you recommend doing that? Currently reading http://manned.org/lsof.8 and it's just a teensy bit rough.

[waldyrious]

Btw I just found out about cheat, and by extension, these. Possibly worth looking at collaboration there too (/cc @chrisallenlane)

[pirate]

Cheat, as mentioned by @waldyrious, was created July 2013 (a few months before tldr) and has been my defacto "mini manpages" source, I'm surprised the author of this project didn't hear about them. Seems like a pity to have 3 projects that overlap so closely, it would be nice to have them be able to read each other's doc directories, otherwise we'll all have aliases/functions like this one.

function halp
    cheat $argv; or bro $argv; or tldr $argv; or man $argv; or echo "Command $argv not found."
end

Cross-compatibility would only make tldr more powerful, while allowing it to remain a separate project with its own strengths and weaknesses.

[igorshubovych]

@pirate i learned about cheat only recently. Actually i am surprised, because the aim of tldr and cheat are quite close, but there are still differences in details: the way content is edited (Markdown vs its own format), the way community is built (commitee vs single developer) and etc. I believe we can collaborate with cheat somehow, just need to find the best way to do it. BTW, they use GPLv3 license.

bro is actually very different: it is main value content is managed only via their API. I have doubts that we can collaborate with them.

Anyway our content is under MIT license, so they can easily import it too. From the license standpoint it is easier to them to import our content.

Thanks for cool idea about halp command.

[M3kH]

Hi everybody! Unfortunately I'm new new to tldr, cheat and even to bro. I just discover these treasures today :-)

I own console.sh and I had in mind to use for similar projects.

I would like to help tldr; for the same reasons @igorshubovych just mention on top, first of everything Markdown and the multi authors structure.

Would you mind if I host the content of tldr; in that domain with a different parser? Can be this be a step to help in eventually merge cheat and tldr;?

I thought was nice to share :-) Cheers.

[igorshubovych]

@M3kH as we use MIT license we can't forbid you doing this :)

Sure, you can do it. Let us know if you need any help with it.

[chrisallenlane]

Hi, guys. I'm the cheat project maintainer.

I believe we can collaborate with cheat somehow, just need to find the best way to do it. BTW, they use GPLv3 license.

I need to look into this later, but FWIW, I have no problem re-licensing or dual-licensing cheat to use the MIT license. I've started using the latter in my newer projects, actually. I/we would be happy to collaborate :)

[igorshubovych]

Wow! Great to hear! :ok_hand:

[leostera]

Awesome! :+1:

On Mon, Jan 4, 2016 at 6:13 PM Igor Shubovych notifications@github.com wrote:

Wow! Great to hear! [image: :ok_hand:]

— Reply to this email directly or view it on GitHub https://github.com/tldr-pages/tldr/issues/266#issuecomment-168739196.

[chrisallenlane]

Hi, guys

FYI, cheat is now dual-licensed as both GPL-3 and MIT :)

https://github.com/chrisallenlane/cheat/issues/261

[zlatanvasovic]

@waldyrious I think this issue should be closed. Do you agree? If cheat community is still interested in the merge, we can open another issue. This one is about bropages.

[waldyrious]

There hasn't been any activity or interest in https://github.com/hubsmoke/bro/issues/57 so I agree that we shouldn't keep this open waiting for feedback that shows no signs of being forthcoming.

On the other hand, collaborating with cheat looks potentially much more likely, especially since @chrisallenlane has commented here and has shown interest. Considering that much of the discussion on this thread has been about cheat, I suppose we could rename this issue and start looking for concrete ways to sync up with cheat.

@chrisallenlane, what are your thoughts about that? How would you see such a collaboration (not a one-time thing, but somehow keeping the repos in sync over time) working? I'm thinking extracting the contents of the cheatsheets folder into a separate repository (or moving the client itself, as we did here) could be a good first step. We could even merge them here rather than setting up a separate repo, if that would be ok with you.

If we go with two repos, then we could decide on a shared format and ensure that the clients fetch from both content repos. But these are just some ideas from the top of my head -- let me know what you think :)

[waldyrious]

By the way, @M3kH: are you still interested in a setup along the lines that you suggested above? If so, that would also be a good option for collaboration between tldr-pages, cheat, and others.

[agnivade]

ping ! Is there still any interest in this ?

cc /@M3kH, @chrisallenlane

[chrisallenlane]

@agnivade

I still like the idea "on paper". In practice, however, I think there are some issues:

1. I'll confess that I'm quite simply very short on time right now, and will be for at least another two months.
2. It might be somewhat tricky to actually implement this, because tldr is built in node, and cheat is built in Python. Thus, to share (and seamlessly install) cheatsheets from a common repository on installation, we might need to get cute with npm scripts and/or... whatever the Python equivalent of that is (I know node much better than Python - lol) to git clone the cheatsheet repository somewhere. (This, of course, would suddenly add git as a hard external dependency to both projects, which isn't ideal.)
3. A while ago we merged a PR into cheat that supports Github-style code-fences as a mechanism for implementing syntax highlighting. If tldr doesn't support that, some of cheat's cheatsheets might be somewhat obnoxious to tldr users.

So, while I'm generally a big advocate of both modular design and collaboration, I'm wondering if this might be more trouble than it's worth.

Thoughts?

I'll note, of course, that cheat has a permissive license, so if nothing else, you're welcome to use its cheatsheets freely, now and forever.

[waldyrious]

@chrisallenlane the tldr clients are already separate from this repo, which pretty much just hosts the pages. Some of them fetch the pages using git (and there's a case to be made for why such a dependency might make sense), but we also provide a tldr.zip archive in the assets directory of tldr-pages.github.io (accessible from https://tldr.sh/assets/tldr.zip), which is updated on every commit to this repo. So cheat could fetch the pages from there, which might be simpler than using git.

If that sounds like something you could do on the cheat side, we would gladly make the work of importing the cheat pages to this repo, so that the pages are placed in a common location.

The formatting might be an issue, though. Can you point to some examples of pages with code fences? Those pages, along with others whose format don't conform to our current guidelines, may need to either be adapted to the tldr-pages format, or remain hosted in the cheat repo. This could work out relatively smoothly if cheat downloads tldr-pages files to a separate directory (say cheat/cheatsheets/tldr-pages, and simply gives precedence to cheat pages before looking in the tldr-pages folder. That would allow a lossless transition.

Does this sound viable to you?

[hubsmoke]

Hey folks, I maintain bropages.org. I have very little time to help, but I am willing to participate in a discussion about possible collaboration. So far, I haven't seen any direct questions for me, so I'm not sure where I can help.

[waldyrious]

@hubsmoke hi! Glad you are open to collaborate :) I believe the main challenge with tldr-pages/bro-pages collaboration is the one I described in the initial comment:

the many-competing-versions model of bropages versus the more wiki-like single-canonical-document model of tldr

I am not sure how we could address that without fundamentally changing the workflow of either of the projects. The only things that occurs to me, off the top of my head, are (1) bro-pages integrating tldr-pages entries in its database of pages (this can be done by periodically downloading the zip archive at https://tldr.sh/assets/tldr.zip, or fetching this repository via git) and (2) tldr-pages importing the top-voted bro pages that don't yet exist in tldr-pages, and periodically adding new ones that have been submitted to bro pages. But both seem like only half-integration to be honest...

Any other ideas are welcome :)

[agnivade]

Hmm from what I see, there needs to be a considerable amount of effort spent from both ends to make it work.

For cheat, we can import the cheat pages which are not present in our repo. And have the cheat client fetch pages from our unified repo. Any new page addition needs to be done in this repo from then on.

For bropages, we can also go the same way, which is (2) as @waldyrious suggested.

Although I doubt, given the lack of time from both parties whether embarking on such an endeavor is a good idea.

[waldyrious]

from what I see, there needs to be a considerable amount of effort spent from both ends to make it work.

I suppose you're mostly talking about bropages, right? For cheat this would be a one-time import IIUC.

[agnivade]

For cheat, even if we import, for them to be able to use our combined pages will take work if I am not wrong.

[hubsmoke]

I'm fine with importing a big ol page as an entry and allowing the page to be subject to the normal upvote and downvotes

Unless there's a better idea 💡

On Wed, May 31, 2017 at 8:43 PM Agniva De Sarker notifications@github.com wrote:

For cheat, even if we import, for them to be able to use our combined pages will take work if I am not wrong.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/tldr-pages/tldr/issues/266#issuecomment-305380982, or mute the thread https://github.com/notifications/unsubscribe-auth/AARBZkNFZef1UIj259POiRJ2f5sS_MXdks5r_jNEgaJpZM4DoKMe .

[waldyrious]

Regarding cheat, let's wait for @chrisallenlane's feedback to see whether there's a viable path forward regarding the proposals made above.

As for bropages: could you expand how you envision that process in more detailed steps, @hubsmoke? In particular, we need to ensure both parties are clear on what steps each one needs to take, so we can move forward :)

[hubsmoke]

Correct me if I'm wrong. My understanding of tldr is that each command has one entry with several examples in it.

For bropages, a command has many entries, each competing for ranking.

My proposal was to display the tldr information for a command as a separate entry. This could be a one time import, but it's probably better to integrate with tldrs API and simply treat it as a separate entry.

It's almost like tldr is a user on bropages that submits entries and edits them periodically.

Does that make sense?

The point is bropages is an experiment that attempts to use votes to rank entries. I'm happy to include tldr entries to allow the community to decide whether the tldr version is useful.

So if we agree on this, the question that remains is does tldr expose an API I can use to integrate with?

On Thu, Jun 1, 2017 at 4:23 PM Waldir Pimenta notifications@github.com wrote:

Regarding cheat, let's wait for @chrisallenlane https://github.com/chrisallenlane's feedback to see whether there's a viable path forward regarding the proposals made above.

As for bropages: could you expand how you envision that process in more detailed steps, @hubsmoke https://github.com/hubsmoke? In particular, we need to ensure both parties are clear on what steps each one needs to take, so we can move forward :)

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/tldr-pages/tldr/issues/266#issuecomment-305647428, or mute the thread https://github.com/notifications/unsubscribe-auth/AARBZtc9foxs8rQhOuDytHRXBaFzpxP-ks5r_0f4gaJpZM4DoKMe .

[waldyrious]

It's almost like tldr is a user on bropages that submits entries and edits them periodically. Does that make sense?

Yes, that sounds quite reasonable.

So if we agree on this, the question that remains is does tldr expose an API I can use to integrate with?

Well, we do provide a zip file with all pages plus an index file, that us rebuilt for every commit (via the build.sh script which is invoken by our Travis script and uploads the results to the assets directory of our website).

The automatically-updated archive does not exactly constitute an API, but it could be used by bropages to periodically re-import the tldr-pages entries, hopefully using an automated process such as a small script and a cronjob. Is that a possibility, or would you require something more elaborated?

[hubsmoke]

This seems like it could work -- I downloaded the zip and I can see the structure of it. Seems like the import can be done using this approach.

On Sat, Jun 3, 2017 at 5:14 AM, Waldir Pimenta notifications@github.com wrote:

It's almost like tldr is a user on bropages that submits entries and edits them periodically. Does that make sense?

Yes, that sounds quite reasonable.

So if we agree on this, the question that remains is does tldr expose an API I can use to integrate with?

Well, we do provide a zip file with all pages plus an index file, that us rebuilt for every commit (via the build.sh script https://github.com/tldr-pages/tldr/blob/master/scripts/build.sh which is invoken by our Travis script https://github.com/tldr-pages/tldr/blob/efedbb28359321804b2f9be094328e72ecb5a8ef/.travis.yml#L10-L11 and uploads the results to the assets directory https://github.com/tldr-pages/tldr-pages.github.io/tree/master/assets of our website).

The automatically-updated archive does not exactly constitute an API, but it could be used by bropages to periodically re-import the tldr-pages entries, hopefully using an automated process such as a small script and a cronjob. Is that a possibility, or would you require something more elaborated?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/tldr-pages/tldr/issues/266#issuecomment-305971366, or mute the thread https://github.com/notifications/unsubscribe-auth/AARBZv1-AZRH5H84p0pI7aqGx4ok3hyeks5sAU5BgaJpZM4DoKMe .

[waldyrious]

Yay! Let us know if there's anything else you'd need from our side :)

Later on we will probably want to discuss how to go about importing pages in the opposite direction, if possible.

[zlatanvasovic]

Have there been any news on this?

[chrisallenlane]

@zdroid, hi, I'm the maintainer of cheat.

The only news I have is that cheat underwent a major refactoring over the past few months, and now, cheatsheets are stored in an external repository:

https://github.com/cheat/cheatsheets

This will probably make it easier for you guys to import them somehow, have you the desire.

I'll be busy over the upcoming holidays, but am always open to collaboration :slightly_smiling_face:

[waldyrious]

Awesome, @chrisallenlane! I've created #3689 to provide a quick list of pages we can create to match cheat's coverage, but I'd love if we could collaborate more deeply. Is there anything in our syntax that is missing to support the type of information cheat uses? I can see for example that simple pages like alias can easily be produced from our current syntax.

[SethFalco]

Looks like bro or bropages has been deprecated/archived.

DEPRECATED - Use tldr or cheat or whatever works for you

We may want to update Similar Projects here: https://github.com/tldr-pages/tldr#similar-projects=

Either removing it, or at least noting that it's deprecated.