*manpageview.txt* Man Page Viewer Aug 05, 2008 Author: Charles E. Campbell, Jr. (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 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]VMan 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 go up one page go up one page 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 = "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 : 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_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 : 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 : 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 to return. (for the reuse option, thanks go to Alan Schmitt) 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}: *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 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! 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 * and 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 and maps v16: Jun 28, 2006 * bypasses sxq with '"' for windows internally Sep 26, 2006 * implemented K to look up a topic under the cursor but in the -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("") 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 - , to scroll one page up, 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 -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, was picking up too much for the K map. 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