summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/pbalance/pbalance.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/pbalance/pbalance.dtx')
-rw-r--r--macros/latex/contrib/pbalance/pbalance.dtx94
1 files changed, 65 insertions, 29 deletions
diff --git a/macros/latex/contrib/pbalance/pbalance.dtx b/macros/latex/contrib/pbalance/pbalance.dtx
index e63bee62a9..63876d5293 100644
--- a/macros/latex/contrib/pbalance/pbalance.dtx
+++ b/macros/latex/contrib/pbalance/pbalance.dtx
@@ -15,7 +15,7 @@
% \iffalse
%
%<package>\NeedsTeXFormat{LaTeX2e}[2015/01/01]
-%<package>\ProvidesPackage{pbalance}[2020/12/03 v1.0 Poor man's balance]
+%<package>\ProvidesPackage{pbalance}[2020/12/16 v1.0.1 Poor man's balance]
%
%<*driver>
@@ -50,9 +50,9 @@
%%\EnableCrossrefs
%%\CodelineIndex
-%%\RecordChanges
+\RecordChanges
-%%\OnlyDescription
+\OnlyDescription
\begin{document}
\DocInput{pbalance.dtx}
@@ -65,6 +65,7 @@
% \CheckSum{0}
%
% \changes{v1.0}{2020/09/14}{Initial version}
+% \changes{v1.0.1}{2020/12/16}{Improvements to documentation}
%
% \GetFileInfo{pbalance.sty}
%
@@ -85,19 +86,19 @@
% This package tries to \emph{safely} make the columns on the last page
% of a two-column document have approximately the same height. It should
% ``just work'' without user intervention, which is particularly useful
-% for class authors, but also offers the user a command to control the
-% result. There are, however, three caveats:
+% for class authors, but also offers the user a command to adjust the
+% height of the columns. There are, however, three caveats:
%
% \begin{enumerate}
% \item Results are adequate, but often not optimal;
-% \item In some cases, the package may give up (the document is
-% generated correctly but the last page is not balanced);
+% \item In some very rare cases, the package may give up (the document
+% is generated correctly but the last page is not balanced);
% \item The package demands additional \LaTeX{} passes.
% \end{enumerate}
%
% \end{abstract}
%
-% \section{Introduction and usage}
+% \section{Introduction}
%
% First things first: this package is a \textbf{hack}. It is also
% \textbf{beta} quality. However, I believe it is \emph{safe},
@@ -119,10 +120,15 @@
% and, in fact, striving to make columns exactly the same height with it
% may sometimes yield poor results, so we do not even try).
%
+% \section{Usage}
+%
% To use the package, add \verb|\usepackage{pbalance}| to the preamble
% and things should ``just work''. However, the document will take more
% \LaTeX{} passes to compile, and minute changes to it that would normally
-% need one additional \LaTeX{} pass will likely need three.
+% need one additional \LaTeX{} pass will likely demand three. If you load
+% the package with the \verb|draft| option (or pass the \verb|draft|
+% option to the document class), balancing is disabled, alleviating the
+% need for extra passes during document preparation.
%
% If the last page does not have floats, footnotes, or marginpars, the
% package simply uses \verb|\balance|, from the \texttt{balance} package;
@@ -132,6 +138,33 @@
% not eliminate the need for extra passes (the package needs to find out
% which page is the last).
%
+% If there are many floats near the end of the document, the \LaTeX{}
+% float placement parameters (\verb|\topfraction|, \verb|topnumber|,
+% etc.) may interfere negatively with the algorithm. In some rare
+% cases\footnote{For example, imagine a document in which page 5 is
+% a float page that happens to be the last one. We will balance page
+% 4, which is the last text page. Balancing page 4 may move a float
+% from the left to the right column, but this may in turn exceed the
+% maximum number of floats in the right column. As a result, one or
+% more floats may be deferred to page 5. At the same time, a float of
+% a different kind from page 5 may be pulled back to the extra space
+% that just opened up in page 4. Depending on the size of this float,
+% the text may no longer fit in page 4, making some text spill onto
+% page 5. This means page 5 is now the last text page and should then
+% be balanced instead of page 4. Oops!}, this may force the package
+% to give up on balancing (the document is still generated correctly
+% in this case). To minimize the chances of this outcome, it is
+% probably a good idea to make the parameters a little more liberal
+% than the default, for example:
+%
+% \begin{verbatim}
+%\setcounter{totalnumber}{5} % default 3
+%\setcounter{topnumber}{3} % default 2
+%\renewcommand{\topfraction}{.85} % default .7
+%\renewcommand{\textfraction}{.15} % default .2
+%\renewcommand{\floatpagefraction}{.75} % default .5, must be < \topfraction
+% \end{verbatim}
+%
% \section{How does it work}
%
% This package works on two fronts:
@@ -149,26 +182,29 @@
%
% \end{enumerate}
%
-% If measurements change between passes, this means the document was
-% edited, so we forget the previously gathered data and start over.
-% However, the package cannot detect changes that happen between the
-% ``collect data'' pass and the ``balance for the first time'' pass:
-% it has to assume that any change at this point is caused by the fact
-% that we started balancing (it can, however, detect if the last text
-% page changed; if this happens, we give up balancing). If the change is
-% small, that is acceptable: we are not aiming at balancing perfectly
-% anyway. If it is a big change (for example, the addition of the
-% bibliography block), results will suffer.
+% If measurements change between passes, either the document was edited
+% or \LaTeX{} is still adding crossrefs, citations, etc. In both cases,
+% the previously gathered data is bogus, so we start over. However, the
+% package cannot detect changes that happen between the ``collect data''
+% pass and the ``balance for the first time'' pass: it has to assume
+% that any change at this point is caused by the fact that we started
+% balancing (it can, however, detect whether the last text page changed;
+% if this happens, we give up balancing). If a small change (such as an
+% updated crossref adding or removing a line somewhere) slips through,
+% that is acceptable: we are not aiming at balancing perfectly anyway.
+% However, if the change is big (for example, the addition of the
+% bibliography block after running bibtex/biber), results will suffer.
%
% To prevent this, it would be ideal to only start the process after all
% passes needed to stabilize the document have run. In practice, however,
-% this would be too hard to detect. What we do instead is simply wait for
-% two consecutive passes to result in columns of the same size in the
-% last page. When this happens, we proceed to balance in the next pass
-% and assume (quite reasonably) that, as long as the document is not
-% modified, the effect of further passes in the last page is small, so
-% ignoring it disturbs the balancing only slightly\footnote{Like I said
-% on the introduction: this package is a hack.}.
+% this would be too hard to detect (and demand even more passes). What
+% we do instead is simply wait for two consecutive passes to result
+% in columns of the same size in the last page. When this happens, we
+% proceed to balance in the next pass and assume (quite reasonably) that,
+% as long as the document is not modified, the effect of concurrent
+% changes during that pass in the last page is small, so ignoring it
+% disturbs the balancing only slightly\footnote{Like I said on the
+% introduction: this package is a hack.}.
%
% \section{TODO / wish list}
%
@@ -183,8 +219,8 @@
% floats and (2) completely disable the balance package;
%
% \item make the mechanism able to work with any page, not just the last,
-% and with more than one page at once. This is useful for book
-% chapters, for example;
+% and with more than one page at once. This is useful for the last
+% page of each chapter of a two-column book, for example;
%
% \item on top of that:
% \begin{enumerate}
@@ -196,7 +232,7 @@
%
% \end{itemize}
%
-% \StopEventually{}
+% \StopEventually{\PrintChanges}
%
% \section{The implementation}
%