%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%	CHANGEBAR STYLE
%
%	Written by:
%		Michael Fine
%		Distributed Systems Architecture.
%		October, 1986.
%
%       Revisions:
%	        Support for twosided.sty added.	January, 1987.
%		
%		Warning message added to indicate that another pass is
%		required. May, 1987.
%
%
% USAGE:
% 
%    \cbstart[dimension]
%    \cbend
%	All material between the two macros is barred.  Nested
%	changebars are allowed.  The optional parameter specifies the
%	width of the bar.  If no width is specified, the current value
%	of the parameter \changebarwidth is used.  Note that \cbstart
%	and \cbend can be used anywhere but must be correctly nested
%	with floats and footnotes.  That is, you cannot have one end of
%	the bar inside a floating insertion and the other outside, but
%	that would be a meaningless thing to do anyhow.
% 
%     \setlength{\changebarwidth}{dimension}
% 	Sets the default width of the bar. 
% 
%     \setlength{\changebarsep}{dimension}
% 	Sets the separation between the bar and the left margin of the
% 	text.
% 
% IMPORTANT NOTE: Just as with cross references and labels, you
% usually need to process the document twice (and sometimes three
% times) to ensure that the changebars come out correctly.  However, a
% warning will be given if another pass is required.
%
%
% PARAMETERS:
%
%    \changebarwidth
%	A LaTeX length parameter that gives the bar width.  It can be
%	changed with the \setlength command.  Changing its value affects
%	all subsequent changebars subject to the scoping rules of
%	\setlength.
%
%    \changebarsep
%	A LaTeX length parameter that gives the separation of the bar
%	from the left margin of the text.  It can be set with the
%	\setlength command.
%
%
% 
% FEATURES:
% 
%	Changebars may be nested within each other.  Each level of
%	nesting can be given a different thickness bar.
% 
% 	Changebars may be nested in other environments including floats
% 	and footnotes.
% 
% 	Changebars are applied to all the material within the ``barred''
% 	environment, including floating bodies regardless of where the
% 	floats float to.  An exeception to this is margin floats.
% 
% 	Changebars may cross page boundaries.
% 
% 
% DEFICIENCIES AND BUGS:
% 
%	The macros blindly use specials points \cb@minpoint through
%	\cb@maxpoint.  If this conflicts with another set of macros, the
%	results will be unpredictable.  (What is really needed is a
%	\newspecialpoint, analogous to \newcount etc.)
% 
%	There is a limit of (\cb@maxpoint-\cb@minpoint+1)/4 bars per
%	page (four special points per bar).  Using more than this number
%	yeilds unpredictable results (but that could be called a feature
%	for a page with so many bars).  This limitation could be
%	increased if desired
% 
% 	Internal macro names are all of the form \@cbxxxx.  No checking
% 	for conflicts with other macros is done.  
% 
%	This implementation has not been designed for two column
%	printing.
% 
% 	The algorithms may fail if a floating insertion is split over
% 	multiple pages.  In LaTeX floats are not split but footnotes may
% 	be.  The simplest fix to this is to prevent footnotes from being
% 	split but this may make TeX very unhappy.
%
%	The \cbend normally gets "attached" to the token after it rather
%	than the one before it.  This may lead to a longer bar than
%	intended.  For example, consider the sequence `word1 \cbend
%	word2'.  If there is a line break between `word1' and `word2'
%	the bar will incorrectly be extended an extra line.  This
%	particular case can be fixed with the incantation `word1\cbend{}
%	word2'.
% 
% 
% BASIC ALGORITHM
%
%	The changebars are implemented using the \specials of the DVI to
%	LN3 translator.  In essence, the start of changebar defines a
%	\special point in the margin at the current vertical position on
%	the page.  The end of a changebar defines another point and then
%	joins the two using the "connect" \special.
%
%	This works fine as long as the two points being connected lie on
%	the same page.  However, if they don't, the bar must be
%	artificially terminated at the page break and restarted at the
%	top of the next page.  The only way to do this (that I can think
%	of) is to modify the output routine so that it checks if any bar
%	is in progress when it ships out a page and, if so, adds the
%	necessary artificial end and begin.
%	
%	The obvious way to indicate to the output routine that a bar is
%	in progress is to set a flag when the bar is begun and to unset
%	this flag when the bar is ended.  This works most of the time
%	but, because of the asynchronous behavior of the output routine,
%	errors occur if the bar begins or ends near a page break.  To
%	illustrate, consider the following scenerio.
%
%	blah blah blah		% page n
%	blah blah blah
%	\cbstart		% this does its thing and set the flag
%	more blah
%		<-------------- pagebreak occurs here
%	more blah
%	\cbend			% does its thing and unsets flag
%	blah blah
%	
%	Since TeX process ahead of the page break before invoking the
%	output routine, it is possible that the \cbend is
%	processed, and the flag unset, before the output routine is
%	called.  If this happens, the necessary artificial end and begin
%	will not be added to page n and n+1, respectively.  Thus, it is
%	not possible to use a flag to signal the output routine that a
%	bar crosses a page break, and some other mechanism is required.
%	
%	The method used with these macros is to create a list of the
%	beginning and end points of each bar in the document together
%	with the page number corresponding to each point.  Then, as a
%	page is completed, a modified output routine checks the list to
%	determine if any bars begun on or before the current page are
%	terminated on subsequent pages, and handles those bars
%	appropriately.  To build the list, information about each
%	changebar is written to the .AUX file as bars are processed.
%	This information is re-read when the document is next processed.
%	Thus, to ensure that changebars are correct, the document must
%	be processed twice, but this is required for LaTeX anyway.
%
%	This apprach is sufficiently general to allow nested bars, bars
%	in floating insertions, and bars around floating insertions.
%	Bars inside floats and footnotes are handled in the same way as
%	bars in regular text.  Bars that encompass floats or footnotes
%	are handled by creating an additional bar that floats with the
%	floating material.  Modifications to the appropriate LaTeX
%	macros check for this condition and add the extra bar.
%
%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%	User Level Commands And Parameters
%
%

%
% \cbstart	\cbend
%
% Start and end a changebar and save state on \cb@currentlist.  Width of
% new bar is determined by adding \changebarwidth to width of current
% bar.  Does not invoke a LaTeX environment.
%
\def\cbstart{\@ifnextchar [{\cb@xstart}{\cb@start\changebarwidth}}
	\def\cb@xstart[#1]{\cb@start{#1}}

\def\cbend{\if e\cb@currentlist
	\message{Badly nested changebars.  Expect erroneous results.}\else
	\cb@end\fi}

%
% \begin{changebar}  \end{changebar}
%
% Identical to \cbstart and \cbend but invokes a LaTeX environment to
% enforce correct nesting.  Cannot be used in tabular and tabbing
% environments.
%
%\newenvironment{changebar}{\@bsphack\cbstart\@esphack}{\@bsphack
%	\cbend\@esphack}


%
% \changebarwidth
%
% A LaTeX length parameter that gives the bar width.  Width of bar is
% given by \changebarwidth multiplied by nesting level.
%
\newlength{\changebarwidth}
\setlength{\changebarwidth}{2pt}

%
% \changebarsep
%
% A LaTeX length parameter that gives the separation of the bar from the
% left margin of the text.
%
\newlength{\changebarsep}
\setlength{\changebarsep}{30pt}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%	Declarations And Initializations
%
%

\let\cb@ig=\ignorespaces %useful abreviation

\def\cb@maxpoint{80}		% max value of used special points
\def\cb@minpoint{1}		% ditto for min;
				% MUST BE ODD ****
\def\cb@nil{0}			% a void value for points

\newcount\cb@nextpoint		% next value of special point to use
\newcount\cb@currentpoint	% current value in use
\cb@nextpoint=\cb@minpoint	% intially = \cb@minpoint

\newcount\cb@page		% count for page value from hist list
\newcount\cb@pagecount		% our internal count of pages output
\cb@pagecount=0			% initially 0 due to timing of increment

\xdef\cb@history{e}		% the history list; initially empty
\xdef\cb@spanlist{e}		% list of bars spanning current page
\xdef\cb@currentlist{e}		% used to implement nesting without using
				% TeX grouping


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%	Macros for beginning and ending bars
%
%

%
% \cb@start#1		#1 is the dimension of the bar
%
% This macro is used to start a change bar.  It assigns a new value to
% the current point and advances the counter for the next point to be
% assigned.  It pushes this info onto \cb@currentlist and then sets the
% point by calling \cb@setBeginPoint with the point number.  Finally, it
% writes the aux file.
%
\def\cb@start#1{\cb@currentpoint=\cb@nextpoint
	\@tempdima=#1\cb@ig				% for \cb@push
	\cb@push\cb@currentlist
	\ifvmode \cb@setBeginPoint\cb@currentpoint
	\else \vbox to 0pt{\vskip -\ht\strutbox		%jump up a line to
	\cb@setBeginPoint\cb@currentpoint		%set point
	\vskip \ht\strutbox}\fi
	\cb@writeAux\cb@advancePoint}

\def\cb@advancePoint{\global\advance\cb@nextpoint by 4\cb@ig
	\ifnum\cb@nextpoint>\cb@maxpoint
	\global\cb@nextpoint=\cb@minpoint\relax\fi}

%
% \cb@end
%
% This macro is used to end a changebar.  It pops the current point and
% nesting level off \cb@currentlist and sets the end point by calling
% \cb@setEndPoint with the parameter corresponding to the BEGINNING
% point number.  It writes the aux file and joins the points.
%
\def\cb@end{\cb@pop\cb@currentlist
	\cb@setEndPoint\cb@currentpoint
	\advance\cb@currentpoint by1\cb@writeAux}


%
% \cb@setBeginPoint#1
%
% Assigns position to points #1 and #1+2.  First computes the position.
%
\def\cb@setBeginPoint#1{\@tempdimb=\hoffset
	\advance\@tempdimb by\oddsidemargin
	\advance\@tempdimb by -\changebarsep
	\special{ln03:defpoint \the#1(\the\@tempdimb,)}\cb@ig
	\@tempcnta#1\advance\@tempcnta by2\@tempdimb=\hoffset
	\advance\@tempdimb by\evensidemargin
	\advance\@tempdimb by\textwidth
	\advance\@tempdimb by\changebarsep
	\special{ln03:defpoint \the\@tempcnta(\the\@tempdimb,)}}

%
% \cb@setEndPoint#1
%
% Assigns position to point #1+1 and point #1+3.  Then does a connect
% special to join #1 and #1+1 or to join #1+2 and #1+3.  Assumes that
% width of bar is given in \@tempdima
%
\def\cb@setEndPoint#1{\@tempcnta=#1\advance\@tempcnta by1\cb@ig
	\@tempdimb=\hoffset
	\advance\@tempdimb by\oddsidemargin
	\advance\@tempdimb by -\changebarsep
	\special{ln03:defpoint \the\@tempcnta\space
	\space(\the\@tempdimb,)}\if@twoside\@tempcntb=#1
	\advance\@tempcntb by3\@tempdimb=\hoffset
	\advance\@tempdimb by\evensidemargin
	\advance\@tempdimb by\textwidth
	\advance\@tempdimb by\changebarsep
	\special{ln03:defpoint \the\@tempcntb\space
	\space(\the\@tempdimb,)}\cb@ig
	{\count9=#1\advance\count9 by2\cb@ig
	\special{ln03:connect \the#1/\the\count9\space\space
	\the\@tempcnta/\the\@tempcntb\space\space\the\@tempdima}}\else
	\special{ln03:connect \the#1 \the\@tempcnta\space\space
	\the\@tempdima}\fi}

%
% \cb@writeAux
%
% Writes the string
% \cb@barpoint{\cb@currentpoint}{\thepage}{\cb@tempdima} to the aux
% file.  Assumes that width of bar is in \@tempdima.
%
\def\cb@writeAux{\begingroup \edef\point{\the\cb@currentpoint}\cb@ig
	\edef\level{\the\@tempdima}\cb@ig
	\let\the=0\edef\cb@temp{\write\@auxout
	{\string\cb@barpoint{\point}{\the\cb@pagecount}{\level}}}\cb@ig
	\cb@temp\endgroup}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%	Macros for Making It Work Across Page Breaks
%


%
% \@makecol
%
% Modifies the LaTex macros to end the changebars spanning the current
% page (if any) and restart them on the next page.  Does the
% following: It resets special points for this page.  Adds begin bars
% to top of box255.  The bars to be begun are saved in \cb@beginSaves.
% Increments the changebar-internal page counter so that the value
% corresponds to the number of this page in strictly sequential order
% (the LaTeX page number can be reset).  Then it builds the list
% \cb@spanlist, then calls \cb@processActive to process the elements
% on the list, then it executes the original \@makecol.
%
\let\cb@makecol=\@makecol
\def\@makecol{\setbox255=\vbox{\special{ln03:resetpoints \cb@minpoint
        \space\cb@maxpoint}\cb@beginSaves\unvbox255}\cb@ig
	\gdef\cb@beginSaves{}\global\advance
	\cb@pagecount by 1\cb@buildActive
	\cb@processActive\cb@makecol}

%
% \cb@processActive
%
% Processes each element on span list.  Each element represents a bar
% that crosses the page break.  There could be more than one if bars are
% nested.  Works as folows:
%
%	pop top element of span list
%	if point null (i.e., list empty) then done
%	else
%	    do an end bar on box255
%	    save start for new bar at top of next page in \cb@startSaves
%	    push active point back onto history list (need to reprocess
%		on next page).
%
\def\cb@processActive{\cb@pop\cb@spanlist
	\ifnum\cb@currentpoint=\cb@nil \else
	\setbox255=\vbox{\unvbox255\cb@setEndPoint\cb@currentpoint}\cb@ig
	\cb@saveBeginPoint\cb@currentpoint \cb@push\cb@history
	\cb@processActive\fi}

%
% \cb@saveBeginPoint#1
%
% Saves a \special to begin a point in expanded macro \cb@beginSaves.
% This is then used to start all spanning bars at the top of the next
% page.  It is almost the same as \cb@setBeginPoint
%
\def\cb@saveBeginPoint#1{\@tempdimb=\hoffset
	\advance\@tempdimb by\oddsidemargin
	\advance\@tempdimb by -\changebarsep
	\xdef\cb@beginSaves{\special{ln03:defpoint \the#1(\the
	\@tempdimb,)}\cb@beginSaves}
	\@tempcnta#1\advance\@tempcnta by2\@tempdimb=\hoffset
	\advance\@tempdimb by\evensidemargin
	\advance\@tempdimb by\textwidth
	\advance\@tempdimb by\changebarsep
	\xdef\cb@beginSaves{\special{ln03:defpoint \the\@tempcnta(\the
	\@tempdimb,)}\cb@beginSaves}}

\def\cb@beginSaves{}                % initially empty




%
% \cb@buildActive
%
% Initializes the spanlist to null.  Pops top of history list.  If point
% is on future page, push back onto history list.  If point on current
% or previous page and odd, add point to span list; if even, pop span
% list since this bar has terminated on current page.
%
\def\cb@buildActive{\xdef\cb@spanlist{e}\cb@pushNextActive}

\def\cb@pushNextActive{\cb@pop\cb@history
	\ifnum\cb@currentpoint=\cb@nil \else
	\ifnum\cb@page>\cb@pagecount \cb@push\cb@history \else
	\ifodd\cb@currentpoint \cb@push\cb@spanlist
	\else \cb@pop\cb@spanlist\fi
	\cb@pushNextActive\fi\fi}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%	Macros For Managing The Lists of Bar points
%
% The macros make use of three lists corresponding to \special
% defpoints.  Each list takes the form
%	<element> . . . <element>e
%
% Each element is of the form xxxnyyypzzzl where xxx is the number of
% the special point, yyy is the page on which this point is set, and zzz
% is the dimension used when connecting this point.
%
% The list \cb@history is built from the log information and initially
% lists all the points.  As pages are processed, points are popped off
% the list and discarded.
%
% The list \cb@spanlist is a temporary list used by the output routine
% and contains the list of all bars crossing the current page (there may
% be more than one with nested bars).  It is built by popping elements
% off the history list.
%
% The list \cb@currentlist contains all the current bars.  A \cb@start
% pushes an element onto this list.  A \cb@end pops the top element off
% the list and uses the info to terminate the bar.
%

%
% \cb@pop#1		#1 is name of list (e.g., \cb@history)
%
% This pops the top element off the named list and puts the point value
% into \cb@currentpoint, the page value into \cb@page and the bar width
% into \@tempdima.  If the list is empty, returns a void value (\cb@nil)
% in \cb@currentpoint and sets \cb@page=0
%
\def\cb@pop#1{\if e#1\cb@currentpoint=\cb@nil\cb@page=0\else
	\expandafter\cb@carcdr#1#1\fi}

\def\cb@carcdr#1n#2p#3l#4e#5{\cb@currentpoint=#1\cb@page=#2\@tempdima=#3\cb@ig
	\xdef#5{#4e}}

%
% \cb@push#1
%
% Pushes \cb@currentpoint, \cb@page and \@tempdima onto the top of the
% named list
%
\def\cb@push#1{\xdef#1{\the\cb@currentpoint n\the\cb@page p\the\@tempdima l#1}}

%
% \cb@backpush#1#2#3
%
% Pushes #1 #2 and #3 onto the BACK of the history list.  #1 is the
% point value, #2 the page, and #3 the bar width.  This is used for
% initializing the history list from the data in tha .AUX file.
%
\def\cb@backpush#1#2#3{\expandafter\cb@append\cb@history#1n#2p#3l}
	\def\cb@append#1e#2n#3p#4l{\xdef\cb@history{#1#2n#3p#4le}}


\let\cb@barpoint=\cb@backpush	% all we do is push aux entries onto back
				% of history list


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%      Macros For Checking That The .AUX File Is Stable
%

%
% \document
%
% This is a replacement for the LaTeX \document macro.  The
% replacement makes a copy of the history list (which has just been
% built from the .AUX file) which is used to compare with the new .AUX
% file that will be created.  It also \lets
% \cb@barpoint=\cb@checkHistory to  prepare for checking the new .AUX
% file.
%
\let\cb@document=\document
\def\document{\cb@document\xdef\cb@prevHistory{\cb@history}\cb@ig
    \let\cb@barpoint=\cb@checkHistory}

%
% \cb@checkHistory
%
% Pops the top of the original history list (\cb@prevHistory) and
% check to see if the point and page numbers are the same as the
% arguements #1 and #2 respectively.  Prints a warning message if
% different. 
%
\def\cb@checkHistory#1#2#3{\cb@pop\cb@prevHistory
        \ifnum #1=\cb@currentpoint
	    \ifnum #2=\cb@page        % do nothing
	    \else \cb@error           % page numbers mismatched
	    \fi
	\else \cb@error               % point numbers mismatched
	\fi}

\def\cb@error{\message{Changebar Warning: Changebar info has changed. %
Rerun to get right.}\gdef\cb@checkHistory##1##2##3{}\let\cb@barpoint=\cb@checkHistory}




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%	Macros For Making It Work With Nested Floats/Footnotes
%		Works for LaTeX 2.09
%

%
% \end@float
%
% This is a replacement for the Latex macro of the same name.  All it
% does is check to see if changebars are active and, if so, it puts
% changebars around the box containing the float.  Then it calls the
% original LaTeX \end@float
%
\let\cb@endfloat=\end@float
\def\end@float{\cb@pop\cb@currentlist\ifnum\cb@currentpoint=\cb@nil
	\else \cb@push\cb@currentlist\global\@tempdima=\@tempdima \egroup \global\setbox
	\@currbox=\vbox{\cb@start\@tempdima\unvbox\@currbox\cb@end}\bgroup\fi
	\cb@endfloat}

\let\endfigure=\end@float	% need to rebind these to new def
\let\endtable=\end@float

%
% \@footnotetext#1
%
% Replacement for the LaTeX macro of the same name.  Simply checks to
% see if changebars are active and if so wraps the macro arguement
% (i.e., the footnote) in changebars.
%
\let\cb@footnote=\@footnotetext
\long\def\@footnotetext#1{\cb@pop\cb@currentlist\ifnum\cb@currentpoint=\cb@nil
	\cb@footnote{#1}\else \cb@push\cb@currentlist
	\edef\cb@temp{\the\@tempdima}\cb@ig
	\cb@footnote{\cb@start{\cb@temp}#1\cb@end}\fi}

%
% \@mpfootnotetext#1
%
% Replacement for the LaTeX macro of the same name.  Same thing as
% \@footnotetext.
%
\let\cb@mpfootnote=\@mpfootnotetext
\long\def\@mpfootnotetext#1{\cb@pop\cb@currentlist
        \ifnum\cb@currentpoint=\cb@nil
	\cb@mpfootnote{#1}\else \cb@push\cb@currentlist
	\edef\cb@temp{\the\@tempdima}\cb@ig
	\cb@mpfootnote{\cb@start{\cb@temp}#1\cb@end}\fi}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
