synchk.txt	Syntax Checker    			Sep 21, 2020

Author:    Charles E. Campbell      <NcampObell@SdrPchip.AorgM-NOSPAM>
           (remove NOSPAM from Campbell's email first)
Copyright: (c) 2012-2018 by Charles E. Campbell     synchk-copyright
           The VIM LICENSE applies to synchk.vim and synchk.txt
           (see copyright) except use "synchk instead of "Vim"
           NO WARRANTY, EXPRESS OR IMPLIED.  USE AT-YOUR-OWN-RISK.

==============================================================================
1. Contents					synchk synchk-contents {{{1

	1. Contents..........................................: synchk-contents
	2. Synchk Usage......................................: synchk-usage
	3. Synchk Manual.....................................: synchk-manual
	4. Synchk History....................................: align-history

==============================================================================
2.Synchk Usage					synchk-usage {{{1

	The synchk.vim plugin helps syntax highlighting plugin writers to
	maintain their syntax highlighting plugin.  Typical use involves
	manually inspecting a test file to insure that its being highlighted
	correctly; once that is so, run :MakeSynChk on it.  This operation
	will save information on the current syntax highlighting;
	subsequently, one may run :SynChk to verify that the highlighting
	has not changed.

	Typically, one has a test directory wherein are a number of files that
	exercise various aspects of syntax highlighting.  After one is
	satisfied that the syntax highlighting is correct, run

		:MakeSynChk

	on the current file.  This operation will create a "synchk/" directory
	if it doesn't already exist, and will create a
	"filename_suffix.synchk" file.

	Assume that one then changes the syntax highlighting plugin; to verify
	that highlighting has not changed in a previously :SynChk'd file, run

		:SynChk

	You may then have to type :messages to see the status.

					MakeManySynChk	ManySynChk
	One may also use the "many-file" variants of these two commands:
		:ManyMakeSynChk filename(s)
		:ManySynChk filename(s)
	These are actually synonyms for SynChk and MakeSynChk.

	Method Used:

	The :MakeSynChk command computes a hash value for each line in the
	current file, saving it to synchk/file_suffix.synchk.  The hash
	involves synIDattr(synID(line("."),col("."),1),"name"); this is
	(see synIDattr, synID, line(), and col())
	the name of the syntax item under the cursor.  The syntax name of
	each character in a line are converted to numbers and hashed together.
	Every line of the current file is thus converted into a hashed value;
	the hashed value is saved.

	Similarly, the :SynChk command also computes hash values for every
	line in the current file; however, instead of saving the hashed value,
	it compares it to the previously saved hash value.  If the two differ,
	then syntax highlighting is considered to have failed.

	Thus, :Synchk is sensitive to syntax highlighting changes on a
	line by line basis, and can be used to locate unexpected changes in
	syntax highlighting.  Of course, "failures" may be intentional.

	Just run :MakeSynChk again when one is satisfied that the current
	file is being highlighted correctly.

==============================================================================
3.Synchk Manual					synchk-manual  {{{1

MakeSynChk					:MakeSynChk

	Makes a synchk/testfile_suffix.synchk file out of the current file.

SynChk						:SynChk

	Runs synchk on the current file or files specified by wildcard.
	Returns 1=passed, 0=failed (changed).
	Also displays a message, via echomsg, either:

		testfile.suffix passed
		testfile.suffix failed

	If there's an "old" version of a syntax file in the syntax file
	directory (ie. sh.vim and oldsh.vim), then when a discrepancy is
	detected, two side-by-side, scroll binded, windows with the same
	buffer will be shown; the left window shows the buffer with the latest
	syntax file (ie. sh.vim) and the right window shows the buffer with
	the "old" syntax file (ie. oldsh.vim).

	Otherwise, if the file in ${HOME}/etc/oldsyntax/<syntaxfile>.vim exists, synchk.vim
	will use that for the "old" version.

	Otherwise, if the file in ${HOME}/etc/syntax/<syntaxfile>.vim exists, synchk.vim
	will use that for the "old" version.

Maps:
	<F3>  : use SynChkHi to locate any syntax differences between the
	        syntax and old/etc syntax windows for the current line
	<F4>  : like <F3>, but work with the lines shown in the Recho error
	        window.
	<s-F4>: restart <F4> with the first error shown in the Recho window

	Note that :ownsyntax, used with these maps on the right hand side,
	does not include .../after/syntax/, which can provide spurious
	differences.

==============================================================================
4.Synchk History				synchk-history {{{1

	v1	Dec 14, 2012		* initial
		Oct 09, 2015		* added ownsyntax and old-syntaxfile two-window
			  		  display upon detection of discrepancies.
		May 29, 2013		* (Bram Moolenaar) pointed out three problems, which
					  are now fixed:

					  In s:SynChkHash(), the hash local variable must
					  always be set to zero

					  The MakeSynChk() takes a range, but the range
					  needed to start with the first line in the file.
					  This should no longer be the case (the synchktab
					  file will be padded with blank lines).

					  In s:SynChkHash(), the check for col('.') >= col('$')
					  is unreliable (changed to use virtcol() instead).
		Feb 18, 2016		  Changed =~ to =~# where appropriate
		Aug 02, 2018		* Included using older syntax file in
					  ~/etc/syntax
		Nov 03, 2018		* Implemented the <F3>, <F4>, and <s-F4> maps
		Aug 22, 2019		* When using the remote echo window
					  with <F4> or <s-F4>, the current
					  problem line will be highlighted


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