Writing and reading man pages
Compiling and Formatting Man Pages
Man pages are stored as bzip or gzip files. You can prepare a man page in several ways, including Perl's pod2man
script. However, most methods use some variant of the troff/groff document formatting systems, which are even older than man in Unix-like systems. These commands are a subject in themselves, but using them to create man pages requires little knowledge.
Write the man page in a text editor or nroff/groff, remembering to spell check. If your editor does not support spell checking, you can copy and paste it to one that does. The first parts of the file name should be the page name, separated by a period from the man section number. As you write, you can check your formatting with the command:
nroff -man FILE | less
When you have finished entering, enter the basic command:
ngroff -man FILE > OUTPUTFILE
Compress the output file with gzip or bzip, and place the compressed file in a directory in the MANPATH
environment variable. To access the new file, add it to the man database with mandb -c
or, in some distributions, make what is
.
You can also convert the output file to Postscript with:
groff -man -Tps FILE > FILE.ps
Similarly, the command to produce a PDF file is
groff -man -Tpdf FILE > FILE.pdf
Another option for PDF conversion is to use the command-line utility ps2pdf
to produce the PDF file from the Postscript file.
Converting to HTML is even simpler. With the man2html
utility installed, enter:
man2html FILE
The output is an HTML file of the same name in the output file's directory
Reading man Pages
Reading man pages requires no more than the basic command followed by the topic (e.g., man ls
). However, what many users don't know is that the man
command can be modified by several options.
To start with, if you prefer to memorize options rather than command names, -f
replaces the whatis
command, giving a short description of the topic. Similarly, the -k
(--apropos
) option gives the same results as the apropos
command, searching the man page names and descriptions for the topic. Using -K
(--global-apropos
), however, searches the entire content of all man pages – a process that takes several minutes on most systems.
Another set of options helps you control the man command's search. With -i
(--ignore case
) added, man ignores the distinction between lower and upper case, whereas with -I
(--match-case
), the command observes the distinction. With --regex
, you can use regular expressions in the topic, and with --wildcard
, you can use standard wild cards. However, because --regex
and --wildcard
can return long lists of results, you can use --names
to ensure that they only search the names of man pages. In some cases, you may be able to save time by adding -a
(--all
), so that all results are listed, instead of the one that the command evaluates as most appropriate.
Other options help you to choose where to find a man page. With -w
(--where
, --path
, --location
), you can track down where man pages are stored. Using -S LIST
(-s LIST
, --sections=list
), you can limit your search to a comma-separated list of man sections, starting with the first section in the list.
If you know of directories that are not listed in man's environment path, you can direct the command's search to that alternate path with -M PATH
(--manpath=PATH
). On a network, -m SYSTEM
extends the man command's search to connected systems, instead of confining itself to the local one.
Man's results can also be formatted without hyphenation (--no-hyphenation
, --nh
), or without the default full justification (--no-justification
, --nj
), producing a ragged right margin that prevents awkward word breaks at the end of lines. You can display man
results in a browser with -H BROWSER
(--html=BROWSER
), which creates HTML-formatted output.
Man Endures
The man
command and the pages written for it are 45 years old; yet, their simplicity means that they continue to be adequate for the task of producing help files. You may find other standards in a particular project – for example, Debian man pages almost always include AUTHORS – but, overall, the basics of man pages have changed little since they first appeared. The largest changes over the years have been to the selection of section headings, and those details are so minor that Dennis Ritchie and Ken Thompson, the writers of the first man pages, would have no trouble using one written today (although they might be appalled by some of the headings and the general verbosity today).
Clearly, man pages are not going away any time soon. Sometimes, parts of them, like the SYNOPSIS, can be intimidating in their detail, but the better you understand them, the more useful they can be.
Infos
- Man pages: https://en.wikipedia.org/wiki/Man_page
- Unix First Edition Manuals: http://man.cat-v.org/unix-1st/
« Previous 1 2
Buy this article as PDF
(incl. VAT)
Buy Linux Magazine
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Support Our Work
Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.
News
-
OSJH and LPI Release 2024 Open Source Pros Job Survey Results
See what open source professionals look for in a new role.
-
Proton 9.0-1 Released to Improve Gaming with Steam
The latest release of Proton 9 adds several improvements and fixes an issue that has been problematic for Linux users.
-
So Long Neofetch and Thanks for the Info
Today is a day that every Linux user who enjoys bragging about their system(s) will mourn, as Neofetch has come to an end.
-
Ubuntu 24.04 Comes with a “Flaw"
If you're thinking you might want to upgrade from your current Ubuntu release to the latest, there's something you might want to consider before doing so.
-
Canonical Releases Ubuntu 24.04
After a brief pause because of the XZ vulnerability, Ubuntu 24.04 is now available for install.
-
Linux Servers Targeted by Akira Ransomware
A group of bad actors who have already extorted $42 million have their sights set on the Linux platform.
-
TUXEDO Computers Unveils Linux Laptop Featuring AMD Ryzen CPU
This latest release is the first laptop to include the new CPU from Ryzen and Linux preinstalled.
-
XZ Gets the All-Clear
The back door xz vulnerability has been officially reverted for Fedora 40 and versions 38 and 39 were never affected.
-
Canonical Collaborates with Qualcomm on New Venture
This new joint effort is geared toward bringing Ubuntu and Ubuntu Core to Qualcomm-powered devices.
-
Kodi 21.0 Open-Source Entertainment Hub Released
After a year of development, the award-winning Kodi cross-platform, media center software is now available with many new additions and improvements.