True to Linux philosophy, the viewing of help pages is a team effort. While the man command is the one you actually type, it relies on a separate pager tool to display its actual contents. Find out what the implications of this system are, and how it can improve your experience of getting help.
What Does Man Do With a Pager?
The man command displays documentation pages for various commands, system calls, library functions, and more. It fetches this information from plain text files in the man page format, usually located under a directory like /usr/share/man/.
Some man pages are short, but most are longer than at least one screen of text. To display these pages, the man program uses a tool called a pager, a concept that is common across Linux.
A pager is simply any tool that displays the contents of a text file, with some support for moving through the file one line—or one screen—at a time.
Without a pager, man will simply dump the entire contents of a man page in your terminal at once, leaving you with just the final page, which will vary according to your terminal window size:
With a pager, on the other hand, man will show you help one page at a time:
One of Linux's great strengths is its tendency to provide small, focused programs that perform specific functions. Using several programs together, you can achieve complex tasks without dedicated software. A pager embodies this philosophy: the man program focuses on looking up help pages and formatting their text, while a pager concentrates on displaying text piece by piece.
In the unusual case that you don't want any paging capability at all, you can use the cat command as a pager. If your terminal app has a scrollback feature and the man page isn't too huge, you'll be able to scroll through the entire contents using your mouse.
How to Change Your Man Pager
Linux programs often provide a few ways to change their behavior , and man is no exception. The core ways are:
-
Command line options.
-
Environment variables.
-
Configuration files.
Each method has its benefits, and the one you choose will usually depend on whether you want the setting to be permanent and how widely you want it to apply.
The first approach is to use a command-line option. The man program supports a -P option to override the pager it would otherwise use:
For example, to look up the help page for ls, using the less pager:
And to look up help for man itself, using the more pager:
You should note that pager can be any valid command, including its own arguments and even pipes:
A good alternative to this command-line argument is an environment variable. Linux often uses envvars for configuration, and two are relevant in this case:
-
PAGER is a widely used setting that should indicate your preferred pager for general use. Supporting programs will pipe their output through the command named in PAGER.
-
MANPAGER overrides PAGER, specifically for the man command. Although other programs are free to use this value, you should find that only man actually does so. This lets you easily specify a pager for man that differs from your general pager.
You can set environment variables for all users in /etc/environment, or for your specific user in a file like ~/.bash_profile; this will vary according to the shell you're using.
As with any command, you can set the environment variable for just a single run by prefixing the command:
Finally, if your version of man supports a configuration file, you can use it to change the pager that man uses permanently.
The version of man included in macOS Tahoe reads a configuration file at /etc/man.conf. Ubuntu 24 comes with man 2.12.0, which does not read a general-purpose configuration file.
If you have a man.conf file, the syntax to set the pager is similar to setting an environment variable:
In all these cases, the command in your MANPAGER can be a full path to an executable, or any word that your shell can treat as a command. If you want an exact version of a known program, use a full absolute path. Otherwise, use a simple command name, and your shell will run whatever program, function, or builtin applies in the current context.
The disadvantage with this approach is that it—apparently—overrides environment variables and the -P command-line argument. So, once set, this value is enforced for every user of the system. This may, rarely, be exactly what you want, but most of the time, you'll have more control if you avoid using man's config file to set the pager.
The Best Pagers to Use With Man
By now, you may recognize the value of a good pager, but wonder which ones are actually good—or even which pagers are available at all. For such a simple tool, there's actually a surprising number of options, but you'll probably only ever use a handful of them.
As a default, man will usually use the lesspager, specifically this command:
The less program, which was released in 1984, is a replacement for an older pager named more, from 1978. While a more command is often still available, it may be the same as less on your system, either by symlinking or just being a direct copy. For example, on macOS Tahoe, running diff /usr/bin/less /usr/bin/morereports no differences; the two executable binaries are identical.
The main advance that less brought was scrolling backwards; believe it or not, but the original version of more could only scroll forwards. Using less, you can scroll forward one page at a time by pressing Space, and one line at a time with Enter. Scroll back one page with band one line at a time with y.
You can also scroll by half pages at a time, which can make it easy to keep track of your context. Use uto scroll back (up) by a half page, and dto scroll forward (down) by a half page.
For man pages, I recommend moving by one line or a half page at a time. Scrolling a page at a time can be useful if you want to navigate quickly, but it can make it harder to follow text when you're reading a man page from beginning to end.
most is a relatively new pager that was released in 2005. Written in C, it's fast and has a tiny executable (125K).
Many of most's features can be useful in a pager, but they don't make a lot of difference to man pages. The pager's windowing features cannot easily be used with man, and horizontal scrolling shouldn't be necessary since man already wraps long lines.
Having said that, a few features may be of use. The -c flag makes searches case-sensitive, which can be useful for navigating headings in man pages, which are always in uppercase.
The "+/search" argument is very useful too. Use this to automatically scroll to the first match, for example:
One more pager of note is ov . This is a newer release, coming out in 2020, and the program is written in Go, with excellent documentation. The project even explains the best use of ov with various other tools, including man .
ov supports an extensive set of interactive commands, which you can view at any time by pressing h:
One of my favorite features is basic, but very useful: G to toggle line numbers. While ov shows the current line number in the bottom-right, this can be easy to lose track of, and line numbers can help you orient yourself, especially within longer man pages.
Like the most pager, ov can display more than one file at once. But, unlike most, it can open multiple files from the command line, so it's possible to read more than one man page at once, using process substitution:
Within ov's interface, you can press ]to move to the next file and [for the previous one. Although it's a little awkward to use, this feature can be handy when comparing the man pages of two similar commands. You could even use it to compare man pages for two different versions of the same command.
Where ov really shines is its configurability. An example of one small win is the --header option, which sets the number of fixed header lines:
This is great for viewing man pages, since the first line is a nice header that reminds you which page you're viewing help for:
The --header option keeps this line always in view, so you won't get lost, even with several man pages open in different terminal windows.
Another useful option is --section-delimiter. ov lets you use this to define where sections occur in the document you're viewing. You can then navigate between sections using Space to move forward and ^ to move backward. Since man pages have clearly defined sections, this is very useful:
The delimiter here is a regular expression that matches lines beginning with a non-space character. Since man pages format section headings like this, with all other content indented by whitespace, this neatly splits a man page into sections, with easy navigation between them.
As a bonus, you'll also get section headers that stay fixed within their current section, like a more advanced version of the --header option:
Your pager is usually a simple tool, so you'd be forgiven for not paying it much thought. But newer pagers like ov can, with a little investment, make reading help pages a quicker and easier task.
