Unix and GNU/Linux Docs - Listed and Explained

Introduction

Today we usually browse the Internet to find help for using Unix and Linux systems. We search for whatever we can find – articles, blog posts, forum threads, video tutorials, etc.

However, most programs already have their official docs written by their actual authors and maintainers. That documentation is authoritative, provides professional insight into a particular software, and should generally be consulted first.

Also, it is either already included with the software or, when it is larger in volume or size, it is distributed in an accompanying documentation-only package. Once installed, it integrates into the rest of the system that expects it.

The official documentation is usually optimized for quick and repeated use as a reference, without needing the browser or Internet at all.

Sometimes it may happen that those docs are too brief or too hard to understand if users have no prior experience or theoretical knowledge. In such cases it is OK to search the Internet for more informal and beginner-oriented guidance first.

This article lists the types and locations of documentation included with Unix, GNU/Linux, and Debian systems, and provides tips on using them effectively.

Manual Pages (Manpages, Man)

The staple of Unix documentation are the so-called “on-line reference manuals”, or man pages for short.

They originated in the first edition of Unix Programmer's Manual in 1971 and are still the default form of Unix documentation.

To install the support for man pages (if not already present on the system), run:

sudo apt install man-db manpages manpages-dev less

Man pages are written in the roff format. When viewed, roff viewers dynamically parse and auto-adjust (typeset) the text to the display device and available size.

Here is an example of the beginning of man page for program ls, rendered on a 24x80 textual display:

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  speci‐ |
       fied.                                                                   |
                                                                               |
       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                                                                |
 Manual page ls(1) line 1 (press h for help or q to quit)                      |

Man Sections

Manpages are grouped into so-called sections (categories). Sections not only organize content, but also allow for the same term to exist in multiple categories. For example, there is a man page for “crontab” in both section 1 and 5.

The main manpage sections in the GNU/Linux version of man are:

These main categories can have subsections. For example, manpages for the Perl programming language are in the section 3perl instead of 3 directly.

When referring to a manpage, by convention the section is listed in parentheses after the name, such as crontab(1) and crontab(5).

Opening Manpages

To open a man page, simply invoke man [SECTION] TERM. For example, run man man to open a manpage for man itself. Press q to exit.

SECTION is optional and defaults to the first section in which the requested manpage is found.

TERM is the manpage to look up, such as ls, man, or xterm.

For example, run man crontab, man 1 crontab, and man 5 crontab.

The mentioned examples use a text-based man interface. You are encouraged to get familiar it and use it as your primary method for browsing the man pages as it is ubiquitous.

However, to view manpages in a graphical browser, open them using your system’s default man viewer (xdg-open man:ls) or yelp (sudo apt install yelp; yelp man:ls).

Navigation in man

The man program (like many Unix programs) uses the standard vi-like keys for navigation. The following keyboard shortcuts are the most important:

• Down and Up, or j and k – scroll text one line down or up

• PageDown and PageUp, or f and b – scroll text one page down or up

• Space – scroll text one page down

• g – jump to top of page

• G – jump to bottom of page

• / – search for a string from current location forwards

• ? – search for a string from current location backwards

• n – jump to next occurrence of searched term

• N – jump to previous occurrence of searched term

• h – open builtin help for man

• q – quit

Finding Manpages

When you are unsure of the exact name of the manpage, use the following helper commands:

• apropos – search the manual page names and descriptions, e.g. apropos crontab

• whatis – display one-line manual page description, e.g. whatis crontab

• whereis – locate the binary, source, and manual page files for a command, e.g. whereis crontab

In addition to searching, there is a convention that manpages have a “SEE ALSO” section at the bottom, listing other related commands. They are a good source of cross-referenced links and pointers to further documentation.

Info Pages (Info)

As mentioned in the History of Unix, BSD, GNU, and Linux, the GNU project was started with the definite goal of replacing all components of Unix with a Free Software implementation.

GNU Info represents GNU’s alternative to Unix man pages, but it did not become the new standard. The adoption is low enough that, if you are not particularly interested in GNU Info, you can forget about it.

Some programs, especially those formally part of the GNU project, come with both man and info pages which confusingly contain different information and level of detail.

Info is a multi-page, hypertext documentation system whose pages are written in the Texinfo format.

