manpageview.txt Man Page Viewer Aug 31, 2022
Author: Charles E. Campbell <NcampObell@SdrPchip.AorgM-NOSPAM>
(remove NOSPAM from Campbell's email first)
Copyright: (c) 2004-2020 by Charles E. Campbell manpageview-copyright
The VIM LICENSE applies to ManPageView.vim and ManPageView.txt
(see copyright) except use "ManPageView" instead of "Vim"
no warranty, express or implied. use at-your-own-risk.
==============================================================================
1. Contents manpageview manpageview-contents {{{1
1. Contents.................................: manpageview-contents
2. ManPageView Usage........................: manpageview-usage
General Format.........................: manpageview-format
Man....................................: manpageview-man
Opening Style..........................: manpageview-open
K Map..................................: manpageview-K
Perl...................................: manpageview-perl
Info...................................: manpageview-info
Php....................................: manpageview-php
Extending ManPageView..................: manpageview-extend
Manpageview Suggestion.................: manpageview-suggest
From the Shell.........................: manpageview-shell
Manpageview History....................: manpageview-history
Manpageview Search.....................: manpageview-search
3. ManPageView Options......................: manpageview-options
4. ManPageView Update History...............: manpageview-updates
==============================================================================
2. ManPageView Usage manpageview-usage {{{1
GENERAL FORMAT manpageview-format {{{2
(command) :[count][HORV]Man [topic] [booknumber]
(map) [count]K
MAN manpageview-man {{{2
Put cursor on topic, press "K" while in normal mode.
(This works if (a) you've not mapped some other key
to <Plug>ManPageView, and (b) if 'keywordprg' is "man",
which it is by default)
If a count is present (ie. 7K), the count will be used
as the booknumber.
If your "man" command requires options, you may specify them
with the g:manpageview_options variable in your <.vimrc>.
OPENING STYLE manpageview-open {{{2
In addition, one may specify open help and specify an
opening style (see g:manpageview_winopen below):
To support perl, manpageview now can switch to using perldoc
instead of man. In fact, the facility is generalized to
allow multiple help viewing systems.
INFO manpageview-info {{{2
Info pages are supported by appending a ".i" suffix:
A number of maps are provided:
The "index" help isn't currently using index information; instead,
its doing some searching in the various info files. The "," and ";"
operators are provided to go to the next and previous matches,
respectively.
K MAP manpageview-K {{{2
ManPageView also supports the use of "K", as a map, to
invoke ManPageView. The topic is taken from the word
currently under the cursor. If a [count] is present, it
will be used as the booknumber.
In the case of an url (http://...), the K map will invoke
the program given in g:manpageview_K_http on the url in
an attempt to show the site in a new tab.
manpageview-s-leftmouse
The <s-leftmouse> button also does a manpageview using the
word under the mouse.
MAN manpageview-.man
When in a file supporting special manpage handling such
as perl or python files, but one wants a regular manpage
anyway, use the ".man" suffix Example:
manpageview-specialhandler
In general, one can force special handling by appending a
special handler's associated suffix to the desired topic:
PERL manpageview-perl manpageview-.pl {{{2
For perl, the following command,
will bring up the perldoc version of sprintf. The perl
support includes a "path" of options to use with perldoc:
Thus just the one suffix (.pl) with manpageview handles
embedded perl documentation, perl builtin functions, and
perl FAQ keywords.
If the filetype is "perl", which is determined by vim
for syntax highlighting, the ".pl" suffix may be dropped.
For example, when editing a "abc.pl" file,
will return the perl help for sprintf.
PHP manpageview-php manpageview-.php {{{2
For php help, Manpageview uses links to get help from
http://www.php.net (by default). The filetype as determined
for syntax highlighting is used to signal manpageview to use
php help. As an example,
will get help for php's bzopen command. When one is editing
a php file, then man will default to getting help for php
(ie. when the filetype is php, :Man bzopen will get the help
for php's bzopen).
Manpageview uses "links -dump http://www.php.net/TOPIC" by
default; hence, to obtain help for php you need to have a
copy of the links WWW browser. The homepage for Elinks is
http://elinks.cz/.
If you want to override just the url used to obtain php help:
PYTHON manpageview-python manpageview-.py {{{2
For python help, Manpageview depends upon pydoc. As an
example, try
EXTENDING MANPAGEVIEW manpageview-extend {{{2
To extend manpageview to handle other documentation systems,
manpageview uses some special variables with a common extension:
For perl, the {ext} is ".pl", and the variables are set to:
For info, that {ext} is ".i", and the extension variables are
set to:
The help on manpageview_extend covers these variables in more
detail.
MULTIPLE MAN PAGES manpageview-pageup manpageview-pagedown
With
one may get multiple man pages in a single buffer. Manpageview
provides two maps to facilitate moving amongst these pages in a
single buffer:
Not all systems, however, put multiple manual pages in a single buffer;
Scientific Linux, for example, has one quit each page before showing
the next manual page. PageUp/PageDown in such cases will then utilize
the same behavior discussed in manpageview-search for the
PageUp/PageDown keys; ie. display the previous/next manpage.
Try "man -a printf" to see a typical example of multiple manpage
behavior.
MANPAGEVIEW SUGGESTION manpageview-suggest
As an example, for C: put in .vim/ftplugin/c/c.vim:
This map allows K to immediately use manpageview with functions in a
C program. One may make similar maps for other languages, of course,
or simply put the map in one's <.vimrc>.
FROM THE SHELL manpageview-shell
There are a lot of ways to get manpageview to work from the shell.
I typically use:
With this function (and with Korn shell or bash), one may use "man"
from the shell's command line and have it bring up gvim with
manpageview instead.
manpageview-history mpv-history
MANPAGEVIEW HISTORY :Manprv :Mannxt
Manpageview keeps track of successful (ie. not empty) pages; you may
use
to go forwards and backwards in the history. In addition, while in
a manpageview help buffer, one also has two maps available:
which you may likewise use to go forwards and backwards in the
history, respectively. One may precede these two maps with a count,
too.
MANPAGEVIEW SEARCH manpageview-search mpv-search
Sometimes the man page one gets isn't in the right book. Use
the following two maps to search for manpages with the same topic:
These maps are only available when in a manpageview generated buffer.
One may precede these maps by a count; ie. 2<s-left>, for example.
==============================================================================
3. ManPageView Options manpageview-options {{{1
g:manpageview_iconv
g:manpageview_iconv : some systems seem to include unwanted
characters. The iconv program can be used to filter out
such characters; by default, manpageview will use
You may avoid manpageview's use of iconv by putting:
in your <.vimrc> file; you may also specify any other
filter you wish with this variable. Also, if iconv
happens to not be executable(), then no filtering
will be done. (Thanks to Matthew Wozniski).
As an example, Hong Xu reports that he has found that
useful when using NetBSD.
g:manpageview_K_http : g:manpageview_K_http
This option is set to one of the following strings:
depending on which of the associated programs is
executable, by default. You may override this
selection by setting g:manpageview_K_http in his/her
.vimrc . See manpageview-K for more.
g:manpageview_multimanpage
g:manpageview_multimanpage (=1 by default)
This option means that the PageUp and PageDown keys
will be mapped to move to the next and previous manpage
in a multi-man-page buffer. Such buffers result with
the "man -a" option. As an example:
g:manpageview_options
g:manpageview_options : extra options that will be passed on when
invoking the man command
examples:
g:manpageview_pgm
g:manpageview_pgm : by default, its "man", but it may be changed
by the user. This program is what is called to actually
extract the manpage.
g:manpageview_winopen
g:manpageview_winopen : may take on one of seven values:
OMan "only" man page will become sole window.
Side effect: All windows' contents will be saved first!
(windo w) Use :q to terminate the manpage and restore the
window setup. Note that mksession is used for this
option, hence the +mksession configure-option is required.
HMan "hsplit" man page will appear in a horizontally split window (default)
VMan "vsplit" man page will appear in a vertically split window
HEMan "hsplit=" man page will appear in a horizontally & evenly split window
VEMan "vsplit=" man page will appear in a vertically & evenly split window
RMan "reuse" man page will re-use current window. Use <ctrl-o> to return.
(for the reuse option, thanks go to Alan Schmitt)
TMan "tab" man page will be on a separate tab
g:manpageview_server g:manpgeview_user
g:manpageview_server : for WinNT; uses rsh to read manpage remotely
g:manpageview_user : use given server (host) and username
examples:
let g:manpageview_server= "somehostname"
let g:manpageview_user = "username"
g:manpageview_init_EXT g:manpageview_K_EXT
g:manpageview_options_EXT g:manpageview_pfx_EXT
g:manpageview_pgm_EXT g:manpageview_sfx_EXT
g:manpageview_syntax_EXT
g:manpageview_init_{ext}: manpageview_extend
g:manpageview_K_{ext}:
g:manpageview_options_{ext}:
g:manpageview_pfx_{ext}:
g:manpageview_pgm_{ext}:
g:manpageview_sfx_{ext}:
g:manpageview_syntax_{ext}:
With these options, one may specify an extension on a topic
and have a special program and customized options for that
program used instead of man itself. As an example, consider
perl:
The g:manpageview_init_{ext} specifies a function to be called
for initialization. The info handler, for example, uses this
function to specify buffer-local maps.
The g:manpageview_K_{ext} specifies a function to be invoked
when the "K" key is tapped. By default, it calls
s:ManPageView().
The g:manpageview_options_{ext} specifies what options are
needed.
The g:manpageview_pfx_{ext} specifies a prefix to prepend to
the nominal manpage name.
The g:manpageview_pgm_{ext} specifies which program to run for
help.
The g:manpageview_sfx_{ext} specifies a suffix to append to
the nominal manpage name. Without this last option, the
provided suffix (ie. Man sprintf.pl 's ".pl") will be elided.
With this option, the g:manpageview_sfx_{ext} will be
appended.
The g:manpageview_syntax_{ext} specifies a highlighting file
to be used for this particular extension type.
You may map some key other than "K" to invoke ManPageView; as an
example:
Put this in your <.vimrc>.
==============================================================================
4. ManPageView History manpageview-updates {{{1
Thanks go to the various people who have contributed changes,
pointed out problems, and made suggestions!
v25: Apr 03, 2013 * (Gary Johnson) suggested changing some of
the default book numbers to zero for more
general searching.
Apr 04, 2013 * eliminated some "noise" while searching
for other books containing the topic
(see mpv-search)
* search now uses an internal List, and so
it also searches manpage books such as 3p,
5x, etc.
Apr 05, 2013 * found why manpageview's mpv-search was
noisy (had to do with g:manpageview_iconv).
Fixed.
Mar 04, 2014 * man glob was failing; manpageview was
identifying the extension as gl. Fixed.
Jan 12, 2016 * man -a printf causes multiple manpage
handling for /usr/bin/man; sometimes
a merged buffer results, sometimes a
quit-to-goto-next page behavior results.
See manpageview-pageup.
Oct 12, 2021 * improvements made to syntax highlighting of
manpages.
Aug 31, 2022 * (Gary Johnson) pointed out that manpageview
doesn't always restore lz (which it
generally sets). Fixed
v24: Jan 03, 2011 * some extra protection against trying to use
a program that is not executable
Mar 30, 2012 * TMan command included
May 25, 2012 * When in a specially supported filetype, such
as perl, allow ".man" as a topic extension to
get regular manpage support. (ex. :Man paps.man)
Aug 07, 2012 * (Gary Johnson) the K map wasn't working correctly
inside C functions.
Jan 17, 2013 * (Zilvinas Valinskas) provided a patch to
make use of $MANWIDTH.
Jan 30, 2013 * worked on :RMan to get it to work right with
vim and tex files
Feb 07, 2013 * added history
* added -k based keyword search support
Feb 08, 2013 * (Michael Henry) provided a patch fixing the
PageUp/PageDown map directions. He also
pointed out that the K map didn't work on
some info pages properly. Fixed.
Jul 23, 2014 * changed www.php.net to php.net (php support)
Jun 01, 2015 * leftmouse used in a manpage was doing the
same as K (manpageview-K). This interfered
with being able to click and drag to pick
up text. So the map has been moved to
<s-leftmouse> instead.
v23: May 18, 2009 * on the third attempt to get a manpage, if
the user provided no explicit
g:manpageview_iconv setting, then the
an attempt is made with iconv off.
* Fixed K mapping for php, tex, etc.
* (in progress) KMan [ext] to set default
extension for the K map
Oct 21, 2010 * added python help via pydoc (suffix: .py)
Oct 25, 2010 * Version 23 released
v22: Nov 10, 2008 * if g:manpageview_K_{ext} (ext is some
extension) exists, previously that would
be enough to institute a K map. Now, if
that string is "", then the K map will not
be generated.
Nov 17, 2008 * handles non-existing manpage requests better
v21: Sep 11, 2008 * when at a top node with info help, the up
directory shows as "(dir)". A "u" issued a
warning and closes the window. It now issues
a warning but leaves the window unchanged.
* improved shellescape() use
* new option: g:manpageview_multimanpage
Sep 27, 2008 * The K map now uses <cword> expansion except when
used inside a manpage (where it uses <cWORD>).
v19: Jun 06, 2008 * uses the shellescape() function for better
security. Thus vim 7.1 is required.
* when shellescape() isn't available, manpageview
will only issue a warning message when invoked
instead of every time vim is invoked.
* syntax/manphp.vim was using "set" instead of
"setlocal" and so new buffers were inadvertently
being prevented from being modifiable.
Aug 05, 2008 * fixed a problem with using K multiple times with
php files
v18: Jun 06, 2008 * <PageUp> and <PageDown> support added to jump
between multiple man pages loaded into one buffer
such as may occur with :Man -a printf
* links -dump used instead of links for php
v17: Apr 18, 2007 * changed the topic cleanup to use 'g' instead
of '' in the substitute().
* Fixed bug with info pages - wasn't able to
use the > and < maps to go to pages named
with spaces.
* Included the g:manpageview_iconv option
Sep 07, 2007 * viewing window now is read-only and swapfile
is turned off
Sep 07, 2007 * The "::" in some help pages (ex. File::stat)
was being parsed out, leaving only the left
hand side word. Manpageview now accepts them.
Nov 12, 2007 * At the request of F. Mehner, with
g:manpageview_winopen is "reuse", manpageview
will re-use any man-page windows that are still
open.
* (F.Mehner) in "reuse" mode, a K on a blank
character terminated vim. Fixed!
May 09, 2008 * Added <PageUp> and <PageDown> maps
v16: Jun 28, 2006 * bypasses sxq with '"' for windows internally
Sep 26, 2006 * implemented <count>K to look up a topic
under the cursor but in the <count>-th book
Nov 21, 2006 * removed s:mank related code; man -k being
handled without it.
Dec 04, 2006 * added fdc=0 to manpageview settings bypass
Feb 21, 2007 * removed modifications to isk; instead,
manpageview attempts to fix the topic and
uses expand("<cWORD>") instead:w
v15: Jan 23, 2006 * works around nomagic option
* works around cwh=1 to avoid Hit-Enter prompts
Feb 13, 2006 * the test for keywordprg was for "man"; now its
for a regular expression "^man\>" (so its
immune to the use of options)
Apr 11, 2006 * HMan, OMan, VMan, Rman commands implemented
Jun 27, 2006 * escaped any spaces coming from tempname()
v14: Nov 23, 2005 * "only" was occasionally issuing an "Already one
window" message, which is now prevented
Nov 29, 2005 * Aaron Griffin found that setting gdefault
gave manpageview problems with ctrl-hs. Fixed.
Dec 16, 2005 * Suresh Govindachar asked about letting
manpageview also handle perldoc -q manpages.
IMHO this was getting cumbersome, so I extended
opt to allow a semi-colon separated "path" of
up to three options to try.
Dec 20, 2005 * In consultation with Gareth Oakes, manpageview
needed some quoting and backslash-fixes to work
properly with windows and perldoc.
Dec 29, 2005 * added links-based help for php functions
v13: Jul 19, 2005 * included niebie's changes to manpageview -
<bs>, <del> to scroll one page up,
<tab> to go to the next hyperlink
d to go to the top-level directory
and some bugfixes ([] to \[ \], and redirecting
stderr to /dev/null by default)
Aug 17, 2005 * report option workaround
Sep 26, 2005 * :Man -k now uses "man -k" to generate a keyword
listing
* included syntax/man.vim and syntax/mankey.vim
v12: Jul 11, 2005 * unmap K was causing "noise" when it was first
used. Fixed.
v11: * K now <buffer>-mapped to call ManPageView()
v10: * support for perl/perldoc:
g:manpageview_{ pgm | options | sfx }_{ extension }
* support for info: g:manpageview_{ K | pfx | syntax }
* configuration option drilling -- if you're in a
*.conf file, pressing "K" atop an option will go
to the associated help page and option, if there's
help for that configuration file
v9: * for vim versions >= 6.3, keepjumps is used to reduce the
impact on the jumplist
* manpageview now turns off linewrap for the manpage, since
re-formatting doesn't seem to work usually.
* apparently some systems resize the [g]vim display when
any filter is used, including manpageview's :r!... .
Setting g:manpageview_dispresize=1 will force retention
of display size.
* before mapping K to use manpageview, a check that
keywordprg is "man" is also made. (tnx to Suresh Govindachar)
v8: * apparently bh=wipe is "new", so I've put a version
test around that setting to allow older vim's to avoid
an error message
* manpageview now turns numbering off in the manpage buffer (nonu)
v7: * when a manpageview window is exit'd, it will be wiped out
so that it doesn't clutter the buffer list
* when g:manpageview_winopen was "reuse", the manpage would
reuse the window, even when it wasn't a manpage window.
Manpageview will now use hsplit if the window was marked
"modified"; otherwise, the associated buffer will be marked
as "hidden" (so that its still available via the buffer list)
v6: * Erik Remmelzwal provided a fix to the g:manpageview_server
support for NT
* implemented Erik's suggestion to re-use manpage windows
* Nathan Huizinga pointed out, <cWORD> was picking up too much for
the K map. <cword> is now used
* Denilson F de Sa suggested that the man-page window be set as
readonly and nonmodifiable
v5: * includes g:manpageview_winmethod option (only, hsplit, vsplit)
v4: * Erik Remmelzwaal suggested including, for the benefit of NT users,
a command to use rsh to read the manpage remotely. Set
g:manpageview_server to hostname (in your <.vimrc>)
g:manpageview_user to username
v3: * ignores (...) if it contains commas or double quotes. elides
any commas, colons, and semi-colons at end
* g:manpageview_options supported
v2: * saves current session prior to invoking man pages :Man will
restore session. Requires +mksession for this new command to
work.
v1: the epoch
==============================================================================
vim:tw=78:ts=8:ft=help:fdm=marker