slama.dev

man

intro to Linux , released 9. 8. 2020, updated 26. 6. 2022

• Usage
  • Specifying sections
  • Changing the way the page is displayed
  • Exporting to other formats
  • Adding color
  • Changing the language
• Internals
• Sources

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:

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:

• a shell command
• a system call
• a C library function

Some common sections include:

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

• man <page>.<section>
• man <page>(<section>)

Changing the way the page is displayed

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

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 languages¹, use the -L flag: man -Lcs gpasswd – man 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

• man man
• Man page Wikipedia page