15 ms·
TLDR pages: Simplified, community-driven man pages
- presiozo 7y agoNice idea. Also, I think that an ELI5 command would be really useful, too
- nathias 7y agoI've been using them for a while, they replace/improve man for most cases/
- deleted 7y ago[deleted]
- avsteele 7y agoExamples are great because they give the curious user an idea of how to use the command in new ways.
- codesections 7y agoI like the idea of tldr pages. Unfortunately, by default, they are a bit too slow to display—I know it's under a second, but it's just enough to break my flow. Fortunately, there are other clients, some of which are much faster. My current favorite is tealdeer:https://github.com/dbrgn/tealdeer https://github.com/dbrgn/tealdeer
- dbrgn 7y agoThanks for the shoutout :) It's funny that my weekend project that I wrote to learn Rust suddenly has almost 500 stars on GitHub...
- FabHK 7y agoThere was a previous HN discussion of "bro", can anyone comment on the differences? "Bro pages: like man pages, but with examples only" https://news.ycombinator.com/item?id=7121268 https://news.ycombinator.com/item?id=7121268
- fredley 7y agotldr has a better name.
- FabHK 7y agoHaving skimmed the endless discussion about the "bro" name, I have to agree.
- nannal 7y agoI can think of about four other projects called bro so without context the name is fairly useless and it appears this is a competitive space, I wouldn't hold much hope for the tdlr esc bro
- stared 7y agoWas BroPages name the only reason it hasn't gone mainstream?
- capableweb 7y agoYes, just like the only reason Facebook went mainstream was because of the incredible name.
- Polylactic_acid 7y agoNo it never went mainstream because it a tool with worse ui and less content than a search engine + stack overflow. I can find simple instructions for almost any tool with a search like "Convert flac to opus ffmpeg"
- FabHK 7y agoFWIW, can be installed on macOS with brew: brew install tldr EDIT to add: and so can the faster (caching) Rust version (note: install one or the other, not both, since they use the same `tldr` command) brew install tealdeer
- ashton314 7y agoWoah. That's way faster. Thanks for mentioning this! I'll switch all my machines over to tealdeer now.
- sammorrowdrums 7y agoYeah cargo install tealdeer was worthwhile. Really good.
- deleted 7y ago[deleted]
- stared 7y agoI would be happy to see such a thing taking off. Typical man pages are well, like learning a language by studying a dictionary, alphabetically. It may contain all information, but a clear F on UX. Some packages get slightly better with starting from the most common use cases, with examples (and digestible errors). However, I would be even more interested to see what is the actual usage pattern (e.g. from .bash_history / .zsh_history). Do you know any datasets with longer such?
- stared 7y agoAlso, I see that there are other similar projects: https://www.ostechnix.com/3-good-alternatives-man-pages-every-linux-user-know/ https://www.ostechnix.com/3-good-alternatives-man-pages-ever...
- CaptArmchair 7y agoMan pages are intended to be an exhaustive description of the individual options, switches and command arguments and what they do; but they won't tell you how to combine those to be useful in your particular case. It's up to you to figure that out. tldr caters to an entirely different heuristic: I have this use case, give me a list of use cases and the corresponding combination of switches, options and arguments for each respective use case. tldr won't explain to you what each individual switch, option or argument does, turning the provided commands into black boxes. Here's the trade off: The former has a steep learning curve and figuring out how a tool works doesn't solve your immediate problem. But if you commit the meaning of switches, options and arguments for common tools such as awk, sed, tar, ls,... to memory, you will become proficient at solving any problem with a few tools over time. The latter has a low learning curve and you just have to copy/paste a command to solve your problem. But tldr won't tell you how those switches and options work. And you will just use them as incantations that magically help you to solve a limited number of cases. If you end up with a use case that isn't listed, you are left in the dark as far as tldr is concerned. So, is tldr a bad tool then? No! If you are confronted with the command line sparingly, then tldr helps to lower the bar and solve your immediate problem. But if you hope to grow into a proficient shell user, then you're still going to have to grok the man pages one switch, option and argument at a time. I'm a polyglot. Studying a language by opening a dictionary and starting alphabetically, is arguably, the worst way to get there. You would start with learning a set of common words and basic grammatical rules, and then expand over time through practice and instruction: speaking, reading and writing. The same applies to command line tools and man pages: they are reference materials first and foremost.
- brudgers 7y agoa lively previous discussion, https://news.ycombinator.com/item?id=15779382 https://news.ycombinator.com/item?id=15779382
- dang 7y agoAlso 2015: https://news.ycombinator.com/item?id=10797303 https://news.ycombinator.com/item?id=10797303 Related from 2014: https://news.ycombinator.com/item?id=7166257 https://news.ycombinator.com/item?id=7166257
- overcast 7y agohttp://bropages.org/ http://bropages.org/ is usually my goto. I learn by example, so naturally I despise man pages, and this makes it tolerable.
- b3kart 7y agoShout out to http://cht.sh http://cht.sh, which could be used without installing anything: curl cht.sh/tr
- zackmorris 7y agoWow that's pretty great. There are so many powerful console utilities with overly opaque manuals that make them hard to jump into when you just want to do a simple thing. Compare these for example: http://cht.sh/jq http://cht.sh/jq https://www.systutorials.com/docs/linux/man/1-jq/ https://www.systutorials.com/docs/linux/man/1-jq/
- fiatjaf 7y agoThe jq manual is very very good.
- pgwhalen 7y agoCompletely agreed. I find my jq answers there more than anywhere else, and I am continually amazed by its balance between accessibility and thoroughness. I would also say though that this cheat sheet looks great as well - cheat sheets absolutely have their place next manuals.
- deleted 7y ago[deleted]
- ausjke 7y agoamazing, just tested it out, i hope it can add devdocs.io support, and update vim plugin to newer ones. this will likely replace my tldr soon
- ausjke 7y agoI have yet to see node.js API support from any REPL or shell or vim or tldr, the only option is access it from browser, which is not enough. https://zealdocs.org https://zealdocs.org is another great source, similar to https://devdocs.io https://devdocs.io
- omaranto 7y agoI don't understand why this needs a client. Why not just install these as man pages in their own section and read them with man? EDIT: My idea is of course not new, see https://github.com/joelekstrom/tldr-man https://github.com/joelekstrom/tldr-man for a way to convert these docs to man pages.
- rgoulter 7y agoI've not used man enough to know the how to look up a particular section. This is a good opportunity for me to compare the out-of-the-box results from tldr vs man: https://tldr.ostera.io/man https://tldr.ostera.io/man https://linux.die.net/man/1/man https://linux.die.net/man/1/man "Why not just install these as man pages in their own section and read them with man?" Because downloading the default program is much easier, most users aren't that concerned about adding a small CLI program on their computer, and most aren't that purist about right way to read documentation is through manpages.
- omaranto 7y agoI don't think tldr is a small CLI program unless you already have Node.js installed. :) And I also don't see why installing that is easier than installing man pages, if appropriately packaged. (I'm not claiming they are currently appropriately packaged, I'm just saying that's what they could have done instead of writing a client.)
- beart 7y agoI don't think you need Nodejs. There are a large number of clients listed here https://github.com/tldr-pages/tldr#clients https://github.com/tldr-pages/tldr#clients
- therealjumbo 7y agoDebian has a package "tldr" implemented in haskell, that's under 1 MB. https://packages.debian.org/search?keywords=tldr https://packages.debian.org/search?keywords=tldr I just found that and installed it after reading this thread. It looks like on first run, like "tldr tar", it calls "git clone" on some repo. Thereafter, other incantations like "tldr grep" use the already local repo. And the repo can be updated with tldr --update. Seems very fast.
- ddevault 7y agoA heartfelt plea: The man pages are community driven, too. If you think they can be improved, instead of investing in rapidly decaying third-party documentation, please take your improvements upstream. The maintainers would be thrilled to have them.
- overcast 7y agoIt seems like the maintainers of man pages just refuse to bother with something so obvious. It's been decades, and man pages are still archaic and not user friendly.
- vmchale 7y agoOn Linux that has been my experience. man pages on Mac are a little better, I've heard the BSDs do better as well.
- spenczar5 7y agoDo you have examples of that refusal? I'm unfamiliar.
- edw 7y agoBased on my experience, the problem may be that man pages are often not where one learns how to use a tool. I still remember from long, long ago when I told a greybeard that I was trying to learn sed by reading the man page. He replied, "God help you," and guffawed. While some man pages have examples, I don't know if man page writers see their job as teaching readers how to use a utility. The goal of man pages more often seems to be _reminding_ a person already familiar with the tool how to use a tool. I'm, umm, _reminded_ of project READMEs. I've come to assume that when I go to a project on GitHub, I'm going to get everything I need (or pointers to everything I need) to get started with a project, but often there's a project web site that is intended to serve that purpose. I just ran into this yesterday with Falcor. Not all man pages are like this obviously. Specifically, the section three man pages on C functions do a good job fully documenting functions.
- ausjke 7y agotldr is the tool I recommend to linux beginners, so they're not afraid of CLI
- 1MachineElf 7y agoVery useful. Thank you for supporting multiple platforms, and the MIT license.
- rkangel 7y agoNeither this, nor the traditional man page list of options is useful on its own. You need a detailed reference of the things you can do, and then you need examples for how to pull those things together in common usages. For a code equivalent, Rust encourages function level documentation. This gives you detailed information on the full API surface and is vital, but if you only had that you wouldn't know where to start. Rust also has the 'examples' directory (I'm talking about a library project) which usually has a few executables that use the library.
- Brave-Steak 7y agotldr doesn't remove man pages. You're free to check the man page for what whatever flags used in a command in tldr mean.
- justinhensley 7y agotldr has been my daily driver for 1-2 years now, almost replacing man entirely. The community has contributed very useful examples. I go to man once or twice for tools that are entirely new to me. Then, I use tldr until I have muscle memory or using a feature that is new to me.
- upofadown 7y agoThis tends to be more of an issue with GNU programs that have info pages. You are not really supposed to use the man pages in that case. The info pages for GNU tar have lots of examples scattered throughout: * http://www.gnu.org/software/tar/manual/ http://www.gnu.org/software/tar/manual/ BSD systems, for example, have much better man pages that have an actual "EXAMPLES" section near the bottom.
- Brave-Steak 7y agoThe thing is - I don't want to go to some website or pour through pages and pages of documentation when I want to do one specific thing. I want to do something and move on with my life. My job isn't learning every command line switch under the job.
- b5n 7y agoIt's just text - so all the text formatting/search/manipulation commands are available to you. Manpages are really easy to use and navigate, given you use them how they're meant to be used. man man | grep -A 10 EXAMPLES man tar | awk -F , '/-v,/ {print $2}'
- Brave-Steak 7y agoOr I type ‘tldr’ and don’t waste my time? I swear to god, engineers are so focused on efficiency and yet are so eager to waste so much time and effort on repeating crap like this unnecessarily. Just think about the context switches alone necessary to type all that.
- b5n 7y agoIt was easy for me, no context switching. I assume basic use of grep and awk shouldn't be too much of a stretch for most Linux savvy engineers. I'm happy TLDR fits your needs. I was just demonstrating how I use manpages effectively in hopes it might assist you.
- drdebug 7y agoman pages sometimes have an EXAMPLES section, may be at some point these could be merged (both ways?)
- josephernest 7y ago1) Great project! Is there a simple way to install it without having to install Node.js or Haskell or Ruby? (I don't want to install Node.js just for it) Is there a apt-get install tldr solution on recent Debian / Ubuntu distros without installing another additional package manager? I mean even the bash solution: bpkg ... does not work out of the box. (bpkg or brew or npm aren't installed by default) 2) Is TLDR linked with the project cht.sh? e.g curl cht.sh/tar? Does it share a common source of documentation are they two totally different projects? 3) Few people won't remember tldr.ostera.io (I won't)... Ok we have bookmarks, but still, it would be more convenient if we could just do: tldr.sh/tar tldr.sh/git_push instead of having to remember ostera.tldr.io oh no ostera.tldr.sh oh no tldr.ostera.sh no...
- dbrgn 7y agoRegarding 1: Tealdeer provides static binaries for Linux. https://github.com/dbrgn/tealdeer/ https://github.com/dbrgn/tealdeer/
- techplex 7y agoThere are many clients that are open source that you can use check these out: https://github.com/tldr-pages/tldr#clients https://github.com/tldr-pages/tldr#clients
- stageleft 7y agoThis is very useful. It's essentially command-line cheat sheets, which are very handy for cmds you don't use every day.
- BrianB 7y agoI would still reference man pages to see what the flags do in the tldr examples.
- kfrzcode 7y agoLaziness is surely not always the answer. I advise learning how to read man pages. Eating your Wheaties, so to speak.
- ajsharp 7y agoThis is such a great idea. Praise fucking be.
- kccqzy 7y agoWell, man pages cover more than just command-line utilities. These typically go in section 1 only. What about section 2 (system calls) or section 3 (library functions)? I guess the audience of this tool doesn't really need these?
- read_if_gay_ 7y agoOf course some information will be omitted, that is the entire purpose of this tool. What’s your point?
- kccqzy 7y agoIt doesn't just omit portions of the man pages deemed to be too long (detailed descriptions). It omits entire man pages. That's the distinction. I would expect such a tool to work so that whenever `man X` produces a long document, searching for X in the tool produces a shortened, example-focused documentation. This is not the case.
- gyoza 7y agoAm I the only one who thinks... This is based on npm and this is the sole reason to not even consider using it??
- noodlesUK 7y agoI think this is an indictment of how awful the man pages are on GNU/Linux systems. The man pages within the various *BSDs are a fantastic resource, as are their other documentation (e.g., the freebsd handbook).
- bostonvaulter2 7y agoI love using tldr, it is great to have some nice succinct examples at the tip of your fingers. And I love that the whole database is downloaded rather than making a network request.
- ebfe1 7y agoI was inspired by cht.sh and wanted to have my own notes hosted without running a python server like cheat.sh so i ended up writing a silly static site generator using consolemd and ship it to surge.sh.Let me know what you think :) https://github.com/santrancisco/cheat/ https://github.com/santrancisco/cheat/
- SanchoPanda 7y agocheat() { curl "http://cheat.sh/$1" } man2txt() { man "$1" | col -bx } manflags(){ man "$1" | awk '{$1=$1;print}' | grep "^\-" } #man pages just the flags more or less, captures some extra ubuman() { w3m -dump "https://manpages.ubuntu.com/manpages/bionic/en/man1/"$1".1.html" } # ubuntu web manpages note bionic, update with do release up ubumanflags() { w3m -dump "https://manpages.ubuntu.com/manpages/bionic/en/man1/$1.1.html" | \ awk '{$1=$1;print}' | grep "^\-" } # ubuntu web manpages explain () { if [ "$#" -eq 0 ]; then while read -p "Command: " cmd; do curl -Gs "https://www.mankier.com/api/v2/explain/?cols="$(tput cols) --data-urlencode "q=$cmd" done echo "Bye!" elif [ "$#" -eq 1 ]; then curl -Gs "https://www.mankier.com/api/v2/explain/?cols="$(tput cols) --data-urlencode "q=$1" else echo "Usage" echo "explain interactive mode." echo "explain 'cmd -o | ...' one quoted command to explain it." fi } # notetoself: check ```info``` check ```help``` check ```apropos``` check ```whatis```
- SanchoPanda 7y ago-- tldr-web() { w3m -dump "https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/$1.md" w3m -dump "https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/linux/$1.md" }
- deadbunny 7y agoYou could improve the ubuman calls so you don't have to change every release: ubuman() { w3m -dump "https://manpages.ubuntu.com/manpages/$(lsb_release -cs)/en/man1/"$1".1.html" }
- SanchoPanda 7y agoI like that, thank you.
- hultner 7y agoIs there any app that combines all these alternative man-pages?
- brian_herman__ 7y agohttp://bropages.org/ http://bropages.org/
- dvfjsdhgfv 7y agohttps://github.com/tldr-pages/tldr/blob/master/pages/common/cpdf.md https://github.com/tldr-pages/tldr/blob/master/pages/common/... - this is advertising dressed up as a "community man page"
- zie 7y agoor just use a BSD which has this all built in.
- musicale 7y agoI learned BSD largely from the man pages, but man pages on Linux distributions always felt a bit deficient to me, partly because of GNU utilities with placeholder man pages that just said "use info instead" and partly because of (at the time at least) many missing EXAMPLES sections. I think they've improved greatly, but man pages on Debian, Ubuntu et al. still feel a bit like second-class citizens. What TLDR pages seem to be getting right is putting EXAMPLES first or second rather than last, and/or having a command to bring up EXAMPLES. Also I want to put in a plug for AUTHORS/HISTORY and BUGS sections. The former can create a sense of community and context and the latter can point out annoying gotchas.
- JdeBP 7y agoContext, definitely. I have myself found them to be very useful. This is why I added HISTORY sections to the user manuals for some of Daniel J. Bernstein's tools when I converted them. * http://cr.yp.to/daemontools/multilog.html http://cr.yp.to/daemontools/multilog.html * http://jdebp.uk./Softwares/djbwares/guide/commands/multilog.xml http://jdebp.uk./Softwares/djbwares/guide/commands/multilog....
- Jemm 7y agoFantastic. Now please someone do something similar with Apple developer documentation.