AutoAlign.txt		Automatic Alignment		Nov 25, 2013

Author:  Charles E. Campbell  <NdrOchip@ScampbellPfamily.AbizM>
(remove NOSPAM from Campbell's email first)
Copyright: (c) 2004-2013 by Charles E. Campbell		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. AutoAlign Tutorial.......: autoalign-tutorial
    4. AutoAlign Manual.........: autoalign-manual
    5. AutoAlign Internals......: autoalign-internals
    6. Elastic Tabs.............: autoalign-elastictabs
    7. 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://www.drchip.org/astronaut/vim/index.html#AUTOALIGN

        2. Using vim 7.1 or later:

              vim AutoAlign.vba.gz
               :so %
               :q

           This process will generate the following files on your runtimepath:

                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


        3. 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 Tutorial 					  autoalign-tutorial

        The tutorial assumes that you have already installed AutoAlign and the
        Align/AlignMap plugins.

        Example 1: when using C
                        x= 1;
                        yy= 2;
                        zzz= 3;
               Results in
                        x= 1;
               and then
                        x  = 1;
                        yy = 2;
               and finally
                        x   = 1;
                        yy  = 2;
                        zzz = 3;
               with the auto-alignment occurring upon the entry of the "="s.
                Such alignments will not occur when the line begins with for,
                if, while, or else.

        Example 2: using C++
                        x= 1;
                        yy= 2;
                        zzz= 3;
               with alignment occuring like it does with C.
                        x   = 1;
                        yy  = 2;
                        zzz = 3;
               C++ auto-alignment also handles << and >> operators, and for
                C++ style comments (ie. //... ).

        Example 3: using LaTeX
                  \begin{center}\begin{tabular}{||l|l|l||}
                        \hline\hline
                        a&b&c\\
               Nothing seems to happen so far. With the next line:
                        dd&ee&ff\\
               The trailing double-backslash triggers the alignment package,
                yielding
                        a  & b  & c  \\
                        dd & ee & ff \\

        Example 4: using Maple
                        eq1:= x= 3*y + z;
                        eq1a:= x= 3*y + 2*z;
               Upon entry of the second line's ":=", the AutoAlign package will align
                the ":="s, yielding
                        eq1  := 3*y + z;
                        eq1a :=


==============================================================================
4. AutoAlign Manual				autoalign-man autoalign-manual

    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.

					autoalign-AA autoalign-AAstart
    There are two commands supported by AutoAlign:

        :AA             - toggles AutoAlign on and off
        :AAstart        - manually set the current insertion block to start at
                          the current line
        :[line]AAstart  - manually set the current insertion block to start at
                          the specified line
        :AAstart [line] - manually set the current insertion block to start at
                          the specified line

    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.

    AUTOALIGN FUNCREF				AutoAlign_funcref

    When AutoAlign is invoked and changes the line, an optional function
    (or functions) may be called via Funcref(s):

    	let g:AutoAlign_funcref10= function("SomeFunctionName")

   or a list of such Funcref(s):

    	let g:AutoAlign_funcref10=[function("SomeFunctionName"),function("AnotherFunc"]

   These functions will be executed after the aligning has been done, but
   before control has been passed back to the user via a :startinsert.

   The number ("10" in the example) following the funcref is the same as the
   number passed to AutoAlign() due to the trigger character.


==============================================================================
5. 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 may be terminated; see below.

    Associated with each trigger character are several patterns and/or line
    numbers.  Also, each trigger character inoremap is to have an associated
    numeric identifier (referred to as "#") below.

							b:autoalign_reqdpat
    b:autoalign_reqdpat#
	This pattern is required for AutoAlign to deem 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
    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_start
    b:autoalign_start#
	This holds a line number specifying where the AutoAlign region
	starts.  It is used instead of b:autoalign_reqdpat# and
	b:autoalign_notpat#, in conjunction with b:autoalign_stop#.
	(not a pattern)

							b:autoalign_stop
    b:autoalign_stop#
	This holds a line number specifying where the AutoAlign region
	starts.  It is used instead of b:autoalign_reqdpat# and
	b:autoalign_notpat#, in conjunction with b:autoalign_start#.
	(not a pattern)

							b:autoalign_suspend
    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
    b:autoalign_cmd#
	This is the command used to invoke alignment on the AutoAlign region.

							b:autoalign_trigger
    b:autoalign_trigger#
	This variable holds the trigger character.

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


==============================================================================
6. Elastic Tabs			autoalign-eltab autoalign-elastictabs

Those of you who are interested in "elastic" non-uniform tab stops may find
the "eltab" filetype of use.  Its not a pure non-uniform tab solution (that
would take a modification to vim itself); however, a filetype of eltab coupled
with AutoAlign makes for an almost elastic-tab solution.

If the tabstop is set to 1 (:set ts=1), then AlignMaps' \tab will do a
no-padding alignment on the tabs.  Thus one gets tabs surrounded by spaces to
do the alignment (with no additional padding).

If your file has a modeline:

        vim: ft=eltab

Subsequently, as you type, tabs will be auto-aligned within each current insertion
block of text; total file alignment can be done with 1V$\tab (ie. select
entire file, align it).


==============================================================================
7. AutoAlign History					autoalign-history

   14 : Sep 20, 2007 * now using startinsert! instead of startinsert.
   		       Currently not using the various autoalign_trigger
		       strings; will see how modification works out.
		     * found some cases where startinsert! isn't a good
		       idea (ex. inserting an "=").  New modification;
		       this one may use the autoalign_trigger string.
		     * The c plugin's AutoAlign.vim was overriding
		       the c++ plugin's AutoAlign.vim settings.
	Feb 22, 2011 * for menus, &go =~# used to insure correct case
	Apr 25, 2012 * added AutoAlign_funcref
	Sep 18, 2012 * added b:autoalign_start and b:autoalign_stop
	Nov 25, 2013 * (Gary Johnson) reported a problem with using C=
		       while atop an "=" sign.  Fixed.
   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