summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/pbalance/pbalance.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2021-05-07 03:01:25 +0000
committerNorbert Preining <norbert@preining.info>2021-05-07 03:01:25 +0000
commitc92d9953347e3bdebc5243c67cf012a2f7a60fb6 (patch)
tree808a0ad402713257a48445f97e662786d95207ee /macros/latex/contrib/pbalance/pbalance.dtx
parent25f20b6d8ccd4edcdfec23c1a3c908516076ee06 (diff)
CTAN sync 202105070301
Diffstat (limited to 'macros/latex/contrib/pbalance/pbalance.dtx')
-rw-r--r--macros/latex/contrib/pbalance/pbalance.dtx180
1 files changed, 101 insertions, 79 deletions
diff --git a/macros/latex/contrib/pbalance/pbalance.dtx b/macros/latex/contrib/pbalance/pbalance.dtx
index 63876d5293..ea00526085 100644
--- a/macros/latex/contrib/pbalance/pbalance.dtx
+++ b/macros/latex/contrib/pbalance/pbalance.dtx
@@ -1,8 +1,8 @@
% \iffalse meta-comment
-% Copyright 2020 Nelson Lago <lago@ime.usp.br>
+% Copyright 2020-2021 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
+% LaTeX Project Public License, either version 1.3c of this license or (at
% your option) any later version. The latest version of this license can be
% found at http://www.latex-project.org/lppl.txt and version 1.3 or later
% is part of all distributions of LaTeX version 2005/12/01 or later.
@@ -15,7 +15,7 @@
% \iffalse
%
%<package>\NeedsTeXFormat{LaTeX2e}[2015/01/01]
-%<package>\ProvidesPackage{pbalance}[2020/12/16 v1.0.1 Poor man's balance]
+%<package>\ProvidesPackage{pbalance}[2021/04/26 v1.1.0 Poor man's balance]
%
%<*driver>
@@ -26,24 +26,15 @@
\urlstyle{sf}
\usepackage{hyperref}
\hypersetup{
- pdfborder={0 0 .6},
- pdfborderstyle={/S/U/W .6},
- urlbordercolor=DodgerBlue,
- citebordercolor=White,
- linkbordercolor=White,
- filebordercolor=White,
+ colorlinks=true,
+ citecolor=DarkGreen,
+ linkcolor=NavyBlue,
+ urlcolor=DarkRed,
+ filecolor=green,
+ anchorcolor=black,
}
\usepackage[draft]{pbalance}
-\makeatletter
-\dimgdef\@PBtmpHeight{0pt}
-\dimgdef\@PBtmpLeftHeight{0pt}
-\dimgdef\@PBtmpLeftFloatsHeight{0pt}
-\dimgdef\@PBtmpRightHeight{0pt}
-\dimgdef\@PBtmpRightFloatsHeight{0pt}
-\dimgdef\@PBtmpUsedLeft{0pt}
-\dimgdef\@PBtmpUsedRight{0pt}
-\makeatother
\usepackage{libertinus}
\usepackage[scale=.85]{sourcecodepro}
@@ -66,6 +57,7 @@
%
% \changes{v1.0}{2020/09/14}{Initial version}
% \changes{v1.0.1}{2020/12/16}{Improvements to documentation}
+% \changes{v1.1.0}{2021/04/26}{Do not crash in one-column mode}
%
% \GetFileInfo{pbalance.sty}
%
@@ -131,13 +123,21 @@
% 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;
+% package simply uses \verb|\balance|, from the \texttt{balance} package,
% otherwise it uses its own algorithm. You may instead use
% \verb|\shrinkLastPage{some-measurement}| to manually define how much
% shorter the first column of the last page should be. This, however, will
% not eliminate the need for extra passes (the package needs to find out
% which page is the last).
%
+% The package actually balances the last \emph{text} page; if the last
+% page is a float page, it is ignored. It also \emph{should} work if you
+% switch to single-column mode mid-document (with \verb|\onecolumn|); it
+% will then balance the last two-column text page. The same should happen
+% in a document that is mainly typeset in one column and you switch to
+% two-column layout (with \verb|\twocolumn|), but \emph{only} if the page
+% to be balanced does \emph{not} contain the \verb|\twocolumn| command.
+%
% 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
@@ -171,12 +171,13 @@
%
% \begin{enumerate}
%
-% \item It uses a \LaTeX{} pass to gather information: which is the last page?
-% Does it have floats? Footnotes? How much free space in each column?
+% \item It uses a \LaTeX{} pass to gather information: which is the last
+% two-column text page? Does it have floats? Footnotes? How much
+% free space in each column?
%
-% \item It uses this information in a subsequent pass to balance the last
+% \item It uses this information in a subsequent pass to balance that
% page. If there are no floats or footnotes, it uses the balance
-% package; otherwise it uses the measurements collected to shrink
+% package, otherwise it uses the measurements collected to shrink
% the first column (using \verb|\enlargethispage|) by a
% ``reasonable'' amount.
%
@@ -198,10 +199,10 @@
% 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 (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
+% we do instead is simply wait for two consecutive passes to result in
+% columns of the same size in the last two-column 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.}.
@@ -212,9 +213,6 @@
%
% \begin{itemize}
%
-% \item add \verb|\if@twocolumn| tests to prevent crashes and
-% other problems;
-%
% \item add options to (1) allow using the balance package on pages with
% floats and (2) completely disable the balance package;
%
@@ -237,11 +235,12 @@
% \section{The implementation}
%
% We define \verb|\@PBlastPage| using \texttt{zref-abspage}; It is the page
-% number for the last page of text. This might \emph{not} be the last page
-% of the document: there may be one or more float pages after it. Still,
-% it \emph{is} the page we want to balance. We do not act on it, however;
-% instead, we save its value to the aux file as \verb|\@PBprevLastPage| and
-% proceed to balance on the next \LaTeX{} pass.
+% number for the last two-column page of text. This might \emph{not} be the
+% last page of the document: there may be one or more float pages after it
+% or the user may have issued \verb|\onecolumn|. Still, it \emph{is} the page
+% we want to balance. We do not act on it, however; instead, we save its value
+% to the aux file as \verb|\@PBprevLastPage| and proceed to balance on the next
+% \LaTeX{} pass.
%
% We also define two toggles:
%
@@ -320,7 +319,7 @@
{#2}
{
% abspage refers to the finished page, not the nascent page
- \ifnumcomp{\@PBprevLastPage - 1}{=}{\value{abspage}}
+ \ifnumcomp{\@PBprevLastPage - 1}{=}{\value{abspage}}
{#1}
{#2}
}
@@ -429,10 +428,10 @@
% For the mechanism above to work, we need to know:
%
% \begin{enumerate}
-% \item The page number of the last page;
-% \item Whether the last page has floats, footnotes etc.;
-% \item The available height in the last page;
-% \item The height of the columns in the last page.
+% \item The page number of the last two-column text page;
+% \item Whether it has floats, footnotes etc.;
+% \item The available height in it;
+% \item The height of the columns in it.
% \end{enumerate}
%
% Let's collect this info for every page.
@@ -601,25 +600,30 @@
\ExplSyntaxOn
\AtBeginShipout{
- \ifboolexpr
- {
- % A float page is not the last text page, ignore
- togl {@PBtmpIsFloatPage}
- or
- % A page with a float column on the left and an empty
- % column on the right is not the last text page, ignore
- (
- togl {@PBtmpHasFloatcol}
- and
- test {\ifdimcomp{\@PBtmpUsedRight}{=}{\topskip}}
- )
- }
- {}
- {
- % This page is a candidate to be the last page
- \xdef\@PBlastPage{\the\value{abspage}}
- \@PBcopyPageData{tmp}{candidate}
- }
+ % It only makes sense to consider pages that actually have two
+ % columns. LaTeX3 does not do short-circuit evaluation, so we
+ % cannot add this test to the ifboolexpr below.
+ \if@twocolumn
+ \ifboolexpr
+ {
+ % A float page is not the last text page, ignore
+ togl {@PBtmpIsFloatPage}
+ or
+ % A page with a float column on the left and an empty
+ % column on the right is not the last text page, ignore
+ (
+ togl {@PBtmpHasFloatcol}
+ and
+ test {\ifdimcomp{\@PBtmpUsedRight}{=}{\topskip}}
+ )
+ }
+ {}
+ {
+ % This page is a candidate to be the last two-column text page
+ \xdef\@PBlastPage{\the\value{abspage}}
+ \@PBcopyPageData{tmp}{candidate}
+ }
+ \fi
% Reset before processing next page
\global\togglefalse{@PBtmpHasFloats}
@@ -635,8 +639,8 @@
% \end{macrocode}
%
-% All pages processed, the last candidate page is actually the last page.
-% Instead of continuing to use the \texttt{@PBcandidate*} macros we already
+% All pages processed, the last candidate page is actually the last two-column
+% page. Instead of continuing to use the \texttt{@PBcandidate*} macros we already
% have, we will keep the information we just gathered associated with the
% page number. We do this because, in the future, we may want to add suport
% for balancing multiple pages (such as the last page of each chapter) and
@@ -645,14 +649,20 @@
%
% \begin{macrocode}
-\AfterLastShipout{\@PBcopyPageData{candidate}{pg\@Roman{\@PBlastPage}}}
+\AfterLastShipout{
+ % If there are no two-column pages in the
+ % document, there is no candidate page.
+ \ifcsdef{@PBlastPage}
+ {\@PBcopyPageData{candidate}{pg\@Roman{\@PBlastPage}}}
+ {}
+}
% \end{macrocode}
%
% \subsubsection{Saving measurements}
% The whole document has already been processed and data about the last
-% page has been collected in macros with names \texttt{@PBpgNUM*}. We now
-% process this collected data and save whatever is relevant in the aux
+% two-column page has been collected in macros with names \texttt{@PBpgNUM*}.
+% We now process this collected data and save whatever is relevant in the aux
% file for the next \LaTeX{} pass.
%
% In the first \LaTeX{} pass, we will save data to the aux file in macros
@@ -978,19 +988,25 @@
\newcommand\@PBsaveUnbalancedInfo[1][]{
- \immediate\write\@mainaux{\gdef\string\@PBprevLastPage{\@PBlastPage}}
-
- \ifboolexpr{test {\ifdefvoid{\@PBprevLastPage}} or test {\ifstrequal{#1}{update}}}
- % Columns are currently unbalanced, either because this is
- % the first pass (we do not have any previous information)
- % or because the document has not stabilized yet, so any
- % previous information is unreliable. Save the information
- % we just collected as ``unbalanced''.
- {\@PBsavePageDataAs{pg\@Roman{\@PBlastPage}}{unbalpg\@Roman{\@PBlastPage}}}
- % Not the first pass, so columns are possibly balanced;
- % to save the unbalanced information, repeat what was
- % gathered during the first pass.
- {\@PBsavePageData{unbalpg\@Roman{\@PBprevLastPage}}}
+ % If there are no two-column pages in the
+ % document, there is nothing to save.
+ \ifcsdef{@PBlastPage}
+ {
+ \immediate\write\@mainaux{\gdef\string\@PBprevLastPage{\@PBlastPage}}
+
+ \ifboolexpr{test {\ifdefvoid{\@PBprevLastPage}} or test {\ifstrequal{#1}{update}}}
+ % Columns are currently unbalanced, either because this is
+ % the first pass (we do not have any previous information)
+ % or because the document has not stabilized yet, so any
+ % previous information is unreliable. Save the information
+ % we just collected as ``unbalanced''.
+ {\@PBsavePageDataAs{pg\@Roman{\@PBlastPage}}{unbalpg\@Roman{\@PBlastPage}}}
+ % Not the first pass, so columns are possibly balanced;
+ % to save the unbalanced information, repeat what was
+ % gathered during the first pass.
+ {\@PBsavePageData{unbalpg\@Roman{\@PBprevLastPage}}}
+ }
+ {}
}
\def\@PBsaveBalancedInfo{
@@ -1002,8 +1018,14 @@
\def\@PBnotifyRerun{
\AtVeryEndDocument{
- \PackageWarningNoLine{pbalance}
- {Last page columns not balanced. Rerun LaTeX}
+ % If there are no two-column pages in the document,
+ % it makes no sense to emit this warning.
+ \ifcsdef{@PBlastPage}
+ {
+ \PackageWarningNoLine{pbalance}
+ {Last two-column page cols not balanced. Rerun LaTeX}
+ }
+ {}
}
}