CTAN sync 202012180301

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