Zameer Manji

Using Vim as $MANPAGER

Created On:

The default pager for man is less. Unfortunately when using less as the pager there is no coloring of the man page, no folding of sections and no way to copy text. Reading man pages would be more enjoyable if man could use a pager that had those features.

This can be easily fixed by using vim as the pager for man. If you read the man page for man we can see that setting the $MANPAGER environment variable allows us to change which pager man uses. To use vim as the pager, just place the following code in your ~/.bash_profile:

export MANPAGER="col -b | vim -c 'set ft=man ts=8 nomod nolist nonu' -c 'nnoremap i <nop>' -"

The above command does a few things. First it uses the col utility to remove extra ^H (backspace) characters because they are not handled correctly by vim. Next we pipe the output into vim and we set a few options:

  1. ft=man enables the coloring of the man page.
  2. ts=8 ensures the width of tab characters matches less.
  3. nomod removes the modification warning when trying to quit.
  4. nonu removes line numbers.
  5. nolist disables listchars so trailing whitespace and extra tabs are not highlighted.
  6. nnoremap i <nop> ensures that we do not accidentally enter insert mode when viewing the man page.

This solution is better than others because it does not involve doing crazy things like writing a shell function for man or aliasing man to some other command. This solution instead uses the provided environment variables to modify the behaviour of man.

Before

After

Edit

Thanks to Jamie Wong my snippet can be modified. Instead of doing a little hack to prevent us from entering insert mode with nnoremap i <nop> we can enable the noma setting. This sets the buffer to not be modifiable. Since the buffer is not modifiable we cannot enter insert mode or modify the buffer at all. With this change the $MANPAGER variable is set to:

export MANPAGER="col -b | vim -c 'set ft=man ts=8 nomod nolist nonu noma' -"

Edit 2

As Peter Lundgren and some redditors have discovered this value of $MANPAGER does not work when using GNU man because it does not allow pipes for the command. The above does work for BSD man but if you want it to work for GNU man or both you need to change the value to a single command. The following snippet folds the above value into a single shell command.

export MANPAGER="/bin/sh -c \"col -b | vim -c 'set ft=man ts=8 nomod nolist nonu noma' -\""