To install info, along with a possibly more user-friendly browser called pinfo, run:

sudo apt install info pinfo

Opening Info Pages

To open an info page, use pinfo, info, or xdg-open:

pinfo crontab

info crontab

xdg-open info:crontab

New Age Examples for Man and Info Pages

NOTE: The resources listed in this section are not local, but connect to the Internet.

Man and info pages are generally written like an authoritative reference, and may contain insufficient introductory text or practical examples for beginners.

Users who find manpages too complicated or lacking examples now have three separate, new-age supplements available: tldr, bropages, and cheat.

Program tldr conveniently also exists as a Debian package: sudo apt install tldr.

These tools provide online-based, practical examples displayed in a man-like format for any commands or topics asked, e.g. tldr ls.

Directory /usr/share/doc/

On Debian GNU-based distributions, there is a policy that every Debian package should place its documentation in directory /usr/share/doc/PACKAGE_NAME/.

All packages are guaranteed to have this directory, because at a minimum the packaging system will place the package’s changelog files there.

Those directories are often very useful – they may contain READMEs, examples, and other supporting documentation written either by the original software authors or Debian packages’ maintainers.

When Debian package maintainers add their own README, it is placed to a file called README.Debian. The READMEs and examples usually provide extra introductory information that is not found in the more reference-oriented man pages.

When documentation files are over 4kB in size, they are automatically gzipped by the packaging tools to save space. That’s why sometimes you will find .gz files in /usr/share/doc/PACKAGE_NAME/. Some text editors like e.g. the vi editor can recognize .gz files and work with them directly. When that is not the case, you can always run sudo gunzip *.gz to decompress files before use.

Some packages come with larger, comprehensive documentation. In such cases the package maintainers may choose to extract documentation into a dedicated package named *-doc, such as python-doc, ruby-doc, perl-doc, bash-doc, and similar.

A quick search can tell how many *-doc packages exist in the Debian repositories at a given time:

apt search --names-only -- '-doc' | grep ^[a-z] | wc -l

4407

Package Metadata

Software packages may have various useful, documentation-related metadata associated with them.

Metadata for Debian packages can be seen with apt-cache show PACKAGE or (in shorter form of output) with apt show PACKAGE.

Particularly useful fields are:

• Maintainer, the name and email of Debian package maintainer(s)

• Homepage, software’s original/non-Debian homepage

• Description, a good summary of package’s purpose and any crucial specifics

In addition to that, there are some dpkg commands which may be useful in the context of meta information:

• dpkg -S /PATH/TO/FILE – reports the name of package to which FILE belongs

• dpkg -L PACKAGE – lists all files installed by PACKAGE

• dpkg -l [PACKAGE] – shows current state of PACKAGE or all packages

TAB Completion

Another somewhat documentation-oriented feature is the so-called tab completion available in most shells.

Typing the beginning of a word and pressing TAB will either auto-complete the word (in case of a unique match) or print ambiguous choices, which can be used as an ad-hoc method for finding commands and files.

For example, typing a[TAB][TAB] will display all commands starting with “a”.

Additionally, if context-aware completion is installed, it will not only search for commands and files on disk, but it will also be command-specific. It will allow choosing and auto-completing individual commands’ options and suitable arguments.

Context-aware completion has its benefits and drawbacks:

On one hand, it allows conveniently completing command-specific options and suboptions, which the regular tab completion can never be aware of and thus cannot help or speed up.

On the other hand, it can be too specific and misleading. For example, if a particular option requires a text file as an argument, the context-aware completion might only suggest *.txt files for completion, whereas your text file could have a different extension or no extension at all. In that case the completion might confuse you or make you think that the file was not in the intended location.

Internet Relay Chat (IRC)

NOTE: this resource connects to the Internet.

Internet Relay Chat (IRC) is a system for instant messaging. It was designed for group communication that takes place in so-called “channels”, enabled by one or more networked IRC servers. It also allows one-on-one communication via private messages, as well as switching to a direct client-to-client (DCC) communication for chats and file sharing.

