Add markdown README

1 files changed, 54 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..80784bb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,54 @@
+## What is `mnpgr`?
+
+`mnpgr` is a tiny TXR Lisp program that allows Vim to be used as a pager for
+reading man pages.
+
+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`.
+
+## 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`.
+
+Using it interpreted. Put it somewhere, for instance your personal `~/bin`
+directory. Then:
+
+    ::txt
+    export MANPAGER=~/bin/mnpgr.tl
+
+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
+
+## 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.
+
+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.
+