vimpager.1

.TH VIMPAGER 1 "August 4, 2014" "vimpager user manual"
.SH NAME
.PP
vimpager - less.sh replacement
.SH SYNOPSIS
.PP
vimpager \[aq]some file\[aq]
.PP
# or (this won\[aq]t always syntax highlight as well)
.PP
cat \[aq]some file\[aq] | vimpager
.SH RUN-TIME DEPENDENCIES
.IP \[bu] 2
vim
.IP \[bu] 2
sharutils or some uudecode (optional)
.SH BUILD DEPENDENCIES
.IP \[bu] 2
sharutils or some uuencode
.IP \[bu] 2
pandoc
.SH INSTALL
.IP
.nf
\f[C]
git\ clone\ git://github.com/rkitover/vimpager
cd\ vimpager
sudo\ make\ install
\f[]
.fi
.PP
In your ~/.bashrc add the following:
.IP
.nf
\f[C]
export\ PAGER=/usr/local/bin/vimpager
alias\ less=$PAGER
alias\ zless=$PAGER
\f[]
.fi
.SH DESCRIPTION
.PP
A slightly more sophisticated replacement for less.sh that also supports
being set as the PAGER environment variable.
Displays man pages, perldocs and python documentation properly.
Works on Linux, Solaris, FreeBSD, NetBSD, OpenBSD, OSX, Cygwin and msys.
Should work on most other systems as well.
.PP
On GitHub: <http://github.com/rkitover/vimpager>
.PP
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.
.PP
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.
.PP
To disable loading plugins, put "set noloadplugins" into a vimpagerrc
file.
.PP
You can also switch on the "vimpager" variable in your vimrc to set
alternate settings for vimpager.
.PP
Put the following into your .vimrc/vimpagerrc if you want to use
gvim/MacVim for your pager window:
.IP
.nf
\f[C]
let\ vimpager_use_gvim\ =\ 1
\f[]
.fi
.PP
To turn off the feature of passing through text that is smaller than the
terminal height use this:
.IP
.nf
\f[C]
let\ vimpager_passthrough\ =\ 0
\f[]
.fi
.PP
See "PASSTHROUGH MODE" further down.
.PP
To start vim with -X (no x11 connection, a bit faster startup) put the
following into your .vimrc/vimpagerrc:
.IP
.nf
\f[C]
let\ vimpager_disable_x11\ =\ 1
\f[]
.fi
.PP
The scroll offset (:help scrolloff), may be specified by placing the
following into your .vimrc/vimpagerrc (default = 5, disable = 0):
.IP
.nf
\f[C]
let\ vimpager_scrolloff\ =\ 5
\f[]
.fi
.PP
The process tree of vimpager is available in the "vimpager_ptree"
variable, an example usage is as follows:
.IP
.nf
\f[C]
if\ exists("vimpager")
\ \ if\ exists("vimpager_ptree")\ &&\ vimpager_ptree[-2]\ ==\ \[aq]wman\[aq]
\ \ \ \ set\ ft=man
\ \ endif
endif
\f[]
.fi
.PP
To disable the use of AnsiEsc.vim to display ANSI colors in the source,
set:
.IP
.nf
\f[C]
let\ vimpager_disable_ansiesc\ =\ 1
\f[]
.fi
.PP
see the section "ANSI ESCAPE SEQUENCES AND OVERSTRIKES" for more
details.
.SH COMMAND LINE OPTIONS
.SS + | +G
.PP
Start at the end of the file, just like less.
.SS -c cmd
.PP
Run a vim command after opening the file.
.SH ANSI ESCAPE SEQUENCES AND OVERSTRIKES
.PP
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.
.PP
Overstrikes such as in man pages will always be removed.
.PP
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.)
.PP
However, your vim must have been compiled with the \[aq]conceal\[aq]
feature enabled.
To check, try
.IP
.nf
\f[C]
:echo\ has("conceal")
\f[]
.fi
.PP
if the result is \[aq]1\[aq] you have conceal, if it\[aq]s \[aq]0\[aq]
you do not, and the AnsiEsc plugin will not be enabled.
.PP
If you\[aq]re on a Mac, the system vim does not enable this feature,
install vim from Homebrew.
.PP
To disable the use of AnsiEsc.vim, set:
.IP
.nf
\f[C]
let\ vimpager_disable_ansiesc\ =\ 1
\f[]
.fi
.PP
in your .vimrc.
.SH PASSTHROUGH MODE
.PP
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, depending on your
"vimpager_disable_ansiesc" setting, otherwise the text will be
highlighted with vimcat.
.PP
You can turn this off by putting
.IP
.nf
\f[C]
let\ vimpager_enable_passthrough\ =\ 0
\f[]
.fi
.PP
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.
.SH CYGWIN/MSYS/MSYS2 NOTES
.PP
vimpager works correctly with the native Windows gvim, just put it in
your PATH and set the vimpager_use_gvim option as described above.
.SH LICENSE AND COPYRIGHT
.PP
Copyright (c) 2014, Rafael Kitover <rkitover@gmail.com> and contributors
(see the list of CONTRIBUTORS at the bottom of the \[aq]vimpager\[aq]
file.)
.PP
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.PP
Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
.PP
Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
.PP
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER ``AS IS\[aq]\[aq] AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.SH AUTHORS
Rafael Kitover <rkitover@gmail.com>.