9 ms·

TLDR pages

401 points by tkfx 11y ago

brillenfux 11y ago
Man pages are really already TLDR pages. They suck for introductory documentation (most times) but are really useful if you just can't quite remember the switch or its parameters. I don't know what niche this is supposed to fill?
- Mojah 11y ago
  I like it because it introduces practical, real-world example commands. Most manpages don't offer those but instead list all parameters and potential input (1) That's nice, but for a quick "which command do I need?" scenario I prefer the examples that `tldr` can provide. (1) Yes, some manpages do provide examples at the very bottom, but not all manpages do.
  - mystikal 11y ago
    The difference between man gcc and tldr gcc is dramatic.
  - Gravityloss 11y ago
    Even the examples are usually completely alien to real usage.
- nailer 11y ago
  TLDR pages are tasked based. Man pages are references to all possible switches in an app. Eg, the tar man page has a focus on tape archiving, referencing $TAPE and /dev/mt0 and didn't used to have examples (IIRC I added them to RHEL a decade ago but I'm not sure if they're still there)
- trymas 11y ago
  Personally, sometimes I want just to see few basic examples at the front of the manual page, with inputs and outputs. Rare manual page has an examples section, or sometimes manual is precise (or uses some terminology you do not know/remember), though is not user-friendly to instantly understand the impact of a command. Like on github. You can find various cool tools, but some include a picture or a gif of example workflow at the top of README, and some don't. Especially I do not understand when some people show their web/gui tool and do not add a screenshot or a gif. So it's the same with man pages for me: I want to use something I do not know or understand, I want to see explanation and/or example at the top explained in a simple manner. If I know the tool, usually I search for the option keywords instantly. Just my $0.02.
  - justincormack 11y ago
    You mean like the excellent FreeBSD man pages, eg tar here https://www.freebsd.org/cgi/man.cgi?query=tar&apropos=0&sektion=0&manpath=FreeBSD+10.2-RELEASE&arch=default&format=html https://www.freebsd.org/cgi/man.cgi?query=tar&apropos=0&sekt... (although they are still not at the top)
- jehna1 11y ago
  This. https://xkcd.com/1168/ https://xkcd.com/1168/
  - chrismorgan 11y ago
    I never got this. I memorised basic usage of tar very quickly and have never had any issues with it since; and even if you didn’t know how to use `tar`, surely `tar --help` would be worth a go? (It’d be the first thing I’d use for an unknown program.)
  - hk__2 11y ago
    Tar options are actually very easy once you take the time to understand them. Want to create an archive? use `-c`. Want to extract? It’s `-x`. From that you know you can use `tar -cf foo.tar foo` (`-f` lets you pass the archive name) and `tar -xf foo.tar`. Want to be verbose? Add `-v`. Want to use gzip compression? Add `-z`. There are a bunch of other options to do more, but just with that you can already understand 99% of what tar is used for.
    - coldtea 11y ago
      >Tar options are actually very easy once you take the time to understand them. That's not the experience of many people. Or maybe, "taking the time to understand them" is not how they want to spend their time, and the mnemonics are bad because the use is not that frequent anyway.
      - tazjin 11y ago
        But the time we're talking about to understand this is less than 5 minutes. Those same people spend more time joking about how complex the options are and linking that xkcd anyways.
        coldtea 11y ago
        Let me rephrase. There's nothing much to "understand". This is not a logical puzzle or a physics lecture. It's an arbitrary set of command line flags and argument order. So what's meant by "understanding" it, is basically "memorize". Sure, if one devoted some time, they could memorize it. Like people can learn the PI to the nth digit. But first, it's not just tar they use -- it's tens of other commands too. Second, a lot of them have clashing flag order or slightly different names for the same arguments. Third, most don't use them that frequently to make it worth it to sit and memorize it. Besides the infrequence of use means that simple memorizing once wont work, as they'll forget them without sitting down again later to refresh their memory. We can memorize complex vim commands because we use them everyday. Commands that we need once a month or once every 3 months, not so much. It would be better for all if tar just did the obvious and intuitive thing.
- buro9 11y ago
  Man pages are manuals. They list all possible ways of controlling the program. Have you seen the man page for curl? http://man.cx/curl http://man.cx/curl If we accept that man pages shouldn't be less than a manual, how then to deliver the top n recipes that demonstrate how the program can be used in the majority of cases? In the case of curl, it's really just a GET, a JSON POST, a file upload... and perhaps add in an auth header or non-standard header. Example: http://stackoverflow.com/questions/356705/how-to-send-a-header-using-a-http-request-through-a-curl-call http://stackoverflow.com/questions/356705/how-to-send-a-head... 458 people upvoted that question, 697 upvoted the answer, hundreds of duplicates of it point to it. In a long man page, well-documented options might as well not exist. You don't need the whole manual all the time, and when someone is busy getting something done they shouldn't be hit with a "Hey, why don't you learn all of this"... they just want to get something done.
  - Tiksi 11y ago
    I mean I don't disagree with the idea behind what you said, but we do have search. You don't have to read the man pages like a book to get use out of them. I'm willing to bet this is quicker than finding the question on stackoverflow: http://paste.click/HrdrGW http://paste.click/HrdrGW And there's even an example.
    - buro9 11y ago
      I'm not sure you understood. Man pages = reference tldr = recipes People learn and use tools different ways. I'm a reference person, it sounds like you are too. But there exists a lot of people who find references hard, but example driven stuff easy (whereas I find examples limiting, and references endlessly useful). Search for those people is difficult, as it's phrased by "this thing I want to do", and not "these keywords I already know". tldr isn't for you and I... it's for those who prefer recipes over references.
      - Tiksi 11y ago
        Like I said, I don't disagree, and I can see the use people get from recipes. And yes, you're right that I'm a "if I need to google it more than 3 times, I'm reading the man pages" kind of person. However that stackoverflow answer is literally a copy and paste from the man pages, with an example (which the man pages I have also contains apparently). The information is the same, the method to search for it is different, but I'm willing to bet my way is faster ;) I don't see anything wrong with tldr, I would have definitely loved to have something like that in the past. I do think that completely ignoring the man pages is a mistake though, since it requires just as little if not less effort as looking it up on stackoverflow, which in this case has the same answer anyways.
- coldtea 11y ago
  >Man pages are really already TLDR pages. They suck for introductory documentation (most times) but are really useful if you just can't quite remember the switch or its parameters. Only if you have the patience and time to go through the tons of flags to find the one you need -- and to decrypt the BS wordings used to describe what each flag does, especially if english isn't your first language. >I don't know what niche this is supposed to fill? The niche for straight to the point command invocation examples for the most common use cases.
morenoh149 11y ago
reminds me of http://bropages.org/ http://bropages.org/
skimmas 11y ago
love the simplicity put in this little tool. Incredibly easy to remember, gives the answer you need 95% of the times, makes it very easy to contribute with new stuff.
deleted 11y ago
[deleted]
Buetol 11y ago
As a side note, `dtrx` is a sane alternative to `tar` that do the right thing by default. http://brettcsmith.org/2007/dtrx/ http://brettcsmith.org/2007/dtrx/ Just `dtrx yourarchive.tar.xz`.
- tazjin 11y ago
  I honestly don't understand the meme of "tar is so hard to use". You only need to know like five parameters (xcvfz) for 99% of use cases, and they're pretty easy to understand.
  - TuringTest 11y ago
    From the manual: "In UNIX or short-option style, each option letter is prefixed with a single dash, as in other command line utilities. If an option takes argument, the argument follows it, either as a separate command line word, or immediately following the option. However, if the option takes an optional argument, the argument must follow the option letter without any intervening whitespace, as in -g/tmp/snar.db. Any number of options not taking arguments can be clustered together after a single dash, e.g. -vkp. Options that take arguments (whether mandatory or optional), can appear at the end of such a cluster, e.g. -vkpf a.tar." When you have several alternative optional syntaxes for the commands, and you mix them with several different mandatory syntaxes for the parameters, the result is way more complex than merely "know five simple parameters for 99% use cases". The following are all valid ways to do exactly the same thing: tar cfv a.tar /etc tar -cvf a.tar /etc tar -c -v -f a.tar /etc tar --create --file a.tar --verbose /etc tar --cre --file=a.tar --verb /etc This offers lots of flexibility, but also means that it will be hard to remember the exact syntax, and that examples that you come by on the net will all look wildly different, making it hard to learn the commands and create a habit by exposure to examples.
- MrBuddyCasino 11y ago
  Looks great, theres also a Brew formula. Not sure I'll remember "dtrx" though...
  - 11y ago
hk__2 11y ago
The issue I have with this kind of projects is that people quickly accept that reading manpages is boring and that they should only use `tldr gcc` or a quick stackoverflow lookup instead of actually learning how to use their tools. It’s like learning how to fish vs. bying fish at the supermarket. Sure, if you know how to fish you can still buy at the supermarket if you’re lazy. But if you don’t you’re stuck with what’s at the supermarket.
- gexos 11y ago
  "It’s like learning how to fish vs. bying fish at the supermarket. Sure, if you know how to fish you can still buy at the supermarket if you’re lazy. But if you don’t you’re stuck with what’s at the supermarket." +1 Comment of the day.
- coldtea 11y ago
  >It’s like learning how to fish vs. bying fish at the supermarket. Sure, if you know how to fish you can still buy at the supermarket if you’re lazy. But if you don’t you’re stuck with what’s at the supermarket If you're already down to the command line, running UNIX commands, and using TLDR you are way beyond "buying fish at the supermarket". And why should you "learning how to use those tools", when what you really want from those tools are the use cases TLDR already covers?
  - jordanpg 11y ago
    Agreed 100 times over. My eyeballs are strained from rolling every time I read some very sage person on SO or HN reply to a well-phrased question or comment with a terse "it's all in the docs". As if 90% of use cases aren't covered by 5 examples. As if we all have unlimited time to spend on reading docs and manpages and "learning how to use the tools". As if there is some intrinsic virtue to "learning how to use the tools". As if the very purpose of sites like SO are something other than distilling the information in docs into some other, more readable form. As if there are no man pages or docs that are absolutely incomprehensible and worth ignoring. No, sorry, this attitude is just another manifestation of standard tech machismo: "real men do it the hard way". Good luck with that!
jkire 11y ago
How does this deal with different versions of a utility having different flags/commands?
- LeonidasXIV 11y ago
  By only supporting the Mac OS X version, apparently, because neither my Debian, Fedora nor Arch have this `brew` tool mentioned on the home page.
draw_down 11y ago
Seems like a good idea, man pages can be almost comically obtuse at times.
- jay-saint 11y ago
  I feel like the examples tldr entries should be required to be written by a third party other than the creator of the software. In my experience the creator of a piece of software or machine always thinks it is simple and writes the man page accordingly.
