Paging man(1) with less(1)

This post is intended to serve as a gentle introduction to the effective navigation of a man(1) page with less(1). I found it useful to become more familiar with this tool when I began using OpenBSD as my operating system of choice (situation permitting).

BACKGROUND

OpenBSD is an operating system following a Unix philosophy. It comes with a complete manual and a coherent philosophy for documentation; the manual is the one source for truth, and the absence or inaccuracy of documentation is considered a bug.

This policy is among OpenBSD’s greatest advantages. Visitors from other operating systems are accustomed to searching the web for solutions – maybe finding blog posts like this one – because those systems often ship with missing or incomplete documentation.

GNU/Linux is a quickly & organically-evolving operating system, so this shouldn’t be construed as a tear down of the community-driven approach to documentation and learning. GNU is Not Unix, but OpenBSD is much more so. Each has its respective merits and drawbacks.

STOP READING NOW

There is gentle discouragement in the OpenBSD community from blog posts like this one. You have no way of knowing if this information has grown stale, and I am not an authoritative source for truth compared to the documentation already on your computer.

Hopefully, I can make it easier to take the direct approach the next time you’re looking for answers:

$ man less

LESS IS MORE

The default pager on OpenBSD is more(1), but the base system includes the more featureful less(1). The introduction that follows is compatible with either pager.

BASIC NAVIGATION

When scrolling a full screen, the line that was just off the screen becomes the first line for the new screen. I usually scroll half a screen at a time when scanning text to stay oriented within the page.

    q      quit
    h      show help

    j      scroll down a line
    d      scroll down a half screen
    f      scroll down a full screen 

    k      scroll up line
    u      scroll up a half screen
    b      scroll up a full screen

    g      jump to top
    G      jump to bottom 

Alternate keys for the basic navigation will also work:

And numbers can be used to jump around the file:

SEARCHING FOR A TAG

The most efficient way to get to the section you’re interested in by searching for tags.

    :t      search for a tag

This requires the manpage you’re reading to be of exceptional quality. On other operating systems, you’re unlikely to be able to take consistent advantage of tag-based navigation.

The tmux(1) manual is a useful example since it is of exception quality and information density.

If you wanted to know what the tmux -u option did, you could type : t u and enter. Or try the tags for select-pane or set-option.

If the tag search matches multiple results (like the k tag for the less page), you can jump between them after searching:

    t       jump to next tag match
    T       jump to previous tag match

SEARCHING FOR A PHRASE

Without tags, pattern matching searches are the easiest way to find what you want:

    /      search forward for /pattern
    ?      search backward for ?pattern

Once you hit / or ?, type the search pattern and hit enter. Patterns are case sensitive by default, but I prefer to change that behavior (see OPTIONS below).

After you type /pattern and hit enter, navigate through the matches with:

    n       jump to next search match
    N       jump to previous search match
    Esc-u   undo search highlighting (repeat to toggle highlighting back on)

You can also search forward with “hiding” of lines that don’t match. This can make it easier to see many matches at once, but you’ll need to clear the effect to see any surrounding context. This hiding filter searches forward like /.

    &       search and filter to only lines matching &pattern (clear filter with &)

MARKS

To reference multiple sections of the same manpage, you could open another terminal session, but it’s much easier to mark your place and return to it later.

    m	    create mark (follow with a lowercase letter to identify the location)
    '       return to your mark (follow with the letter)

For example, create a mark with m a , then jump to another section and create another mark with m b . Now jump back between the two marks with ' a and ' b

NOTE: Marks do not persist between invocations of less

OPTIONS

Here’s my preferred environ(7):

# man(1) will page with less(1) instead of more(1)
export MANPAGER=less

# -i  lowercase search matches uppercase too (but uppercase search only matches upper)
# -J  search matches are also highlighted with an asterisk in the left column
# -m  bottom prompt is more verbose like more(1), e.g. showing % through file
export LESS=-iJm

# maintain search history between invocations (default LESSHISTSIZE=100)
export LESSHISTFILE=$HOME/.lesshst

ASIDE: If you already set less as PAGER it is unnecessary to set MANPAGER.

SEE ALSO

It’s worth getting comfortable learning from manual pages. Once you develop some muscle memory for the basic commands, you can avoid the unnecessary switching cost of opening a browser tab to parse through search results of uncertain quality.

The benefits accrue when you follow the Unix approach more generally, using the same basic tools for multiple purposes. You can use less to page any text file (e.g. less /var/log/messages) or pipe text on stdin (e.g. dmesg | less).

ASIDE: You can also customize less commands and key bindings; see lesskey(1)