IRC was de-facto standard for Internet chat in the 90s and 2000s, hosting millions of users on various IRC networks. It has since lost the majority of its non-technical user base to mostly commercial platforms, first to the likes of trifling Mirabilis ICQ and AOL Instant Messenger (AIM), and then to social media and new protocols like XMPP and Matrix. Since the year 2020, a surprising number of businesses and projects have also switched from a self-hosted IRC server to cloud-based Slack. However, IRC remains ever-present, and many IRC channels now host bots that bridge messages between their users on various chat platforms.

IRC is accessed via IRC clients, such as the graphical HexChat, Pidgin, KVIrc, or mIRC, or textual ircII and irssi. There is a large number of IRC clients available, which can be seen in the comparison of Internet Relay Chat clients.

The biggest IT-related IRC networks operated today are Libera Chat and Open and Free Technology Community (OFTC).

If you are unable to install an IRC client, both Libera and OFTC websites offer web-based IRC clients at https://web.libera.chat/ and https://webchat.oftc.net/.

IRC networks are nowadays often a target of spammers, intent on getting their nonsensical messages displayed to as many users as possible. That has prompted many IRC channels to start requiring users to be authenticated (registered with an email address and password, and logged in) before they could either join channels or post their own messages.

As a result, as one of the first things after joining an IRC network, you will most likely want to run /msg nickserv help to receive instructions on registering your username (called a “nickname”) on that network.

You should become a regular IRC user on the Libera Chat and Open and Free Technology Community (OFTC) networks. After registering and logging in, run /list to receive the list of existing channels which you can join and add to your auto-join list.

Request for Comments (RFCs)

Requests for Comments (RFCs) were instigated by Steve Crocker in 1969 during his work for ARPANET. They were first used to record unofficial notes on ARPANET’s development, but have since become the official publication channel for the Internet Engineering Task Force (IETF), the Internet Architecture Board (IAB), and the global community of computer network researchers.

As the Wikipedia page says, “RFCs are authored by individuals or groups of engineers and computer scientists in the form of memorandums describing methods, behaviors, research, or innovations applicable to the working of the Internet and Internet-connected systems. They are submitted either for peer review or to convey new concepts, information, or, occasionally, engineering humor”.

The IETF adopts some of the proposals published as RFCs as Internet Standards. These standard document Internet specifications, communications protocols, procedures, and events; they are shaping the Internet’s inner workings, but are not widely known outside the community.

Wikipedia maintains a List of RFCs, but they are also available as Debian packages named doc-rfc-*. They can be installed all at once with apt install doc-rfc-*, and all the installed RFCs will be found in directory /usr/share/doc/RFC/.

HOWTOs and FAQs

Unix and Linux “HOWTOs” are documents that describe specific steps needed to achieve a particular goal. The goals are sometimes very specific, such as configuring a particular hardware device, and sometimes very broad, such as administering a network for an ISP. When users were searching the Internet for user-friendly guides it was customary to include the word “howto” in the search, such as in e.g. “linux networking howto”.

Frequently Asked Questions (FAQs) are an Internet tradition originating from the technical limitations of early mailing lists from NASA in the early 1980s. Users tended to post the same questions to the mailing lists over and over, without first searching the mailing list archives for answers. which was considered bad practice and against the netiquette.

So sometime between 1982 and 1985 the acronym and concept of FAQs were accepted to organize frequently asked questions and answers in an even more user-friendly format. This approach was then adopted by other mailing lists, Usenet newsgroups, and Internet in general. FAQs started serving as sort of grab-bags of introductory and clarifying information and answers on particular topics, regardless of whether the questions were actually “frequently” asked.

Due to the emergence of wikis and blogs, HOWTOs and FAQs have come out of general use. One place that collected and preserved those past materials is the Linux Documentation Project, which started publishing its content in 1992-1993 via FTP and the venerable SunSITE.unc.edu. Its homepage is now TLDP.org.

Linux Kernel Documentation

Linux kernel documentation is an enormous documentation effort with its home page available at https://www.kernel.org/doc/.

Documentation included directly in the Linux kernel tree can be browsed at e.g. https://github.com/torvalds/linux/tree/master/Documentation.

Quiz

Imagine you find yourself working at a computer at 00:30 AM on a given day.

After long hours, to rest and chuckle you decide to run man xbill.

But instead of a manpage, or at least a message explaining that one isn’t available, to your amazement you see:

$ man xbill

gimme gimme gimme

Do you know what happened?

Read about this man Easter egg.