What is mnpgr?

mnpgr is a tiny TXR Lisp program that allows Vim to be used as a pager for reading man pages.

It works in such a way that Vim will remember your last position in each man page (if Vim is configured to remember file positions).

The program handles the backspace-driven overstrikes that indicate italic, bold and italic+bold text, translating them to a notation which is colorized by the Vim syntax provided in mnpgr.vim. Thus it has accurate syntax coloring, like what you see less.

Because mngpr itself resolves the overstrikes, the resulting rendering in Vim is searchable.

Another benefit of mnpgr is that it replaces with a plain ASCII dash (U+002D) all the nonsense Unicode dashes output by GNU groff. This is not just esthetics. In some systems, the U+2010 hyphen seriously corrupts the terminal display, rendering man pages unreadable.

Installation

The mnpgr.vim file goes into your ~/.vim/syntax directory, which you have to create if you have never installed custom syntax files.

The TXR language is required.

You can use the mnpgr.tl program interpreted, or compile it to mnpgr.tlo.

To use it interpreted, put it somewhere, for instance your personal ~/bin directory. Then:

export MANPAGER=~/bin/mnpgr.tl

Make sure it has execute permissions.

Compiling is recommended if you read large man pages on a very slow machine.

To compile mnpgr.tl to mnpgr.tlo use:

txr --compile=mnpgr.tl

Then put the mnpgr.tlo into ~/bin and:

export MANPAGER=~/bin/mnpgr.tlo

If mnpgr.tl has execute permissions, the compiler will propagate that, otherwise you have to remember to chmod +x mnpgr.tlo.

Why not use vim +MANPAGER or other approaches?

This doesn't handle the backspace overstrikes output by man; it can only be used on man output that has been stripped of the overstrikes.

That will then not highlight keywords in the text; there is only a half-baked highlighting that handles section headings and a few other things

Vim can be coaxed into handling backspace overstrikes by tweaks to the ctrlh syntax it comes with.

However, that only makes the emphasized elements look good.

They are left unsearchable because the representation with the backspace overstrikes is retained under the hood.

The mnpgr project started as an answer to a Unix StackExchange question, where that was the initial solution. The question is specifically about saving the last position. If Vim alone is used as a pager without a shim script between it and man, it will not save the last position.

Troubleshooting

I see terminal escape sequences in the output!

This is an issue in some installations of the man program from man-db, whereby it is not setting the environment variable GROFF_NO_SGR=1 to prevent GNU groff from emitting terminal escapes. Try exporting that environment variable; if the problem goes away, that is it.

I see an error @page(@section) ... failed to match

You are on some Unix system like MacOS; mnpgr currently only works with the man program from man-db commonly installed on may GNU/Linux systems, namely this one.

Sorry!

That implementation of man establishes a MAN_PN environment variable whose value we are depending on to get name of the man page and section number.

A patch to make mngpr work with other man implementations would be welcome.