Comments (39)
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 :)
from tldr.
Hi, guys
FYI, cheat
is now dual-licensed as both GPL-3 and MIT :)
https://github.com/chrisallenlane/cheat/issues/261
from tldr.
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.
from tldr.
@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 🙂
from tldr.
I still like the idea "on paper". In practice, however, I think there are some issues:
- I'll confess that I'm quite simply very short on time right now, and will be for at least another two months.
- It might be somewhat tricky to actually implement this, because
tldr
is built in node, andcheat
is built in Python. Thus, to share (and seamlessly install) cheatsheets from a common repository on installation, we might need to get cute withnpm scripts
and/or... whatever the Python equivalent of that is (I know node much better than Python - lol) togit clone
the cheatsheet repository somewhere. (This, of course, would suddenly addgit
as a hard external dependency to both projects, which isn't ideal.) - 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 ofcheat
's cheatsheets might be somewhat obnoxious totldr
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.
from tldr.
from tldr.
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.
from tldr.
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.
from tldr.
There hasn't been any activity or interest in hubsmoke/bro#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 :)
from tldr.
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: hubsmoke/bro#47 and this hubsmoke/bro#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.
from tldr.
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).
from tldr.
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.
from tldr.
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.
from tldr.
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 😄).
from tldr.
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.
from tldr.
@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.
from tldr.
@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!
from tldr.
How would you recommend doing that? Currently reading http://manned.org/lsof.8 and it's just a teensy bit rough.
from tldr.
Btw I just found out about cheat, and by extension, these. Possibly worth looking at collaboration there too (/cc @chrisallenlane)
from tldr.
@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.
from tldr.
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.
from tldr.
@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.
from tldr.
Wow! Great to hear!
👌
from tldr.
Awesome! 👍
On Mon, Jan 4, 2016 at 6:13 PM Igor Shubovych [email protected]
wrote:
Wow! Great to hear!
[image: 👌]—
Reply to this email directly or view it on GitHub
#266 (comment).
from tldr.
@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.
from tldr.
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.
from tldr.
ping ! Is there still any interest in this ?
cc /@M3kH, @chrisallenlane
from tldr.
@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?
from tldr.
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.
from tldr.
@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 :)
from tldr.
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.
from tldr.
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.
from tldr.
For cheat, even if we import, for them to be able to use our combined pages will take work if I am not wrong.
from tldr.
from tldr.
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 :)
from tldr.
from tldr.
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?
from tldr.
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.
from tldr.
Have there been any news on this?
from tldr.
Related Issues (20)
- `set-alias-page.py` generates misleading pages HOT 2
- Proposal: partially revert #9672 because of misleading translations
- MAINTAINERS: add @spageektti as collaborator HOT 2
- Page modification request: ! command title HOT 4
- Page request: huggingface-cli
- Broken links HOT 6
- Typo on the README HOT 2
- Truncating Repo HOT 2
- Page modification request: dconf-reset HOT 1
- Page modification request: convert, mogrify HOT 1
- MAINTAINERS: add @spageektti to Org HOT 2
- Page modification request: rsync HOT 2
- Page modification request: gzip report progress with -v
- Let's document: Adding a video walkthrough for contributing to TLDR HOT 1
- Let's document: Apple iOS, Cisco IOS, and MikroTik RouterOS commands
- Update outdated translations
- Duplicate page title: common/brew-mas (pages.zh) and osx/mas (pages) HOT 1
- Update links to man pages HOT 3
- Page request: minio
- Page request: mc HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from tldr.