% \iffalse THIS IS A META-COMMENT
%<*dtx>
\ProvidesFile
%========================================================================
{BALANCE.DTX}
%========================================================================
%</dtx>
%% Copyright 1993-1999 Patrick W Daly
%% Max-Planck-Institut f\"ur Aeronomie
%% Max-Planck-Str. 2
%% D-37191 Katlenburg-Lindau
%% Germany
%% E-mail: daly@linmpi.mpg.de
%
% This program can be redistributed and/or modified under the terms
% of the LaTeX Project Public License Distributed from CTAN
% archives in directory macros/latex/base/lppl.txt; either
% version 1 of the License, or any later version.
%
% This is a contributed file to the LaTeX2e system.
% -------------------------------------------------
% This is a LaTeX package to balance the last two columns in twocolumn mode.
% Installation:
% LaTeX this file: creates docstrip installation file balance.ins
% AND the (LaTeX2e) documentation
% (La)TeX balance.ins: creates package files balance.sty, and optionally
% documentation driver balance.drv
% (balance.ins may be edited as needed)
% Docstrip options available:
% package - to produce a (LaTeX2e) package .sty file
% driver - to produce a driver file to print the documentation
% 209 - (with package) for package that runs under LaTeX 2.09
% subpack - (with package) for coding included in other packages
%--------------------------------------------------------------------------
%<*!subpack>
%<package&209>\def\ProvidesPackage#1#2]
%<package&209> {\typeout{Style option `#1'#2]}}
%
% *** Identify the package file:-
%<package&!209>\NeedsTeXFormat{LaTeX2e}[1994/06/01]
%<package>\ProvidesPackage{balance}
%</!subpack>
%
% *** Provide command to dislay module version
%<package&subpack>\def\ModuleVersion#1[#2]{}
%<package&subpack> \ModuleVersion{balance}
%
% *** Identify the driver file:-
%<driver>\NeedsTeXFormat{LaTeX2e}
%<driver>\ProvidesFile{balance.drv}
%
% *** The DATE, VERSION, and other INFO
%\fi
%\ProvidesFile{balance}
[1999/02/23 4.3 (PWD)]
% \changes{4.0}{1993 Oct 10}{First release with \texttt{docstrip}}
% \changes{4.0}{1993 Oct 20}{Change so \cs{balance} makes redefinitions
% and does not just set flag}
% \changes{4.1}{1994 May 16}{Convert to \LaTeXe}
% \changes{4.1a}{1994 Jun 22}{Update to first official release of \LaTeXe}
% \changes{4.1b}{1995 Jan 2}{Update documentation to PWD standard}
% \changes{4.2}{1995 Nov 7}{Fix up \cmd{\cleardoublepage}}
% \changes{4.2a}{1997 Mar 16}{Fix copyright for subpackage and other minor
% things}
% \changes{4.2b}{1997 Apr 29}{Conform to new \texttt{docstrip}}
% \changes{4.3}{1999 Feb 23}{Update copyright notice}
%
% \CheckSum{168}
% \CharacterTable
% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
% Digits \0\1\2\3\4\5\6\7\8\9
% Exclamation \! Double quote \" Hash (number) \#
% Dollar \$ Percent \% Ampersand \&
% Acute accent \' Left paren \( Right paren \)
% Asterisk \* Plus \+ Comma \,
% Minus \- Point \. Solidus \/
% Colon \: Semicolon \; Less than \<
% Equals \= Greater than \> Question mark \?
% Commercial at \@ Left bracket \[ Backslash \\
% Right bracket \] Circumflex \^ Underscore \_
% Grave accent \` Left brace \{ Vertical bar \|
% Right brace \} Tilde \~}
% \iffalse
%<*install>
%^^A =============================================
%^^A Here is the docstrip installation file
%^^A It is written on first LaTeX run if it
%^^A does not already exist
%^^A =============================================
\begin{filecontents*}{balance.ins}
% File: balance.ins
% Copyright 1999 Patrick W. Daly
%
% This file can be redistributed and/or modified under the terms
% of the LaTeX Project Public License Distributed from CTAN
% archives in directory macros/latex/base/lppl.txt; either
% version 1 of the License, or any later version.
%
% It is an installation file for extracting package and driver
% files from the original source file. Simply process it under
% TeX or LaTeX.
\input docstrip
\preamble
=============================================
IMPORTANT NOTICE:
This program can be redistributed and/or modified under the terms
of the LaTeX Project Public License Distributed from CTAN
archives in directory macros/latex/base/lppl.txt; either
version 1 of the License, or any later version.
This is a generated file.
It may not be distributed without the original source file \inFileName.
Full documentation can be obtained by LaTeXing that original file.
Only a few abbreviated comments remain here to describe the usage.
=============================================
\endpreamble
\postamble
<<<<< End of generated file <<<<<<
\endpostamble
\declarepreamble\driver
============================================
This is the driver file to produce the LaTeX documentation
from the original source file \inFileName.
Make changes to it as needed. (Never change the file \inFileName!)
============================================
\endpreamble
\declarepostamble\driverq
End of documentation driver file.
\endpostamble
\keepsilent
\askforoverwritefalse
\generate{\file{balance.sty}{\from{balance.dtx}{package}}
\file{balance.drv}{\usepreamble\driver\usepostamble\driverq
\from{balance.dtx}{driver}}
}
\obeyspaces
\Msg{******************************************}%
\Msg{* For documentation, process balance.dtx *}%
\Msg{* or the driver file balance.drv *}%
\Msg{******************************************}
\endbatchfile
\end{filecontents*}
%</install>
%<*driver>
\documentclass{ltxdoc}
%<driver>%\documentclass[twoside]{ltxdoc}
%<driver>%\documentclass[a4paper]{ltxdoc}
%<driver>%\documentclass[twoside,a4paper]{ltxdoc}
\raggedbottom
%** To include the detailed explanation of the coding, comment out
%** the next line
\OnlyDescription
%** To produce a command index: add the following line for one run,
%** then run makeindex -s gind.ist natbib
%** and reprocess, with or without this line (much faster without)
%<driver>% \EnableCrossrefs\CodelineIndex
%** To produce a change history: add the following line for one run,
%** then run makeindex -s gglo.ist -o natbib.gls natbib.glo
%** and reprocess, with or without this line (faster without)
%<driver>% \RecordChanges
\DisableCrossrefs %May stay; zapped by \EnableCrossrefs
\CodelineNumbered %May stay
\begin{document}
\DocInput{balance.dtx}
\end{document}
%</driver>
% \fi
%
% \DoNotIndex{\begin,\CodelineIndex,\CodelineNumbered,\def,\DisableCrossrefs}
% \DoNotIndex{\DocInput,\documentclass,\EnableCrossrefs,\end,\GetFileInfo}
% \DoNotIndex{\NeedsTeXFormat,\OnlyDescription,\RecordChanges,\usepackage}
% \DoNotIndex{\ProvidesClass,\ProvidesPackage,\ProvidesFile,\RequirePackage}
% \DoNotIndex{\LoadClass,\PassOptionsToClass,\PassOptionsToPackage}
% \DoNotIndex{\DeclareOption,\CurrentOption,\ProcessOptions,\ExecuteOptions}
% \DoNotIndex{\AtEndOfClass,\AtEndOfPackage,\AtBeginDocument,\AtEndDocument}
% \DoNotIndex{\InputIfFileExists,\IfFileExists,\ClassError,\PackageError}
% \DoNotIndex{\ClassWarning,\PackageWarning,\ClassWarningNoLine}
% \DoNotIndex{\PackageWarningNoLine,\ClassInfo,\PackageInfo,\MessageBreak}
% \DoNotIndex{\space,\protect,\DeclareRobustCommand,\CheckCommand}
% \DoNotIndex{\newcommand,\renewcommand,\providecommand\newenvironment}
% \DoNotIndex{\renewenvironment,\newif,\newlength,\newcounter,\setlength}
% \DoNotIndex{\setcounter,\if,\ifx,\ifcase,\ifnum,\ifdim,\else,\fi}
% \DoNotIndex{\texttt,\textbf,\textrm,\textsl,\textsc}
% \DoNotIndex{\textup,\textit,\textmd,\textsf,\emph}
% \DoNotIndex{\ttfamily,\rmfamily,\sffamily,\mdseries,\bfseries,\upshape}
% \DoNotIndex{\slshape,\scshape,\itshape,\em,\LaTeX,\LaTeXe}
% \DoNotIndex{\filename,\fileversion,\filedate,\let}
% \DoNotIndex{\@@warning,\@M,\@colht,\@combinedblfloats,\@dblfloatplacement}
% \DoNotIndex{\@firstcolumnfalse,\@firstcolumntrue,\@leftcolumn,\@outputbox}
% \DoNotIndex{\@outputdblcol,\@outputpage,\@startdblcolumn,\@tempdima}
% \DoNotIndex{\@whilesw,\advance,\baselineskip,\begingroup,\box,\columnseprule}
% \DoNotIndex{\columnwidth,\copy,\dimen,\divide,\dp,\else,\endgroup,\fi}
% \DoNotIndex{\global,\hbox,\hfil,\hss,\ht,\if@fcolmade,\if@firstcolumn}
% \DoNotIndex{\if@twocolumn,\ifdim,\kern,\loop,\multiply,\newdimen}
% \DoNotIndex{\outputpenalty,\penalty,\repeat,\setbox,\splittopskip}
% \DoNotIndex{\string,\textwidth,\topskip,\unvbox,\vbadness,\vbox}
% \DoNotIndex{\vfil,\vrule,\vsplit}
%
% \setcounter{IndexColumns}{2}
% \setlength{\IndexMin}{10cm}
% \setcounter{StandardModuleDepth}{1}
%
% \GetFileInfo{balance}
%
% \title{\bfseries Balancing the Two Columns of Text on the Last Page}
%
% \author{Patrick W. Daly}
%
% \date{This paper describes package \texttt{\filename}\\
% version \fileversion{} from \filedate\\[1ex]
% \textsl{It is part of the \texttt{preprint} collection of packages}
% }
%
% \maketitle
%
% \pagestyle{myheadings}
% \markboth{P. W. Daly}{BALANCING TWO COLUMN TEXT}
%
%^^A In order to keep all marginal notes on the one (left) side:
%^^A (otherwise they switch sides disasterously with twoside option)
% \makeatletter \@mparswitchfalse \makeatother
%
%\begin{small}\begin{center}\textbf{Summary}\end{center}
% The stripped version of this file contains the following brief description:
%\iffalse
%<*package&!subpack>
%\fi
% \begin{verbatim}
% In order to balance the columns on a page, \balance must be given
% somewhere within the first column. To turn off the feature, give
% \nobalance. One has to look at the unbalanced text first to decide
% where best to place \balance.
% \end{verbatim}
%\iffalse
%-----------------------------------------------------------
%</package&!subpack>
%\fi
%\end{small}
%
% \section{Introduction}
% When a \LaTeX{} document is to be set in two-column mode, one can
% add |twocolumn| as an option to |\documentstyle| (\LaTeX~2.09)
% or to |\documentclass| (\LaTeXe), or one can use the
% |\twocolumn| command in the text. In either case, the columns on the last
% page, or those before a |\cleardoublepage| command, will be of unequal
% height. This is because \LaTeX{} views the columns as pages which are
% just output as pairs, and it no longer knows about the left-hand column
% when a short right-hand one is finished.
%
% The macros in this package solve this problem by modifying the output
% routines in two-column mode.
%
% \section{Invoking the Package}
% The macros in this package are included in the main document
% with the |\usepackage| command of \LaTeXe,
% \begin{quote}
% |\documentclass[..,twocolumn,..]{...}|\\
% |\usepackage{|\texttt{\filename}|}|
% \end{quote}
% There are no \LaTeXe{} options for this package.
%
% Alternatively, the name of the package is added as an option to the
% |\documentstyle| command in \LaTeX~2.09 compatibility mode, as
% \begin{quote}
% |\documentstyle[..,twocolumn,|\texttt{\filename}|..]{...}|
% \end{quote}
%
% \section{Usage}
% Including the \texttt{\filename} package as shown above does not activate it
% immediately. There are a number of reasons for this.
% \begin{enumerate}
% \item It could be that a newer (or much older) version of \LaTeX{} is
% being used for which the modified |\output| routines are
% incompatible; in this case, the new routines must be left inactive.
%
% \item Sometimes the modified output routine does not work well for normal
% pages, especially with floats (figures and tables) or footnotes.
%
% \end{enumerate}
% For these reasons, it is thought better to have the modified output
% routines left inactive, and to turn them on only when needed.
% \DescribeMacro{\balance}
% This is done with the command |\balance|, which should be issued
% somewhere in the text of what would be the first column of the last page
% without balanced columns. If it is issued too late, i.e., in the second
% column, then a warning message is printed that balancing may not take
% place.
%
% \DescribeMacro{\nobalance}
% To turn off the balancing routines, call |\nobalance|. This might be
% useful where there are many `last' pages, say at the end of book
% chapters. The |\balance| command should be given for each page that
% needs balancing, and then turned off at the end of the second column.
%
% It might well be that |\balance| can be left on all the time, but one
% should check the output carefully, and turn it off if need be.
%
% \section{An Alternative}
% Making multicolumn text with Mittelbach's {\tt multicol} package is
% perhaps a better method. It balances automatically, and allows more than
% just two columns. Never use \texttt{\filename} together with {\tt multicol}!
%
% \StopEventually{\PrintIndex\PrintChanges}
%
% \section{Options with \texttt{docstrip}}
% The source \texttt{.dtx} file is meant to be processed with
% \texttt{docstrip}, for which a number of options are available:
% \begin{description}
% \item[\tt package] to produce a \texttt{.sty} package file with most
% comments removed;
% \item[\tt 209] for a package file that will also run under the older
% \LaTeX~2.09 and not just under the newer (mid-1994) \LaTeXe;
% \item[\tt subpack] (together with \texttt{package}) for coding that is to
% be included inside a larger package; even more comments are removed,
% as well as \LaTeXe{} option handling and identification;
% \item[\tt driver] to produce a driver \texttt{.drv} file that will print
% out the documentation under \LaTeXe; with the \texttt{209} option,
% a driver \texttt{.209} file is also produced, for printing the
% documentation under \LaTeX~2.09.
% \end{description}
% The source file \texttt{\filename.dtx} is itself a driver file and can
% be processed directly by \LaTeXe.
%
% \section{The Coding}
% This section presents and explains the actual coding of the macros.
% It is nested between |%<*package>| and |%</package>|, which
% are indicators to \texttt{docstrip} that this coding belongs to the package
% file.
%
% The \texttt{docstrip} option |<subpack>| should only be called if the
% coding is to be included as part of another package, in which case the
% announcement text and \LaTeXe{} options are suppressed.
%
% An inferior version of this coding is provided for running as a
% style file under \LaTeX~2.09. Code lines belonging to this are
% indicated with guard |<209>|; those for LaTeXe{} only with |<!209>|.
%
% \subsection{Altering the Standard {\tt\bslash output} Routines}
% The column balancing procedure here involves making changes to the
% standard output routines in \LaTeX. I normally do not like assuming
% anything from {\tt latex.tex} because it may have been different in
% earlier versions, and may change again. There I try as much as possible
% to save current definitions of internal macros and then simply add
% revisions.
%
% In this case, that is not possible. I have had to take the routine
% |\@outputdblcol| from \LaTeX{} version 2.09, (1992 March~25) as basis.
% However, I notice that they have not changed for many versions, so that
% maybe there is some stability here.
%
% The newer \LaTeXe{} version (1994 Dec.~01) also has the same definition
% of |\@outputdblcol|, so there should be no problems of compatibility
% here.
%
% In earlier versions of \texttt{\filename}, |\@outputdblcol| was changed
% such that
% a flag would activate the new coding if set, otherwise the old coding
% took place. This assumes that the `old' coding is known, because I give
% it explicitly in the new definition. This is where problems could arise
% if |\@outputdblcol| is ever changed.
%
% I now do this differently. The old definition of |\@outputdblcol| is
% stored (without knowing what it is), and the |\balance| command redefines
% it. Without giving |\balance|, one has the default output routines as
% though \texttt{\filename} were never selected. This gives the user the
% chance to turn everything off if any problems should arise.
%
% Since the balancing act does not always work for normal pages (where the
% two columns are full) especially when floats are involved, it is better
% to turn it on with |\balance| only where it is needed. It may then be
% turned off again with |\nobalance|.
%
% \subsection{The Principle Behind Balancing Columns}
% Let me first explain how |\@outputdblcol| normally works. By the time it
% is called, the accumulated text for the `page' (\TeX{} considers each
% column to be a page at this point) is contained in the box |\@outputbox|.
% The routine checks if this is the first column, and if so stuffs
% |\@outputbox| into the box |\@leftcolumn|; it then toggles the
% |\if@firstcolumn| flag. On the next call to |\@outputdblcol|, it combines
% |\@leftcolumn| with |\@outputbox| side by side on a single page, all
% stored in |\@outputbox|.
%
% For column balancing, the procedure is slightly different. If it is the
% first column, then the height of the column (|\@colht| = |\textheight|
% minus double-column floats and footnotes) is doubled and the contents of
% |\@outputbox| are dumped back into the processing. The height must be
% doubled temporarily to allow this, otherwise the |\output| routines will
% be immediately called again. On the second column, the new routine
% |\@BAlancecol| is called to split |\@outputbox| into two equally high
% pieces of text, stored in |\@leftcolumn| and |\@outputbox|, which are
% then placed side by side as usual.
%
% \subsection{Macro Definitions}
% \begin{macro}{\@BAlancecol}
% \changes{4.0}{1993 Nov 1}{Add \cmd{\vfil} after
% \cmd{\unvbox1} to prevent underfull vbox}
% \changes{4.1}{1994 May 16}{New name for \cmd{\@balancecol}, to conform
% more with newer conventions for package programming.}
% \changes{4.1a}{1994 Jun 22}{Use \cmd{\newcommand} instead of \cmd{\def}}
% We begin by defining |\@BAlancecol|, the routine that splits
% |\@outputbox| into two nearly equally high boxes, which are then stored
% in boxes |\@leftcolumn| and |\@outputbox|. This routine is almost
% identical with that of Knuth in the \TeX{}Book (macro |\balancecolumns|
% on page~417). The loop keeps going until the first column is less than
% the second in height, making 1~pt changes in the specification each time.
% \begin{macrocode}
%<*package>
\newcommand{\@BAlancecol}{\if@twocolumn
\setbox0=\vbox{\unvbox\@outputbox} \@tempdima=\ht0
\advance\@tempdima by \topskip \advance\@tempdima
by -\baselineskip \divide\@tempdima by 2
\splittopskip=\topskip
{\vbadness=\@M \loop \global\setbox3=\copy0
\global\setbox1=\vsplit3 to \@tempdima
\ifdim\ht3>\@tempdima \global\advance\@tempdima by 1pt \repeat}
\setbox\@leftcolumn=\vbox to \@tempdima{\unvbox1\vfil}
\setbox\@outputbox=\vbox to \@tempdima
{\dimen2=\dp3\unvbox3\kern-\dimen2
\vfil}
\fi}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@BAdblcol}
% \changes{4.1}{1994 May 16}{New name for \cmd{\@baldblcol}, to conform
% more with newer conventions for package programming.}
% \changes{4.1a}{1994 Jun 22}{Use \cmd{\newcommand} instead of \cmd{\def}}
% \changes{4.1a}{1994 Jun 22}{Use \cmd{\PackageWarningNoLine} instead of
% \cmd{\@@warning}}
% Now define the revised routine |\@outputdblcol|, and name it
% |\@BAdblcol|. In the first column, it just puts |\@outputbox| back into
% the processing with a doubled column height (|\@colht|). In the second
% column, it calls |\@BAlancecol| and the places the boxes |\@leftcolumn|
% and |\@outputbox| side by side in almost the same way that the original
% |\@outputdblcol| does. The difference is that the final vbox is made to
% be |\@colht| high and a |\vfil| must be added below to fill up the
% missing space. In the original, the column boxes themselves are |\@colht|
% high, so this is not necessary. If this feature were left off, then the
% final box would not have the correct height, something that is noticeable
% when a footline is added at the bottom.
% \begin{macrocode}
\newif\if@BAlanceone
\global\@BAlanceonefalse
\newdimen\oldvsize
\newcommand{\@BAdblcol}{\if@firstcolumn
\unvbox\@outputbox \penalty\outputpenalty
\global\oldvsize=\@colht \global\multiply \@colht by 2
\global\@BAlanceonetrue
\global\@firstcolumnfalse
\else \global\@firstcolumntrue
\if@BAlanceone
\global\@BAlanceonefalse\@BAlancecol
\global\@colht=\oldvsize \else
%<!209> \PackageWarningNoLine{balance}
%<209> \@@warning
{You have called \protect\balance\space
%<!209> in second column\MessageBreak
%<209> in second column^^J
Columns might not be balanced}\fi
\setbox\@outputbox\vbox to \@colht{\hbox to\textwidth
{\hbox to\columnwidth {\box\@leftcolumn \hss}\hfil
\vrule width\columnseprule\hfil \hbox to\columnwidth
{\box\@outputbox \hss}}\vfil}\@combinedblfloats
\@outputpage \begingroup \@dblfloatplacement
\@startdblcolumn \@whilesw\if@fcolmade \fi
{\@outputpage\@startdblcolumn}\endgroup
\fi}
% \end{macrocode}
% The flag |\if@BAlanceone| seems redundant, since it is always the
% complement of |\if@firstcolumn|. However, its function is to ensure that
% the |\balance| command, that activates |\@BAdblcol|, actually occurs
% before the first column of text is completed. If this is not the case, if
% |\balance| is issued too late, then the procedure cannot function. In
% this case, |\@BAdblcol| is entered with both |\if@firstcolumn| and
% |\if@BAlanceone| set \meta{false}, so that the call to |\@BAlancecol| is
% suppressed and warning message is printed.
% \end{macro}
%
% \begin{macro}{\cleardoublepage}
% \changes{4.2}{1995 Nov 07}{Add revised definition for balanced mode}
% A new version of |\cleardoublepage| is necessary when |\balance| is
% active. The regular command adds two |\newpage| commands on an even page
% in two column mode, since each |\newpage| only starts a new column.
% However, when |\balance| is active, each |\newpage| makes two balanced
% columns, to it actually starts a new page, and not just a new column.
% \begin{macrocode}
\newcommand{\@BAcleardblpage}{\clearpage\if@twoside \ifodd\c@page\else
\hbox{}\newpage\fi\fi}
\newcommand{\@@cleardblpage}{}
\let\@@cleardblpage=\cleardoublepage
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\balance}
% \changes{4.0}{1993 Oct 20}{Change from setting flag to redefining output
% routine.}
% \changes{4.1a}{1994 Jun 22}{Use \cmd{\newcommand} instead of \cmd{\def}}
% \changes{4.2}{1995 Nov 07}{Add revised \cmd{\cleardoublepage}}
% The command that activates the balancing replaces |\@outputdblcol|
% with the new |\@BAdblcol|.
% \begin{macrocode}
\newcommand{\@@utputdblcol}{}
\let\@@utputdblcol=\@outputdblcol
\newcommand{\balance}{\global\let\@outputdblcol=\@BAdblcol
\global\let\cleardoublepage=\@BAcleardblpage}
% \end{macrocode}
% \end{macro}
% \begin{macro}{\nobalance}
% \changes{4.0}{1993 Oct 20}{Change from setting flag to restoring
% original output routine.}
% \changes{4.1a}{1994 Jun 22}{Use \cmd{\newcommand} instead of \cmd{\def}}
% \changes{4.2}{1995 Nov 07}{Add revised \cmd{\cleardoublepage}}
% To turn off the balancing routine, call |\nobalance|.
% \begin{macrocode}
\newcommand{\nobalance}{\global\let\@outputdblcol=\@@utputdblcol
\global\let\cleardoublepage=\@@cleardblpage}
%</package>
% \end{macrocode}
% \end{macro}
%
% \Finale