vis.txt	The Visual Block Tool				Sep 07, 2016

Author:  Charles E. Campbell  <NdrchipO@ScampbellPfamily.AbizM>
	  (remove NOSPAM from Campbell's email first)
Copyright: (c) 2004-2016 by Charles E. Campbell	vis-copyright
           The VIM LICENSE applies to vis.vim and vis.txt
           (see copyright) except use "vis" instead of "Vim"
	   No warranty, express or implied.  Use At-Your-Own-Risk.


==============================================================================
1. Contents					vis vis-contents vis.vim

	1. Contents......................: vis-contents
	2. Visual Block Manual...........: vis-manual
	3. Visual Block Search...........: vis-srch
	4. Required......................: vis-required
	5. Sorting Examples..............: vis-sort
	6. History.......................: vis-history


==============================================================================
2. Visual Block Manual			visman vismanual vis-manual v_:B

	Performs an arbitrary Ex command on a visual highlighted block.

	Mark visual block (CTRL-V) or visual character (v),
		press ':B ' and enter an Ex command [cmd].

		ex. Use ctrl-v to visually mark the block then use
			:B cmd     (will appear as   :'<,'>B cmd )

		ex. Use v to visually mark the block then use
			:B cmd     (will appear as   :'<,'>B cmd )

	Command-line completion is supported for Ex commands.

	There must be a space before the '!' when invoking external shell
	commands, eg. ':B !sort'. Otherwise an error is reported.

	The script works by deleting the selected region into register "a.
	The register "a itself is first saved and later restored.  The text is
	then put at the end-of-file, modified by the user command, and then
	deleted back into register "a.  Any excess lines are removed, and the
	modified text is then put back into the text at its original
	location.

	Popular uses for this command include:

	  :B s/pattern/output/
	  :B left
	  :B right

	1: apply a substitute command to just the selected visual block,
	2: left justify the selected block, and
	3: right justify the selected block, respectively.

	The concept for this plugin is originally Stefan Roemer's
	<roemer@informatik.tu-muenchen.de>; however, both the implementation
	and methods used internally have completely changed since Roemer's
	version.

	g:vis_empty_character : this character should not appear in your
	text.  By default: users of euc-jp will get a 0x01, otherwise
	it wil be a 0xff.  Used to prevent an empty result in the
	moving back the modified text operation, which otherwise results
	in an unwanted extra blank space being inserted.


==============================================================================
3. Visual Block Search				vis-search vis-srch vis-S

	Visual block search provides two ways to get visual-selection
	based searches.  Both these methods work well with :set hls
	and searching may be repeated with the n or N commands.

	Using // and ?? after a visual selection (the // is only available
	if you have g:vis_WantSlashSlash=1 in your <.vimrc> file):

		ex. select region via V, v, or ctrl-v
		    //pattern

	You'll actually get a long leader string of commands to restrict
	searches to the requested visual block first.  You may then enter
	the pattern afterwards.  For example, using "v" to select this
	paragraph, you'll see something like:

		/\%(\%(\%80l\%>12v\)\|\%(\%83l\%<53v\)\|\%(\%>80l\%<83l\)\)\&

	You may enter whatever pattern you want after the \&, and the
	pattern search will be restricted to the requested region.

	The "S" command in visual mode:

		ex. select region via V, v, or ctrl-v
		    :S pattern

	    The ":S pattern" will appear as ":'<,'>S pattern".  This
	    command will move the cursor to the next instance of the
	    pattern, restricted to the visually selected block.

	An "R" command was contemplated, but I currently see no way to
	get it to continue to search backwards with n and N commands.


==============================================================================
4. Required							vis-required

	The latest <vis.vim> (v20f or later) now requires vim 7.0 (or later),
	as it has been split into plugin/ and an autoload/ sections for
	on-demand loading.

	Starting with version 11, <vis.vim> required <cecutil.vim>.  It uses
	the SaveWinPosn() and RestoreWinPosn() functions therein.  You may get
	<cecutil.vim> from

		http://www.drchip.org/astronaut/vim/index.html#CECUTIL


