Introduction

This article follows up on my previous blog post on improving the experience of digging through the documentation of command line interface tools. In that article, I detailed my preferred method for fetching documentation using the cheat.sh website.

This method, however, requires an internet connection. What if Microsoft decides to do another automatic software update, during the night, and crashes the worldwide web, again (looking at you CrowdStrike)? This would leave the rest of humanity with only the man pages to piece together all of human knowledge. Could we not make the experience of interacting with the man pages a bit more pleasant? That will be the goal of this article.

Manpager

Did you know that you can choose the application that is used for displaying the man pages? By default, it is set to the less pager, which doesn’t provide the best user experience due to its lack of proper syntax highlighting. The environment variable MANPAGER defines the program used for viewing the man pages.

`bat`

My favorite alternative to less is the bat program. It is part of series of common GNU CLI tools that have been rewritten in Rust, and often extended with additional functionality. This list includes bat as a drop-in replacement for cat and less, fd for find and ripgrep for grep. bat provides syntax highlighting for most programming languages and has even replaced cat and less for me entirely:

alias less="bat"
alias cat="bat -pp"

By default, bat acts like a pager similar to less. The -pp flag disables the paging option and prints the entire file, making bat function exactly like cat.

Moreover, it can be used as the MANPAGER with the following command taken from their README

export MANPAGER="sh -c 'col -bx | bat -l man -p'"

Check out the results:

Comparison of less (left) and bat (right) as Manpagers

On my Mac, this command worked out of the box. However, on my Linux machine I was encountering formatting issues due to lingering color codes in the output (e.g., 1mgrep). From the bat documentation, this issue can be resolved by setting the following environment variable export MANROFFOPT="-c"

Neovim

Alternatively, you can use neovim as your MANPAGER which will even respect your color scheme

export MANPAGER='nvim +Man!'

Comparison of less (left) and neovim (right) as Manpagers

However, since it also loads all of your plugins (unless you were diligent in setting up lazy loading of packages), it will necessarily be a bit slower than bat, which is why I use it instead.

Source

I was made aware of the MANPAGER environment variable by this video from DistroTube. Go check him out, he makes great Linux related content!