Highlight.txt	Highlighting      				Jan 09, 2015

Author:    Charles E. Campbell  <NdrOchip@ScampbellPfamily.AbizM>
           (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: