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:
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:
man -P pager
For example, to look up the help page for ls, using the less pager:
man -P less ls
And to look up help for man itself, using the more pager:
man -P more man
You should note that pager can be any valid command, including its own arguments and even pipes:
man -P "grep operand | wc -l" ls
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:
MANPAGER=most man pwd
Finally, if your version of man supports a configuration file, you can use it to change the pager that man uses permanently.
If you have a man.conf file, the syntax to set the pager is similar to setting an environment variable:
MANPAGER less -s
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 less pager, specifically this command:
less -Sr
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 b and 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 u to scroll back (up) by a half page, and d to scroll forward (down) by a half page.
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.
The "+/search" argument is very useful too. Use this to automatically scroll to the first match, for example:
man -P 'most +/symbolic' ls
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:
ov <(man ls) <(man pwd)
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:
man -P 'ov --header 1' man
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:
man -P 'ov --section-delimiter "^[^\s]"' man
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.
