sponsor Vim development Vim logo Vim Book Ad

vimpager : Use ViM as PAGER

 script karma  Rating 400/164, Downloaded by 15010  Comments, bugs, improvements  Vim wiki

created by
Rafael Kitover
 
script type
utility
 
description
A PAGER using less.vim with support for highlighting of man pages and many other features. Works on most UNIX-like systems as well as Cygwin and MSYS.

On github:
http://github.com/rkitover/vimpager
 
install details
% VIMPAGER(1) vimpager user manual
% Rafael Kitover <rkitover@gmail.com>
% April 29, 2015

# NAME

vimpager - less.sh replacement

# SYNOPSIS

vimpager 'some file'

# or (this won't always syntax highlight as well)

cat 'some file' | vimpager

# RUN-TIME DEPENDENCIES

* vim
* sharutils or some uudecode (optional)

# BUILD DEPENDENCIES

* sharutils or some uuencode
* pandoc

# INSTALL

```bash
git clone git://github.com/rkitover/vimpager
cd vimpager
sudo make install
```

If you got vimpager from the vim.org scripts section, just put it
somewhere in your PATH, e.g.:

```bash
cp vimpager ~/bin
chmod +x ~/bin/vimpager
```

In your ~/.bashrc add the following:

```bash
export PAGER=/usr/local/bin/vimpager
alias less=$PAGER
alias zless=$PAGER
```

# DESCRIPTION
A PAGER using less.vim with support for highlighting of man pages and
many other features. Works on most UNIX-like systems as well as Cygwin
and MSYS.

On GitHub: <http://github.com/rkitover/vimpager>;

To use a different vimrc with vimpager, put your settings into a ~/.vimpagerrc
or ~/.vim/vimpagerrc or a file pointed to by the VIMPAGER_RC environment
variable.

You can also have a global config file for all users in /etc/vimpagerrc, users
can override it by creating a ~/.vimpagerrc or a ~/.vim/vimpagerrc.

These are the keys for paging while in vimpager, they are the same as in
less for the most part:

| _Key_   | _Action_            | _Key_   | _Action_                  |  
|---------|---------------------|---------|---------------------------|  
|<Space>  |One page forward     |b        |One page backward          |  
|d        |Half a page forward  |u        |Half a page backward       |  
|<Enter>  |One line forward     |k        |One line backward          |  
|G        |End of file          |g        |Start of file              |  
|N%       |percentage in file   |,h       |Display this help          |  
|/pattern |Search for pattern   |?pattern |Search backward for pattern|  
|n        |next pattern match   |N        |Previous pattern match     |  
|:n<Enter>|Next file            |:p<Enter>|Previous file              |  
|q        |Quit                 |,v       |Toggle Less Mode           |  

To disable loading plugins, put "set noloadplugins" into a vimpagerrc
file.

You can also switch on the "vimpager" variable in your vimrc to set alternate
settings for vimpager.

Put the following into your .vimrc/vimpagerrc if you want to use gvim/MacVim
for your pager window:

```vim
let vimpager_use_gvim = 1
```

To turn off the feature of passing through text that is smaller than the
terminal height use this:

```vim
let vimpager_passthrough = 0
```

See "PASSTHROUGH MODE" further down.

To start vim with -X (no x11 connection, a bit faster startup) put the following
into your .vimrc/vimpagerrc:

```vim
let vimpager_disable_x11 = 1
```

The scroll offset (:help scrolloff), may be specified by placing the
following into your .vimrc/vimpagerrc (default = 5, disable = 0):

```vim
let vimpager_scrolloff = 5
```

The process tree of vimpager is available in the "vimpager_ptree" variable, an
example usage is as follows:

```vim
if exists("vimpager")
  if exists("vimpager_ptree") && vimpager_ptree[-2] == 'wman'
    set ft=man
  endif
endif
```

To disable the use of AnsiEsc.vim to display ANSI colors in the source,
set:

```vim
let vimpager_disable_ansiesc = 1
```