ravicious 11y ago
Maybe instead of creating something entirely new we could improve the existing thing, that is prepend man pages with some examples?
- ymse 11y ago
  There have been discussions in the past about "standardizing" on an Examples section. It is usually what I miss the most in any manual.
  - nailer 11y ago
    The man maintainers, at least from my own dealings with them, often don't like contributors. "Examples are nice, and I like your changes, but what if Paul Vixie doesn't?" It's easier to fork man completely and take it away from them, Xorg style.
  - dave2000 11y ago
    "I've done this, to fix the problem." "Ah yeah, no need; that problem's been discussed in the past". "Ok, what happened" "IT...WAS...DISCUSSED!"
- pervycreeper 11y ago
  You're free to try to incorporate these into the man pages. The creators of this (brilliant idea, btw, just what I have desired so many times in the past) are under no obligation to do so.
peteretep 11y ago
One thing I love about Perl, which has seemed sorely lacking in many other languages, is the habit of documenting all modules with a "Synopsis" section, which is essentially short examples of use. A good 50% of modules I use I don't need to read further!
coldtea 11y ago
I do find TLDR useful, but is there anything preventing adding it as a standard section of the actual manpages we all use? Perhaps with a switch (man --tldr) or something? Wouldn't a project to add those short examples to manpages be good?
- zuzun 11y ago
  For each example in the TLDR pages repository, find the corresponding man page on your system, render the markdown to groff, insert it as EXAMPLE section before AUTHOR/SEE ALSO or at the end of the file if these sections are missing. See man(7), man-pages(7)
- nikcub 11y ago
  You can add a section 0 to man pages for example (tldr) versions. Man also already supports rendering HTML if that is the preferred format that contributors want to write. With a handful of commands i've got the tldr pages rendering in man: mkdir /usr/local/share/man/man0/ pandoc -f markdown_github -t html https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/tar.md > /usr/local/share/man/man0/tar.0.html export MANPAGER="`which lynx` -stdin" man 0 tar tada. We really shouldn't be rewriting tools and fragmenting community effort to fit a new feature that is already 90% implemented. edit: one idea I do like is having content that is easy to contribute to, such as man pages, in separate repositories. Contributing to open source projects for content writers can often be intimidating - having a pure text separate man page repo that all the distro's use would be great.
  - mch82 11y ago
    Generally agree that augmenting existing man pages is then way to go. However, using a new number to categorize "use cases" or "examples" is probably incorrect. man page categories (1, 2, 3, etc.) are organized by type of command. See: http://www.schweikhardt.net/man_page_howto.html#q2 http://www.schweikhardt.net/man_page_howto.html#q2 Reviewing the convention for man pages, it seems like adding an EXAMPLES section to existing man pages is the correct way to augment the documentation. Definitely support your position that improving existing documentation is the way to go. Just wanted to share my research on how man pages are supposed to work.
Paul_S 11y ago
These should be appended to the top of regular man pages.
- runarberg 11y ago
  function man { cat <(tldr $1) <(/usr/bin/man $1) | less }
sergiotapia 11y ago
Also see bropages! http://bropages.org/ http://bropages.org/ Very interesting tools. I still don't know how to navigate man pages to find what I need.
- krick 11y ago
  Yep, also have used them for a while and even though they're lacking content still, the concept I'd say is rather better than tldr-pages. Contributing is easier and documentation is specifically focused on examples, not trying to replace the original documentation, which should be improved separately, if needed.
no_gravity 11y ago
Instead of installing one of the clients, it might be easier to just put this line into your bash.rc: function tldr { curl https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/$1.md; }
- pervycreeper 11y ago
  Internet access is not a given at all times. One is often more likely to need manuals when there is a problem with it.
  - dyladan 11y ago
    Well to be fair, you can just use the man pages if you don't have network access. Or you could git clone the repo and print it from the repo. I think his point is that this is a problem that is easy to overengineer and really doesn't need that much work to be done.
- stinos 11y ago
  there's also linux/osx/.. pages; but I like the idea so here's some Powershell function tldr($what) { ("common", "linux") | foreach { try { (iwr raw.githubusercontent.com/tldr-pages/tldr/master/pages/$_/$what.md).Content return } catch{} } }
- carlesfe 11y ago
  Even better if you pipe it to a markdown renderer: function tldr() { curl -s https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/"$1.md" | mad -; } You can download `mad` at https://github.com/tj/mad.git https://github.com/tj/mad.git
awalGarg 11y ago
I think man pages aren't always verbose or unreadable. In fact, most of the time, they are pretty easy on eyes for me. But generally, it is not a "tl;dr" that I am looking for in man pages, it is that one thing I need not very often, but can't remember, like "what switch does `git pull` take to rebase" (ok, not very good of an example, but since these are things I "can't remember", I can't pull one out of my head right now). And for these cases, `less`, my default pager, has excellent searching capabilities. For instance, I needed to check how to tell OpenVPN CLI client to take username and password from a file instead of stdin. I knew I had done it before, but didn't know which flag it was... just the third instance of "username" on the openvpn manpage called it out (--auth-user-pass). Such things, are IMO, more often needed, but not something a tl;dr would cover. Great project anyways :)
geff82 11y ago
most useful thing ever. All you need in 90% of the time. Hope to see it in Redhat soon :)
ap22213 11y ago
Cool idea - but like others allude, it would be useful if the TRDR content was organized along with the man page content. Even better: it'd be nice if there was a repository of just content that was structured in some standardized way. Then, some MVC-like system could easily consume all of the content.
haenx 11y ago
What about https://github.com/chrisallenlane/cheat https://github.com/chrisallenlane/cheat ?
- waldir 11y ago
  Didn't know about that one, thanks for the link! I've added it to the discussion at https://github.com/tldr-pages/tldr/issues/266 https://github.com/tldr-pages/tldr/issues/266
