slama.dev

man

9. 8. 2020; intro to Linux

man is a program for interacting with your system’s reference manuals and is an absolute necessity when working on the command line. It can display useful information about the purpose and usage of things like executables, system calls, special files and much, much more.

Usage

Let’s use man to examine what ls does. To do this, run man ls – a window should open with the documentation of the command ls.

This is the default way to use man – it tries to look for a manual page(s), whose name matches the provided argument(s). However, there are other it can also do different things, depending on if the following flags are specified:

Flag Description
-f, --whatis Gives short descriptions of the matching manual pages.
-K, --global-apropos Searches for text in the man pages themselves.
-w, --where Only print the location of the page, don’t display it.
-a, --all Attempt to show all matched pages (not just the first one.

Although the default usage is arguably the most useful, it is still good to know of others.

Specifying sections

As mentioned above, man covers a variety of topics, divided in to various sections. The division is necessary, because (for example) exit could mean any of the following:

Some common sections include:

Section Description
1 General commands
2 System calls
3 Library functions, mostly the C standard library
4 Special files (usually devices from /dev) and drivers
5 File formats and conventions
6 Games and screensavers
7 Miscellanea
8 System administration commands and daemons
9 Kernel routines
l Local documentation
n Tcl/Tk keywords

To specify, which section the page should be displayed from, either of the following works:

Changing the way the page is displayed

man contains a few flags for modifying how the text is rendered:

Flag Description
-E, Set the encoding of the displayed page.
--nh, Prevent line breaks on words that don’t contain hyphens.
--nj, Don’t justify to both margins.

Also, if you set the MANWIDTH environment variable, the width of the page will automatically adjusted to its value. If not, it will default to taking up the whole terminal window width.

Exporting to other formats

One can use the -T option to convert a manpage to a different format. For example, man -Tpdf ls > ls_man_page.pdf will generate a neat-looking PDF. Other formats like PS and HTML are also supported – to see the full list, see groff’s documentation (namely the -T flag).

Adding color

In my opinion, man pages are, by default, rather dull-looking. They use less by default to do the displaying and while it does offer some forms of highlighting (bold, italics,…), it is quite limited and not nearly as nice as it could be.

One way to change this is to use most comes in – it’s also a pager, similar to less, but offers nice coloring out-of-the-box. To use it, first install it using your package manager and then use the -P flag: man -Pmost ls. A good idea to make this change persistent would either be to create an alias, or to change the PAGER/MANPAGER variable in your shell to most.

Changing the language

The language that man uses is determined by the LANG and LC_MESSAGES environment variables. If you prefer to display the manual pages in other languages1, use the -L flag: man -Lcs gpasswdman will try to open the page in the language of your choice and will default to English if it isn’t successful.

Internals

man internally uses /etc/man_db.conf for configuration. Examining the file can tell you where man looks for the reference pages that it can display, and also the order in which sections are searcher for your manpage.

The manual files are (normally) stored in the nroff format (compressed in the .gz format) and are then processed using various pre-processors, followed by the groff formatting system and then either ran through additional post-processors, or presented to the user via a pager (less by default).

A sample page’s source file (ls, for example, found in /usr/share/man/man1/ls.1.gz on my machine) looks something like this:

.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.3.
.TH LS "1" "March 2020" "GNU coreutils 8.32" "User Commands"
.SH NAME
ls \- list directory contents
.SH SYNOPSIS
.B ls
[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
.SH DESCRIPTION
.\" Add any additional description here
.PP
List information about the FILEs (the current directory by default).
Sort entries alphabetically if none of \fB\-cftuvSUX\fR nor \fB\-\-sort\fR is specified.
.PP
Mandatory arguments to long options are mandatory for short options too.
.TP
\fB\-a\fR, \fB\-\-all\fR
do not ignore entries starting with .
.TP
\fB\-A\fR, \fB\-\-almost\-all\fR
do not list implied . and ..

Interestingly enough, this particular man page is actually auto-generated from ls’s --help and --version flags using the help2man. I found that some other commands (uname, printf, chroot, date) also do it, but a lot of them don’t.

The above results in the following output:

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 ..

Sources

  1. Sadly, the language support for most of the languages is rather limited. Browsing through a few of them, a lot of translations are in a WIP state and they only cover the most essential commands. Let’s hope that this will change in the future 🙂.