*pchk.vim*	Plugin Checker    			Aug 21, 2016

Author:    Charles E. Campbell      <NdrOchip@ScampbellPfamily.AbizM>
           (remove NOSPAM from Campbell's email first)
Copyright: (c) 2016 by Charles E. Campbell     	*pchk-copyright*
           The VIM LICENSE applies to pchk.vim and pchk.txt
           (see |copyright|) except use "pchk" instead of "Vim"
           NO WARRANTY, EXPRESS OR IMPLIED.  USE AT-YOUR-OWN-RISK.

==============================================================================
1. Contents			*pchk* *pchk-contents* {{{1
	1. Contents.................: |pchk-contents|
	2. PChk Manual..............: |pchk-manual|
	3. PChk Usage...............: |pchk-usage|
	3. PChk History.............: |pchk-history|

==============================================================================
2. PChk Manual			*pchkman* *pchkmanual* *pchk-manual* {{{1


				*PChkTry* *PChkMake* *PChk* *PChkStep*
    Start a test by editing it, then run one of the following four commands:

	:PChkTry	  : try the test.  Will stop at :PChkSnapshot lines
	:PChkMake	  : make an Expected/tst###.out file
	:PChk		  : compare snapshot hashes currently obtained
			    with previously obtained expected test results
	:PChkStep	  : step through each line of a test, not just at
			    the :PChkSnapshot commands.


    Test File Commands         *PChkSnapshot* *PChkFeedkeys* *PChkPause*

	:PChkSnapshot	  : runs a hashing algorithm over the remote display.
			    Result is saved in/compared with Expected/tst###.out
	:PChkFeedkeys ... : send keys to server.  ^X translates to control
			    characters (ie. ^M is a ENTER)
	:PChkPause	  : pause the test (uses |input()|).  One may
				* <cr> =continue
				* c    =check
				* s    =step
				* t    =try
	:..cmd		  : send cmd to server to execute..
	^\s*#...	  : echomsg comment in client vim (will not be sent
			    to server)
	..cmd..		  : send cmd to server to execute as a normal command
	*..reply..	  : netrw issues prompt; reply to it with this string


    Special Variables:		*g:netrw_pchk*
	g:netrw_pchk	  : suppresses netrw version number from banner if true
			    (avoid spurious errors due to changes in netrw versions)

==============================================================================
3. PChk Usage	*pchkusage* *pchk-usage* *pchk-userguide* {{{1

	PChk provides a testing framework for plugins and requires:

	 * +clientserver (|clientserver|)
	   ie. :echo has("clientserver") needs to show a "1"

	 * gvim
	   ie. :echo has("gui") needs to show a "1"

	PChk runs a gvim in a server (remote instance) which is started up
	using a vim initialization file called pchk.vimrc; it is searched
	for as: >

	  * pchk.vimrc (current directory)
	  * $HOME/.vim/pchk.vimrc
	  * $HOME/pchk.vimrc
	  * $VIMRUNTIME/pchk.vimrc
<
	The gvim being started uses >

		gvim -u vimrc -U NONE --servername PCHKREMOTE
<
	where "vimrc" is wherever pchk found pchk.vimrc from the list above.

	A typical pchk.vimrc: >

		set nocp
		filetype plugin on
		set ve=all
		set directory=$HOME/.vim/VITMP

<	The last setting causes swap files to be placed in a directory
	away from the current one (pchk was developed to support netrw
	testing, and letting swap files litter the current directory
	would alter test results).

	PChk uses test files (input) which exercise the plugin.  These test files
	may

	  * have the remote gvim run commands (ex. :let g:netrw_liststyle=3)

	  * send keys to the remote gvim (as if a user had typed them) with
	    a translation of ^[A-Z] into associated control characters

	  * send normal mode commands

	  * send response strings

	  * take a "snapshot"

	  * query remote gvim for some status via an "assert"ion

	PChk writes (output) and uses (input) Expected/*.out files which hold
	the results of the test files.

	The :PChkSnapshot command is of central importance to the PChk plugin.
	It generates a hash (an integer) which is sensitive to:

	  * geometry: each tab, each window, what windows are next to which
	    windows (left, right, above, below)

	  * the contents of each window (text and syntax)

	If any of these things that go into a hash changes, PChk will detect
	that something differs.

	A plugin may cause something to change (such as a setting or variable
	value) that is not captured by a :PChkSnapshot.  To capture such
	changes, a >
		:PChkAssert command
<	will act as if an ":echo command" was sent to the remote gvim and the
	results therefrom are either entered into the Expected/*.out file or
	compared with it.

	As an example, consider tst007 for netrw: >

	    # c : make browsing directory the current directory
	    :let g:netrw_pchk= 1
	    :cd dir001
	    :e .
	    :PChkSnapshot
	    :e dirA
	    :PChkSnapshot
	    :PChkAssert b:netrw_curdir != getcwd()
	    c
	    :PChkAssert b:netrw_curdir == getcwd()

<	This test does the following: >

	    # c : make browsing directory the current directory
<		nothing, its just a comment >
	    :let g:netrw_pchk= 1
<		tells netrw not to include the version in the banner >
	    :cd dir001
<		changes the directory to dir001 >
	    :e .
<		tells netrw to generate a listing for the current directory >
	    :PChkSnapshot
<		record/compare a snapshot of the remote gvim state >
	    :e dirA
<		tells netrw to "edit" a subdirectory (dirA) >
	    :PChkSnapshot
<		record/compare a snapshot of the remote gvim state >
	    :PChkAssert b:netrw_curdir != getcwd()
<		record/compare the result of comparing the b:netrw_curdir
		variable with vim's current directory >
	    c
<		issues a "c" normal mode command to netrw (see |netrw-c|) >
	    :PChkAssert b:netrw_curdir == getcwd()
<		record/compare the result of comparing the b:netrw_curdir
		variable with vim's current directory

	PChk can be run in one of three ways: >

	:PChkTry
<		This command tells PChk to try the current file as a test.  It
		will stop at any :PChkSnapshot lines allowing one to see if
		things are going as expected.  It splits the test window and
		shows the results of the hashing in the right side window. >

	:PChkMake
<		This command tells PChk to run the current file as a test
		and to save the :PChkSnapshot and :PChkAssert results in
		Expected/FILENAME.out for future comparisons. >

	:PChk
<		This command tells PChk to run the current file as a test,
		comparing the current :PChkSnapshot and :PChkAssert results
		with the previously run Expected/*.out results.

==============================================================================
4. PChk History	       		*pchk-history* {{{1

	v3:	Aug 21, 2016	* PChkRun included
	v2:	Apr 05, 2016	* included sensitivity to window names
				  (using expand("%:t") )
	v1:	Nov 25, 2015	* initial release
		Feb 19, 2016	* included current window number in s:WinGeoHash()

==============================================================================
Modelines: {{{1
vim:tw=78:ts=8:ft=help:fdm=marker: