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:

tar tldr

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.

-a, –all
do not ignore entries starting with .

-A, –almost-all
do not list implied . and ..

–author
with -l, print the author of each file

-b, –escape
print C-style escapes for nongraphic characters

–block-size=SIZE
scale sizes by SIZE before printing them; e.g., ‘–block-size=M’ prints sizes in units of 1,048,576 bytes; see SIZE format below

-B, –ignore-backups
do not list implied entries ending with ~

-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.):
$ ls -Flag
total 48
drwxrwxr-x 3 jim 4096 Jun 6 17:45 ./
drwxr-xr-x 43 jim 4096 Jun 6 17:45 ../
-rw-rw-r– 1 jim 11962 Jun 6 17:41 bar
-rw-rw-r– 1 jim 0 Jun 6 17:42 baz
-rw-rw-r– 1 jim 544 Jun 6 17:44 corge
-rw-rw-r– 1 jim 7771 Jun 6 17:41 foo
-rw-rw-r– 1 jim 3259 Jun 6 17:45 .hidden_file
-rw-rw-r– 1 jim 4 Jun 6 17:43 quux
-rw-rw-r– 1 jim 182 Jun 6 17:44 quuz
drwxrwxr-x 2 jim 4096 Jun 6 17:43 qux/

Those are (almost) all of the options I’ve ever bothered to memorize. According to ‘man’ there are 59 different options, but no user-friendly examples, accessible for a newbie, or someone in a hurry.

'tldr' to the rescue!
The ‘tldr’ Github page describes itself as:
“A collection of simplified and community-driven man pages.”
That sounds pretty promising. Let’s install it and try it out!

$ sudo npm install -g tldr

(Unfortunately, on two of my systems, that produced hundreds of lines of errors about ‘node-gyp’ and something called ‘webworker-threads’. No worry, there’s a ‘snap’ package I can install:
$ sudo snap install tldr

which worked without a hitch.)
Let’s try it out with ‘ls’:
$ tldr ls
Page not found. Updating cache ..
Creating index…
Done

ls

List directory contents.

– List files one per line:
ls -1

– List all files, including hidden files:
ls -a

– Long format list (permissions, ownership, size and modification date) of all files:
ls -la

– Long format list with size displayed using human readable units (KB, MB, GB):
ls -lh

– Long format list sorted by size (descending):
ls -lS

– Long format list of all files, sorted by modification date (oldest first):
ls -ltr


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.

Leave a Reply