tldr - alternative man with self-titled name

We all love --help and man . Despite the emergence of numerous forums, the Stack Exchange and other resources, it is still good for the beginning of solving your problems to remain an independent search for an answer in the official documentation (and you will most likely be immediately reminded of these resources on these resources) . However, laziness continues to move progress even where it is not always expected. However, this is not only laziness - there are other arguments in favor of “simplifications” ...

In general, it turned out that the classic man does not suit everyone. Therefore, the project tldr appeared, which, following its decoding “Too long; didn’t read, ”decided to bring into the console concise documentation containing only the most important thing. The tldr project is more than 3 years old, but for some reason they haven’t written about it yet.


')

What is it?

The authors of tldr describe their offspring as “a collection of man-pages simplified by the community”. The main product of their activity is the library itself from markdown files, which are alternative reference pages for popular console utilities. Most of them belong to the “common” and “Linux” categories, however there are also separate pages for macOS and even Windows.

What is stored in these pages? As an example, the GitHub project demonstrates tldr tar help:



As you can see, this is a minimal description of the utility purpose and a compact list of the most frequent commands. For tar , there are 7 ready commands, for ls - 6, for top - 5.

Who needs it? A good question, the answer to which I leave to the reader. The obvious option is to assign beginners to comprehend the console (not everyone can be persuaded to read all the documentation at the beginning of their journey, so that life will be easier later). Anyway, the project already has more than 15 thousand stars on GitHub, more than a thousand forks and more than 20 clients (see the next section for more information about them) - these indicators are enough to state: there is demand.


Ⓒ xkcd # 1168: tar

Installation and use

To access the tldr pages, you need to install one of the clients. Their current list is provided on this wiki page . The implementations are available on Node.js (considered “most mature client”), PHP, Python, Ruby, Perl, Go, Bash, C ++, Haskell, Rust, Emacs ... there are a couple of versions for Android and for iOS, a bot for Slack, there is two web interfaces (one of which, by the way, is hosted on DistroWatch ).


Tldr.ostera.io web interface

The installation of the main client should look like this:

 npm install -g tldr 

... however, in my case (Ubuntu) led to the need to install a large number of dependencies (because Node.js / npm is not installed on the system), so I preferred this “youthful” Linux path:

 $ sudo snap install tldr 

This command installs the “main” Nold.js client tldr (version 3.1.0 in the current snap package) into the system.

What does he do?

 $ tldr Usage: tldr command [options] Simplified and community-driven man pages Options: -h, --help output usage information -V, --version output the version number -l, --list List all commands for the chosen platform in the cache -a, --list-all List all commands in the cache -1, --single-column List single command per line (use with options -l or -a) -r, --random Show a random command -e, --random-example Show a random example -f, --render [file] Render a specific markdown [file] -m, --markdown Output in markdown format -o, --os [type] Override the operating system [linux, osx, sunos] --linux Override the operating system with Linux --osx Override the operating system with OSX --sunos Override the operating system with SunOS -t, --theme [theme] Color theme (simple, base16, ocean) -s, --search [keywords] Search pages using keywords -u, --update Update the local cache -c, --clear-cache Clear the local cache Examples $ tldr tar $ tldr du --os=linux $ tldr --search "create symbolic link to file" $ tldr --list $ tldr --list-all $ tldr --random $ tldr --random-example To control the cache $ tldr --update $ tldr --clear-cache To render a local file (for testing) $ tldr --render /path/to/file.md 

Let's see the list of available pages:

 $ tldr -l Local cache is empty Please run tldr --update 

They are (locally) not yet, but it is fixable:

 $ tldr --update Updating... { Error: ENOENT: no such file or directory, unlink '/home/user/snap/tldr/162/.tldr/cache/pages/shortIndex.json' at Error (native) errno: -2, code: 'ENOENT', syscall: 'unlink', path: '/home/user/snap/tldr/162/.tldr/cache/pages/shortIndex.json' } Done Creating index... Done $ tldr -l 7z, 7za, 7zr, ab, ack, adb, adduser, ag, alias, alpine, ansible, ansible-galaxy, ansible-playbook, ... 

There were 671 entries in total. Where do they come from ? Fixed in client config.json . And then everything is simple:

 $ tldr ls 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 $ tldr tldr tldr Simplified man pages. - Get typical usages of a command (hint: this is how you got here!): tldr command - Update the local cache of tldr pages: tldr --update 

Please note that all certificates are in English only (and there are no initiatives to localize them).

Alternatives and summaries

Directly in the tldr project's README are alternatives that solve the same problem - “simplifying” the man pages:

• Cheat - written in Python utility (it has implementations in Bash, as well as a web service ), supports about 180 pages;
• eg is another Python equivalent that has a much smaller library and is less frequently updated;
• bropages is a web project (and a console client for Ruby, but it hasn’t been updated for a long time), where the community is updating its online database of concise examples of using console commands.

Looking at the available alternatives, it is obvious that tldr managed to go far ahead of its competitors. So if there is a need for such an application / service, then definitely pay attention to this utility.

However, all this does not negate the need for complete documentation, which gives a much more complete picture of the principles of operation and the utility capabilities, each product has (where the developers themselves took care of the least), contains all relevant information (and they can change with different versions ).