TLDR pages

[teddyh]

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=7123328)

[coldtea]

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?

[ravicious]

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

[ymse]

There have been discussions in the past about "standardizing" on an Examples section. It is usually what I miss the most in any manual.

[pervycreeper]

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.

[niuzeta]

I find it rather redundant to bropages: http://bropages.org/

Still, a readable manpage alternative is always welcome!

[masukomi]

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]

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

[no_gravity]

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; }

[carlesfe]

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

[stinos]

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{}
    }
  }

[pervycreeper]

Internet access is not a given at all times. One is often more likely to need manuals when there is a problem with it.

[sergiotapia]

Also see bropages! http://bropages.org/

Very interesting tools. I still don't know how to navigate man pages to find what I need.

[krick]

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.

[peteretep]

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!

[Buetol]

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

Just `dtrx yourarchive.tar.xz`.

[tazjin]

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.

[MrBuddyCasino]

Looks great, theres also a Brew formula. Not sure I'll remember "dtrx" though...

[awalGarg]

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 :)

[morenoh149]

reminds me of http://bropages.org/

[brillenfux]

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?

[buro9]

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

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-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.

[trymas]

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.

[coldtea]

>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.

[Mojah]

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.

[jehna1]

This.

https://xkcd.com/1168/

[nailer]

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)

[hk__2]

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.

[coldtea]

>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?

[kbart]

Continuing your tool analogy, if I used a hammer only to drive a nail, why would I need to read the whole manual of building a wooden house? Knowing your tool is important, but I find myself spending way too much time reading manpages and looking for how to accomplish a trivial task on Linux, so TLDR for most common (simple) use cases looks like a great idea.

[ZenoArrow]

Nobody can be an expert in every single tool they use, furthermore it's a waste of time if you have the option of learning things when the need arises. Not only would you have forgotten most of the text of man pages after reading it, you're also unlikely to ever use most of the options you found in them.

The important first step in learning how to use a command line tool is to have a first working example, i.e. you've made the tool do something you wanted. From there, all you need to know is how to find out more about what it can do. Skim read through some examples, anything else you think could be useful? Try it out. The rest can be forgotten. There's no harm in keeping knowledge outside our memory if we know how to research it if needed.

[manigandham]

How is this much different from today? plenty of people just learn what they need from Google for their use case without reading through man pages and understanding every option.

If you need more than the supermarket... then learn how to fish?

[beshrkayali]

That's true, but I don't think it'd be a problem since you won't be able to really understand how something works and eventually you'd not know how to use the thing.

There's always a wrong way to use something. The good thing is that this is not being promoted as a replacement, but rather a helpful addition. I see it very useful as an alternative to hunting down for tutorials before you want to use some tool to figure out the details (a good example in this case would be something like lxc/lxd) or as a quick memory jogger, the examples that can be provided in a tldr man page could even have a specific context, like a cheatsheet kind of a man page.

[nommm-nommm]

Thats like saying you dont know how to fish unless you learn the detailed operation of 10 different types of fishing boats. None of which you have access to, you're fishing from the dock and your budget is $20.

[lunchbox]

Yes but overall, isn't it better to at least have the choice to go to the supermarket? (As you kind of acknowledge in your own example.)

[iamtew]

Agreed, currently the pages only show quick syntax examples, would be good to have a brief description of the tool and what it does.

Also perhaps have a tldr page on how to read man pages could be useful.

Or this: http://www.tfug.org/helpdesk/general/man.html

[wtbob]

> It’s like learning how to fish vs. bying fish at the supermarket.

And then there are the sad misguided souls using fish as their login shells (I kid, I kid…).

[logingone]

I was surprised the other day when I was reading something about containers, and the author explained what the touch command does.

[gexos]

"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.

[mch82]

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

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".

[Paul_S]

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

[runarberg]

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

[jkire]

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

[LeonidasXIV]

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.

[ap22213]

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]

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

[waldir]

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

[cheshire137]

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.

[skimmas]

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.