see the section "ANSI ESCAPE SEQUENCES AND OVERSTRIKES" for more
details.

# COMMAND LINE OPTIONS

## + | +G

Start at the end of the file, just like less.

## -c cmd

Run a vim command after opening the file. Multiple -c arguments are
supported.

## --cmd cmd

Run a vim command when entering vim before anything else. Multiple --cmd
arguments are supported.

## -u vimrc

Use alternate .vimrc or .vimpagerrc.

# ANSI ESCAPE SEQUENCES AND OVERSTRIKES

If your source is using ANSI escape codes, the AnsiEsc plugin will be
used to show them, rather than the normal vim highlighting, however read
the caveats below. If this is not possible, they will be stripped out
and normal vim highlighting will be used instead.

Overstrikes such as in man pages will always be removed.

vimpager bundles the
[AnsiEsc](http://www.vim.org/scripts/script.php?script_id=4979)
plugin (it is expanded at runtime,
there is nothing you have to do to enable it.)

However, your vim must have been compiled with the 'conceal' feature
enabled. To check, try

```vim
:echo has("conceal")
```

if the result is '1' you have conceal, if it's '0' you do not, and the
AnsiEsc plugin will not be enabled.

If you're on a Mac, the system vim does not enable this feature, install
vim from Homebrew.

To disable the use of AnsiEsc.vim, set:

```vim
let vimpager_disable_ansiesc = 1
```

in your .vimrc.

# PASSTHROUGH MODE

If the text sent to the pager is smaller than the terminal window, then
it will be displayed without vim as text. If it has ansi codes, they
will be preserved, otherwise the text will be highlighted with vimcat.

You can turn this off by putting

```vim
let vimpager_passthrough = 0
```

Passthrough mode requires a POSIX shell with arithmetic expansion, if
there is one on your system and it is not detected please submit an
issue with the path and your OS version.

# CYGWIN/MSYS/MSYS2 NOTES

vimpager works correctly with the native Windows gvim, just put it in
your PATH and set the vimpager_use_gvim option as described above.
 

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
vimpager 2.06 2015-06-28 7.0 Rafael Kitover * more Solaris fixes
* remove array syntax from vimcat #118
vimpager 2.05 2015-06-06 7.0 Rafael Kitover * minor AnsiEsc fixes
vimpager 2.04 2015-05-25 7.0 Rafael Kitover * fix Solaris regression
vimpager 2.03 2015-05-15 7.0 Rafael Kitover * use getpos('.') instead of getcurpos() in ansi retab script, some vims do not have getcurpos() #114
* add ,v mapping to switch back and forth between less mode and editing mode #101
* add ,h mapping for help #107
vimpager 2.02 2015-04-30 7.0 Rafael Kitover * fix gvim/mvim support broken in 2.0
vimpager 2.0 2015-04-29 7.0 Rafael Kitover * full support for ANSI highlighted text
  using bundled AnsiEsc
* support MSYS2
* experimental highlighting support for perl
  in perldocs by Magnus Woldrich
* better detection of C man pages with
  highlighting
* suppress errors about things that look like
  modelines
* support for -- and safer opening of any
  file names
* passthrough mode where text that is shorter
  than the terminal window is just printed is
  now the default and supports all
  highlighting
* clean up mappings like 'h' that caused some
  people problems, we bundle our own less.vim
  now so this is easier
* default to bg=dark when using terminal vim,
  this is helpful for people without vim
  configs since most people use a dark
  background but vim defaults to light
* multiple -c and --cmd options are now
  supported, as well as the -u option
vimpager 1.8.9 2014-05-25 7.0 Rafael Kitover * security enhancements (snordhausen: Stefan Nordhausen) #78
vimpager 1.8.8 2014-04-07 7.0 Rafael Kitover * don't clobber user's PATH (mayersj1: Steve Mayer)  #77
vimpager 1.8.7 2014-03-10 7.0 Rafael Kitover * use more lines for fallback man page detection, misc. code cleanups (eworm-de: Christian Hesse)
vimpager 1.8.6 2014-02-22 7.0 Rafael Kitover * allow _vimrc on non-windows (mortonfox: Morton Fox)
vimpager 1.8.5 2014-02-12 7.0 Rafael Kitover * fix up arrow binding again, broken in 1.8.4
vimpager 1.8.4 2014-02-09 7.0 Rafael Kitover * disable help screen 'h' binding, cursor moves left instead (Github issue #71)
vimpager 1.8.3 2013-12-23 7.0 Rafael Kitover * reexec self under bash or ksh when available, especially on Solaris (Github issue #63)
* add vim command -c option (aroig: Abdo Roig-Maranges)
* allow ~/.vim/vimpagerrc as conf file (lucc: Lucas Hoffmann)
vimpager 1.8.2 2013-04-26 7.0 Rafael Kitover * better man page detection heuristics, when detection by process tree fails
vimpager 1.8.1 2013-04-15 7.0 Rafael Kitover * License under 2-clause BSD (GitHub Issue #59)
vimpager 1.8.0 2013-03-20 7.0 Rafael Kitover * fix man detection on NetBSD (nonakap: NONAKA Kimihiro)
vimpager 1.7.8 2012-12-31 7.0 Rafael Kitover * set filetype for man pages correctly on FreeBSD (justinkb: Paul Mulders)
vimpager 1.7.7 2012-11-26 7.0 Rafael Kitover * fix screen flashing (GitHub Issue #46)
* fix q with visual selection (GitHub Issue #45)
* support for +G or + command line option to start at the end of the file (vincer: Vince Rosso)
vimpager 1.7.6 2012-11-13 7.0 Rafael Kitover * support /usr/local/etc/vimpagerrc and /etc/vimpagerrc, read after user's .vimrc
* fix for .vimrc paths with spaces (Github Issue #49)
* support compressed file extensions case-insensitively
vimpager 1.7.5 2012-09-29 7.0 Rafael Kitover * set nocp with -u, fixes Pathogen compatibility (Github Issue #40)
* delete temp directory if file is zero length
* remove .gz/.Z suffixes on temp files for compressed files
* support global config file /etc/vimpagerrc (eworm-de: Christian Hesse)
vimpager 1.7.4 2012-09-19 7.0 Rafael Kitover * improve $VIM detection for Win32 (cygwin/msys)
vimpager 1.7.3 2012-09-15 7.0 Rafael Kitover * fix usage without a vimrc (Github Issue #38) broken in 1.7.2
vimpager 1.7.2 2012-09-13 7.0 Rafael Kitover * passthrough option for small text (Wei Dai)
* major code refactor and cleanup
vimpager 1.7.1 2012-07-23 7.0 Rafael Kitover * fix arrow keys (Adam Lickel)
vimpager 1.7.0 2012-06-25 7.0 Rafael Kitover * make sure plugins don't override q (GitHub Issue #34)
* attempt fix for OpenBSD ps (GitHub Issue #33)
vimpager 1.6.9 2012-06-19 7.0 Rafael Kitover * stop sourcing vimrc/gvimrc twice (Dave Goodell)
vimpager 1.6.8 2012-04-11 7.0 Rafael Kitover * fix scrolloff and custom scrolloff setting (GitHub Issue #30)
* safe mode for temp directory (Anselm Strauss)
* turn off relative line numbers (Simon Olofsson and Anisse Astier)
vimpager 1.6.7 2012-01-29 7.0 Rafael Kitover * more intuitive arrow key behavior (patch by Iftekharul Haque)
* add vimpager_ptree variable to hold the process tree (patch by Wei Dai)
vimpager 1.6.6 2012-01-10 7.0 Rafael Kitover * fix malformed utf8 warnings
vimpager 1.6.5 2012-01-10 7.0 Rafael Kitover * fix "col: illegal byte sequence" errors
vimpager 1.6.4 2011-12-31 7.0 Rafael Kitover * configurable scrolloff by Peter Fern
vimpager 1.6.3 2011-12-09 7.0 Rafael Kitover * fix zero length check on cygwin
vimpager 1.6.2 2011-11-28 7.0 Rafael Kitover * Pathogen compatibility
* slightly faster startup
vimpager 1.6.1 2011-11-22 7.0 Rafael Kitover * only source .vimrc if it exists
vimpager 1.6.0 2011-11-18 7.0 Rafael Kitover * work around broken sed on OSX by using col -b if available
vimpager 1.5.9 2011-11-17 7.0 Rafael Kitover * remove -X by default (GitHub issue #19)
vimpager 1.5.8 2011-11-13 7.0 Rafael Kitover * re-source vimrc/gvimrc after less.vim to preserve user highlights and mappings
vimpager 1.5.7 2011-07-25 7.0 Rafael Kitover * remove mouse=h to allow mouse scrolling
vimpager 1.5.6 2011-07-17 7.0 Rafael Kitover * fix for filenames with spaces by Damien Pollet
vimpager 1.5.5 2011-06-30 7.0 Rafael Kitover * remove --noplugin
* better gvimrc detection on cygwin
vimpager 1.5.4 2011-06-24 7.0 Rafael Kitover * support ~/.vimpagerrc and VIMPAGER_RC
vimpager 1.5.3 2011-06-23 7.0 Rafael Kitover * exit immediately for zero length files
vimpager 1.5.2 2011-06-05 7.0 Rafael Kitover * turn off terminal reset on OSX
vimpager 1.5.1 2011-05-22 7.0 Rafael Kitover * better msys support
vimpager 1.5.0 2011-05-07 7.0 Rafael Kitover * set scrolloff-5
vimpager 1.4.9 2011-05-01 7.0 Rafael Kitover * trap more signals for temp file removal
* clear terminal on OSX only for terminal vim
vimpager 1.4.8 2011-04-22 7.0 Rafael Kitover * fix compatibility with Cygwin
* fix compatibility with Windows gvim in Cygwin and msys
* detect ssh session on OSX and Cygwin
* remove "Input not from a terminal" warning entirely
vimpager 1.4.7 2011-04-15 6.0 Rafael Kitover * fix some "input not from terminal" warnings
* fix for invocations on files not in current directory
vimpager 1.4.6 2011-04-11 6.0 Rafael Kitover * MacVim support
* override GUI colors from .gvimrc
* fix syntax highlighting for files opened directly
* reset terminal on completion
vimpager 1.4.5 2011-04-08 6.0 Rafael Kitover * fixes for Mac OSX
* -X option to speed up startup (jdevera)
vimpager 1.4.4 2011-03-21 6.0 Rafael Kitover * .vimrc option let vimpager_use_gvim = 1 to use gvim as the pager window
vimpager 1.4.3 2011-03-20 6.0 Rafael Kitover * Support for .Z and .gz files
vimpager 1.4.2 2011-03-20 6.0 Rafael Kitover * Extensive rewrite using awk for real Solaris compatibility by Wout Mertens.
* Filter ANSI color codes and backspaces for all pager invocations (github issue #2)
vimpager 1.4 2011-01-07 6.0 Rafael Kitover * fix for python2 docs on archlinux from Ivan S. Freitas
vimpager 1.3 2010-05-17 6.0 Rafael Kitover * added 'set nonu'
vimpager 1.2 2010-04-30 6.0 Rafael Kitover * fix for FreeBSD
* add esc-u mapping to turn off hlsearch
vimpager 1.1 2009-05-22 6.0 Rafael Kitover Fix bug where it wouldn't move on searches at launch without moving the cursor first
vimpager 1.0 2009-05-21 6.0 Rafael Kitover Fix for perldoc on Cygwin
vimpager 0.9 2009-05-19 6.0 Rafael Kitover Fix for filenames with spaces.
vimpager 0.8 2009-03-27 6.0 Rafael Kitover Turn off folds (correctly this time.)
ip used for rating: 54.157.61.194

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
   
Vim at Github