reitanqild 11y ago
Brilliant idea! Now, did I misunderstand or does this need npm?
- hit8run 11y ago
  As far as I see there are different clients available as options. You don't necessarily need npm but I don't know in what shape the clients are. For example the go client seems broken to me (hard coded wrong tldr-page url, no caching, platform is always set to common) https://github.com/pranavraja/tldr https://github.com/pranavraja/tldr I like the idea. Maybe I will create a better Go client.
- cp9 11y ago
  You can use the python one. I tried it and the npm one and the npm one seems like it's in much better shape (colors were all screwed up on the python one). so, I guess YMMV
teddyh 11y ago
That project is a symptom of manual pages not having good “EXAMPLES” sections. The examples on that web page should be contributed upstream to the manuals pages of the software that they are for. If you want a fast way to read the EXAMPLES section only for a command, here is a shell function which creates an ‘eg’ command which only displays the “EXAMPLES” section of manual pages: eg(){ MAN_KEEP_FORMATTING=1 man "$@" 2>/dev/null \ | sed --quiet --expression='/^E$\x08.$X$\x08.$\?A$\x08.$\?M$\x08.$\?P$\x08.$\?L$\x08.$\?E/{:a;p;n;/^[^ ]/q;ba}' \ | ${MANPAGER:-${PAGER:-pager -s}} } Usage: $ eg tar EXAMPLES Create archive.tar from files foo and bar. tar -cf archive.tar foo bar List all files in archive.tar verbosely. tar -tvf archive.tar Extract all files from archive.tar. tar -xf archive.tar $ (Previously: https://news.ycombinator.com/item?id=10025216 https://news.ycombinator.com/item?id=10025216, https://news.ycombinator.com/item?id=7123328 https://news.ycombinator.com/item?id=7123328)
- vitd 11y ago
  I don't mean to sound cynical, but if oft-used man pages haven't already added "EXAMPLES" sections over the last 30 years, how likely is it that they'd add them now? This project exists because man has failed to as useful as it needs to be for current users. I don't think that adding this info to the "EXAMPLES" sections will help anything, personally.
  - deleted 11y ago
    [deleted]
  - deleted 11y ago
    [deleted]
  - klodolph 11y ago
    > if oft-used man pages haven't already added "EXAMPLES" sections over the last 30 years, how likely is it that they'd add them now? Lots of reasons they didn't add examples earlier. Maybe nobody happened to care, but if you submit a patch, they'll gladly accept it? Why so cynical?
  - 11y ago
mch82 11y ago
What if we put community energy into contributing improvements to existing man pages for open source projects? As many commenters have noted, it is possible to accomplish the goals of TLDR by improving existing man pages, without establishing a separate documentation system. A man page can be formatted to include any number of sections. All that is needed is an EXAMPLES section that lists examples for typical command usage. Here are instructions for creating a man page: http://www.schweikhardt.net/man_page_howto.html#q3 http://www.schweikhardt.net/man_page_howto.html#q3 Side note... isn't the usage of TL;DR in this project incorrect? TL;DR is a synonym for "abstract", "synopsis", and "executive summary". It is already confusing enough to use TL;DR in place of those words without overloading the term to mean "tasks", "example usage", or "typical use cases".
- falsedan 11y ago
  Historical man pages have been the comprehensive reference for a command. You can't write a document that serves both as a gentle introduction to a tool for a new user, and retain the encyclopedic list of every possible option. Adding EXAMPLE/SYNOPSIS to existing man pages helps a little, but tldr is squarely aimed at lowering the barrier for entry.
  - mch82 11y ago
    For hundreds of years we've been writing summative introductions called "abstracts" to long documents called "journal articles", "lede" paragraphs introduce "journalism", and "introductions" summarize "books". People understand how to use these conventions. How is it easier for the end user to have to learn to install, use, and understand an additional tool chain? How is it easier for a project maintainer to manage documentation in multiple locations? https://xkcd.com/1319/ https://xkcd.com/1319/
    - falsedan 11y ago
      It's not easy? It's hard to write documentation that's suited for reference AND expert users AND new users. All of the materials you mentioned are for informing/entertaining people, not training them to acquire new skills. There is a field of study specifically for this: education. Also, be less patronising.
cheshire137 11y ago
Yes! Thank you, all I want is an example of how to use the command. Man pages never help me, they give a bunch of non-concrete examples. I always just Google for the command and someone's blog post helps me out.
oldmanjay 11y ago
If there was anything the frozen computer interface of the 70s needed to complete itself, it was silly Internet neologisms. Thanks, author, for bringing the worst of several eras together.
masukomi 11y ago
To everyone suggesting people send patches in to the original repos instead of using this, or anything like it: Have you ever tried hunting down the canonical source repo for any of those ancient commands? It's nigh-impossible for many (most?). Seriously, give it a try for one of the small ones that haven't been touched in a few years.
- joshstrange 11y ago
  If if you do good luck getting your patch merged, wait a year for the next release, and then sit back and wait a few years (if ever) for the versions to trickle into real distributions Just look at the timeline of the last 4 releases of Tar: Tar 1.28 - 27 Jul 2014 Tar 1.27.1 - 17 Nov 2013 Tar 1.27 - 20 Oct 2013 Tar 1.26 - 12 Mar 2011
humility 11y ago
there's also a ruby gem called bropages!(gem install bropages) example usage: bro man even allows user submission/voting on answers
ajones 11y ago
TL;DR a collection of TL;DRs for common *nix commands with clients to display the shorter docs
debaserab2 11y ago
Seems like most tools basically provide this with a -h or --help switch.
niuzeta 11y ago
I find it rather redundant to bropages: http://bropages.org/ http://bropages.org/ Still, a readable manpage alternative is always welcome!
dcposch 11y ago
looks just like bro pages bropages.org

401 points by tkfx 11y ago

Man pages are really already TLDR pages. They suck for introductory documentation (most times) but are really useful if you just can't quite remember the switch or its parameters. I don't know what niche this is supposed to fill?

Mojah 11y ago
I like it because it introduces practical, real-world example commands. Most manpages don't offer those but instead list all parameters and potential input (1) That's nice, but for a quick "which command do I need?" scenario I prefer the examples that `tldr` can provide. (1) Yes, some manpages do provide examples at the very bottom, but not all manpages do.
- mystikal 11y ago
  The difference between man gcc and tldr gcc is dramatic.
- Gravityloss 11y ago
  Even the examples are usually completely alien to real usage.
nailer 11y ago
TLDR pages are tasked based. Man pages are references to all possible switches in an app. Eg, the tar man page has a focus on tape archiving, referencing $TAPE and /dev/mt0 and didn't used to have examples (IIRC I added them to RHEL a decade ago but I'm not sure if they're still there)
trymas 11y ago
Personally, sometimes I want just to see few basic examples at the front of the manual page, with inputs and outputs. Rare manual page has an examples section, or sometimes manual is precise (or uses some terminology you do not know/remember), though is not user-friendly to instantly understand the impact of a command. Like on github. You can find various cool tools, but some include a picture or a gif of example workflow at the top of README, and some don't. Especially I do not understand when some people show their web/gui tool and do not add a screenshot or a gif. So it's the same with man pages for me: I want to use something I do not know or understand, I want to see explanation and/or example at the top explained in a simple manner. If I know the tool, usually I search for the option keywords instantly. Just my $0.02.
- justincormack 11y ago
  You mean like the excellent FreeBSD man pages, eg tar here https://www.freebsd.org/cgi/man.cgi?query=tar&apropos=0&sektion=0&manpath=FreeBSD+10.2-RELEASE&arch=default&format=html https://www.freebsd.org/cgi/man.cgi?query=tar&apropos=0&sekt... (although they are still not at the top)
jehna1 11y ago
This. https://xkcd.com/1168/ https://xkcd.com/1168/
- chrismorgan 11y ago
  I never got this. I memorised basic usage of tar very quickly and have never had any issues with it since; and even if you didn’t know how to use `tar`, surely `tar --help` would be worth a go? (It’d be the first thing I’d use for an unknown program.)
- hk__2 11y ago
  Tar options are actually very easy once you take the time to understand them. Want to create an archive? use `-c`. Want to extract? It’s `-x`. From that you know you can use `tar -cf foo.tar foo` (`-f` lets you pass the archive name) and `tar -xf foo.tar`. Want to be verbose? Add `-v`. Want to use gzip compression? Add `-z`. There are a bunch of other options to do more, but just with that you can already understand 99% of what tar is used for.
  - coldtea 11y ago
    >Tar options are actually very easy once you take the time to understand them. That's not the experience of many people. Or maybe, "taking the time to understand them" is not how they want to spend their time, and the mnemonics are bad because the use is not that frequent anyway.
    - tazjin 11y ago
      But the time we're talking about to understand this is less than 5 minutes. Those same people spend more time joking about how complex the options are and linking that xkcd anyways.
      - coldtea 11y ago
        Let me rephrase. There's nothing much to "understand". This is not a logical puzzle or a physics lecture. It's an arbitrary set of command line flags and argument order. So what's meant by "understanding" it, is basically "memorize". Sure, if one devoted some time, they could memorize it. Like people can learn the PI to the nth digit. But first, it's not just tar they use -- it's tens of other commands too. Second, a lot of them have clashing flag order or slightly different names for the same arguments. Third, most don't use them that frequently to make it worth it to sit and memorize it. Besides the infrequence of use means that simple memorizing once wont work, as they'll forget them without sitting down again later to refresh their memory. We can memorize complex vim commands because we use them everyday. Commands that we need once a month or once every 3 months, not so much. It would be better for all if tar just did the obvious and intuitive thing.
buro9 11y ago
Man pages are manuals. They list all possible ways of controlling the program. Have you seen the man page for curl? http://man.cx/curl http://man.cx/curl If we accept that man pages shouldn't be less than a manual, how then to deliver the top n recipes that demonstrate how the program can be used in the majority of cases? In the case of curl, it's really just a GET, a JSON POST, a file upload... and perhaps add in an auth header or non-standard header. Example: http://stackoverflow.com/questions/356705/how-to-send-a-header-using-a-http-request-through-a-curl-call http://stackoverflow.com/questions/356705/how-to-send-a-head... 458 people upvoted that question, 697 upvoted the answer, hundreds of duplicates of it point to it. In a long man page, well-documented options might as well not exist. You don't need the whole manual all the time, and when someone is busy getting something done they shouldn't be hit with a "Hey, why don't you learn all of this"... they just want to get something done.
- Tiksi 11y ago
  I mean I don't disagree with the idea behind what you said, but we do have search. You don't have to read the man pages like a book to get use out of them. I'm willing to bet this is quicker than finding the question on stackoverflow: http://paste.click/HrdrGW http://paste.click/HrdrGW And there's even an example.
  - buro9 11y ago
    I'm not sure you understood. Man pages = reference tldr = recipes People learn and use tools different ways. I'm a reference person, it sounds like you are too. But there exists a lot of people who find references hard, but example driven stuff easy (whereas I find examples limiting, and references endlessly useful). Search for those people is difficult, as it's phrased by "this thing I want to do", and not "these keywords I already know". tldr isn't for you and I... it's for those who prefer recipes over references.
    - Tiksi 11y ago
      Like I said, I don't disagree, and I can see the use people get from recipes. And yes, you're right that I'm a "if I need to google it more than 3 times, I'm reading the man pages" kind of person. However that stackoverflow answer is literally a copy and paste from the man pages, with an example (which the man pages I have also contains apparently). The information is the same, the method to search for it is different, but I'm willing to bet my way is faster ;) I don't see anything wrong with tldr, I would have definitely loved to have something like that in the past. I do think that completely ignoring the man pages is a mistake though, since it requires just as little if not less effort as looking it up on stackoverflow, which in this case has the same answer anyways.
coldtea 11y ago
>Man pages are really already TLDR pages. They suck for introductory documentation (most times) but are really useful if you just can't quite remember the switch or its parameters. Only if you have the patience and time to go through the tons of flags to find the one you need -- and to decrypt the BS wordings used to describe what each flag does, especially if english isn't your first language. >I don't know what niche this is supposed to fill? The niche for straight to the point command invocation examples for the most common use cases.

morenoh149 11y ago

reminds me of http://bropages.org/ http://bropages.org/

skimmas 11y ago

love the simplicity put in this little tool. Incredibly easy to remember, gives the answer you need 95% of the times, makes it very easy to contribute with new stuff.

deleted 11y ago

[deleted]

Buetol 11y ago

As a side note, `dtrx` is a sane alternative to `tar` that do the right thing by default. http://brettcsmith.org/2007/dtrx/ http://brettcsmith.org/2007/dtrx/ Just `dtrx yourarchive.tar.xz`.

tazjin 11y ago
I honestly don't understand the meme of "tar is so hard to use". You only need to know like five parameters (xcvfz) for 99% of use cases, and they're pretty easy to understand.
- TuringTest 11y ago
  From the manual: "In UNIX or short-option style, each option letter is prefixed with a single dash, as in other command line utilities. If an option takes argument, the argument follows it, either as a separate command line word, or immediately following the option. However, if the option takes an optional argument, the argument must follow the option letter without any intervening whitespace, as in -g/tmp/snar.db. Any number of options not taking arguments can be clustered together after a single dash, e.g. -vkp. Options that take arguments (whether mandatory or optional), can appear at the end of such a cluster, e.g. -vkpf a.tar." When you have several alternative optional syntaxes for the commands, and you mix them with several different mandatory syntaxes for the parameters, the result is way more complex than merely "know five simple parameters for 99% use cases". The following are all valid ways to do exactly the same thing: tar cfv a.tar /etc tar -cvf a.tar /etc tar -c -v -f a.tar /etc tar --create --file a.tar --verbose /etc tar --cre --file=a.tar --verb /etc This offers lots of flexibility, but also means that it will be hard to remember the exact syntax, and that examples that you come by on the net will all look wildly different, making it hard to learn the commands and create a habit by exposure to examples.
MrBuddyCasino 11y ago
Looks great, theres also a Brew formula. Not sure I'll remember "dtrx" though...
- 11y ago

hk__2 11y ago

The issue I have with this kind of projects is that people quickly accept that reading manpages is boring and that they should only use `tldr gcc` or a quick stackoverflow lookup instead of actually learning how to use their tools. It’s like learning how to fish vs. bying fish at the supermarket. Sure, if you know how to fish you can still buy at the supermarket if you’re lazy. But if you don’t you’re stuck with what’s at the supermarket.

gexos 11y ago
"It’s like learning how to fish vs. bying fish at the supermarket. Sure, if you know how to fish you can still buy at the supermarket if you’re lazy. But if you don’t you’re stuck with what’s at the supermarket." +1 Comment of the day.
coldtea 11y ago
>It’s like learning how to fish vs. bying fish at the supermarket. Sure, if you know how to fish you can still buy at the supermarket if you’re lazy. But if you don’t you’re stuck with what’s at the supermarket If you're already down to the command line, running UNIX commands, and using TLDR you are way beyond "buying fish at the supermarket". And why should you "learning how to use those tools", when what you really want from those tools are the use cases TLDR already covers?
- jordanpg 11y ago
  Agreed 100 times over. My eyeballs are strained from rolling every time I read some very sage person on SO or HN reply to a well-phrased question or comment with a terse "it's all in the docs". As if 90% of use cases aren't covered by 5 examples. As if we all have unlimited time to spend on reading docs and manpages and "learning how to use the tools". As if there is some intrinsic virtue to "learning how to use the tools". As if the very purpose of sites like SO are something other than distilling the information in docs into some other, more readable form. As if there are no man pages or docs that are absolutely incomprehensible and worth ignoring. No, sorry, this attitude is just another manifestation of standard tech machismo: "real men do it the hard way". Good luck with that!

jkire 11y ago

How does this deal with different versions of a utility having different flags/commands?

LeonidasXIV 11y ago
By only supporting the Mac OS X version, apparently, because neither my Debian, Fedora nor Arch have this `brew` tool mentioned on the home page.

draw_down 11y ago

Seems like a good idea, man pages can be almost comically obtuse at times.

jay-saint 11y ago
I feel like the examples tldr entries should be required to be written by a third party other than the creator of the software. In my experience the creator of a piece of software or machine always thinks it is simple and writes the man page accordingly.

ravicious 11y ago

Maybe instead of creating something entirely new we could improve the existing thing, that is prepend man pages with some examples?

ymse 11y ago
There have been discussions in the past about "standardizing" on an Examples section. It is usually what I miss the most in any manual.
- nailer 11y ago
  The man maintainers, at least from my own dealings with them, often don't like contributors. "Examples are nice, and I like your changes, but what if Paul Vixie doesn't?" It's easier to fork man completely and take it away from them, Xorg style.
- dave2000 11y ago
  "I've done this, to fix the problem." "Ah yeah, no need; that problem's been discussed in the past". "Ok, what happened" "IT...WAS...DISCUSSED!"
pervycreeper 11y ago
You're free to try to incorporate these into the man pages. The creators of this (brilliant idea, btw, just what I have desired so many times in the past) are under no obligation to do so.

peteretep 11y ago

One thing I love about Perl, which has seemed sorely lacking in many other languages, is the habit of documenting all modules with a "Synopsis" section, which is essentially short examples of use. A good 50% of modules I use I don't need to read further!

coldtea 11y ago

I do find TLDR useful, but is there anything preventing adding it as a standard section of the actual manpages we all use? Perhaps with a switch (man --tldr) or something? Wouldn't a project to add those short examples to manpages be good?

zuzun 11y ago
For each example in the TLDR pages repository, find the corresponding man page on your system, render the markdown to groff, insert it as EXAMPLE section before AUTHOR/SEE ALSO or at the end of the file if these sections are missing. See man(7), man-pages(7)
nikcub 11y ago
You can add a section 0 to man pages for example (tldr) versions. Man also already supports rendering HTML if that is the preferred format that contributors want to write. With a handful of commands i've got the tldr pages rendering in man: mkdir /usr/local/share/man/man0/ pandoc -f markdown_github -t html https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/tar.md > /usr/local/share/man/man0/tar.0.html export MANPAGER="`which lynx` -stdin" man 0 tar tada. We really shouldn't be rewriting tools and fragmenting community effort to fit a new feature that is already 90% implemented. edit: one idea I do like is having content that is easy to contribute to, such as man pages, in separate repositories. Contributing to open source projects for content writers can often be intimidating - having a pure text separate man page repo that all the distro's use would be great.
- mch82 11y ago
  Generally agree that augmenting existing man pages is then way to go. However, using a new number to categorize "use cases" or "examples" is probably incorrect. man page categories (1, 2, 3, etc.) are organized by type of command. See: http://www.schweikhardt.net/man_page_howto.html#q2 http://www.schweikhardt.net/man_page_howto.html#q2 Reviewing the convention for man pages, it seems like adding an EXAMPLES section to existing man pages is the correct way to augment the documentation. Definitely support your position that improving existing documentation is the way to go. Just wanted to share my research on how man pages are supposed to work.

Paul_S 11y ago

These should be appended to the top of regular man pages.

runarberg 11y ago
function man { cat <(tldr $1) <(/usr/bin/man $1) | less }

sergiotapia 11y ago

Also see bropages! http://bropages.org/ http://bropages.org/ Very interesting tools. I still don't know how to navigate man pages to find what I need.

krick 11y ago
Yep, also have used them for a while and even though they're lacking content still, the concept I'd say is rather better than tldr-pages. Contributing is easier and documentation is specifically focused on examples, not trying to replace the original documentation, which should be improved separately, if needed.

no_gravity 11y ago

Instead of installing one of the clients, it might be easier to just put this line into your bash.rc: function tldr { curl https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/$1.md; }

pervycreeper 11y ago
Internet access is not a given at all times. One is often more likely to need manuals when there is a problem with it.
- dyladan 11y ago
  Well to be fair, you can just use the man pages if you don't have network access. Or you could git clone the repo and print it from the repo. I think his point is that this is a problem that is easy to overengineer and really doesn't need that much work to be done.
stinos 11y ago
there's also linux/osx/.. pages; but I like the idea so here's some Powershell function tldr($what) { ("common", "linux") | foreach { try { (iwr raw.githubusercontent.com/tldr-pages/tldr/master/pages/$_/$what.md).Content return } catch{} } }
carlesfe 11y ago
Even better if you pipe it to a markdown renderer: function tldr() { curl -s https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/"$1.md" | mad -; } You can download `mad` at https://github.com/tj/mad.git https://github.com/tj/mad.git

awalGarg 11y ago

I think man pages aren't always verbose or unreadable. In fact, most of the time, they are pretty easy on eyes for me. But generally, it is not a "tl;dr" that I am looking for in man pages, it is that one thing I need not very often, but can't remember, like "what switch does `git pull` take to rebase" (ok, not very good of an example, but since these are things I "can't remember", I can't pull one out of my head right now). And for these cases, `less`, my default pager, has excellent searching capabilities. For instance, I needed to check how to tell OpenVPN CLI client to take username and password from a file instead of stdin. I knew I had done it before, but didn't know which flag it was... just the third instance of "username" on the openvpn manpage called it out (--auth-user-pass). Such things, are IMO, more often needed, but not something a tl;dr would cover. Great project anyways :)

geff82 11y ago

most useful thing ever. All you need in 90% of the time. Hope to see it in Redhat soon :)

