TLDR ( Too Long; Didn’t Read ) - A Simplified Linux Man Pages

Linux command line users must be familiar with "man" command. It stands for manual pages, which means that every Linux command or utility comes with the set of instructions or possible usage of the command. Man pages are of great help while working on the command line, but often, the documentation available via man pages is too lengthy or too confusing to learn. It also does not provide any real life examples too. All it include is the details of what that particular command does, and what are its available switches ( also called options ). TLDR is a community driven efforts to improve default Linux man pages, TLDR ( Too Long; Didn’t Read ) provides an easy to under documentation for every command or utility and it also demonstrates the usage of the command with pretty simple examples. In this article, we will be learning the process to install TLDR and how to use it to work better on Linux terminals.

How to install TLDR on Ubuntu and CentOS Systems

The easiest way to install TLDR is by using NPM and Nodejs. So we need to first install these two components on our system. Ubuntu system users can install NPM and Nodejs by using the following command.

sudo apt-get install nodejs npm

CentOS users will need to first enable Yum's EPEL repository.  Run the following command to install Epel repository, once it is active, then we will be able to install nodejs and npm using YUM.

yum install epel-release -y

Run the following command on CentOS system to install Node and NPM.

sudo yum install nodejs npm

Alright, run following command on your system now to complete the installation process for TLDR.

sudo npm install -g tldr

Congratulations, you have successfully equipped your Linux system with an easy to understand command manuals.

TLDR examples

The syntax to get help using TLDR is pretty simple, use the following format.

tldr Command

Where replace "Command" with actual utility or command name you are trying to get documentation for.

The documentation for "ls" command looks like as shown below when tried via TLDR.

# 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

Isn't it extremely easy and descriptive way? here is how tar command's documentation looks like:

# tldr tar

tar
Archiving utility.
Optional compression with gzip / bzip.

- Create an archive from files:
tar cf target.tar file1 file2 file3

- Create a gzipped archive:
tar czf target.tar.gz file1 file2 file3

- Extract an archive in a target folder:
tar xf source.tar -C folder

- Extract a gzipped archive in the current directory:
tar xzf source.tar.gz

- Extract a bzipped archive in the current directory:
tar xjf source.tar.bz2

- Create a compressed archive, using archive suffix to determine the compression program:
tar caf target.tar.xz file1 file2 file3

As you can see, TLDR offers a very intuitive way to search information about commands. It shows examples of the different usages of every command, which makes them very easy to understand.

You can also list all the available commands in the repository by typing:

$ tldr -l

Contributing

If you don't find a command or you have more examples for an existing command, you're welcome to contribute to the project!

Firstly and very important, make sure you respect all these items:

Guidelines

1. It's best to keep pages at around 5 examples. If it's really needed, pages can be longer, but can't exceed 8 examples. The page doesn't have to cover everything, that's what man is for.
2. When you are in doubt with something, go for the secure method that you know it will work always. For example: Commands that require sudo should include it directly in the examples.
3. Include spelled-out options in addition to single-letter options. This gives the possibility to the user to understand what he/she is doing.
4. In the examples, start with the easier options and then continue with the more complex ones.
5. Avoid explaining general UNIX concepts, only focus on the commands' specific details.

I recommend you to look at some TLDR existing pages to see how they are written and be able to create consistent documentation.

Markdown format

The format of each page should be like this:

# command-name

> Short, snappy description.
> Preferably one line; two are acceptable if necessary.

- Example description:

`command -opt1 -opt2 -arg1 {{arg_value}}`

- Example description:

`command -opt1 -opt2`

There is a formatter that enforces the above format. It's run automatically in every pull request, but you can install it to see how your contributions will look like:

$ sudo npm install tldr-lint
$ tldrl -f {{page.md}}

You can check more uses or tldrl by typing:

$ tldr tldrl

Token syntax

Use {{token}} syntax for user-provided values to allow tldr clients to highlight them. Multi-word tokens shoul use snake_case.

Guidelines for choosing token names:

1. Token values have to be short and descriptive. For example: {{file_route}} or {{home/user/.bashrc}}
2. If the example is clearer using an actual value rather than writing the input variable,parameter name, or whatever, use the actual value. For example: Use shutdown -h {{5}} rather than shutdown -h {{time_in_HHmm}}
3. For any reference to paths to files or folders, use the format {{path/to/<placeholder>}}. For example, ln -s {{path/to/file}} {{path/to/symlink}}. In case of a possible reference both to a file or a folder, use {{path/to/file_or_folder}}
4. Follow the {{path/to/<placeholder>}} convention when there is a path-related command, except when the file location is implicit.
5. If there is a command that expects a file to have a specific extension, show it. Example: unrar x {{compressed_file.rar}}. If a generic extension is needed, use {{.ext}}

This are only guidelines, no strict rules, just try to follow them and make the examples the most intuitive possible.

Submitting a pull request

Your can use the method that you prefer:

Github's web interface

The easiest way is to edit the page directly from the Github UI. You can see some instructions over here.

Command line

1. Fork the repository from the Github UI
2. Clone your fork to your local computer

   https://help.github.com/articles/editing-files-in-another-user-s-repository/

3. Create a feature branch

   git checkout -b {{branch_name}}

4. Make your changes
5. Commit the changes

    git commit --all -m "{{commit_message}}"</>

6. Push to your fork

    git push origin {{branch_name}}</>

7. Go to the github page for your fork and click the green pull request button.

Send only related changes in the same request.

For the commit message, use this command:

<command>: type of change

Example: ls: add page

You can also refer to the official repository to find more documentation.

Updating TLDR

TLDR is continuously adding more and more documentation to it,  if you don't find details for any command /utility in TLDR, you can update it by using the following command. It is important to keep TLDR updated so you may have most up-to-date information available.

tldr --update

Using Online ( Web-based) TLDR

Yes, you read it right :-) you can also view the documentation/help for Linux command using the online version of TLDR. TLDR developers have a web URL which you can use to search for the documentation or help for any Linux utility/command.  Head to the following URL and simply type your desired command/utility name and press "Enter", you will be presented with community documentation of the searched command and it is pretty eye candy interface.

Hope you enjoyed this article, we have discussed the installation and usage process for TLDR command in this tutorial. You can also use the online version of this utility to improve your daily Linux command line working productivity. It saves you a lot of time and provides you much-needed information in extremely easy and detailed way possible. Try it today! do let us know in the comments section about your experience with this utility.