*autoalign.txt*		Automatic Alignment		Oct 19, 2006

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

==============================================================================
1. Contents				*autoalign* *autoalign-contents*

    1. Contents.................: |autoalign-contents|
    2. Installing...............: |autoalign-install|
    3. Alignment Manual.........: |autoalign-manual|
    4. AutoAlign Internals......: |autoalign-internals|
    5. AutoAlign History........: |autoalign-history|

==============================================================================
2. Installing AutoAlign					*autoalign-install*

	1. AutoAlign needs the Align/AlignMaps utilities
	   which are available from either:
>
		http://vim.sourceforge.net/scripts/script.php?script_id=294
		http://mysite.verizon.net/astronaut/vim/textab.html
<
	  a) Put the compressed archive (Align.tar.gz) in your
	     .vim (Unix) or vimfiles\ (Windows) directory
	  b) Decompress it:  gunzip Align.tar.gz
	  c) De-archive it:  tar -oxvf Align.tar


	2. AutoAlign is composed of a plugin and several
	   ftplugins.  It is available from:
>
        	http://vim.sourceforge.net/scripts/script.php?script_id=884
<
	3. Decompress it:  gunzip Align.tar.gz
	4. De-archive it: tar -oxvf Align.tar
	5. Steps 3 and 4 will provide you with:
>
	        plugin/cecutil.vim
	        ftplugin/bib/AutoAlign.vim
	        ftplugin/c/AutoAlign.vim
	        ftplugin/cpp/AutoAlign.vim
	        ftplugin/maple/AutoAlign.vim
	        ftplugin/tex/AutoAlign.vim
	        ftplugin/vim/AutoAlign.vim
<
	6. In order to make help available while using vim for AutoAlign:
>
		vim
		:helptags ~/.vim/doc                 <-- Unix
		:helptags (wherever)/vimfiles/doc    <-- Windows
		:q
<

	7. To enable plugins and filetype plugins generally, including
	   AutoAlign, have the following in your <.vimrc> file:
>
		"  Initialize: {{{1
		set nocp
		if version >= 600
		 filetype plugin indent on
		endif
<

