summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/pbalance
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2020-12-18 03:01:03 +0000
committerNorbert Preining <norbert@preining.info>2020-12-18 03:01:03 +0000
commit95242c8a1bf6073dc44ee74ca09e791c05bccbc0 (patch)
tree7d67657668c6dc8ba36015a943018971f4a6d3fc /macros/latex/contrib/pbalance
parent69b64e1de8e6fdcce00047e99369a1ea498a99dd (diff)
CTAN sync 202012180301
Diffstat (limited to 'macros/latex/contrib/pbalance')
-rw-r--r--macros/latex/contrib/pbalance/README.md14
-rw-r--r--macros/latex/contrib/pbalance/pbalance.dtx94
-rw-r--r--macros/latex/contrib/pbalance/pbalance.ins1
-rw-r--r--macros/latex/contrib/pbalance/pbalance.pdfbin307144 -> 240071 bytes
4 files changed, 76 insertions, 33 deletions
diff --git a/macros/latex/contrib/pbalance/README.md b/macros/latex/contrib/pbalance/README.md
index 6ac43ea0c8..a26f9b2a5e 100644
--- a/macros/latex/contrib/pbalance/README.md
+++ b/macros/latex/contrib/pbalance/README.md
@@ -3,12 +3,18 @@
This is a LaTeX package that tries to *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:
+class authors, but also offers the user a command to adjust the height of
+the columns. There are, however, three caveats:
1. Results are adequate, but often not optimal;
-2. In some cases, the package may give up (the document is
- generated correctly but the last page is not balanced);
+2. In some very rare cases, the package may give up (the document
+ is generated correctly but the last page is not balanced);
3. The package demands additional LaTeX passes.
Code etc: <https://gitlab.com/lago/pbalance>
+
+Copyright 2020 Nelson Lago <lago@ime.usp.br>
+
+This work may be distributed and/or modified under the conditions of the
+LaTeX Project Public License, either version 1.3 of this license or (at
+your option) any later version.
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}
%
diff --git a/macros/latex/contrib/pbalance/pbalance.ins b/macros/latex/contrib/pbalance/pbalance.ins
index 2e7d2a2db8..bb6356b0bf 100644
--- a/macros/latex/contrib/pbalance/pbalance.ins
+++ b/macros/latex/contrib/pbalance/pbalance.ins
@@ -12,6 +12,7 @@
\input docstrip.tex
\keepsilent
+\askforoverwritefalse
\usedir{tex/latex/pbalance}
\preamble
diff --git a/macros/latex/contrib/pbalance/pbalance.pdf b/macros/latex/contrib/pbalance/pbalance.pdf
index 319570a8dd..a3a0beccd6 100644
--- a/macros/latex/contrib/pbalance/pbalance.pdf
+++ b/macros/latex/contrib/pbalance/pbalance.pdf
Binary files differ