*Highlight.txt*	Highlighting      				Jan 09, 2015

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

==============================================================================
1. Contents					*Highlight* *Highlight-contents* {{{1

	1. Contents.................: |Highlight-contents|
	2. Highlight Manual.........: |Highlight-manual|
	5. Highlight History........: |Highlight-history|

==============================================================================
2. Hightlight Manual					*Highlight-manual* {{{1

   The highlight command is designed to work with gvim only.

COMMANDS: {{{2

	:HLcolor					*HLcolor*
	:HLcolors
		Lists currently selected highlighting colors

	:HLcolor name name name ...
		Sets list of names to be the highlighting colors.
		Default: HLcolor IndianRed orange3 khaki3 OliveDrab3 ...
		                 MediumSeaGreen CornflowerBlue turquoise3 ...
				 MediumPurple3 burlywood4 grey72 *4

		A "color" in the format *[digits] tells Highlight to repeat
		the set an additional "number" times.

	:[count]HLsrch					*HLsrch*
		Uses the last pattern (|@/|) to highlight with the count'th
		color

	:[count]HLsrch pattern
		Uses the specified pattern (|@/|) to highlight with the count'th
		color

	:HLclear					*HLclear*
		If the cursor is atop one of the Highlighted patterns, then
		that pattern will be cleared.  Otherwise, all Highlighted
		patterns will be cleared.

	:HLclear 1+
		If a positive integer is given, then the Highlighting for the
		given id will be cleared.

	:HLclear 0
		All Highlighted patterns will be cleared

	:HLclear -1
		If the cursor is atop one of the Highlighted patterns, then
		the subpattern associated with the item under the cursor will
		be cleared.  Otherwise, all highlighted patterns will be
		cleared.    (see <kDivide>)

	:HLclear -2
		If the cursor is atop one of the Highlighted patterns, then
		all subpatterns associated with that highlighting id will be
		cleared.    (see <kPoint>)

	:HLw [id] Like the |\HLw| map			*:HLw*
	:HLl [id] Like the |\HLl| map			*:HLl*
	:HL  [id] Like the |\HL|  map			*:HL*
	:HLW [id] Like |:HLw|, but for the word under the cursor	*:HLW*
	:HLL [id] Like |:HLl|, but for the line under the cursor	*:HLL*
	:HLC [id] Like |:HLclear|					*:HLC*

	:[count]HLN go to the count-th next     highlighted pattern
	:[count]HLP go to the count-th previous highlighted pattern
	            For both these commands, the default count is 1.

		    						*:HLu*  *:HLr*
	:HLu	Undo the last highlighting operation
	:HLr	Redo the last highlighting operation

		    					*:HLread* *:HLwrite*
	:HLwrite Write the current highlighting matches to a file called
		.HL_(current filename).  The current filename may not include
		any slashes.
	:HLread Read the current highlighting matches from a file called
		.HL_(current filename).  The current filename may not include
		any slashes.

NORMAL MAPS: {{{2
	[count]\HLw					*\HLw*
		A HLsrch pattern will be constructed which highlights the
		word under the cursor.  The count'th id highlighting color
		will be used.  ie.  expand("<cword.")

	[count]\HLl					*\HLl*
		A HLsrch pattern will be constructed which highlights the
		line under the cursor.  The count'th id highlighting color
		will be used.  ie.  '^\%'.line(".").'l.*$'

	<k1> ... <k0> : keypad numbers assign a color to the word below the
		        cursor; previous pattern associated with this color
			is overwritten.
	<c-k1> ... <c-k0> : keypad numbers assign a color to the word below the
		        cursor; previous pattern associated with this color
			is appended to.

	<kPlus>	    increments the color assigned to the word below the cursor.
	<kMinus>    decrements the color assigned to the word below the cursor.
	<kMultiply> highlights entire current line with next available color
	<kDivide>   clears current subpattern of its highlighting
	            (like :HLclear -1)
	<kPoint>    clears all highlighting associated with the matching
	            pattern.   (like :HLclear -2)

	One may override the "under the cursor" and other search patterns with
	any of the visual mode selections (|V|, |v|, |CTRL-V|).  Visual mode
	selections will be used literally (ie. magic characters are escaped).

VISUAL MAP:						*\HL*   {{{2
	[count]\HL
		A HLsrch patttern will be constructed which will highlight
		just the visually selected text. ie.
		'\%'.line("'<").'l\%'.col("'<").'c\_.*\%'.line("'>").'l\%'.(col("'>")+1).'c'

SUGGESTED FUNCTION KEY MAPS: {{{2

nmap <silent> <c-F10>	:call Highlight#Clear(-1)<cr>
nmap <silent> <c-F11>	:call Highlight#Srch(v:count,'^\%'.line(".").'l.*$')<cr>
vmap <silent> <c-F11>	:<c-u>call Highlight#Srch(v:count,'\%'.line("'<").'l\%'.col("'<").'c\_.*\%'.line("'>").'l\%'.(col("'>") + (col("'>") != col("$"))).'c')<cr>

With these maps:

	<c-F10>          ctrl-functionkey-10  will clear the Highlighted pattern
	                                      under the cursor.

	[count]<c-F11>   ctrl-functionkey-11  (normal mode) will Highlight the
	                                      current line with the count'th
					      Highlighting color.

	[count]<c-F11>   ctrl-functionkey-11  (visual mode) will Highlight the
	                                      current visual block with the
					      count'th Highlighting color.

	As a codicil to the above: re-using a Highlighting color will result
	in the next available Highlighting Color being used.  When using the
	maps above, repeatedly pressing <c-F11> will also sequentially use
	Highlighting colors.

OPTIONS: {{{2

	*g:HighlightKeypad* :  default: 1
		If true, keypad maps are enabled. (<k0>-<k9>, <kEnter>, etc)

==============================================================================
3. History						*Highlight-history* {{{1

   	v1	Nov 25, 2008	* The epoch
		Nov 26, 2008	* Added a ColorScheme autocmd so that changes
				  in the colorscheme don't wipe out the High-
				  lighting colors.
		Nov 19, 2010	* Now has a menu with gvim
		Jan 18, 2011	* Added :HLN and HLP commands
		Sep 06, 2011	* Supports keypad numbers for
				  setting/incrementing/decrementing highlight color.
		Nov 21, 2014	* Added <c-k1> to <c-k0> maps and
				  functionality (appends highlighting patterns)
		Nov 28, 2014	* Added |:HLu|, |:HLr|, |:HLread|, |:HLwrite|
		Dec 17, 2014	* |HLcolor| support for *# included

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