texlive[57161] Master/texmf-dist: pbalance (17dec20)
commits+karl at tug.org
commits+karl at tug.org
Thu Dec 17 23:17:53 CET 2020
Revision: 57161
http://tug.org/svn/texlive?view=revision&revision=57161
Author: karl
Date: 2020-12-17 23:17:53 +0100 (Thu, 17 Dec 2020)
Log Message:
-----------
pbalance (17dec20)
Modified Paths:
--------------
trunk/Master/texmf-dist/doc/latex/pbalance/README.md
trunk/Master/texmf-dist/doc/latex/pbalance/pbalance.pdf
trunk/Master/texmf-dist/source/latex/pbalance/pbalance.dtx
trunk/Master/texmf-dist/source/latex/pbalance/pbalance.ins
trunk/Master/texmf-dist/tex/latex/pbalance/pbalance.sty
Modified: trunk/Master/texmf-dist/doc/latex/pbalance/README.md
===================================================================
--- trunk/Master/texmf-dist/doc/latex/pbalance/README.md 2020-12-17 22:17:39 UTC (rev 57160)
+++ trunk/Master/texmf-dist/doc/latex/pbalance/README.md 2020-12-17 22:17:53 UTC (rev 57161)
@@ -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 at 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.
Modified: trunk/Master/texmf-dist/doc/latex/pbalance/pbalance.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/source/latex/pbalance/pbalance.dtx
===================================================================
--- trunk/Master/texmf-dist/source/latex/pbalance/pbalance.dtx 2020-12-17 22:17:39 UTC (rev 57160)
+++ trunk/Master/texmf-dist/source/latex/pbalance/pbalance.dtx 2020-12-17 22:17:53 UTC (rev 57161)
@@ -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}
%
Modified: trunk/Master/texmf-dist/source/latex/pbalance/pbalance.ins
===================================================================
--- trunk/Master/texmf-dist/source/latex/pbalance/pbalance.ins 2020-12-17 22:17:39 UTC (rev 57160)
+++ trunk/Master/texmf-dist/source/latex/pbalance/pbalance.ins 2020-12-17 22:17:53 UTC (rev 57161)
@@ -12,6 +12,7 @@
\input docstrip.tex
\keepsilent
+\askforoverwritefalse
\usedir{tex/latex/pbalance}
\preamble
Modified: trunk/Master/texmf-dist/tex/latex/pbalance/pbalance.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/pbalance/pbalance.sty 2020-12-17 22:17:39 UTC (rev 57160)
+++ trunk/Master/texmf-dist/tex/latex/pbalance/pbalance.sty 2020-12-17 22:17:53 UTC (rev 57161)
@@ -18,7 +18,7 @@
%% The Current Maintainer of this work is Nelson Lago <lago at ime.usp.br>.
%%
\NeedsTeXFormat{LaTeX2e}[2015/01/01]
-\ProvidesPackage{pbalance}[2020/12/03 v1.0 Poor man's balance]
+\ProvidesPackage{pbalance}[2020/12/16 v1.0.1 Poor man's balance]
\RequirePackage{etoolbox}
\RequirePackage{expl3}
More information about the tex-live-commits
mailing list.