==============================================================================
3. AutoAlign Manual						*autoalign-man*

    The AutoAlign filetype plugins operate while vim is in insert mode.  They
    apply appropriate Align/AlignMaps to the most recent contiguous region,
    thereby keeping such things as "=" aligned.  See |align| and |alignmaps|.

        :AA   - toggles AutoAlign on and off

    The mark 'a is used by AutoAlign to indicate where the start of the
    automatic alignment region begins.  Changing 'a to some other place will
    also stop AutoAlign from operating on that region.  One may temporarily
    suppress AutoAlignment that way.

              Language  AutoAlignment   AutoAlignment
                            Trigger        Taken On
              --------  -------------   -------------
                bib           =               =
                c             =               =
                cpp           =               =
                              <              <<
                              >              >>
                maple         =              :=
                tex           \            & and \\
                vim           =               =

    The AutoAlignment trigger character invokes a call to the appropriate
    filetype's AutoAlign.  Only when:

    * the current line matches a filetype specific pattern (to avoid
    aligning <= >= == etc)

    * the b:autoalign_vim variable records the first line which
    satisfied the filetype specific pattern in the current
    region.  If it matches the mark ('a)'s line, then AutoAlignment
    will occur.  Thus the user can temporarily disable AutoAlignment
    on the current region merely by changing where the mark 'a is
    set to.

    * Although frequently the trigger character is also used in
    the alignment, sometimes a longer pattern is used (ex. maple's
    :=) for alignment.

    The AutoAlign plugin is fairly trivial to use -- just type.  Alignment
    will occur for the following patterns automatically.  These patterns
    are stored in b:autoalign_reqdpat1, b:autoalign_reqdpat2, etc.

    FILETYPE PATTERNS

    bib    ^\(\s*\h\w*\(\[\d\+]\)\{0,}\(->\|\.\)\=\)\+\s*[-+*/^|%]\==
    c      ^\(\s*\*\{0,}\h\w*\%(\[\%(\d\+\|\h\w*\)]\)\{0,}\%(->\|\.\)\=\)\+\s*[-+*/^|%]\==
    cpp    ^\(\s*\h\w*\(\[\d\+]\)\{0,}\(->\|\.\)\=\)\+\s*[-+*/^|%]\==
    cpp    <<
    cpp    >>
    maple  :=
    matlab \%(^.*=\)\&\%(^\s*\%(\%(if\>\|elseif\>\|while\>\|for\>\)\@!.\)*$
    tex    ^\([^&]*&\)\+[^&]*\\\{2
    vim    ^\s*let\>.*=

    AutoAlign looks backwards from the current line, searching for the first
    preceding line _not_ containing the pattern.  It uses b:autoalign_notpat1,
    b:autoalign_notpat2, etc for this.  If the "not pattern" has moved since
    the mark ('a) was made, AutoAlign will start aligning from the current
    line.


==============================================================================
4. AutoAlign Internals					*autoalign-internals*

    AutoAlign is triggered to operate during insert mode when a special
    character (such as "=") is encountered using an inoremap.  Each ftplugin
    specifies its own triggers.  The inoremap turns virtualedit off, calls
    AutoAlign(), and then deletes the trigger character (which may have or may
    not have moved) and then inserts it to keep the operation otherwise
    transparent.

    AutoAlign attempts to perform its automatic alignment on an "AutoAlign
    region".  Alignment, of course, is performed over that region.  The idea
    is to start an AutoAlign region upon receipt of a trigger character and
    a matching required pattern; subsequently, alignment is done over the
    AutoAlign region is active and whenever the region has more than one line
    in it.

    Such a region begins with the presence of a required pattern.  That first
    line is also marked with mark-a ('a).  If the mark 'a is moved, then the
    AutoAlign region is terminated.  There are several ways that an AutoAlign
    region is terminated; see below.

    Associated with each trigger character are three or four patterns.  Also,
    each trigger character inoremap is to have an associated count, referred
    to as "#" below.
>
    b:autoalign_reqdpat#
<       This pattern is required for AutoAlign to consider that an AutoAlign
	region has started.  If a positive # is passed to AutoAlign(), then
	the required pattern is needed to allow the AutoAlign region to
	continue whenever a trigger character is encountered.  A negative #, a
	trigger character, and a failed match to b:autoalign_reqdpat# will
	terminate the AutoAlign region.
>
    b:autoalign_notpat#
<       This pattern must match just before the AutoAlign region starts.  It
	is used to search before the current line.  If the non-pattern
	matching line is not the same as it was when the AutoAlign region
	began, then the AutoAlign region is terminated.
>
    b:autoalign_suspend#
<       This pattern is optional; if it matches, the AutoAlign region is
        terminated.  The fplugin/html/AutoAlign.vim script uses </table>,
	for example, to terminate table aligning.
>
    b:autoalign_cmd#
<       This is the command used to invoke alignment on the AutoAlign region.
>
    b:autoalign_trigger#
<	This variable holds the trigger character.

    Of course, the :AA command is also available to turn AutoAlign off.


==============================================================================
5. AutoAlign History					*autoalign-history*

   13 : Oct 19, 2006 : ftplugin/cpp/AutoAlign.vim fixed for < and >.
                       Introduced b:autoalign_trigger# so AutoAlign
		       can put cursor back where it belongs.
		     * AutoAlign now pluginkiller immune
	Mar 26, 2007 * AutoAlign's invocation of Align sometimes caused
		       the cursor to jump to the first line rather than
		       the current line (ex: for Maple's :=).  Fixed.
	Aug 15, 2007 * Changed the imaps's right-hand-side to use,
	               typically, =<c-r>=AutoAlign(#) instead of
		       =<c-o>:silent call AutoAlign(#).
		       Thanks to Antony Scriven!  Gets that "|.|"
		       repeater working.
   12 : Sep 19, 2006 : ftplugin/bib/AutoAlign.vim fixed
   11 : Mar 23, 2006 : v10 had debugging enabled; this one has debugging
                       deactivated.
		     * now decides to use startinsert vs startinsert!
		       before the alignment by using the "atend" variable,
		       which holds the result of testing whether the cursor
		       is at the end-of-line or not.
   10 : Mar 16, 2006 : using startinsert! to recommence editing
                       AutoAlign only triggered when the trigger character
		       is at the end of the current line being inserted.
		     * works with ve=all and ve=  (see |'ve'|)
    9 : Mar 16, 2006 : seems to have stopped working with virtualedit off.
                       Now works with virtualedit off or on.  If vim 7.0
		       is in use, AutoAlign doesn't use SaveWinPosn()
		       or RestoreWinPosn(), so it may work faster.
    8 : Jan 18, 2006 : cecutil updated to use keepjumps
                     * plugin/AutoAlign.vim was missing from distribution
    7 : Mar 31, 2005 : supports html
		     * b:autoalign_suspend# for suspend-alignment pattern
		       implemented, along with using AutoAlign(-#) to avoid
		       having a reqdpat failure doing an AutoAlign suspension.
		       The absolute value of # is used to refer to
		       b:autoalign_reqdpat#, b:autoalign_notpat#, and
		       b:autoalign_suspend#.
        Apr 22, 2005 * sanity check included to prevent an attempt to access
		       an undefined variable (b:autoalign_reqdpat{i})
    6 : Mar 30, 2005 : AutoAlign is split into a plugin containing the
		       majority of vimscript; the supported ftplugins
		       contain the invoking imaps and pattern definitions
		       that the plugin uses.
    5 : Jan 24, 2005 : first release of AutoAlign using vim's user-help.
		     * using g:mapleader instead of a built-in backslash to
		       access AlignMaps
		     * map and function changed to allow use of "." to
		       repeat entry of =... expressions.
    4, Jul 02, 2004  : see |i_ctrl-g_u| -- breaks undo sequence at every align
    3, Mar 03, 2004  : autoalign not taken if a no-pattern line is
                       in-between the keepalign line and the current line
    2                : b:autoalign==0: turns autoalign off
                       b:autoalign==1: turns autoalign back on
                     * 'a now used during autoalign, and AlignMap's \t=
                       If user changes 'a, then AutoAlign recognizes that
                       it is not to keep aligning
                     * The :AA command can be used to toggle AutoAlign
    1                : The Epoch

==============================================================================
vim:tw=78:ts=8:ft=help
