Permalink
Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
438 lines (375 sloc) 18 KB
*manpageview.txt* Man Page Viewer Nov 26, 2008
Author: Charles E. Campbell, Jr. <NdrchipO@ScampbellPfamily.AbizM>
(remove NOSPAM from Campbell's email first)
Copyright: (c) 2004-2008 by Charles E. Campbell, Jr. *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|
3. ManPageView Options......................: |manpageview-options|
4. ManPageView History......................: |manpageview-history|
==============================================================================
2. ManPageView Usage *manpageview-usage* {{{1
GENERAL FORMAT *manpageview-format* {{{2
(command) :[count][HORV]Man [topic] [booknumber]
(map) [count]K
MAN *manpageview-man* {{{2
>
:[count]Man topic
:Man topic booknumber
:Man booknumber topic
:Man topic(booknumber)
:Man -- will restore position prior to use of :Man
(only for g:manpageview_winopen == "only")
<
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): >
:[count]HMan topic -- g:manpageview_winopen= "hsplit"
:[count]HEMan topic -- g:manpageview_winopen= "hsplit="
:[count]VMan topic -- g:manpageview_winopen= "vsplit"
:[count]VEMan topic -- g:manpageview_winopen= "vsplit="
:[count]OMan topic -- g:manpageview_winopen= "osplit"
:[count]RMan topic -- g:manpageview_winopen= "reuse"
<
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: >
:Man info.i
< A number of maps are provided: >
MAP EFFECT
> n go to next node
< p go to previous node
d go to the top-level directory
u go to up node
t go to top node
H give help
i ask for "index" help
<bs> go up one page
<del> go up one page
<tab> go to next hyperlink
<
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
>
[count]K
<
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.
PERL *manpageview-perl* {{{2
For perl, the following command, >
:Man sprintf.pl
< will bring up the perldoc version of sprintf. The perl
support includes a "path" of options to use with perldoc: >
g:manpageview_options_pl= ";-f;-q"
< 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, >
:Man sprintf
< will return the perl help for sprintf.
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, >
:Man bzopen.php
< 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/.
EXTENDING MANPAGEVIEW *manpageview-extend* {{{2
To extend manpageview to handle other documentation systems,
manpageview has some special variables with a common extension: >
g:manpageview_pgm_{ext}
g:manpageview_options_{ext}
g:manpageview_sfx_{ext}
<
For perl, the {ext} is ".pl", and the variables are set to: >
let g:manpageview_pgm_pl = "perldoc"
let g:manpageview_options_pl = ";-f;-q"
<
For info, that {ext} is ".i", and the extension variables are
set to: >
let g:manpageview_pgm_i = "info"
let g:manpageview_options_i = "--output=-"
let g:manpageview_syntax_i = "info"
let g:manpageview_K_i = "<sid>ManPageInfo(0)"
let g:manpageview_init_i = "call ManPageInfoInit()"
<
The help on |manpageview_extend| covers these variables in more
detail.
MULTIPLE MAN PAGES *manpage-pageup* *manpage-pagedown*
With >
man -a topic
< one may get multiple man pages in a single buffer. Manpageview
provides two maps to facilitate moving amongst these pages: >
PageUp : move to preceding manpage
PageDown: move to succeeding manpage
<
==============================================================================
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 >
iconv -c
< You may avoid manpageview's use of iconv by putting: >
let g:manpageview_iconv= ""
< 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).
*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: >
:Man -a printf
<
*g:manpageview_options*
g:manpageview_options : extra options that will be passed on when
invoking the man command
examples:
let g:manpageview_options= "-P 'cat -'"
let g:manpageview_options= "-c"
let g:manpageview_options= "-Tascii"
*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 six values:
"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.
"hsplit" man page will appear in a horizontally split window (default)
"vsplit" man page will appear in a vertically split window
"hsplit=" man page will appear in a horizontally & evenly split window
"vsplit=" man page will appear in a vertically & evenly split window
"reuse" man page will re-use current window. Use <ctrl-o> to return.
(for the reuse option, thanks go to Alan Schmitt)
*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: >
let g:manpageview_pgm_pl = "perldoc"
let g:manpageview_options= ";-f;-q"
<
Note that, for perl, the options consist of a sequence of
options to be tried, separated by semi-colons.
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: >
nmap V <Plug>ManPageView
< Put this in your <.vimrc>.
==============================================================================
4. ManPageView History *manpageview-history* {{{1
Thanks go to the various people who have contributed changes,
pointed out problems, and made suggestions!
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