summaryrefslogtreecommitdiff
path: root/macros/latex/required/tools/multicol.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/required/tools/multicol.dtx')
-rw-r--r--macros/latex/required/tools/multicol.dtx164
1 files changed, 112 insertions, 52 deletions
diff --git a/macros/latex/required/tools/multicol.dtx b/macros/latex/required/tools/multicol.dtx
index 1d16a01c15..8d868357da 100644
--- a/macros/latex/required/tools/multicol.dtx
+++ b/macros/latex/required/tools/multicol.dtx
@@ -98,7 +98,7 @@
%<driver> \ProvidesFile{multicol.drv}
% \fi
% \ProvidesFile{multicol.dtx}
- [2019/12/09 v1.8y multicolumn formatting (FMi)]
+ [2021/10/28 v1.9b multicolumn formatting (FMi)]
%
%
%%
@@ -115,6 +115,8 @@
% \changes{v1.0f}{1989/07/11}{Changed \cs{z@} to 0pt in redefinition of
% description.}
% \changes{v1.1a}{1989/09/20}{\cs{multicolssep} changed to \cs{multicolsep}.}
+% \changes{v1.9b}{2021/10/22}{Swap names \cs{mult@gfirstbox}
+% and \cs{mult@firstbox} (gh/701)}
%
% \def\description{\list{}{\labelwidth 0pt \leftmargin\descriptionmargin
% \itemindent-\leftmargin \let\makelabel\descriptionlabel}}
@@ -564,6 +566,14 @@
% forced into the second column (resulting in some white
% space between paragraphs in the first column).
%
+% From version 1.9 onwards \cs{columnbreak} accepts an optional
+% argument (just like \cs{pagebreak}) in which you can specify the
+% desirability to break the column at that point: supported values are
+% \texttt{0} (slightly desirable) to \texttt{4} (forced).
+% This version also adds \cs{newcolumn}
+% which forces a column break but runs the column short (comparable to
+% \cs{newpage}).
+%
% \subsection{Floats inside a \mc{} environment}
%
% Within the \mc{} environment the usual star float commands are
@@ -727,7 +737,7 @@
% When it finishes it must return the individual columns in boxes
% suitable for further processing with |\page@sofar|. This means
% that the left column should be stored in box register
-% |\mult@gfirstbox|, the next
+% |\mult@firstbox|, the next
% in register |\mult@firstbox|${}+2$, \ldots,
% only the last one as an exception in
% register |\mult@grightbox|. Furthermore it has to set up
@@ -981,7 +991,8 @@
% \changes{v1.8x}{2019/10/15}{Use \cs{@maxdepth} not \cs{maxdepth} (gh/190)}
% \begin{macrocode}
\let\mc@gridwarn\maxdimen
-\DeclareOption{grid}{\def\mc@gridwarn{\@maxdepth}}
+\DeclareOption{grid}
+ {\def\mc@gridwarn{\@maxdepth}}
% \end{macrocode}
%
% \changes{v1.8e}{2014/04/23}{Support \cs{docolaction}}
@@ -1071,7 +1082,8 @@
% \changes{v1.6e}{2004/02/14}{Avoid self-referencing definition of
% \cs{@footnotetext} (pr/3618)}.
% \begin{macrocode}
- \ifx\@footnotetext\mult@footnotetext\else
+ \ifx\@footnotetext\mult@footnotetext
+ \else
\let\orig@footnotetext\@footnotetext
\let\@footnotetext\mult@footnotetext
\fi
@@ -1512,10 +1524,13 @@
\def\clearpage{%
\ifx\@deferlist\@empty\else
\PackageError{multicol}%
- {Deferred floats not cleared}%
- {A \string\clearpage\space inside multicols acts like
- \string\newpage\space and doesn't clear floats.\MessageBreak
- Move it before the multicols environment if you need it.}%
+ {Deferred floats not cleared}%
+ {A \string\clearpage\space inside
+ multicols acts like
+ \string\newpage\space and doesn't
+ clear floats.\MessageBreak
+ Move it before the multicols
+ environment if you need it.}%
\fi
\newpage}%
% \end{macrocode}
@@ -1701,7 +1716,8 @@
% for later.
% \changes{v1.8r}{2018/01/28}{Macro added}
% \begin{macrocode}
-\mathchardef\@Mvi=10006 % 10005 is \columnbreak
+\mathchardef\@Mvi=10006 % 10005 is
+ % \columnbreak
% \end{macrocode}
% \end{macro}
%
@@ -1724,7 +1740,8 @@
% \changes{v1.8c}{2013/11/03}{Add \cs{color@endgroup} to prevent color leak}
% \changes{v1.8f}{2014/06/19}{Discard spaces before adding \cs{color@endgroup}}
% \begin{macrocode}
- \remove@discardable@items\color@endgroup\egroup
+ \remove@discardable@items
+ \color@endgroup\egroup
% \end{macrocode}
% Now we call |\balance@columns| the routine that balances material
% stored in the box |\mult@box|.
@@ -1754,7 +1771,7 @@
{Restore kept marks to\MessageBreak
first: \meaning\kept@firstmark
\MessageBreak bot\space\space:
- \meaning\kept@botmark }%
+ \meaning\kept@botmark }%
%</marktrace>
% \end{macrocode}
% This finishes the code for the ``boxed'' case.
@@ -2203,7 +2220,7 @@
% \changes{v1.8x}{2019/10/15}{Use \cs{@maxdepth} not \cs{maxdepth} (gh/190)}
% \begin{macrocode}
\def\vfilmaxdepth{\vskip \z@ \@plus .0001fil
- \@minus \@maxdepth}
+ \@minus \@maxdepth}
% \end{macrocode}
% \end{macro}
%
@@ -2281,7 +2298,7 @@
% |\@kludgeins| box will be the negation of the size by which the
% page should be enlarged. If the star form of this command has
% been used then we also need to shrink the resulting column.
-
+%
% That local change will be reverted at the end of the output
% routine So for the next page the original state will be
% reestablished. However, in theory there is a possibility to sneak
@@ -2308,7 +2325,7 @@
% 4,\ldots\ (plus offset).
% \changes{v1.5a}{1992/11/04}{New box mechanism}
% \begin{macrocode}
- \process@cols\mult@gfirstbox{%
+ \process@cols\mult@firstbox{%
\setbox\count@
\vsplit\@cclv to\dimen@
% \end{macrocode}
@@ -2335,7 +2352,8 @@
\setbox\count@
\vbox to\dimen@
{\unvbox\count@
- \ifshr@nking\vfilmaxdepth\fi}%
+ \ifshr@nking
+ \vfilmaxdepth\fi}%
}%
% \end{macrocode}
% Then the last column follows.
@@ -2615,7 +2633,8 @@
% \changes{v1.8r}{2018/01/28}{Handling end of env through special penalty}
% \begin{macrocode}
\ifnum\outputpenalty = -\@Mvi
- \mult@info\@ne{End penalty of multicols seen}%
+ \mult@info\@ne{End penalty of
+ multicols seen}%
% \end{macrocode}
% If we are at this point then we have to run the balancing code
% (which was previously its own output routine). First we pretend
@@ -2626,7 +2645,9 @@
% in a better way; basically it is like this, because of the older
% code was using different ORs and I simply reused most of it.
% \begin{macrocode}
- \outputpenalty\@M % pretend we had a natural forced break
+ \outputpenalty\@M % pretend we had
+ % a natural
+ % forced break
\balance@columns@out
\else
% \end{macrocode}
@@ -2647,7 +2668,8 @@
% this is possible with |\xdef|.)
% \changes{v1.2a}{1990/02/05}{Float boxes freed.}
% \begin{macrocode}
- \xdef\@freelist{\@freelist\@currlist}%
+ \xdef\@freelist{\@freelist
+ \@currlist}%
\gdef\@currlist{}%
\fi
\fi
@@ -2822,8 +2844,9 @@
% |\enlargethispage| command.
% \changes{v1.8a}{2011/12/20}{Support for \cs{enlargethispage}}
% \begin{macrocode}
- \ifvbox\@kludgeins\insert\@kludgeins
- {\unvbox\@kludgeins}\fi
+ \ifvbox\@kludgeins
+ \insert\@kludgeins
+ {\unvbox\@kludgeins}\fi
% \end{macrocode}
% Then we |\unvbox| the |\partial@page| (which may be void if we
% are not processing the first page of this \mc{} environment.
@@ -2833,7 +2856,8 @@
% Then we return the first and bottom mark and the gathered
% material to the main vertical list.
% \begin{macrocode}
- \return@nonemptymark{first}\kept@firstmark
+ \return@nonemptymark{first}%
+ \kept@firstmark
\return@nonemptymark{bot}\kept@botmark
\page@sofar
% \end{macrocode}
@@ -2960,12 +2984,14 @@
% \changes{v1.8w}{2019/03/01}{Provide minrows counter for balancing}
% \begin{macrocode}
\@tempdima\dimexpr
- \topskip +\c@minrows\baselineskip-\baselineskip\relax
+ \topskip +\c@minrows\baselineskip
+ -\baselineskip\relax
\ifnum\dimen@<\@tempdima
\mult@info\@ne
{Start value
\the\dimen@ \space ->
- \the\@tempdima \space (corrected for minrows)}%
+ \the\@tempdima \space
+ (corrected for minrows)}%
\dimen@\@tempdima
\fi
% \end{macrocode}
@@ -3057,7 +3083,7 @@
% untouched so that we can start over again if this trial was
% unsuccessful.
% \begin{macrocode}
- {\process@cols\mult@firstbox{%
+ {\process@cols\mult@gfirstbox{%
\global\setbox\count@
\vsplit\mult@grightbox to\dimen@
% \end{macrocode}
@@ -3111,19 +3137,19 @@
\global\setbox\mult@grightbox
\vbox{\unvbox\mult@grightbox}%
% \end{macrocode}
-% We also save a copy |\mult@firstbox| at its ``natural'' size
+% We also save a copy |\mult@gfirstbox| at its ``natural'' size
% for later use.
% \begin{macrocode}
\setbox\mult@nat@firstbox
- \vbox{\unvcopy\mult@firstbox}%
+ \vbox{\unvcopy\mult@gfirstbox}%
% \end{macrocode}
% After |\process@cols| has done its job we have the following
% situation:
% \begin{center}
% \begin{tabular}{r@{$\:\:\longleftarrow\:\:$}l}
% box |\mult@rightbox| & all material \\
-% box |\mult@gfirstbox| & first column \\
-% box |\mult@gfirstbox|${}+2$ & second column \\
+% box |\mult@firstbox| & first column \\
+% box |\mult@firstbox|${}+2$ & second column \\
% \multicolumn{1}{c}{$\vdots$} &
% \multicolumn{1}{c}{$\vdots$} \\
% box |\mult@grightbox| & last column
@@ -3144,10 +3170,10 @@
% to later columns but it is actually producing incorrect results
% (overprinting of text) in boundary cases, so since version v1.5q
% |\raggedcolumns| means allows for all columns to run slightly short.
-% \changes{v1.5q}{1998/01/19}{Do not reset \cs{mult@firstbox} (pr2739)}
+% \changes{v1.5q}{1998/01/19}{Do not reset \cs{mult@gfirstbox} (pr2739)}
% \begin{macrocode}
% \ifshr@nking
-% \global\setbox\mult@firstbox
+% \global\setbox\mult@gfirstbox
% \copy\mult@nat@firstbox
% \fi
% \end{macrocode}
@@ -3465,8 +3491,11 @@
% allocating after 255. This is all done quite low-level by looking
% directly at the values of the allocation counters.
% \changes{v1.8y}{2019/12/09}{Allow for 20 columns (gh/237)}
+% \changes{v1.9b}{2021/10/22}{Drop one unnecessary box allocation (gh/701)}
% \begin{macrocode}
-\ifnum\numexpr \count20-\count14-1<41 % = 2 * 20 + 1
+\ifnum\numexpr
+ \count20-\count14-1<40
+ % this is = 2 * 20
\count14=\@cclv
\fi
% \end{macrocode}
@@ -3474,8 +3503,8 @@
% \begin{macrocode}
\newbox\mult@rightbox
\newbox\mult@grightbox
-\newbox\mult@gfirstbox
\newbox\mult@firstbox
+\newbox\mult@gfirstbox
\newbox\@tempa\newbox\@tempa
\newbox\@tempa\newbox\@tempa
\newbox\@tempa\newbox\@tempa
@@ -3494,7 +3523,6 @@
\newbox\@tempa\newbox\@tempa
\newbox\@tempa\newbox\@tempa
\newbox\@tempa\newbox\@tempa
-\newbox\@tempa
\let\@tempa\relax
% \end{macrocode}
% \end{macro}
@@ -4071,34 +4099,66 @@
%
% \begin{macro}{\columnbreak}
% \changes{v1.5u}{1999/05/25}{Macro added}
+% \changes{v1.9a}{2021/10/08}{Added optional argument for conditional break}
+% \changes{v1.9b}{2021/10/28}{Corrected error message text (gh/703)}
% |\columnbreak| is modeled after |\pagebreak| except that we
% generate a penalty -10005.
% \begin{macrocode}
\mathchardef\@Mv=10005
-\def\columnbreak{%
+\newcommand\columnbreak[1][4]{%
% \end{macrocode}
% We have to ensure that it is only used within a \mc{}
% environment since if that penalty would be seen by the unmodified
% \LaTeX{} output routine strange things would happen.
% \begin{macrocode}
- \ifnum\col@number<\tw@
- \PackageError{multicol}%
- {\noexpand\columnbreak outside multicols}%
- {This command can only be used within
- a multicols or multicols* environment.}%
- \else
- \ifvmode
- \penalty -\@Mv\relax
- \else
- \@bsphack
- \vadjust{\penalty -\@Mv\relax}%
- \@esphack
- \fi
- \fi}
+ \ifnum\col@number<\tw@
+ \PackageError{multicol}%
+ {\noexpand\columnbreak outside multicols}%
+ {This command can only be used within
+ a multicols or multicols* environment.}%
+ \else
+% \end{macrocode}
+% Increasingly lower penalty based on argument value. This is like
+% \cs{pagebreak} but we use other penalty values are the \LaTeX{}
+% defaults aree rather pointless for pagination.
+% \begin{macrocode}
+ \edef\mc@break@pen
+ {-\ifcase#1\@m\or 3333\or 6666\or 9999\else\@Mv\fi\relax}%
+ \ifvmode
+ \penalty \mc@break@pen
+ \else
+ \@bsphack
+ \vadjust{\penalty \mc@break@pen}%
+ \@esphack
+ \fi
+ \fi}
% \end{macrocode}
% \end{macro}
%
%
+%
+% \begin{macro}{\newcolumn}
+% \changes{v1.9a}{2021/10/08}{Macro added}
+% This is modeled after \cs{newpage} but for column breaks.
+% \begin{macrocode}
+\newcommand\newcolumn{%
+ \ifnum\col@number<\tw@
+ \PackageError{multicol}%
+ {\noexpand\newcolumn outside multicols}%
+ {This command can only be used within
+ a multicols or multicols* environment.}%
+ \else
+ \ifvmode
+ \nobreak\vfill\penalty -\@Mv\relax
+ \else
+ \@bsphack
+ \vadjust{\nobreak\vfill\kern\z@\penalty -\@Mv\relax}%
+ \@esphack
+ \fi
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\colbreak@box}
% \changes{v1.5u}{1999/05/25}{Macro added}
% Need a box to collect the galley up to the column break.
@@ -4128,7 +4188,7 @@
% \end{macrocode}
% We loop through the columns with |\process@cols|
% \begin{macrocode}
- \process@cols\mult@gfirstbox{%
+ \process@cols\mult@firstbox{%
% \end{macrocode}
% If the depth of the current box is larger than the maximum found
% so far in |\dimen2| we update that register for later use.
@@ -4151,7 +4211,7 @@
\@width\columnseprule}\hss}%
% \end{macrocode}
% As you will have noticed, we started with box register
-% |\mult@gfirstbox| (i.e.\
+% |\mult@firstbox| (i.e.\
% the left column). So this time |\count@| looped through 2,
% 4,\ldots\ (plus the appropriate offset).
% Finally we add box |\mult@rightbox| and we are done.
@@ -4193,7 +4253,7 @@
% First step is to put all rules in the right place (without adding
% the comes which are instead represented by a space of |\hsize|.
% \begin{macrocode}
- \process@cols\mult@gfirstbox{%
+ \process@cols\mult@firstbox{%
\hskip\hsize
\hss{\columnseprulecolor\vrule
\@width\columnseprule}\hss
@@ -4211,7 +4271,7 @@
% column using the same approach until we are done with all but the
% final column.
% \begin{macrocode}
- \process@cols\mult@gfirstbox{%
+ \process@cols\mult@firstbox{%
\ifdim\dp\count@>\dimen\tw@
\global\dimen\tw@\dp\count@ \fi
\hskip-\hsize