Linux

Linux - Read and Use System Documentation

Documentation is a set of written materials that provide information about a system. It helps users and developers to read and use the system documentation. Linux's documentation is clear, concise, and easy to understand, and includes information on all of the system's commands.

In this blog, we will see how to read and use system documentation in Linux.

Importance of Linux Documentation

There will be many commands we will use in Linux. And each command has a lot of command-line switches. For example, let’s look at the ls command that lets us see what files and directories we have on the computer.

ls

We use the -a flag to show us all entries, even “hidden” files and directories. See the command below:

ls -a

We use the -l flag to show a long listing format that has more data. See the command below:

ls -l

This command will show file creation time, file owner, permissions, and so on.

How are we supposed to remember -a and -l?

As we use a command over and over again, we’ll learn everything about it and memorize what each option, e.g., -l or -a, does. But initially, we might forget about these options after just one or two uses. That’s why Linux gives you multiple ways to access “help manuals” and documentation right at the command line.

Accessing Linux Command Options: --help Flag

You can access Linux help manuals using the --help flag.

Let’s say you want to see that long listing format with ls, to get a look at file permissions. But you forgot what the correct option was. Was it -p for permissions? We can get a quick reminder by running this command:

ls --help

This will show us a lot of output. But if we scroll up, we’ll find what we’re looking for

You can see how command-line options are sorted alphabetically and described with a short text. That’s why --help will very often be helpful when we forget about these options; we definitely will because each command has so many.

Accessing Linux Manual Pages: man Command

--help shows a condensed form with very short explanations. For ls, that’s ok, as it’s a very simple command. Other commands, however, are very complex, and we need to read longer explanations to understand what they do and how to use them.

Let’s take journalctl as an example, a command that lets us read system logs. Run this command:

journalctl --help

It will show an output similar to this:

We’ll notice that this opens in a slightly different way (look at “lines 1-27”) in the bottom left corner. This opened up in what Linux calls a “pager”. It’s simply a “text viewer” of sorts that lets us scroll up and down with our arrow keys or PAGE UP, PAGE DOWN. To exit this help page, press q.

All important commands in Linux have their own manuals or “man pages.” To access a command’s manual, enter man name_of_command. In our case, we’d use:

man journalctl

Now we get:

Short description of what the command does in NAME.
General syntax of command in SYNOPSIS
Detailed command description, how it works, and so on, in DESCRIPTION.
Detailed descriptions of command line options in OPTIONS.
Some manual pages even have some EXAMPLES near the end of the manual.

Sometimes, you will have two man pages with the same name. Example: printf is a command. But printf is also a function that programmers can use. Manual pages can fall into one of these categories (sections):

If you want to read the man page about printf, you tell man you want to consult printf from section 1, as shown below:

man 1 printf

If you want to read about printf, the function, you tell man you want to look at section 3, as shown below:

man 3 printf

💡

Note: During online Linux certification exams, you are allowed to use man and --help. Try to use --help if you forgot a command-line option, as that gives you the fastest results. Diving deep into a manual page will take up more time.

But this is all good and well when we know what command we want to explore. But what if we can’t even remember the name of the command that we need to use?

Searching for Commands that Do Something (apropos/man -k)

Imagine you forgot the name of the command that lets you create a new directory. How would you search for it?

apropos is a command that lets you search through man pages. It looks at the short descriptions of each man page and tries to see if it matches the text we entered. For example, with the next line, we can search for all man pages with the word “director” in their short descriptions. We’ll use “director” and not “directory.” “director” will match commands that contain the word “directory” but also the ones that contain “directories.” So we keep it more generic this way.

apropos director

apropos relies on a database. A program has to refresh it periodically. Since we just started this virtual machine, the database hasn’t been created yet. We can create it manually by running this command:

sudo mandb

On servers that have already run for days, there should be no need to do this, as it will be done automatically.

Now the apropos command should work:

apropos director

But those are a lot of entries which makes it hard to spot what we’re looking for. You see, apropos doesn’t just list commands. It also lists some other things we don’t currently need. We see stuff like (2). That signals that that entry is in section 2 of the man pages (system calls provided by the Linux kernel). That’s just too advanced for our purposes. Commands will be found in categories (sections) 1 and 8. We can tell apropos to only filter out results that lead to commands from these categories. We do this by using the -s option, followed by a list of the categories we need.

apropos -s 1,8 director

And we can now spot what we are looking for:

Notice how mkdir’s description contains the word “directories.” If we’d used the word “directory” in our apropos search, this command wouldn’t have appeared since “directory” wouldn’t have matched “directories.” This is something to remember when you want to make your searches as open as possible to match more stuff.

Tab for Suggestions or Autocompletion

Although this is not technically system documentation, it can still be helpful. Many commands have suggestions on what you can type next. For example, run this:

systemctl

Add a space after the command (don’t press ENTER), and now press TAB twice.

You get a huge list of suggestions. This can help you figure out what your options for that command are. However, you should not always rely on it because not all options are included in this suggestion list.

Another thing is that you’ll save a lot of time with autocompletion. Type the following and then press Tab:

systemc

Your command will be autocompleted:

systemctl

Add to that by typing the following and pressing the Tab key:

systemctl list-dep

endencies will get added at the end, and you get: systemctl list-dependencies. When you press Tab once, if your command interpreter can figure out what you want to do, it will automatically fill in the letters. If there are many autocomplete options, and it can’t figure out which one you want, press TAB again, and it will show the list of suggestions we observed earlier.

Autocompletion is a huge timesaver in the long run, and it might even help you shave off a few seconds here and there when tackling an exam.

Tab suggestions and auto-completion also work for filenames or directory names. Type the following and press Tab:

ls /u

It should autocomplete as shown below:

ls /usr/

Now we can see directories available in /usr/ without even needing to explore this directory with ls beforehand. And if we have a long filename like “wordpress_archive.tgz” we might be able to just type “wor,“ press Tab, and that long name will be autocomplete.

Enroll in our Linux Basics Course to learn more Linux concepts.

Conclusion

In this blog post, you learn how to access Linux documentation using commands. Additionally, you learned to increase your operation speed and efficiency by using auto-completion features. Mastering these two concepts will help you operate the Linux system like a pro.

Mumshad Mannambeth

Feb 18, 2022 • 7 min read