*align.txt*	The Alignment Tool			Apr 11, 2005

Author:  Charles E. Campbell, Jr.  <NdrOchip@ScampbellPfamily.AbizM>
	  (remove NOSPAM from Campbell's email first)

==============================================================================
1. Contents					*align* *align-contents*

	1. Contents.................: |align-contents|
	2. Alignment Manual.........: |align-manual|
	3. Alignment Usage..........: |align-usage|
	   Alignment Control........: |align-control|
	     Separators.............: |alignctrl-separators|
	     Initial Whitespace.....: |alignctrl-w| |alignctrl-W| |alignctrl-I|
	     Justification..........: |alignctrl-l| |alignctrl-r| |alignctrl-c|
	     Justification Control..: |alignctrl--| |alignctrl-+| |alignctrl-:|
	     Cyclic/Sequential......: |alignctrl-=| |alignctrl-C|
	     Separator Justification: |alignctrl-<| |alignctrl->| |alignctrl-||
	     Line (de)Selection.....: |alignctrl-g| |alignctrl-v|
	     Temporary Settings.....: |alignctrl-m|
	     Padding................: |alignctrl-p| |alignctrl-P|
	     Current Options........: |alignctrl-settings| |alignctrl-|
	   Alignment................: |align-align|
	   Maps.....................: |align-maps|
	     \a,....................: |alignmap-a,|
	     \a?....................: |alignmap-a?|
	     \a<....................: |alignmap-a<|
	     \abox..................: |alignmap-abox|
	     \acom..................: |alignmap-acom|
	     \anum..................: |alignmap-anum|
	     \ascom.................: |alignmap-ascom|
	     \adec..................: |alignmap-adec|
	     \adef..................: |alignmap-adef|
	     \afnc..................: |alignmap-afnc|
	     \adcom.................: |alignmap-adcom|
	     \aocom.................: |alignmap-aocom|
	     \tsp...................: |alignmap-tsp|
	     \tsq...................: |alignmap-tsq|
	     \tt....................: |alignmap-tt|
	     \t=....................: |alignmap-t=|
	     \T=....................: |alignmap-T=|
	     \Htd...................: |alignmap-Htd|
	4. Alignment Tool History...: |align-history|

==============================================================================

2. Align Manual			*alignman* *alignmanual* *align-manual*

	To Enable: put <Align.vim> and <AlignMaps.vim> into your .vim/plugin
	To see a user's guide, see |align-usage|
	To see examples, see |alignctrl| and |alignmaps|
>
 /==============+=============================================================\
 ||             |Dflt|                                                       ||
 ||  Commands   |Val-|                 Explanation                           ||
 ||             | ue |                                                       ||
 ++=============+====+=======================================================++
<||  AlignCtrl  |    |  =Clrc-+:pPIWw [..list-of-separator-patterns..]       ||
 ||             |    +-------------------------------------------------------+|
 ||             |    |  may be called as a command or as a function:         ||
 ||             |    |  :AlignCtrl =lp0P0W & \\                              ||
 ||             |    |  :call AlignCtrl('=lp0P0W','&','\\')                  ||
 ||             |    |                                                       ||
 ||             |    +-------------------------------------------------------++
 ||   1st arg   |  = | =  all separator patterns are equivalent and are      ||
 ||             |    |    simultaneously active. Patterns are |regexp|.      ||
 ||             |    | C  cycle through separator patterns.  Patterns are    ||
 ||             |    |    |regexp| and are active sequentially.              ||
 ||             |    |                                                       ||
 ||             |  < | <  left justify separator   Separators are justified, ||
 ||             |    | >  right justify separator  too.  Separator styles    ||
 ||             |    | |  center separator         are cyclic.               ||
 ||             |    |                                                       ||
 ||             |  l | l  left justify   Justification styles are always     ||
 ||             |    | r  right justify  cyclic (ie. lrc would mean left j., ||
 ||             |    | c  center         then right j., then center, repeat. ||
 ||             |    | -  skip this separator                                ||
 ||             |    | +  re-use last justification method                   ||
 ||             |    | :  treat rest of text as a field                      ||
 ||             |    |                                                       ||
 ||             | p1 | p### pad separator on left  by # blanks               ||
 ||             | P1 | P### pad separator on right by # blanks               ||
 ||             |    |                                                       ||
 ||             |  I | I  preserve and apply first line's leading white      ||
 ||             |    |    space to all lines                                 ||
 ||             |    | W  preserve leading white space on every line, even   ||
 ||             |    |    if it varies from line to line                     ||
 ||             |    | w  don't preserve leading white space                 ||
 ||             |    |                                                       ||
 ||             |    | g  second argument is a selection pattern -- only     ||
 ||             |    |    align on lines that have a match  (inspired by     ||
 ||             |    |    :g/selection pattern/command)                      ||
 ||             |    | v  second argument is a selection pattern -- only     ||
 ||             |    |    align on lines that _don't_ have a match (inspired ||
 ||             |    |    by :v/selection pattern/command)                   ||
 ||             |    |                                                       ||
 ||             |    | m  Map support: AlignCtrl will immediately do an      ||
 ||             |    |    AlignPush() and the next call to Align() will do   ||
 ||             |    |    an AlignPop at the end.  This feature allows maps  ||
 ||             |    |    to preserve user settings.                         ||
 ||             |    |                                                       ||
 ||             |    | default                                               ||
 ||             |    |    AlignCtrl default                                  ||
 ||             |    |    will clear the AlignCtrl                           ||
 ||             |    |    stack & set the default:  AlignCtrl "Ilp1P1=" '='  ||
 ||             |    |                                                       ||
 ||             +----+-------------------------------------------------------+|
 ||  More args  |  More arguments are interpreted as describing separators   ||
 ||             +------------------------------------------------------------+|
 ||   No args   |  AlignCtrl will display its current settings               || >
 ||=============+============================================================+|
<||[range]Align |   [..list-of-separators..]                                 ||
 ||             +------------------------------------------------------------+|
 ||             |  Aligns text over the given range.  The range may be       ||
 ||             |  selected via visual mode (v, V, or ctrl-v) or via         ||
 ||             |  the command line.  The Align operation may be invoked     ||
 ||             |  as a command or as a function.                            ||
 ||             |   :[range]Align                                            ||
 ||             |   :[range]Align [list of separators]                       ||
 ||             |   :[range]call Align()                                     ||
 ||             |   :[range]call Align("list","of","separators",...)         ||
 \============================================================================/

==============================================================================

3. Alignment Usage				*alignusage* *align-usage*

        The <Align.vim> script includes two primary commands and two
	minor commands:

	  AlignCtrl : this command/function sets up alignment options
	              which persist until changed for later Align calls.
		      It controls such things as: how to specify field
		      separators, initial white space, padding about
		      separators, left/right/center justification, etc. >
			ex.  AlignCtrl wp0P1
                             Interpretation: during subsequent alignment
			     operations, preserve each line's initial
			     whitespace.  Use no padding before separators
			     but provide one padding space after separators.
<
	  Align     : this command/function operates on the range given
	              it to align text based on one or more separator
		      patterns.  The patterns may be provided via AlignCtrl
		      or via Align itself. >
			ex. :%Align ,
			    Interpretation: align all commas over the entire
			    file.
<
	  AlignPush : this command/function pushes the current AlignCtrl
	              state onto an internal stack. >
			ex. :AlignPush
			    Interpretation: save the current AlignCtrl
			    settings, whatever they may be.  They'll
			    also remain as the current settings until
			    AlignCtrl is used to change them.
<
	  AlignPop  : this command/function pops the current AlignCtrl
	              state from an internal stack. >
			ex. :AlignPop
			    Interpretation: presumably AlignPush was
			    used (at least once) previously; this command
			    restores the AlignCtrl settings when AlignPush
			    was last used.
<

ALIGNMENT CONTROL				*alignctrl* *align-control*

	This command doesn't do the alignment operation itself, it provides
	various alignment options.

	The first argument to AlignCtrl is a string which may contain one or
	more alignment control commands.  Most of the commands are single
	letter commands; the exceptions are the p# and P# commands which
	interpret digits following the p or P as specifying padding about the
	separator.

	The typical text line is considered to be composed of two or more
	fields separated by one or more separator pattern(s):
>
		ws field ws separator ws field ws separator ...
<
	where "ws" stands for "white space" such as blanks and/or tabs.

	
	Separators				*alignctrl-separators*

	As a result, separators may  not have white space (tabs or blanks) on
	their outsides (ie.  ":  :" is fine as a separator, but " :: " is
	not).  Usually such separators are not needed.

	However, if you really need to have such separators with leading or
	trailing whitespace, consider handling them by performing a substitute
	first (ie. s/  ::  /@/g), do the alignment on the temporary pattern
	(ie. @), and then perform a substitute to revert the separators back
	to their desired condition (ie. s/@/  ::  /g).

	The Align() function will first convert tabs over the region into
	spaces and then apply alignment control.  Except for initial white
	space, white space surrounding the fields is ignored.  One has three
	options just for handling initial white space:


	--- 						*alignctrl-w*
	wWI 	INITIAL WHITE SPACE			*alignctrl-W*
	--- 						*alignctrl-I*
		w : ignore all selected lines' initial white space
		W : retain all selected lines' initial white space
		I : retain only the first line's initial white space and
		    re-use it for subsequent lines

	Example: Leading white space options: >
                         +---------------+-------------------+----------------+
	                 |AlignCtrl w= :=|  AlignCtrl W= :=  |AlignCtrl I= := |
      +------------------+---------------+-------------------+----------------+
      |     Original     |   w option    |     W option      |    I option    |
      +------------------+---------------+-------------------+----------------+
      |   a := baaa      |a     := baaa  |   a      : = baaa |  a     := baaa |
      | caaaa := deeee   |caaaa := deeee | caaaa    : = deeee|  caaaa := deeee|
      |       ee := f    |ee    := f     |       ee : = f    |  ee    := f    |
      +------------------+---------------+-------------------+----------------+
<
	The original has at least one leading white space on every line.
	Using Align with w eliminated each line's leading white space.
	Using Align with W preserved  each line's leading white space.
	Using Align with I applied the first line's leading two spaces
	to each line.


	------						*alignctrl-l*
	lrc-+:	FIELD JUSTIFICATION			*alignctrl-r*
	------						*alignctrl-c*

	With "lrc", the fields will be left-justified, right-justified, or
	centered as indicated by the justification specifiers (lrc).  The
	"lrc" options are re-used by cycling through them as needed:

		l   means llllll....
		r   means rrrrrr....
		lr  means lrlrlr....
		llr means llrllr....

	Example: Justification options: Align = >
	+------------+-------------------+-------------------+-------------------+
	|  Original  |  AlignCtrl l      | AlignCtrl r       | AlignCtrl lr      |
	+------------+-------------------+-------------------+-------------------+
	| a=bb=ccc=1 |a   = bb  = ccc = 1|  a =  bb = ccc = 1|a   =  bb = ccc = 1|
	| ccc=a=bb=2 |ccc = a   = bb  = 2|ccc =   a =  bb = 2|ccc =   a = bb  = 2|
	| dd=eee=f=3 |dd  = eee = f   = 3| dd = eee =   f = 3|dd  = eee = f   = 3|
	+------------+-------------------+-------------------+-------------------+
        | Alignment  |l     l     l     l|  r     r     r   r|l       r   l     r|
	+------------+-------------------+-------------------+-------------------+
<
		AlignCtrl l : The = separator is repeatedly re-used, as the cycle
			      only consists of one character (the "l").  Every
			      time left-justification is used for fields.
		AlignCtrl r : The = separator is repeatedly re-used, as the cycle
			      only consists of one character (the "l").  Every
			      time right-justification is used for fields.
		AlignCtrl lr: Again, the "=" separator is repeatedly re-used, but
			      the fields are justified alternately between left
			      and right.

	Even more separator control is available.  With "-+:":

	    - : skip treating the separator as a separator.		*alignctrl--*
	    + : repeat use of the last "lrc" justification		*alignctrl-+*
	    : : treat the rest of the line as a single field		*alignctrl-:*

	Example: More justification options:  Align = >
	+------------+---------------+--------------------+---------------+
	|  Original  |  AlignCtrl -l | AlignCtrl rl+      | AlignCtrl l:  |
	+------------+---------------+--------------------+---------------+
        | a=bb=ccc=1 |a=bb   = ccc=1 |  a = bb  = ccc = 1 |a   = bb=ccc=1 |
        | ccc=a=bb=2 |ccc=a  = bb=2  |ccc = a   = bb  = 2 |ccc = a=bb=2   |
        | dd=eee=f=3 |dd=eee = f=3   | dd = eee = f   = 3 |dd  = eee=f=3  |
	+------------+---------------+--------------------+---------------+
        | Alignment  |l        l     |  r   l     l     l |l     l        |
	+------------+---------------+--------------------+---------------+
<
	In the first example in "More justification options":

	  The first "=" separator is skipped by the "-" specification,
	  and so "a=bb", "ccc=a", and "dd=eee" are considered as single fields.
         
	  The next "=" separator has its (left side) field left-justified.
	  Due to the cyclic nature of separator patterns, the "-l" specification
	  is equivalent to "-l-l-l ...".
         
	  Hence the next specification is a "skip", so "ccc=1", etc are fields.

	In the second example in "More justification options":

	  The first field is right-justified, the second field is left justified,
	  and all remaining fields repeat the last justification command
	  (ie. they are left justified, too).

	  Hence rl+ is equivalent to         rlllllllll ...
	  (whereas plain rl is equivalent to rlrlrlrlrl ... ).

	In the third example in "More justification options":

	  The text following the first separator is treated as a single field.

	Thus using the - and : operators one can apply justification to a
	single separator.

	ex. 1st separator only:    AlignCtrl l:
	    2nd separator only:    AlignCtrl -l:
	    3rd separator only:    AlignCtrl --l:
	    etc.


	---							*alignctrl-=*
	=C	CYCLIC VS ALL-ACTIVE SEPARATORS			*alignctrl-C*
	---

	The separators themselves may be considered as equivalent and
	simultaneously active ("=") or sequentially cycled through ("C").
	Separators are regular expressions (|regexp|) and are specified as
	the second, third, etc arguments.  When the separator patterns are
	equivalent and simultaneously active, there will be one pattern
	constructed: >

		AlignCtrl ... pat1 pat2 pat3
		\(pat1\|pat2\|pat3\)
<
	Each separator pattern is thus equivalent and simultaneously active.
	The cyclic separator AlignCtrl option stores a list of patterns, only
	one of which is active for each field at a time.

	Example: Equivalent/Simultaneously-Active vs Cyclic Separators >
 +-------------+------------------+---------------------+----------------------+
 |   Original  | AlignCtrl = = + -| AlignCtrl = =       | AlignCtrl C = + -    |
 +-------------+------------------+---------------------+----------------------+
 |a = b + c - d|a = b + c - d     |a = b + c - d        |a = b         + c - d |
 |x = y = z + 2|x = y = z + 2     |x = y         = z + 2|x = y = z     + 2     |
 |w = s - t = 0|w = s - t = 0     |w = s - t     = 0    |w = s - t = 0         |
 +-------------+------------------+---------------------+----------------------+
<
	The original is initially aligned with all operators (=+-) being
	considered as equivalent and simultaneously active field separators.
	Thus the "AlignCtrl = = + -" example shows no change.

	The second example only accepts the '=' as a field separator;
	consequently "b + c - d" is now a single field.

	The third example illustrates cyclic field separators and is
	analyzed in the following illustration: >

	field1 separator field2    separator field3 separator field4
	   a      =      b             +       c        -       d
	   x      =      y = z         +       2
	   w      =      s - t = 0
<
	The word "cyclic" is used because the patterns form a cycle
	of use; in the above case, its = + - = + - = + - = + -...

	Example: Cyclic separators >
		Label : this is some text discussing ":"s | ex. abc:def:ghi
		Label : this is some text with a ":" in it | ex. abc:def
<
	  apply AlignCtrl lWC : | |
	        (select lines)Align >
                Label : this is some text discussing ":"s  | ex. abc:def:ghi
                Label : this is some text with a ":" in it | ex. abcd:efg
<
	In the current example,
	  : is the first separator        So the first ":"s are aligned
	  | is the second separator       but subsequent ":"s are not.
	  | is the third separator        The "|"s are aligned, too.
	  : is the fourth separator       Since there aren't two bars,
	  | is the fifth separator        the subsequent potential cycles
	  | is the sixth separator        don't appear.
	 ...

	In this case it would probably have been a better idea to have used >
		AlignCtrl WCl: : |
<	as that alignment control would guarantee that no more cycling
	would be used after the vertical bar.

	Example: Cyclic separators

	    Original: >
		a| b&c | (d|e) & f-g-h
		aa| bb&cc | (dd|ee) & ff-gg-hh
		aaa| bbb&ccc | (ddd|eee) & fff-ggg-hhh
<
	    AlignCtrl C | | & - >
		a   | b&c     | (d|e)     & f   - g-h
		aa  | bb&cc   | (dd|ee)   & ff  - gg-hh
		aaa | bbb&ccc | (ddd|eee) & fff - ggg-hhh
<
	In this example,
	the first and second separators are "|",
	the third            separator  is  "&", and
	the fourth           separator  is  "-",

	(cycling)
	the fifth and sixth  separators are "|",
	the seventh          separator  is  "&", and
	the eighth           separator  is  "-", etc.

	Thus the first "&"s are (not yet) separators, and hence are
	treated as part of the field.  Ignoring white space for the
	moment, the AlignCtrl shown here means that Align will work
	with >

	field | field | field & field - field | field | field & field - ...
<

	---						*alignctrl-<*
	<>|	SEPARATOR JUSTIFICATION			*alignctrl->*
	---						*alignctrl-|*

	Separators may be of differing lengths as shown in the example
	below.  Hence they too may be justified left, right, or centered.
	Furthermore, separator justification specification is cyclic:

		<  means <<<<<...    justify separator(s) to the left
		>  means >>>>>...    justify separator(s) to the right
		|  means |||||...    center separator(s)

	Example: Separator Justification: Align -\+ >
				+-----------------+
				|    Original     |
				+-----------------+
				| a - bbb - c     |
				| aa -- bb -- ccc |
				| aaa --- b --- cc|
	+---------------------+-+-----------------+-+---------------------+
	|     AlignCtrl <     |     AlignCtrl >     |     AlignCtrl |     |
	+---------------------+---------------------+---------------------+
	| a   -   bbb -   c   | a     - bbb   - c   | a    -  bbb  -  c   |
	| aa  --  bb  --  ccc | aa   -- bb   -- ccc | aa  --  bb  --  ccc |
	| aaa --- b   --- cc  | aaa --- b   --- cc  | aaa --- b   --- cc  |
	+---------------------+---------------------+---------------------+
<

	---						*alignctrl-g*
	gv	SELECTIVE APPLICATION			*alignctrl-v*
	---


	These two options provide a way to select (g) or to deselect
	(v) lines based on a pattern.  Ideally :g/pat/Align  would
	work; unfortunately it results in Align() being called on
	each line satisfying the pattern separately. >

		AlignCtrl g pattern
<
	Align will only consider those lines which have the given pattern. >

		AlignCtrl v pattern
<
	Align will only consider those lines without the given pattern.
	As an example of use, consider the following example: >

				           :AlignCtrl v ^\s*/\*
	  Original          :Align =       :Align =
	+----------------+------------------+----------------+
	|one= 2;         |one     = 2;      |one   = 2;      |
	|three= 4;       |three   = 4;      |three = 4;      |
	|/* skip=this */ |/* skip = this */ |/* skip=this */ |
	|five= 6;        |five    = 6;      |five  = 6;      |
	+----------------+------------------+----------------+
<
	The first "Align =" aligned with all "="s, including that
	one in the "skip=this" comment.

	The second "Align =" had a AlignCtrl v-pattern which caused
	it to skip (ignore) the "skip=this" line when aligning.
	
	To remove AlignCtrl's g and v patterns, use (as appropriate) >

		AlignCtrl g
		AlignCtrl v
<
	To see what g/v patterns are currently active, just use the
	reporting capability of a plain AlignCtrl call: >

		AlignCtrl
<

	---
	 m	MAP SUPPORT				*alignctrl-m*
	---

	This option primarily supports the development of maps.  The AlignCtrl
	call will first do an AlignPush() (ie. retain current alignment
	control settings).  The next Align() will, in addition to its
	alignment job, finish up with an AlignPop().  Thus the AlignCtrl
	settings that follow the "m" are only temporarily in effect for just
	the next Align().


	---
	p###						*alignctrl-p*
	P###	PADDING					*alignctrl-P*
	---

	These two options control pre-padding and post-padding with
	blanks about the separator.  One may pad separators with zero
	to nine spaces; the padding number(s) is/are treated as a
	cyclic parameter.  Thus one may specify padding separately
	for each field or re-use a padding pattern. >

	Example:          AlignCtrl p102P0
	+---------+----------------------------------+
	| Original| a=b=c=d=e=f=g=h=1                |
        | Align = | a =b=c  =d =e=f  =g =h=1         |
        +---------+----------------------------------+
	| prepad  |   1 0   2  1 0   2  1 0          |
        +---------+----------------------------------+
<
	This example will cause Align to:

		pre-pad the first  "=" with a single blank,
		pre-pad the second "=" with no blanks,
		pre-pad the third  "=" with two blanks,
		pre-pad the fourth "=" with a single blank,
		pre-pad the fifth  "=" with no blanks,
		pre-pad the sixth  "=" with two blanks,
	        etc.

	---------------				*alignctrl-settings*
	No option given		DISPLAY STATUS	*alignctrl-*
	---------------				*alignctrl-no-option*

	AlignCtrl, when called with no arguments, will display the
	current alignment control settings.  A typical display is
	shown below: >

		AlignCtrl<=> qty=1 AlignStyle<l> Padding<1|1>
		Pat1<\(=\)>
<
	Interpreting, this means that the separator patterns are all
	equivalent; in this case, there's only one (qty=1).  Fields
	will be padded on the right with spaces (left justification),
	and separators will be padded on each side with a single
	space.

	One may get a string which can be fed back into AlignCtrl: >

		:let alignctrl= AlignCtrl()
<
	This form will put a string describing the current AlignCtrl
	options, except for the "g" and "v" patterns, into a
	variable.  The AlignCtrl() function will still echo its
	settings, however.  One can feed any non-supported "option"
	to AlignCtrl() to prevent this, however: >

		:let alignctrl= AlignCtrl("d")
<



ALIGNMENT						*align-align*

	Once the alignment control has been determined, the user
	specifies a range of lines for the Align command/function to
	do its thing.  Alignment is often done on a line-range basis,
	but one may also restrict alignment to a visual block using
	ctrl-v.  For any visual mode, one types the colon (:) and
	then "Align".  One may, of course, specify a range of lines:

		:[range]Align [list-of-separators]

	where |range| is the usual Vim-powered set of possibilities;
	the list of separators is the same as the AlignCtrl
	capability.  There is only one list of separators, but
	either AlignCtrl or Align can be used to specify that list.

	Align makes two passes over the text to be aligned.
	The first pass determines how many fields there are and
	determines the maximum sizes of each field which are
	then stored in a vector.  The second pass pads the field
	(left/right/centered as specified) to bring its length up
	to the maximum size of the field.  Then the separator and
	its AlignCtrl-specified padding is appended.

		Pseudo-Code:
		 During pass 1
		 | For all fields in the current line
		 || Determine current separator
		 || Examine field specified by current separator
		 || Determine length of field and save if largest thus far
		 Initialize newline based on initial whitespace option (wWI)
		 During pass 2
		 | For all fields in current line
		 || Determine current separator
		 || Extract field specified by current separator
		 || Prepend/append padding as specified by AlignCtrl
		 || (right/left/center)-justify to fit field into max-size field
		 || Append separator with AlignCtrl-specified separator padding
		 || Delete current line, install newly aligned line

	The g and v AlignCtrl patterns cause the passes to not
	consider lines for alignment, either by requiring that the
	g-pattern be present or that the v-pattern not be present.

	The whitespace on either side of a separator is ignored.


ALIGNMENT MAPS				*alignmaps* *align-maps* *alignmap*

	There are a number of maps using AlignCtrl() and Align()
	in the <AlignMaps.vim> file.  This file may also be put
	into the plugins subdirectory.  Since AlignCtrl and Align
	supercede textab and its <ttalign.vim> file, the maps either
	have a leading "t" (for "textab") or the more complicated
	ones an "a" (for "alignment") for backwards compatibility.

	  \a,   : useful for breaking up comma-separated
	          declarations prior to \adec			|alignmap-a,|
	  \a?   : aligns (...)? ...:... expressions on ? and :	|alignmap-a?|
	  \a<   : aligns << and >> for c++			|alignmap-a<|
	  \a=   : aligns := assignments   			|alignmap-a=|
	  \abox : draw a C-style comment box around text lines	|alignmap-abox|
	  \acom : useful for aligning comments			|alignmap-acom|
	  \adcom: useful for aligning comments in declarations  |alignmap-adcom|
	  \anum : useful for aligning numbers 			|alignmap-anum|
	          NOTE: For the visual-mode use of \anum, <vis.vim> is needed!
		    See
		    http://mysite.verizon.net/astronaut/vim/index.html#VimFuncs
		    at the label "Visual Block Commands"
	  \aenum: align a European-style number			|alignmap-anum|
	  \aunum: align a USA-style number			|alignmap-anum|
	  \adec : useful for aligning declarations		|alignmap-adec|
	  \adef : useful for aligning definitions		|alignmap-adef|
	  \afnc : useful for aligning ansi-c style functions'
	          argument lists				|alignmap-afnc|
	  \adcom: a variant of \acom, restricted to comment     |alignmap-adcom|
	          containing lines only, but also only for
		  those which don't begin with a comment.
		  Good for certain declaration styles.
	  \aocom: a variant of \acom, restricted to comment     |alignmap-aocom|
	          containing lines only
	  \tab  : align a table based on tabs			*alignmap-tab*
	          (converts to spaces)
	  \tml  : useful for aligning the trailing backslashes	|alignmap-tml|
	          used to continue lines (shell programming, etc)
	  \tsp  : use Align to make a table separated by blanks	|alignmap-tsp|
	          (left justified)
	  \Tsp  : use Align to make a table separated by blanks	|alignmap-Tsp|
	          (right justified)
	  \tsq  : use Align to make a table separated by blanks	|alignmap-tsq|
	          (left justified) -- "strings" are not split up
	  \tt   : useful for aligning LaTeX tabular tables	|alignmap-tt|
	  \tx   : make a left-justified  alignment on
	          character "x" where "x" is: ,:<=@|#		|alignmap-t=|
	  \Tx   : make a right-justified alignment on
	          character "x" where "x" is: ,:<=@#		|alignmap-T=|
	  \Htd  : tabularizes html tables:			|alignmap-Htd|
	          <TR><TD> ...field... </TD><TD> ...field... </TD></TR>

	The leading backslash is actually <leader> (see |mapleader|
	for how to customize the leader to be whatever you like).
	These maps use the <Align.vim> package and are defined in
	the <AlignMaps.vim> file.  Although the maps use AlignCtrl
	options, they typically use the "m" option which pushes
	the options (AlignPush).  The associated Align call which
	follows will then AlignPop the user's original options back.

	In the examples below, one may select the text with a "ma"
	at the first line, move to the last line, then execute
	the map.  Alternatively, one may select the text with the
	"V" visual mode selector.

	For those complex alignment maps which do alignment on
	constructs (e.g. \acom, \adec, etc), a series of substitutes
	is used to insert "@" symbols in appropriate locations.
	Align() is then used to do alignment directly on "@"s;
	then it is followed by further substitutes to do clean-up.
	However, the maps \WS and \WE protect any original embedded
	"@" symbols by first converting them to <DEL> characters,
	doing the requested job, and then converting them back.


	---------------------------
	Alignment Map Examples: \a,				*alignmap-a,*
	---------------------------

	Original: illustrates comma-separated declaration splitting: >
		int a,b,c;
		struct ABC_str abc,def;
<
	Becomes: >
		int a;
		int b;
		int c;
		struct ABC_str abc;
		struct ABC_str def;
<

	---------------------------
	Alignment Map Examples: \a?				*alignmap-a?*
	---------------------------

	Original: illustrates ()?: aligning >
		printf("<%s>\n",
		  (x == ABC)? "abc" :
		  (x == DEFG)? "defg" :
		  (x == HIJKL)? "hijkl" : "???");
<
	Becomes:  select "(x == ..." lines, then \a? >
		printf("<%s>\n",
		  (x == ABC)?   "abc"   :
		  (x == DEFG)?  "defg"  :
		  (x == HIJKL)? "hijkl" : "???");
<

	---------------------------
	Alignment Map Examples: \a<				*alignmap-a<*
	---------------------------

	Original: illustrating aligning of << and >> >
		cin << x;
		cin      << y;
		cout << "this is x=" << x;
		cout << "but y=" << y << "is not";
<
	Becomes:  select "(x == ..." lines, then \a< >
		cin  << x;
		cin  << y;
		cout << "this is x=" << x;
		cout << "but y="     << y  << "is not";
<

	---------------------------
	Alignment Map Examples: \a=				*alignmap-a=*
	---------------------------

	Original: illustrates how to align := assignments >
		aa:=bb:=cc:=1;
		a:=b:=c:=1;
		aaa:=bbb:=ccc:=1;
<	
	Bcomes: select the three assignment lines, then \a:= >
		aa  := bb  := cc  := 1;
		a   := b   := c   := 1;
		aaa := bbb := ccc := 1;
<

	---------------------------
	Alignment Map Examples: \abox				*alignmap-abox*
	---------------------------

	Original: illustrates how to comment-box some text >
		This is some plain text
		which will
		soon be surrounded by a
		comment box.
<
	Becomes:  Select "This..box." with ctrl-v, press \abox >
		/***************************
		 * This is some plain text *
		 * which will              *
		 * soon be surrounded by a *
		 * comment box.            *
		 ***************************/
<

	---------------------------
	Alignment Map Examples: \acom				*alignmap-acom*
	---------------------------

	Original: illustrates how to align C-style comments (works for //, too) >
		if(itworks) { /* this */
			then= dothis; /* is a */
			} /* set of three comments */
<
	Becomes: Select the three lines, press \acom >
	        if(itworks) {         /* this                  */
	                then= dothis; /* is a                  */
	                }             /* set of three comments */
<
	Also see |alignmap-aocom|


	---------------------------
	Alignment Map Examples: \anum				*alignmap-anum*
	---------------------------

	Original: illustrates how to get numbers lined up >
		 -1.234 .5678 -.901e-4
		 1.234 5.678 9.01e-4
		 12.34 56.78 90.1e-4
		 123.4 567.8 901.e-4
<
	Becomes: Go to first line, ma.  Go to last line, press \anum >
		  -1.234    .5678   -.901e-4
		   1.234   5.678    9.01e-4
		  12.34   56.78    90.1e-4
		 123.4   567.8    901.e-4
<
	Original: >
		 | -1.234 .5678 -.901e-4 |
		 | 1.234 5.678 9.01e-4   |
		 | 12.34 56.78 90.1e-4   |
		 | 123.4 567.8 901.e-4   |
<
	Becomes: Select the numbers with ctrl-v (visual-block mode), >
	         press \anum
	         |  -1.234    .5678   -.901e-4 |
	         |   1.234   5.678    9.01e-4  |
	         |  12.34   56.78    90.1e-4   |
	         | 123.4   567.8    901.e-4    |
<
	Original: >
		 -1,234 ,5678 -,901e-4
		 1,234 5,678 9,01e-4
		 12,34 56,78 90,1e-4
		 123,4 567,8 901,e-4
<
	Becomes: Go to first line, ma.  Go to last line, press \anum >
		  -1,234    ,5678   -,901e-4
		   1,234   5,678    9,01e-4
		  12,34   56,78    90,1e-4
		 123,4   567,8    901,e-4
<
	In addition:
	  \aenum is provided to support European-style numbers
	  \aunum is provided to support USA-style numbers

	One may get \aenum behavior for \anum >
	  let g:alignmaps_euronumber= 1
<	or \aunum behavior for \anum if one puts >
	  let g:alignmaps_usanumber= 1
<	in one's <.vimrc>.


	---------------------------
	Alignment Map Examples: \ascom				*alignmap-ascom*
	---------------------------

	Original: >
		/* A Title */
		int x; /* this is a comment */
		int yzw; /* this is another comment*/
<
	Becomes: Select the three lines, press \ascom >
	        /* A Title */
	        int x;   /* this is a comment       */
	        int yzw; /* this is another comment */
<

	---------------------------
	Alignment Map Examples: \adec				*alignmap-adec*
	---------------------------

	Original: illustrates how to clean up C/C++ declarations >
		int     a;
		float   b;
		double *c=NULL;
		char x[5];
		struct  abc_str abc;
		struct  abc_str *pabc;
		int     a;              /* a   */
		float   b;              /* b   */
		double *c=NULL;              /* b   */
		char x[5]; /* x[5] */
		struct  abc_str abc;    /* abc */
		struct  abc_str *pabc;    /* pabc */
		static   int     a;              /* a   */
		static   float   b;              /* b   */
		static   double *c=NULL;              /* b   */
		static   char x[5]; /* x[5] */
		static   struct  abc_str abc;    /* abc */
		static   struct  abc_str *pabc;    /* pabc */
<
	Becomes: Select the declarations text, then \adec >
		int                    a;
		float                  b;
		double                *c    = NULL;
		char                   x[5];
		struct abc_str         abc;
		struct abc_str        *pabc;
		int                    a;           /* a    */
		float                  b;           /* b    */
		double                *c    = NULL; /* b    */
		char                   x[5];        /* x[5] */
		struct abc_str         abc;         /* abc  */
		struct abc_str        *pabc;        /* pabc */
		static int             a;           /* a    */
		static float           b;           /* b    */
		static double         *c    = NULL; /* b    */
		static char            x[5];        /* x[5] */
		static struct abc_str  abc;         /* abc  */
		static struct abc_str *pabc;        /* pabc */
<

	---------------------------
	Alignment Map Examples: \adef				*alignmap-adef*
	---------------------------

	Original: illustrates how to line up #def'initions >
		#define ONE 1
		#define TWO 22
		#define THREE 333
		#define FOUR 4444
<
	Becomes: Select four definition lines, apply \adef >
	#	 define ONE   1
	#	 define TWO   22
	#	 define THREE 333
	#	 define FOUR  4444
<

	---------------------------
	Alignment Map Examples: \afnc				*alignmap-afnc*
	---------------------------

	This map is an exception to the usual selection rules.
	It uses "]]" to find the function body's leading "{".
	Just put the cursor anywhere in the function arguments and
	the entire function declaration should be processed.

	Because "]]" looks for that "{" in the first column, the
	"original" and "becomes" examples are in the first column,
	too.

	Original: illustrates lining up ansi-c style function definitions >
	int f(
	  struct abc_str ***a, /* one */
	  long *b, /* two */
	  int c) /* three */
	{
	}
<
	Becomes: put cursor anywhere before the '{', press \afnc >
	int f(
	  struct abc_str ***a,	/* one   */
	  long             *b,	/* two   */
	  int               c)	/* three */
	{
	}
<

	---------------------------
	Alignment Map Examples: \adcom				*alignmap-adcom*
	---------------------------

	Original: illustrates aligning comments that don't begin
		lines (optionally after some whitespace). >
		struct {
			/* this is a test */
			int x; /* of how */
			double y; /* to use adcom */
			};
<
	Becomes: Select the inside lines of the structure,
		then press \adcom.  The comment-only
		line is ignored but the other two comments
		get aligned. >
		struct {
                        /* this is a test */
                        int x;    /* of how       */
                        double y; /* to use adcom */
			};
<

	---------------------------
	Alignment Map Examples: \aocom				*alignmap-aocom*
	---------------------------

	Original: illustrates how to align C-style comments (works for //, too)
	          but restricted only to aligning with those lines containing
		  comments.  See the difference from \acom (|alignmap-acom|). >
		if(itworks) { /* this comment */
			then= dothis;
			} /* only appears on two lines */
<
	Becomes: Select the three lines, press \aocom >
                if(itworks) { /* this comment              */
                        then= dothis;
                        }     /* only appears on two lines */
<
	Also see |alignmap-acom|


	---------------------------
	Alignment Map Examples: \tsp				*alignmap-tsp*
	---------------------------

	Normally Align can't use white spaces for field separators as such
	characters are ignored surrounding field separators.  The \tsp and
	\Tsp maps get around this limitation.

	Original: >
	 one two three four five
	 six seven eight nine ten
	 eleven twelve thirteen fourteen fifteen
<
	Becomes: Select the lines, \tsp >
	 one    two    three    four     five
	 six    seven  eight    nine     ten
	 eleven twelve thirteen fourteen fifteen
<
	Becomes: Select the lines, \Tsp >
	    one    two    three     four    five
	    six  seven    eight     nine     ten
	 eleven twelve thirteen fourteen fifteen
<

	---------------------------
	Alignment Map Examples: \tsq				*alignmap-tsq*
	---------------------------

	The \tsp map is useful for aligning tables based on white space,
	but sometimes one wants double-quoted strings to act as a single
	object in spite of embedded spaces.  The \tsq map was invented
	to support this. (thanks to Leif Wickland)

	Original: >
	 "one two" three
	 four "five six"
<
	Becomes: Select the lines, \tsq >
	 "one two" three
	 four      "five six"
<

	---------------------------
	Alignment Map Examples: \tt				*alignmap-tt*
	---------------------------

	Original: illustrates aligning a LaTex Table >
	 \begin{tabular}{||c|l|r||}
	 \hline\hline
	   one&two&three\\ \hline
	   four&five&six\\
	   seven&eight&nine\\
	 \hline\hline
	 \end{tabular}
<
	Becomes: Select the three lines inside the table >
	(ie. one..,four..,seven..) and press \tt
	 \begin{tabular}{||c|l|r||}
	 \hline\hline
	   one   & two   & three \\ \hline
	   four  & five  & six   \\
	   seven & eight & nine  \\
	 \hline\hline
	 \end{tabular}
<

	----------------------------
	Alignment Map Examples: \tml				*alignmap-tml*
	----------------------------

        Original:  illustrates aligning multi-line continuation marks >
	one \
	two three \
	four five six \
	seven \\ \
	eight \nine \
	ten \
<
        Becomes:  >
        one           \
        two three     \
        four five six \
        seven \\      \
        eight \nine   \
        ten           \
<

	---------------------------
	Alignment Map Examples: \t=				*alignmap-t=*
	---------------------------

	Original: illustrates left-justified aligning of = >
		aa=bb=cc=1;/*one*/
		a=b=c=1;/*two*/
		aaa=bbb=ccc=1;/*three*/
<
	Becomes: Select the three equations, press \t= >
		aa  = bb  = cc  = 1; /* one   */
		a   = b   = c   = 1; /* two   */
		aaa = bbb = ccc = 1; /* three */
<

	---------------------------
	Alignment Map Examples: \T=				*alignmap-T=*
	---------------------------

	Original: illustrates right-justified aligning of = >
		aa=bb=cc=1; /* one */
		a=b=c=1; /* two */
		aaa=bbb=ccc=1; /* three */
<
	Becomes: Select the three equations, press \T= >
                 aa =  bb =  cc = 1; /* one   */
                  a =   b =   c = 1; /* two   */
                aaa = bbb = ccc = 1; /* three */
<

	---------------------------
	Alignment Map Examples: \Htd				*alignmap-Htd*
	---------------------------

	Original: for aligning tables with html >
	  <TR><TD>...field one...</TD><TD>...field two...</TD></TR>
	  <TR><TD>...field three...</TD><TD>...field four...</TD></TR>
<
	Becomes: Select <TR>... lines, press \Htd >
	  <TR><TD> ...field one...   </TD><TD> ...field two...  </TD></TR>
	  <TR><TD> ...field three... </TD><TD> ...field four... </TD></TR>
<
==============================================================================

4. Alignment Tool History					*align-history*

ALIGN HISTORY
	26 : Aug 20, 2004 : loaded_align now also indicates version number
	                    GetLatestVimScripts :AutoInstall: now supported
	25 : Jul 27, 2004 : For debugging, uses Dfunc(), Dret(), and Decho()
	24 : Mar 03, 2004 : (should've done this earlier!) visualmode(1)
	                    not supported until v6.2, now Align will avoid
			    calling it for earlier versions.  Visualmode
			    clearing won't take place then, of course.
	23 : Oct 07, 2003 : Included Leif Wickland's ReplaceQuotedSpaces()
	                    function which supports \tsq
	22 : Jan 29, 2003 : Now requires 6.1.308 or later to clear visualmode()
	21 : Jan 10, 2003 : BugFix: similar problem to #19; new code
	                    bypasses "norm! v\<Esc>" until initialization
	                    is over.
	20 : Dec 30, 2002 : BugFix: more on "unable to highlight" fixed
	19 : Nov 21, 2002 : BugFix: some terminals gave an "unable to highlight"
	                    message at startup; Hari Krishna Dara tracked it
	                    down; a silent! now included to prevent noise.
	18 : Nov 04, 2002 : BugFix: re-enabled anti-repeated-loading
	17 : Nov 04, 2002 : BugFix: forgot to have AlignPush() push s:AlignSep
	                    AlignCtrl now clears visual-block mode when used so
	                    that Align won't try to use old visual-block
	                    selection marks '< '>
	16 : Sep 18, 2002 : AlignCtrl <>| options implemented (separator
	                    justification)
	15 : Aug 22, 2002 : bug fix: AlignCtrl's ":" now acts as a modifier of
	                             the preceding alignment operator (lrc)
	14 : Aug 20, 2002 : bug fix: AlignCtrl default now keeps &ic unchanged
	                    bug fix: Align, on end-field, wasn't using correct alignop
	                    bug fix: Align, on end-field, was appending padding
	13 : Aug 19, 2002 : bug fix: zero-length g/v patterns are accepted
	                    bug fix: always skip blank lines
	                    bug fix: AlignCtrl default now also clears g and v
	                             patterns
	12 : Aug 16, 2002 : moved keep_ic above zero-length pattern checks
	                    added "AlignCtrl default"
	                    fixed bug with last field getting separator spaces
	                    at end line
	11 : Jul 08, 2002 : prevent separator patterns which match zero length
	                    -+: included as additional alignment/justification
	                    styles
	10 : Jun 26, 2002 : =~# used instead of =~ (for matching case) 
	                    ignorecase option handled
	 9 : Jun 25, 2002 : implemented cyclic padding

ALIGNMENT MAP HISTORY					*alignmap-history*
	31  : Feb 01, 2005 : * \adcom included, with help
			     * \a, now works across multiple lines with different
			       types
			     * AlignMaps now uses <cecutil.vim> for its mark and
			       window-position saving and restoration
	      Mar 04, 2005   * improved \a,
	      Apr 06, 2005   * included \aenum, \aunum, and provided
			       g:alignmaps_{usa|euro]number} options
	30  : Aug 20, 2004 : * \a, : now handles embedded assignments and does \adec
			     * \acom  now can handle Doxygen-style comments
	                     * g:loaded_alignmaps now also indicates version
	                     * internal maps \WE and \WS are now re-entrant
	29  : Jul 27, 2004 : * \tml aligns trailing multi-line single backslashes
	                       (thanks to Raul Benavente!)
	28  : May 13, 2004 : * \a, had problems with leading blanks; fixed!
	27  : Mar 31, 2004 : * \T= was having problems with == and !=
	                     * Fixed more problems with \adec
	26  : Dec 09, 2003 : * \ascom now also ignores lines without comments
	                     * \tt  \& now not matched
	                     * \a< handles both << and >>
	25  : Nov 14, 2003 : * included \anum (aligns numbers with periods and
	                       commas).  \anum also supported with ctrl-v mode.
	                     * \ts, \Ts, : (aligns on commas, then swaps leading
	                       spaces with commas)
	                     * \adec ignores preprocessor lines and lines with
	                       with comments-only
	23  : Sep 10, 2003 : * fixed bug in \afnc.  No longer overwrites marks y,z
	                     * fixed bug in \tsp, \tab, \Tsp, and \Tab - lines
	                       containing backslashes were having their
	                       backslashes
	                       removed.  Included Leif Wickland's patch for \tsq.
	                     * \adef now ignores lines holding comments only
	18  : Aug 22, 2003 :   \a< lines up C++'s << operators
	                       saves/restores gdefault option (sets to nogd)
	                       all b:..varname.. are now b:alignmaps_..varname..
	17  : Nov 04, 2002 :   \afnc now handles // comments correctly and commas
	                       within comments
	16  : Sep 10, 2002 :   changed : to :silent! for \adec
	15  : Aug 27, 2002 :   removed some <c-v>s
	14  : Aug 20, 2002 :   \WS, \WE mostly moved to functions, marks y and z
	                       now restored
	11  : Jul 08, 2002 :   \abox bug fix
	 9  : Jun 25, 2002 :   \abox modified to handle leading initial white space
	                   :   various bugfixes to \afnc, \T=, etc

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