man page version of "Man Pages - The Complete Guide"

man-guide.1

.TH "MAN PAGES" "1" "03/13/2023" "Man Pages" "Man Pages"
.hy
.SH Man Pages \[em] The Complete Guide
.SS Introduction
.PP
UNIX users frequently use the \f[V]man\f[R] command to learn about
different tools, but few actually learn its inner workings.
In this article you\[cq]ll learn everything there is to know about man
pages.
.PP
If you are an experienced user, you can skip ahead and skim through the
headlines.
If something piques your interest, feel free to deep dive.
.SS Part 1: The Basics
.SS 1. What is a \[lq]man page\[rq]?
.PP
\[lq]Man page\[rq] is short for \[lq]manual page.\[rq] Man pages are a
well-known form of software documentation usually found on UNIX-like
operating systems.
.PP
Like any complex tool, your operating system comes with a
manual \[em] In this case, it\[cq]s a virtual manual that you can read
from within the operating system itself.
.SS 2. How to read man pages?
.PP
You can read man pages by typing the \f[V]man\f[R] command on your
terminal, followed by the name of the \[lq]man page\[rq] you want to
read.
.PP
For example, type \f[V]man ls\f[R] to read the man page for the
\f[V]ls\f[R] command.
.RS
.PP
Note: There are several implementations of the \f[V]man\f[R] command.
The most popular ones are \[lq]man-db\[rq] and \[lq]mandoc.\[rq] They
both follow the POSIX specification.
We\[cq]ll take a closer look at all of this later.
.RE
.SS 3. How are man pages organized?
.PP
The virtual manual is usually split into sections.
Each section contains entries describing a specific topic.
A single entry is called a \[lq]man page.\[rq]
.PP
There are some conventions:
.IP \[bu] 2
The section names are usually numbers (1, 2, 3, etc.).
Each number has a specific meaning (\[lq]1\[rq] is for executable
programs, \[lq]2\[rq] is for system calls, etc.)
.IP \[bu] 2
Every \[lq]man page\[rq] usually follows a known structure
(\[lq]Name\[rq], \[lq]Synopsis\[rq], \[lq]Description\[rq], etc.).
.IP \[bu] 2
Man pages are usually designated by its name followed by its section
within parentheses (For example \f[V]ls(1)\f[R] and \f[V]null(4)\f[R])
.SS 4. Are there man pages for every program?
.PP
Man pages aim to document the operating system and every software in it.
Thereby, the software you install is expected to add its own man pages.
.PP
But, with the rise of the internet and competing forms of documentation,
some programs (and even some operating systems) have their main
documentation elsewhere.
Some don\[cq]t provide \[lq]man pages\[rq] at all!
.PP
Still, man pages continue to be the canonical way to document software
in UNIX, particularly when it\[cq]s \[lq]close to the metal\[rq] or
accessible through the command line.
.SS 5. What are man pages actually made of?
.PP
Man pages are usually written in the \[lq]roff\[rq] markup
language \[em] A tradition that started with the first edition of the
UNIX manual.
.PP
Some man page authors use other markup languages such as Markdown or
reStructuredText to write their documentation.
However, they are usually converted to roff before being included in the
final man page file.
.SS 6. What are the sections of the manual pages?
.PP
The common sections are:
.IP \[bu] 2
\f[B]1 \[em] Executable programs or shell commands\f[R]
.IP \[bu] 2
\f[B]2 \[em] System calls\f[R] (Functions which wrap operations
performed by the OS kernel.)
.IP \[bu] 2
\f[B]3 \[em] Library calls\f[R] (Functions within libraries.
That is, functions meant to be called by other programs, not by the end
user.
They are usually defined in terms of a particular programming language,
like C.)
.IP \[bu] 2
\f[B]4 \[em] Special files\f[R] (Aka \[lq]devices.\[rq] Usually files
found in \f[V]/dev\f[R], which allow access to devices through the
kernel.
\[lq]Device\[rq] is a term used mostly for hardware-related stuff that
belongs to the system, like disks or printers.
There are also \[lq]pseudo-devices\[rq]which emulate the behaviour of a
device in software, like \f[V]/dev/null\f[R] and \f[V]/dev/random\f[R])
.IP \[bu] 2
\f[B]5 \[em] File formats and configuration files\f[R] (Describes
various human-readable file formats and configuration files,
e.g.\ \f[V]/etc/passwd\f[R])
.IP \[bu] 2
\f[B]6 \[em] Games\f[R]
.IP \[bu] 2
\f[B]7 \[em] Miscellaneous\f[R] (Overviews or descriptions of various
topics, conventions, and protocols, character set standards, the
standard filesystem layout, and miscellaneous other things.)
.IP \[bu] 2
\f[B]8 \[em] System administration commands\f[R] (Commands which either
can be or are normally used only by the superuser, like
system-administration commands, daemons, and hardware-related commands.)
.PP
You might find some deprecated sections in the wild (9, o, n, l), but
they shouldn\[cq]t be used.
.PP
Sometimes additional characters are appended to the section number.
For example, Debian uses \[lq]1posix\[rq] to document the POSIX version
of some commands.
The intent is to \[lq]namespace\[rq] or to indicate that some
documentation belongs to a specific project.
.SS 7. What are the sections within a manual page?
.PP
The conventional sections are:
.PP
\f[B]NAME\f[R]
.PP
This section has a standardized format consisting of a comma-separated
list of program or function names (usually only one), followed by a
dash, followed by a short one-line description.
For example:
.IP
.nf
\f[C]
ls - list directory contents
\f[R]
.fi
.PP
\f[B]LIBRARY\f[R] (Normally only in sections 2 and 3)
.PP
The library providing a symbol.
It shows the common name of the library, and in parentheses, the name of
the library file.
.PP
\f[B]SYNOPSIS\f[R]
.PP
A brief summary of the command or function\[cq]s interface.
.PP
The following conventions apply to this section:
.IP \[bu] 2
\f[B]bold text\f[R] \[em] Type exactly as shown.
.IP \[bu] 2
\f[I]italic text\f[R] \[em] Replace with appropriate argument.
.IP \[bu] 2
\f[V][optional]\f[R] \[em] Any or all arguments within \f[V][]\f[R] are
optional.
.IP \[bu] 2
this | that \[em] The vertical bars (\f[V]|\f[R]) separate choices
.IP \[bu] 2
argument\&... \[em] Argument is repeatable
.PP
Exact rendering may vary depending on the output device.
For instance, man will usually not be able to render \f[I]italics\f[R]
when running in a terminal, and will typically use underlined or
coloured text instead.
.PP
The command or function illustration is a pattern that should match all
possible invocations.
In some cases it\[cq]s recommended to illustrate several exclusive
invocations, as shown in the SYNOPSIS section of man-db\[cq]s
\f[V]man(1)\f[R].
.PP
\f[B]CONFIGURATION\f[R] (Normally only in sections 4)
.PP
Configuration details for a device.
.PP
\f[B]DESCRIPTION\f[R]
.PP
An explanation of what the program, function, or format does.
It shows how it interacts with files and standard input, and what it
produces on standard output or standard error.
.PP
It should omit internals and implementation details unless they\[cq]re
critical for understanding the interface.
.PP
It should only describe the usual case \[em] information about
command-line options should go in the OPTIONS section.
.PP
\f[B]OPTIONS\f[R] (Normally only in sections 1 and 8)
.PP
A description of the command-line options accepted by a program and how
they change its behavior.
.PP
\f[B]EXIT STATUS\f[R] (Normally only in sections 1 and 8)
.PP
A list of the possible exit status values of a program and the
conditions that cause these values to be returned.
.PP
\f[B]RETURN VALUE\f[R] (Normally only in sections 2 and 3)
.PP
A list of the values the library function will return to the caller and
the conditions that cause these values to be returned.
.PP
\f[B]ERRORS\f[R] (Normally only in sections 2 and 3)
.PP
A list of the values that may be placed in \f[V]errno\f[R] in the event
of an error, along with information about the cause of the errors.
(\f[V]errno\f[R] is a variable that holds the number of the last error
that occurred in a system call or a library function.
You can use the \f[V]errno\f[R] command to look up the meaning of an
error number or an error name.)
.PP
\f[B]ENVIRONMENT\f[R]
.PP
A list of all environment variables that affect the program or function
and how they affect it.
.PP
\f[B]FILES\f[R]
.PP
A list of the files the program or function uses, such as configuration
files, startup files, and files the program directly operates on.
.PP
These are meant to be full pathnames of these files.
In fact, it is expected that these paths on the man page were
dynamically generated during the program\[cq]s installation to match the
user preferences.
.PP
In short, you can expect the file paths in this section to be both
factual and actual.
.PP
\f[B]ATTRIBUTES\f[R] (Normally only in sections 2 and 3)
.PP
A summary of various attributes of the function.
Mostly related to memory and thread safety.
.PP
\f[B]VERSIONS\f[R] (Normally only in sections 2 and 3)
.PP
A summary of systems where the API performs differently, or where
there\[cq]s a similar API.
.PP
\f[B]STANDARDS\f[R]
.PP
A description of any standards or conventions that relate to the
function or command.
Commonly just a list of standards.
.PP
If the API is not governed by any standards but commonly exists on other
systems, it should be noted.
This is also the place to note if the function or command is
Linux-specific or GNU-specific.
If it\[cq]s available in the BSDs, it should be noted here too.
.PP
\f[B]HISTORY\f[R]
.PP
A brief summary of the versions where a system command or function
appeared, or changed significantly in its operation.
.PP
\f[B]NOTES\f[R]
.PP
Miscellaneous notes.
.PP
\f[B]CAVEATS\f[R]
.PP
Warnings about typical user misuse that doesn\[cq]t constitute a bug or
design defect.
.PP
\f[B]BUGS\f[R]
.PP
A list of limitations or known defects.
.PP
\f[B]EXAMPLES\f[R]
.PP
One or more examples demonstrating how this function, file, or command
is used.
.PP
Note: An innovative project in the man pages space, mankier.com, shows
an EXAMPLES section right after the NAME section.
This author encourages this non-standard practice, particularly in view
of the success of example-first documentation projects such as \[lq]tldr
pages.\[rq]
.PP
\f[B]AUTHORS\f[R]
.PP
A list of authors of the documentation or program.
.PP
Some people discourage this section as it tends towards clutter.
.PP
\f[B]SEE ALSO\f[R]
.PP
A comma-separated list of related man pages, possibly followed by other
related documents.
.PP
The list should be ordered by section number and then alphabetically by
name.
.PP
Given the distributed, autonomous nature of FOSS projects and their
documentation, it is sometimes desirable that the SEE ALSO section
includes references to manual pages provided by other projects.
.SS Part 2: History of Man Pages
.SS 8. RUNOFF
.PP
While it\[cq]s usual to think of man pages as something you read on a
screen, its origins lay in the physical world of printing.
.PP
The oldest ancestor of man pages is a program called RUNOFF from the
legendary CTSS operating system.
The name RUNOFF comes from the idiomatic expression \[lq]run off,\[rq]
meaning \[lq]to print or make a photocopy.\[rq] It\[cq]s one of the
earliest text formatting (or \[lq]typesetting\[rq]) programs.
.SS 9. RUNOFF as a markup language
.PP
If the idea of a file containing both natural-language and specific
formatting commands sounds a lot like a \[lq]markup language\[rq] like
HTML, LaTeX, or Markdown, that\[cq]s because it is.
In fact, RUNOFF and other early text formatting programs are the origins
of markup languages.
.PP
The word \[lq]markup\[rq] comes from the millennial art of \[lq]marking
up\[rq] a manuscript, which involves adding handwritten printing
instructions in the margins.
These instructions are then read by the person or system tasked with
creating the final version of the document.
.SS 10. From RUNOFF to troff/groff
.PP
RUNOFF was eventually rewritten as roff (1971) for UNIX.
Notably, \[lq]roff\[rq] was used to format the first edition of the UNIX
Manual, which had a similar structure to the man page layout used today.
.PP
Next came nroff (new roff), which supported both monospace printing and
displaying on terminals.
Then troff (typesetter roff), featuring proportional fonts and other
advanced features used in state-of-the-art photographic typesetters.
.PP
Although troff was eventually replaced by other programs and markup
languages, it is still used to format UNIX documentation, and some
people continue to use it for other tasks due to its reliability and
wide availability.
.PP
The GNU troff (groff) is considered the most popular troff variation in
modern UNIX installations.
.SS 11. The first \[lq]man\[rq] command
.PP
While the first edition of UNIX didn\[cq]t have a dedicated
\[lq]man\[rq] command.
The second edition, a few months later, introduced it:
.PP
That \[lq]man\[rq] command was a shell script that expected the title of
the required manual page and, optionally, a section number.
.PP
Its job was to find the source file for the manual page, and pass it to
roff, which does the heavy lifting of processing it for displaying to
the user.
(In those days, displaying involved printing on paper.)
.PP
Not much has changed.
These days, the implementations of the \[lq]man\[rq] command work in a
similar way.
.SS Part 3: POSIX
.SS 12. The \[lq]man\[rq] specification
.PP
\[lq]man\[rq] is one of the utilities defined by POSIX, a family of
standards designed to maintain compatibility between UNIX-like operating
systems.
.PP
Both \[lq]man-db\[rq] and \[lq]mandoc\[rq] conform to the \[lq]man\[rq]
POSIX specification.
.PP
The POSIX people discussed at length how much or how little should be
required of \[lq]man\[rq] implementations to be conformant.
Eventually they settled on minimalism: POSIX specifies a simple usage
without options and with the option \f[V]-k\f[R], plus a few
environmental variables.
.SS 13. The \[lq]man\[rq] command without options
.PP
When calling man without options (for example, \f[V]man name\f[R]),
POSIX says the following:
.RS
.PP
\[lq]If \f[I]name\f[R] is the name of a standard utility, \f[I]man\f[R]
at a minimum shall write a message describing the syntax used by the
standard utility, its options, and operands (arguments).\[rq]
.RE
.PP
Note that POSIX doesn\[cq]t say anything about the format of the final
message, or about the markup of the source files, or about
roff/groff \[em] That\[cq]s considered an implementation detail.
You can go ahead and write your own POSIX-conformant \[lq]man\[rq]
command in Markdown and COBOL and no one can stop you!
.PP
Indeed, \[lq]mandoc\[rq] is an implementation that doesn\[cq]t call
groff at all, although it does expect the source files to be in either
the \[lq]man\[rq] or \[lq]mdoc\[rq] macros, which are built on top of
the roff language.
.SS 14. The \[lq]man\[rq] command with the \[lq]-k\[rq] option, or \[lq]apropos\[rq]
.PP
command according to POSIX.
.PP
When calling man with the \f[V]-k\f[R] option (\f[V]man -k name\f[R]),
POSIX says that man should search for \[lq]name\[rq] in a \[lq]utilities
summary database\[rq] that contains a \[lq]brief description of the
purpose of each utility\[rq], and it should write all the matching
results.
.PP
In other words, \f[V]man -k name\f[R] should be equivalent to
\f[V]grep -Ei \[oq]name\[cq] summary-database\f[R] (the \f[V]-i\f[R]
flag means case-insensitive and the \f[V]-E\f[R] flag means that `name'
can be a regular expression.)
.PP
This assumes that the \[lq]summary-database\[rq] is a text file with a
single entry per line \[em] POSIX says that this organization is not
required, it\[cq]s just an illustrative example of the type of search
intended.
Indeed, older man implementations used to have a text file just like
this, but \[lq]man-db\[rq] uses an actual database.
.PP
There are two important details about \f[V]man -k\f[R] not mentioned by
POSIX:
.IP \[bu] 2
Man implementations generally use the text from the \[lq]Name\[rq]
section of a man page as its entry in the summary database.
.IP \[bu] 2
\f[V]man -k\f[R] is equivalent to the command \f[V]apropos\f[R], which
is provided by both \[lq]man-db\[rq] and \[lq]mandoc.\[rq]
.SS 15. The \[lq]man\[rq] command with the \[lq]-f\[rq] option, or \[lq]whatis\[rq]
.PP
While POSIX doesn\[cq]t define the \f[V]-f\f[R] option (or the
equivalent \f[V]whatis\f[R] command), it says that \[lq]the \f[V]-f\f[R]
option was considered, but due to implementation differences, it was not
included in this volume of POSIX.1\[en]2017\[rq], so it\[cq]s likely to
be included eventually.
.PP
The actual implementation differences between \[lq]man-db\[rq] and
\[lq]mandoc\[rq] are trivial.
.PP
\f[V]whatis name\f[R] is just like \f[V]apropos name\f[R], except that
man searches for \[lq]name\[rq] only in the manual page names, not in
the full description.
If a match is found, the returned value is the same as in
\f[V]apropos\f[R].
.PP
In other words, \f[V]man -f name\f[R] should be equivalent to
\f[V]grep -Ei \[oq]\[ha]name \[cq] summary-database\f[R] (same as
before, but it looks for lines beginning with \[lq]name\[rq] followed by
a space.)
.SS 16. The \[lq]man\[rq] environmental variables
.PP
POSIX also defines the following environmental variables:
.IP \[bu] 2
\f[V]LANG\f[R]: Set a language for internationalization.
.IP \[bu] 2
\f[V]LC_ALL\f[R], \f[V]LC_CTYPE\f[R], \f[V]LC_MESSAGES\f[R] and
\f[V]NLSPATH\f[R]: Other variables for internationalization.
.IP \[bu] 2
\f[V]PAGER\f[R]: An output filtering command to write the output to a
terminal.
The page output is to be piped through this command.
This defaults to the \[lq]more\[rq] pager (the POSIX pager), although
these days the \[lq]less\[rq] pager is almost universally preferred.
.PP
There\[cq]s one more environmental variable mentioned but not defined by
POSIX: \f[V]MANPATH\f[R].
Both \[lq]man-db\[rq] and \[lq]mandoc\[rq] define it as a sequence of
directory names separated by colons (just like \f[V]PATH\f[R]).
It\[cq]s one of the ways to override the default root where the man page
source files are located on the system.
But most users should not need to set it.
.PP
With this, we cover everything that POSIX has to say about the man
command.
Now let\[cq]s move into the most popular man implementation: man-db.
.SS Part 3: Man-db
.SS 17. Regular use of the \[lq]man\[rq] command.
.PP
In regular use, the manual page associated with each of the
\f[I]page\f[R] arguments is found and displayed.
.PP
A \f[I]section\f[R], if provided, directs man to look only in that
section.
The default action is to search in all of the available sections
following an order defined during man-db\[cq]s installation, and to show
only the first page found.
.PP
Some valid alternative spellings of \f[V]man 7 man\f[R] are:
.IP \[bu] 2
\f[V]man man.7\f[R]
.IP \[bu] 2
\f[V]man \[aq]man(7)\[aq]\f[R]
.SS 18. The \[lq]-K\[rq] option, or \[lq] \[em] global-apropos\[rq]
.PP
global-apropos searches not just the short description (like
\f[V]apropos\f[R]), but the full text in all manual pages.
.PP
This is a brute-force search, and is likely to take some time \[em] if
you can, you should specify a section.
Search terms may be simple strings (the default), or regular expressions
if the \f[V]--regex\f[R] option is used.
.PP
Note that this searches the \[lq]roff\[rq] sources of the manual pages,
not the rendered text, and so may include false positives due to things
like comments in source files.
.PP
Note also that \[lq]global apropos\[rq] will actually try to render
every found match, so if you expect many results you might want to also
add the \f[V]-w\f[R] flag (which we\[cq]ll see later) to make it
\f[I]man\f[R]ageable.
.SS 19. The \[cq]-l\[rq] option, or \[lq]local file mode\[rq]
.PP
In local mode, \f[V]-l\f[R] or \f[V]--local-file\f[R] , \f[V]man\f[R]
formats and displays local manual files instead of searching through the
system\[cq]s manual page collection.
.PP
Each manual page argument will be interpreted as a \[lq]roff\[rq] source
file.
.PP
If \f[V]-\f[R] is passed as the argument, input will be taken from
\f[V]stdin\f[R].
.PP
When this option is not used, and man fails to find the page required,
before displaying the error message, it attempts to act as if this
option was supplied, using the name as a file-name and looking for an
exact match.
.SS 20. The \[lq]-w\[rq] option, or \[lq] \[em] where\[rq]
.PP
prints the location of the source roff file instead of displaying it.
.SS 21. Cat pages, and the \[lq]-W\[rq] or \[lq] \[em] where-cat\[rq] option.
.PP
When using modern \f[V]man-db\f[R], it\[cq]s possible to store the
formatted manual pages on disk so that future requests do not have to be
formatted again.
.PP
These pre-formatted man pages are known as \[lq]cat pages.\[rq]
.PP
Although cat pages require some megabytes of disk space, they
substantially increase speed.
Indeed, cat pages might load two or three times faster!
.PP
The increase in computer performance since the 90s has considerably
reduced the need for cat pages, so you probably won\[cq]t even notice
the milliseconds of speed improvement.
But it\[cq]s worthwhile if you want to squeeze every bit of performance
out of your system.
.PP
The hierarchy of cat pages is created in a separate folder from the
hierarchy of man pages \[em] It mirrors the folders and file names of
the man hierarchy.
In short, it\[cq]s a cache.
.PP
Whether or not cat pages are created on your system depends on several
factors, not least how man-db was installed.
So make sure to read its manual (\f[V]man-db-manual.{ps/txt}\f[R]), its
configuration file (\f[V]/etc/man_db.conf\f[R]),
and \[em] naturally \[em] the man page for man.
.PP
You will find that in most systems, by default, cat pages are created
only if you try to run \f[V]man\f[R] with a column width set to 80
(easily done with the env variable \f[V]MANWIDTH=80\f[R]), which after
all is a beautiful looking default for any screen size!
.PP
You might also need to manually run the commands \f[V]mandb\f[R] and
\f[V]catman\f[R], usually as root, to create the cat pages hierarchy for
all your man pages.
.PP
You can verify if there is a cat page for a given man page by running
\f[V]man -W ls\f[R].
That is, with the flag \f[V]-W\f[R] (also \f[V]--where-cat\f[R] or
\f[V]--location-cat\f[R]).
It should print the location of the cat page for the \f[V]ls\f[R]
command.
It\[cq]s purrtastic!
.SS 22. The \[lq]-L\[rq] option, or \[lq] \[em] locale\[rq]
.PP
The \f[V]-L\f[R] or \f[V]--locale\f[R] option allows you to specify the
locale used.
This overrides env variables that we\[cq]ve seen before such as
\f[V]LC_MESSAGES\f[R] and \f[V]LANG\f[R].
.PP
It looks for a page in the provided language, and falls back to English.
.SS 23. The \[lq]-M\[rq] option, or \[lq] \[em] manpath\[rq]
.PP
The \f[V]-M\f[R] or \f[V]--manpath=path\f[R] option allows you to
specify an alternate man path to use.
It overrides the \f[V]MANPATH\f[R] env variable that we\[cq]ve seen
before, or the settings on your configuration file
(\f[V]/etc/man_db.conf\f[R]).
The value should be a colon-delimited list of directories, just like
\f[V]PATH\f[R].
.PP
A directory within \f[V]MANPATH\f[R] must be the root of a manual page
hierarchy structured into sections as the ones used by man-db.
.PP
Your system can have multiple man page hierarchies at the same time, and
when you run \f[V]man\f[R] you are searching in all of them.
Most likely, your system has man pages on several hierarchies.
To verify that, you can run the \f[V]manpath\f[R] command which prints
the current manpath value.
.PP
The \f[V]-M\f[R] option could be useful if you want to roll up your own
documentation system on top of the man command.
If you just want to view man pages from a different location, you can
use the \f[V]-l\f[R] option.
.SS 24. The \[lq] \[em] regex,\[rq] \[lq] \[em] wildcard,\[rq] and \[lq] \[em] names-only\[rq] options
.PP
The \f[V]--wildcard\f[R] option shows all pages with any part of either
their names or their descriptions matching each page argument using
shell-style wildcards (same as \f[V]--apropos -wildcard\f[R]).
Like \f[V]--regex\f[R], it also implies \f[V]-a\f[R] (\f[V]--all\f[R]).
.PP
The \f[V]--names-only\f[R] option, when used with the \f[V]--regex\f[R]
or \f[V]--wildcard\f[R] option, matches only the page names and not the
page descriptions (same as \f[V]whatis\f[R]).
If neither the \f[V]--regex\f[R] nor the \f[V]--wildcard\f[R] option is
used, this option has no effect because \f[V]man\f[R] does
\[lq]names-only\[rq] search by default.
.SS 25. The \[lq]all\[rq] option, or \[lq] \[em] all\[rq]
.PP
By default, \f[V]man\f[R] exits after displaying the most suitable
manual page it finds.
To force \f[V]man\f[R] to display all matching manual pages, use the
\f[V]-a\f[R] or \f[V]--all\f[R] option.
.PP
Now, this option is a bit inconvenient because it works by showing you
the first match, and, when you close it, it asks if you want to see the
next one.
A better option might be to run \f[V]man -a -w\f[R] to show all the
matching \f[I]files\f[R] at the same time.
.SS 26. The \[lq] \[em] no-subpages\[rq] option
.PP
By default, \f[V]man\f[R] tries to interpret pairs of manual page names
given on the command line as equivalent to a single manual page name
containing a hyphen or an underscore.
.PP
In short, if a command has a subcommand (like \f[V]git diff\f[R]), then,
by convention, it\[cq]s manual page will have the name
\f[V]git-diff\f[R], but you can still access it by typing
\f[V]man git diff\f[R].
The \f[V]no-subpages\f[R] option disables this behavior.
.SS 27. The \[lq] \[em] pager\[rq] and \[lq] \[em] prompt\[rq] options
.PP
Using the \f[V]-P\f[R] or \f[V]--pager\f[R] option, you can specify the
output pager to use.
By default, \f[V]man\f[R] uses \f[V]less\f[R].
This option overrides the \f[V]MANPAGER\f[R] and \f[V]PAGER\f[R] env
variables.
.PP
The \f[V]-r\f[R] or \f[V]--prompt\f[R] option is useful when a recent
version of \f[V]less\f[R] is used as the pager.
The default prompt used by \f[V]man\f[R] shows this on the bottom of the
less screen: \f[V]Manual page name(section) line x\f[R].
.PP
I really like this less feature, it allows anyone to set a custom
prompt.
\f[V]man\f[R] makes good use of it.
.SS 28. The \[lq] \[em] no-hyphenation\[rq] and \[lq] \[em] no-justification\[rq] options
.PP
The \f[V]--no-hyphenation\f[R] or \f[V]--nh\f[R] option disables
automatic hyphenation at line breaks.
This is useful for finding and copying text in the \f[V]less\f[R] pager
without worrying about possible hyphenation of the search term.
.PP
Have you noticed that man pages have fully-justified text?
That\[cq]s the secret to its smoothness!
The \f[V]--no-justification\f[R] or \f[V]--nj\f[R] option disables full
justification, leaving the text justified only to the left margin.
.SS 29. The \[lq]-t\[rq] option \[em] Output to PostScript and PDF
.PP
Using the \f[V]-t\f[R] or \f[V]--troff\f[R] option puts you in the
\[lq]troff mode\[rq] of groff, which means that the output is no longer
targeted at a terminal (\[lq]nroff mode\[rq]).
By default, it generates PostScript, which is the language that PDF
files are built on.
.PP
To convert a manual page to PostScript, run
\f[V]man -t ls > ls.ps\f[R] and to convert it to a PDF, you can use
\f[V]man -T pdf ls > ls.pdf\f[R].
Keep in mind that the formatted pdf is directed to the standard output,
so you can use the (\f[V]>\f[R]) operator to create a file.
.PP
The PDF output usually looks quite good, but it\[cq]s limited to the
Times New Roman font with some hard-coded things.
And some manual pages in the wild might not render correctly, especially
if there are long tables or unconventional formatting.
.SS 30. Output to HTML \[em] Here be dragons
.PP
Converting manual pages to HTML using \f[V]man -H\f[R] is generally not
recommended with man-db because the resulting output can be of poor
quality.
Complex formatting is often converted into low-resolution images, which
doesn\[cq]t look appealing or accessible.
.PP
Some developers who build online manual pages have resorted to creating
their own roff-to-HTML converters to generate cleaner and better-looking
HTML outputs.
.PP
Some people use mandoc for HTML conversion, which in my opinion
generates a better layout and, more importantly, doesn\[cq]t generate
those weird low-resolution images.
.SS 31. Apropos database and init script
.PP
Man-db is actually called like that because it uses an actual database,
usually Berkeley DB, to store and maintain the manual pages.
To keep this database up to date, man-db has an init script that runs
the \f[V]mandb\f[R] command.
Depending on your system and installation, it might be set to run
periodically in systemd.
.PP
Running this script creates and updates the indices for the database,
which allows to use the \f[V]apropos\f[R] and \f[V]whatis\f[R] commands.
In different modes of operations, the database updates can be automatic
or done manually using \f[V]mandb\f[R].
You can consult the man-db manual (\f[V]man-db-manual.{ps/txt}\f[R]) for
more information.
.SS Part 4: Miscellaneous
.SS 32. Man page alternatives \[em] tldr
.PP
In addition to traditional man pages, there are alternative projects
like tldr that provide concise and practical examples for command-line
tools.
Tldr pages are community-driven and can be a great companion to the more
comprehensive man pages.
.PP
You can invoke them using the \f[V]tldr\f[R] command.
For example, \f[V]tldr ls\f[R].
.PP
There are several implementations of the \f[V]tldr\f[R] command.
The classic one is good, but I personally recommend the Rust one,
tealdeer, because it\[cq]s actually really fast.
.PP
These days you might as well ask an AI how to do something on the
terminal.
This is available, for example, with Copilot for CLI.
.SS 33. Online man pages
.PP
There are several nice online man pages.
Some are associated with OSs and distros, like Arch Man Pages.
.PP
Others, like manned.org, contain man pages for different versions of OSs
and host the source \[lq]roff\[rq] files too.
.PP
Innovative resources like ManKier include the \[lq]tldr\[rq] information
as the first section of the man page, table of contents on the side, and
internal hyperlinks.
.PP
I would also like to point out that some of the old-school online man
pages, like OpenBSD\[cq]s and Void Linux, actually show you the native
\[lq]roff\[rq] tags as you hover around!
.SS 34. Creating man pages
.PP
There are various ways to create man pages, the old-school way being to
write them in \[lq]roff\[rq] format.
There are several resources available, such as \[lq]Practical Unix
Manuals: mdoc\[rq] and the Groff manual.
.PP
Man pages can also be generated from other sources, such as Markdown,
with tools like pandoc, and ronn from the Ruby world.
.SS 35. The \[lq]man-pages\[rq] project
.PP
Despite its generic name, the man-pages project actually provides a
wealth of information in the form of man pages about the Linux kernel.
It also includes \[lq]intro\[rq] pages for every section of the manual,
reinforcing the concept of sections being part of one single manual.
.PP
Recently, it has expanded to include man pages for other generic Linux
tools, not only for the kernel.
.PP
This project also contains a nice guideline for the generic sections
within man pages on its man-pages(7).
.SS 36. The international man-pages project
.PP
Man pages are also available in different languages, thanks in part to
the man-pages internationalization project.
.PP
This project aims to translate and maintain man pages in various
languages, making the documentation more accessible to users around the
world.
.SS Closing thoughts
.PP
These tips should get your man page senses tingling.
You\[cq]ll find that the techniques covered here are enough to bring all
the men to the yard, and to powers all you Linux documentation needs.
.PP
Stay tuned for part two, in which we\[cq]ll cover man page authoring
with Groff.