==============================================================================
5. Sorting Examples						vis-sort

	Assume we start with the following three lines:

    	    one   two   three
    	    four  five  six
    	    seven eight nine

	Example 1: Use visual-block mode to select the center three
	words: ctrl-v select two/five/eight, then :'<,'>sort:

    	    four  five  six
    	    one   two   three
    	    seven eight nine

	Note that the visual-block is ignored, other than as a way to
	select the three lines.  The resulting sorting is done on the
	three words "one/four/seven".

	(this example presumed that you're using vim 7.0; if you're using
	an earlier version vim, try  :'<,\> !sort  instead)

	Example 2: Using vis.vim's B command:
	Again, use visual-block mode to select the center
	three words: ctrl-v select two/five/eight, then :'<,'>B sort:

    	    one   eight three
    	    four  five  six
    	    seven two   nine

	This operation sorts the selected three words (two/five/eight),
	leaving all characters outside the visual block alone.

	(this example presumed that you're using vim 7.0; if you're using
	an earlier version vim, try  :'<,\> !sort  instead)

	Example 3: Using vissort.vim's Vissort() function
	Use visual block mode to select the center three words;
	ctrl-v select two/five/eight, then :'<,'>Vissort:

    	    seven eight nine
    	    four  five  six
    	    one   two   three

	This time, the entire lines are sorted, but the sorting is done
	based on the visual-block selected region (ie. two/five/eight).


==============================================================================
6. History						vis-history {{{1

    v21 : Apr 01, 2013	- visual block and ragged right detection; there was
			  a conflict between using ve= and ve=all
			  (internally); one was good for ragged right and
			  the other for smooth right visual block selections.
			  I found a way to detect ragged right vs smooth right
			  and so vis.vim now works properly in both
			  situations.
	  Apr 02, 2013	- The detection method above hung when on line 1.
			  Fixed.
	  Jan 15, 2015	- Small adjustment to prevent a leading space from
	  		  being inserted.
	  Feb 10, 2016  - (Stefan Siegal) provided a patch making
			  visPlugin.vim restore cpo
	  Sep 07, 2016	- addressed an empty-string bug : if the block
	  		  command causes an empty string to appear in the
			  modified text, vim would insert a blank rather than
			  do nothing.  Fixed by prepending an
			  "empty-character" and then removing it
    v20 : May 20, 2009	- cecutil bugfix
	  May 19, 2010	- split into plugin/ and autoload/ for faster
			  loading and on-demand loading.
	  Mar 18, 2013	- (Gary Johnson) pointed out that changing
			  cedit to <Esc> caused problems with visincr;
			  the cedit setting is now bypassed in vis, too.
	  Mar 29, 2013	- Fixed a problem with vis#VisBlockCmd() where it
	  		  missed substitutes due to a short last line.
			  s:SaveUserSettings() now makes ve=all instead of
			  ve=  (see 've')
    v19 : Jan 06, 2006	- small modification included to allow AlignMaps
			  maps to work (visual select, :B norm \somemap)
			- cecutil updated to use keepjumps
	  Jan 24, 2006	- works around formatoption setting
	  Jan 25, 2006	- uses SaveWinPosn(0) to avoid SWP stack use
    v18 : Jul 11, 2005	- vis.vim now works around a virtcol() behavior
			  difference between ve=all vs ve=block
    v17 : Apr 25, 2005	- vis.vim now uses cecutil (SaveWinPosn, etc) so the
			  tarball now includes a copy of cecutil.vim
    v16 : Feb 02, 2005	- fixed a bug with visual-block + S ; the first line
			  was being omitted in the search
	  Mar 01, 2005	- <q-args> used instead of '<args>'
	  Apr 13, 2005	- :'<,'>S plus v had a bug with one or two line
			  selections (tnx to Vigil for pointing this out)
	  Apr 14, 2005	- set ignorecase caused visual-block searching
			  to confuse visual modes "v" and "V"
    v15 : Feb 01, 2005	- includes some additions to the help
    v14 : Sep 28, 2004	- visual-block based searching now supported.  One
			  do this either with :'<,'>S pattern or with a / or ?
	  Jan 31, 2005	- fixed help file
    v13 : Jul 16, 2004	- folding commands added to source
			- GetLatestVimScript hook added for automatic updating
    v12 : Jun 14, 2004	- bugfix (folding interfered)
    v11 : May 18, 2004	- Included calls to SaveWinPosn() and RestoreWinPosn()
			  to prevent unwanted movement of the cursor and window.
			  As a result, <vis.vim> now requires <cecutil.vim>
			  (see vis-required).
    v10 : Feb 11, 2003	- bugfix (ignorecase option interfered with v)
     v9 : Sep 10, 2002	- bugfix (left Decho on, now commented out)
     v8 : Sep 09, 2002	- bugfix (first column problem)
     v7 : Sep 05, 2002	- bugfix (was forcing begcol<endcol for "v" mode)
     v6 : Jun 25, 2002	- bugfix (VirtcolM1 instead of virtcol()-1)
     v5 : Jun 21, 2002	- now supports character-visual mode (v) and
			  linewise-visual mode (V)
     v4 : Jun 20, 2002	- saves sol, sets nosol, restores sol
			- bugfix: 0 inserted: 0\<c-v>G$\"ad
			- Fixed double-loading (was commented
			  out for debugging purposes)
     v3 : Jun 20, 2002	- saves ve, unsets ve, restores ve
     v2 : June 19, 2002	- Charles Campbell's <vis.vim>
     v?   June 19, 2002	  Complete rewrite - <vis.vim> is now immune to
			  the presence of tabs and is considerably faster.
     v1 Epoch		- Stefan Roemer <roemer@informatik.tu-muenchen.de>
			  wrote the original <vis.vim>.

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