## 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](/cgit/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:

    ::txt
    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:

    ::txt
    txr --compile=mnpgr.tl

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

    ::txt
    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](https://unix.stackexchange.com/questions/758676/open-man-or-info-pages-from-the-same-position-where-you-left-off-last-time)
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]( https://gitlab.com/man-db/man-db).

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.