System-Local GNU/Linux Documentation

Introduction

Today, when we need information about Unix or GNU/Linux, we use an Internet search engine to search for blog posts, StackOverflow threads, or video tutorials.

However, Unix and all its derivatives come with a whole body of documentation available directly within the operating system, usually in the form of installable packages. That documentation is authoritative, comes directly from software developers and maintainers, and is available with no need to access the Internet after installation.

This article lists authoritative sources of Unix, GNU/Linux, and Debian documentation, and provides tips on using them effectively.

Manual Pages (Manpages, Man)

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

They are written in the roff format. Roff viewers parse and auto-adjust (typeset) text to the display device at time of rendering.

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

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

sudo apt install man-db manpages manpages-dev less

Man Sections

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

The main manpage sections in 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.

If the section of a particular man page is important, by convention it is mentioned 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 of man itself.

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.

Navigation in man

The man program, like many programs, uses standard vi-like keys for navigating through pages. 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

If you are unsure about the name of the command you want to look up, use the following three tools:

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

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

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

In addition to that, there is a convention that manpages have a “SEE ALSO” section near the end, listing other related commands. They are a good source of cross-referenced links.

Info Pages (Info)

GNU’s alternative to Unix man pages is GNU Info.

Info is a multi-page, hypertext documentation system. Its 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, type pinfo TERM or info TERM.

pinfo crontab

info crontab

New Age Examples for Man and Info Pages

(Note: this resource is Internet-based)

Man and info pages are generally written like a reference, and may contain insufficient introductory text or practical examples.

Newcomers who find manpages too complicated or lacking examples have three separate, new-age supplements available: tldr, bropages, and cheat. These tools provide practical examples in man-like format, of which program tldr conveniently exists as a Debian package: sudo apt install tldr.

Running those programs connects to the Internet and provides short, examples-oriented help for commands and topics asked.

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 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, or other supporting documentation written either by the original software authors or packages’ Debian maintainers.

When Debian package maintainers add their own README, it is placed in file 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 tools 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 gunzip to decompress them before use.

Note that some packages come with extensive documentation. In such cases, to keep content properly separated, 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

4149

Package Metadata

Software packages may have various useful, documentation-oriented 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), Homepage (software’s original/non-Debian homepage), and Description. The description field often gives a good summary of package’s purpose and any crucial specifics.

In addition to that, there are three commands which may be useful in the context of documentation or meta information:

• dpkg -S 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 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.

That 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 extended completion is installed, it will not only search for commands and files on disk, but it will also be command-aware. It will allow choosing and auto-completing command’s options and suitable arguments.

Note that, with command-aware completion, cd [TAB] will only show directories (because only directories can be cd-ed into), and typing tar zxf [TAB] will only display files ending with “.gz” (because the option “z” already implied gzip). This can be undesirable for users who expect filename completion to always show all possible matches without context sensitivity.

Internet Relay Chat (IRC)

(Note: this resource is Internet-based)

Internet Relay Chat (IRC) is a text-based chat system for instant messaging. It is designed for group communication that takes place in so-called “channels”, and also allows one-on-one communication via private messages, 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 trifling commercial platforms, first to the likes of Mirabilis ICQ and AOL Messenger, 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 self-hosted IRC to cloud-based Slack. However, IRC remains ever-present, and many channels host bots that bridge messages between various chat platforms.

IRC is accessed via IRC clients, such as graphical HexChat or mIRC, or textual ircII and irssi. But 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 nowdays often targets of bots intent on spamming and getting their nonsensical messages displayed to as many users as possible. That has prompted many channels to start requiring users to be registered with an email address before they could 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 intructions on registering your username (called a “nickname”) on that network.

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, Guides, FAQs

Unix and Linux HOWTOs are documents that describe specific steps needed to achieve particular goals. These goals are sometimes very specific, such as configuring a particular hardware device, and sometimes very broad, such as administering a network for an ISP.

Frequently Asked Questions (FAQs) are an Internet tradition originating from the technical limitations of early mailing lists from NASA in the early 1980s. As users tended to repeatedly post questions to the mailing list instead of searching the archives, repeating the “right” answers became tedious and was against netiquette.

So the acronym and concept of FAQs were developed between 1982 and 1985 to organize frequently asked questions and corresponding answers. The format was then picked up by other mailing lists, Usenet newsgroups, and Internet in general. FAQs started serving as sort of grab-bags of introductory or clarifying questions 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, but they remain significant. One place that collected and grouped such 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 work hours, to rest and chuckle you run man xbill.

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

$ man xbill

gimme gimme gimme

Do you know what happened?

Read about this man easter egg.