manpageview.txt	Man Page Viewer			Jan 12, 2016

Author:  Charles E. Campbell  <NdrchipO@ScampbellPfamily.AbizM>
	 (remove NOSPAM from Campbell's email first)
Copyright: (c) 2004-2015 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

	:[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"
		:[count]TMan topic     -- g:manpageview_winopen= "tab"

	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

	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.

	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:

		:Man syslog.man

				manpageview-specialhandler
	In general, one can force special handling by appending a
	special handler's associated suffix to the desired topic:

		Suffix	  Special Handler
		------    ---------------
		.man	: normal manpages
		.i	: special info handler
		.php	: special php handler
		.pl	: special perl handler
		.py	: special python handler
		.tex	: special tex handler
		.vim	: special vim handler
		

	PERL		manpageview-perl 	 manpageview-.pl {{{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	 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/.

	If you want to override just the url used to obtain php help:
		let g:manpageview_php_url="..."


	PYTHON		manpageview-python	manpageview-.py {{{2

	For python help, Manpageview depends upon pydoc.  As an
	example, try
		:Man pprint.py


	EXTENDING MANPAGEVIEW			manpageview-extend {{{2

	To extend manpageview to handle other documentation systems,
	manpageview uses 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"

	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		manpageview-pageup manpageview-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 in a
	single buffer:

		PageUp  : move to preceding  manpage
		PageDown: move to succeeding manpage

	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:
		nno <buffer> K  :<c-u>exe v:count."Man ".expand("<cword>")<cr>
	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:

		function man
		{
		gvim -c "Man $*" -c "silent! only"
		}

	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
		:[count]Mannxt
		:[count]Manprv

	to go forwards and backwards in the history.  In addition, while in
	a manpageview help buffer, one also has two maps available:

		<s-up>
		<s-down>

	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:

		<s-left>	in smaller book numbers
		<s-right>	in larger book numbers

	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
			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).

		    As an example, Hong Xu reports that he has found that
		      let g:manpageview_iconv= "iconv -c UTF-8 -t UTF-8"
		    useful when using NetBSD.

	g:manpageview_K_http :			g:manpageview_K_http
		    This option is set to one of the following strings:
		    	lynx -dump
			links -dump
			elinks -dump
			wget -O -
			curl
		    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:
		    	: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 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:

			let g:manpageview_pgm_pl = "perldoc"
			let g:manpageview_options= "-f"

		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-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.
	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