Replacing man

A fondness of reading is a good habit to inculcate, but Shashank Sharma believes it requires more than spending quality time with man pages.

A fondness of reading is a good habit to inculcate, but Shashank Sharma believes it requires more than spending quality time with man pages.

There’s very little you can achieve with CLIbased tools and utilities without referring to the manual pages. Commonly known as man pages, these serve as an introduction to all the myriad available options for the different commands, tools and utilities. But as useful as the man pages are, they can also overwhelm you with information. For instance, the man page for the curl command is over 3,000 lines long. The man page for pdftk similarly runs onto over 500 lines. By comparison, the pages for these commands in the TLDR utility clock in at fewer than 140 and 20 lines respectively.

The stark contrast in size will have already help explain the name of the project. TL;DR (too long; didn’t read) is a popular internet slang, and is often used to provide a summary of long text. According its own description, TLDR is a community-driven effort which strives to simplify man pages into easily digestible pieces of information.

While man pages remain the canonical and official source of complete information for different commandline tools, utilities and commands, you don’t always need to be completely versed in all the different capabilities before using it. You shouldn’t think of TLDR as a replacement or alternative to man pages, but only as an effort towards providing the most basic information to enable you to start using the tool as soon as possible.

In fact, the contribution guidelines make this point rather succinctly: “Try to keep pages at around 5 examples. Pages can be longer or shorter when appropriate, but don’t exceed 8 examples. Remember, it’s OK if the page doesn’t cover everything; that’s what man is for”.

Installing and using TLDR

Some popular desktop distributions carry TLDR in their software repositories; however, as the TLDR pages are being constantly updated by the community, it makes sense to use the official package.

TLDR is a Node.js utility, which means that you must first install Node.js on your distribution before you can use the npm package manager to install it. If you’re running Debian/Ubuntu or a derivative distribution, you can install npm with the sudo apt install nodejs npm command. For Fedora, npm is now part of the Nodejs package, so the sudo dnf install nodejs command is all you need to install it on Fedora. You’ll find distribution specific instructions for installing npm package manager on the project’s website.

With the npm package manager installed, you can now run the sudo npm install -g tldr command to

install TLDR. By default, npm installs the specified package in the current working directory, called the local mode, so you must use the -g command option if you want to install the package in global mode.

Before you can start using TLDR to quickly assimilate different commands, tools and utilities, you must first update its cache with the tldr --update command:

$ tldr --update

Updating...

Creating index...

If you’re comfortable working with Snap packages, you can also install TLDR with the sudo snap install tldr command. With TLDR installed, you can now read the page for any command with the tldr

command:

$ tldr ssh ssh

Secure Shell is a protocol used to securely log onto remote systems.

It can be used for logging or executing commands on a remote server.

- Connect to a remote server: ssh username@remote_host

- Connect to a remote server with a specific identity (private key):

ssh -i path/to/key_file username@remote_host - Connect to a remote server using a specific port:

ssh username@remote_host -p 2222

- Run a command on a remote server:

…

As you can see, TLDR provides a quick one-line explanation of what the specified command does, along with a few command options, with their description and example usage. In this way, TLDR helps you quickly assimilate the usage without overwhelming you with information. By comparison, the man page of SSH runs close to 1,000 lines.

Skip to the end!

If you don’t remember the exact name of the command, but only have a basic idea of what it can do, you can use the tldr -s

command. For instance, run the following command if you’re looking for a tool that can be used to manipulate or edit PDF files:

$ tldr -s edit PDF

Searching for: edit PDF

$ pdfunite

$ qpdf

$ pdftk

$ mutool

$ ocrmypdf

$ pdfjoin

$ pueue-edit

$ cpdf

$ pdffonts

$ xpdf

Run tldr to see specific pages.

The tldr -s

command presents a list of commands that feature your search terms. You can then run the tldr command to read more about these suggested tools to narrow down the one that you wish to use. Your choice of keywords is quite important as TLDR individually matches each specified word, and provides a list of commands that feature it in the description. So, the command tldr -s enable firewall will produce different results than configure firewall .

Unlike man pages, which are often rather lengthy, TLDR pages make it easy to assimilate commands. If you’re new to the CLI and not all that familiar with the different commands, tools and utilities, you can take advantage of the tldr -r command, which opens a random TLDR page from the cache.

You can similarly run the tldr -a command for a list of all the pages in the TLDR cache. The command tldr -l can instead be used to list only the platform-specific pages. If you’re currently running Linux, but want to list all the OSX specific pages, you can do so with the

tldr -l --osx command.

The TLDR pages are stored in the ~/.tldr/cache/ pages directory, and sorted into different operating systems such as Linux, OSX (or rather MacOS as it’s now called), Android, SunOS and Windows. TLDR also warns you when you try to access the TLDR page about a command that’s not available on your current operating system:

$ tldr xcopy

Command xcopy does not exist for the host platform.

Displaying the page from windows platform xcopy

Copy files and directory trees.

More information: https://docs.microsoft.com/ windows-server/administration/windows-commands/ xcopy.

- Copy the file(s) to the specified destination: xcopy path/to/file_or_directory path/to/destination - List files that will be copied before copying: xcopy path/to/file_or_directory path/to/destination /p - Copy the directory structure only, excluding files: xcopy path/to/file_or_directory path/to/destination /t - Include empty directories when copying: xcopy path/to/file_or_directory path/to/destination /e - Keep the source ACL in the destination:

…

TLDR is fairly straightforward to use, and can help take away some of the ‘fear of the unknown’ that novice users might harbour towards the command-line.

You can override the terminal’s colours using the tldr <command> -t <theme> command to define the theme for TLDR, whether simple, base16 or ocean.

Ironically, TLDR doesn’t have a man page of its own. If you want information on what the tool can do, run the tldr tldr or the tldr -h command.