tldr, what’s missing from Unix ‘man’ pages

Today’s article is an introduction to the ‘tldr’ utility, a collection of simplified and community-driven man pages. ‘tldr’ enhances Unix/Linux by providing clear, real-world examples for using command line utilities.

When I was a kid, I had the kind of parents who would never tell you the meaning of a word.
“Get the dictionary and look it up,” I was told over and over.
It was good for me, of course, as a learning exercise, but at the time, it seemed almost punitive.
“Ugh, do I haaaave to? Can’t you just tell me??”

Well, if you’re like me, that’s how it feels to work with Unix “man’ pages–you know that all the answers to your questions are in there, somewhere, but the compilers of the pages seem to have forsaken readability for completeness and uniformity.
That doesn’t help, when some commands are notoriously hard to remember:

Unix ‘man’ pages have been around since 1971, first written by Dennis Ritchie and Ken Thompson, the most venerated names in Unix. They are necessary and thorough, don’t get me wrong. I have nothing but respect for them. It’s just that, well, once in a while, they were a bit more, readable and perhaps, concise. For example, here’s (a bit of) what ‘man’ has to say about the ‘ls’ command:

$ man ls
LS(1) User Commands LS(1)

NAME
ls – list directory contents

SYNOPSIS
ls [OPTION]… [FILE]…

DESCRIPTION
List information about the FILEs (the current directory by default). Sort entries alphabetically if none of -cftuvSUX nor –sort is specified.

Mandatory arguments to long options are mandatory for short options too.

-c with -lt: sort by, and show, ctime (time of last modification of file status information); with -l: show ctime and sort by name; otherwise: sort by ctime, newest first

(That’s just the start. It goes on for a total of 206 lines on my system.)
Reading that feels a bit like taking that long walk to the bookshelf to open the dictionary, only to be overwhelmed with seemingly irrelevant information, when the information you actually needed could have been cleared up with an example or two. (Again, I’m not advocating the dumbing down of the ‘man’ page system–it’s comprehensive, as it needs to be. It’s just that there’s room for something more, especially as more and more casual users discover Linux.)

ls is one of the simplest commands in the *nix shell. Essentially, it lists out the contents of a directory. You can run it by itself:

$ ls
bar baz corge foo quux quuz qux

That will list out the names of the non-hidden files in a directory. If you want to see the hidden files, you add the ‘-a’ option:

$ ls -a
. .. bar baz corge foo .hidden_file quux quuz qux

If you want to list out pretty much everything, add a bunch more options, that spell out “-Flag” (That’s 4 options, ‘F’, ‘l’, ‘a’ and ‘g’, not a word. ‘galF’ would work as well, but ‘Flag’ is easier to remember.):

That was even easier than Googling stackoverflow. (Of course, if you were to *ask* on stackoverflow something as simple as options for ‘ls’, you’d immediately get sent to the ‘man’ pages.) Fortunately, there are places to go for questions like this.

If you’re not ready to install tldr on your own system yet, you can always use the online version.

I hope this has been helpful. I only found out about ‘tldr’ this morning, as it was linked to from a post on Reddit and wanted to share it with you all.