ap22213 11y ago

Cool idea - but like others allude, it would be useful if the TRDR content was organized along with the man page content. Even better: it'd be nice if there was a repository of just content that was structured in some standardized way. Then, some MVC-like system could easily consume all of the content.

haenx 11y ago

What about https://github.com/chrisallenlane/cheat https://github.com/chrisallenlane/cheat ?

waldir 11y ago
Didn't know about that one, thanks for the link! I've added it to the discussion at https://github.com/tldr-pages/tldr/issues/266 https://github.com/tldr-pages/tldr/issues/266

reitanqild 11y ago

Brilliant idea! Now, did I misunderstand or does this need npm?

hit8run 11y ago
As far as I see there are different clients available as options. You don't necessarily need npm but I don't know in what shape the clients are. For example the go client seems broken to me (hard coded wrong tldr-page url, no caching, platform is always set to common) https://github.com/pranavraja/tldr https://github.com/pranavraja/tldr I like the idea. Maybe I will create a better Go client.
cp9 11y ago
You can use the python one. I tried it and the npm one and the npm one seems like it's in much better shape (colors were all screwed up on the python one). so, I guess YMMV

teddyh 11y ago

That project is a symptom of manual pages not having good “EXAMPLES” sections. The examples on that web page should be contributed upstream to the manuals pages of the software that they are for. If you want a fast way to read the EXAMPLES section only for a command, here is a shell function which creates an ‘eg’ command which only displays the “EXAMPLES” section of manual pages: eg(){ MAN_KEEP_FORMATTING=1 man "$@" 2>/dev/null \ | sed --quiet --expression='/^E$\x08.$X$\x08.$\?A$\x08.$\?M$\x08.$\?P$\x08.$\?L$\x08.$\?E/{:a;p;n;/^[^ ]/q;ba}' \ | ${MANPAGER:-${PAGER:-pager -s}} } Usage: $ eg tar EXAMPLES Create archive.tar from files foo and bar. tar -cf archive.tar foo bar List all files in archive.tar verbosely. tar -tvf archive.tar Extract all files from archive.tar. tar -xf archive.tar $ (Previously: https://news.ycombinator.com/item?id=10025216 https://news.ycombinator.com/item?id=10025216, https://news.ycombinator.com/item?id=7123328 https://news.ycombinator.com/item?id=7123328)

vitd 11y ago
I don't mean to sound cynical, but if oft-used man pages haven't already added "EXAMPLES" sections over the last 30 years, how likely is it that they'd add them now? This project exists because man has failed to as useful as it needs to be for current users. I don't think that adding this info to the "EXAMPLES" sections will help anything, personally.
- deleted 11y ago
  [deleted]
- deleted 11y ago
  [deleted]
- klodolph 11y ago
  > if oft-used man pages haven't already added "EXAMPLES" sections over the last 30 years, how likely is it that they'd add them now? Lots of reasons they didn't add examples earlier. Maybe nobody happened to care, but if you submit a patch, they'll gladly accept it? Why so cynical?
- 11y ago

mch82 11y ago

What if we put community energy into contributing improvements to existing man pages for open source projects? As many commenters have noted, it is possible to accomplish the goals of TLDR by improving existing man pages, without establishing a separate documentation system. A man page can be formatted to include any number of sections. All that is needed is an EXAMPLES section that lists examples for typical command usage. Here are instructions for creating a man page: http://www.schweikhardt.net/man_page_howto.html#q3 http://www.schweikhardt.net/man_page_howto.html#q3 Side note... isn't the usage of TL;DR in this project incorrect? TL;DR is a synonym for "abstract", "synopsis", and "executive summary". It is already confusing enough to use TL;DR in place of those words without overloading the term to mean "tasks", "example usage", or "typical use cases".

falsedan 11y ago
Historical man pages have been the comprehensive reference for a command. You can't write a document that serves both as a gentle introduction to a tool for a new user, and retain the encyclopedic list of every possible option. Adding EXAMPLE/SYNOPSIS to existing man pages helps a little, but tldr is squarely aimed at lowering the barrier for entry.
- mch82 11y ago
  For hundreds of years we've been writing summative introductions called "abstracts" to long documents called "journal articles", "lede" paragraphs introduce "journalism", and "introductions" summarize "books". People understand how to use these conventions. How is it easier for the end user to have to learn to install, use, and understand an additional tool chain? How is it easier for a project maintainer to manage documentation in multiple locations? https://xkcd.com/1319/ https://xkcd.com/1319/
  - falsedan 11y ago
    It's not easy? It's hard to write documentation that's suited for reference AND expert users AND new users. All of the materials you mentioned are for informing/entertaining people, not training them to acquire new skills. There is a field of study specifically for this: education. Also, be less patronising.

cheshire137 11y ago

Yes! Thank you, all I want is an example of how to use the command. Man pages never help me, they give a bunch of non-concrete examples. I always just Google for the command and someone's blog post helps me out.

oldmanjay 11y ago

If there was anything the frozen computer interface of the 70s needed to complete itself, it was silly Internet neologisms. Thanks, author, for bringing the worst of several eras together.

masukomi 11y ago

To everyone suggesting people send patches in to the original repos instead of using this, or anything like it: Have you ever tried hunting down the canonical source repo for any of those ancient commands? It's nigh-impossible for many (most?). Seriously, give it a try for one of the small ones that haven't been touched in a few years.

joshstrange 11y ago
If if you do good luck getting your patch merged, wait a year for the next release, and then sit back and wait a few years (if ever) for the versions to trickle into real distributions Just look at the timeline of the last 4 releases of Tar: Tar 1.28 - 27 Jul 2014 Tar 1.27.1 - 17 Nov 2013 Tar 1.27 - 20 Oct 2013 Tar 1.26 - 12 Mar 2011

humility 11y ago

there's also a ruby gem called bropages!(gem install bropages) example usage: bro man even allows user submission/voting on answers

ajones 11y ago

TL;DR a collection of TL;DRs for common *nix commands with clients to display the shorter docs

debaserab2 11y ago

Seems like most tools basically provide this with a -h or --help switch.

niuzeta 11y ago

I find it rather redundant to bropages: http://bropages.org/ http://bropages.org/ Still, a readable manpage alternative is always welcome!

dcposch 11y ago

looks just like bro pages bropages.org