From 70aaae3b3c98fb6357c846ad54ce2367e9682f50 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Fri, 4 Oct 2019 20:57:14 +0000
Subject: latex2e (4oct19)

git-svn-id: svn://tug.org/texlive/trunk@52286 c570f23f-e606-0410-a88d-b1316a301751
---
 Master/texmf-dist/source/latex/tools/multicol.dtx | 147 +++++++++++++---------
 1 file changed, 91 insertions(+), 56 deletions(-)

(limited to 'Master/texmf-dist/source/latex/tools/multicol.dtx')

diff --git a/Master/texmf-dist/source/latex/tools/multicol.dtx b/Master/texmf-dist/source/latex/tools/multicol.dtx
index fd77d6247dc..d68f471fcd4 100644
--- a/Master/texmf-dist/source/latex/tools/multicol.dtx
+++ b/Master/texmf-dist/source/latex/tools/multicol.dtx
@@ -20,7 +20,7 @@
 % \iffalse    This is a METACOMMENT
 %
 %% Package `multicol' to use with LaTeX2e
-%% Copyright 1989-2018 Frank Mittelbach
+%% Copyright 1989-2019 Frank Mittelbach
 %%
 %%  In addition to the terms of LPPL any distributed version
 %%  (unchanged or modified) of multicol has to keep the statement
@@ -98,7 +98,7 @@
 %<driver> \ProvidesFile{multicol.drv}
 % \fi
 %         \ProvidesFile{multicol.dtx}
-          [2018/12/27 v1.8v  multicolumn formatting (FMi)]
+          [2019/03/01 v1.8w  multicolumn formatting (FMi)]
 %
 %
 %%
@@ -145,7 +145,7 @@
 % \DoNotIndex{\z@}
 %
 % \MakeShortVerb{\|}
-% \newcommand{\mc}{{\sf multicols}}
+% \newcommand{\mc}{\textsf{multicols}}
 % \newcommand{\TUB}{{\sl TUGboat\/}}
 % \newcommand{\TB}{{\sl\TeX book\/}}
 %
@@ -191,13 +191,15 @@
 %    Also added was support for |\enlargethispage|. This means it is
 %    now possible to request a page to be artificially  enlarged or
 %    shortened. Note that if you enlarge pages by more than one line
-%    you may have to increase the {\sf collectmore} counter value to
+%    you may have to increase the \textsf{collectmore} counter value to
 %    ensure that enough material is being picked up.
 %
 %    This command was used on the second page of this manual to shorten
 %    it by one line, in order to get rid of a number of widow lines on
 %    the following pages.
 %
+%   There are also some small enhancements to the balancing algorithm
+%   including a ways to require a minimum number of rows in the result.
 %
 %    Finally, version 1.8 adds the command |\docolaction| to help with
 %   more complicated actions that depend on the current column. This
@@ -278,8 +280,8 @@
 %   \LaTeX{}, but every use of |\twocolumn| or |\onecolumn|
 %   starts a new page. Moreover, the last page of two-column output
 %   isn't balanced and this often results in an empty, or nearly
-%   empty, right column. When I started to write macros for {\sf
-%   doc.sty} (see ``The {\tt doc}--Option'', \TUB\
+%   empty, right column. When I started to write macros for
+% \textsf{doc.sty} (see ``The \texttt{doc}--Option'', \TUB\
 %   volume 10~\#2, pp.~245--273) I thought that it would be nice to
 %   place the index
 %   on the same page as the bibliography. And balancing the last page
@@ -319,7 +321,7 @@
 % \enlargethispage{-1\baselineskip}
 %
 % \DescribeMacro\premulticols
-% As its first action, the {\sf multicols} environment measures the
+% As its first action, the \textsf{multicols} environment measures the
 % current page to determine whether there is enough room for some
 % portion of multicolumn output. This is controlled by the
 % \meta{dimen} variable |\premulticols| which can be changed by
@@ -372,7 +374,7 @@
 % \DescribeMacro\columnseprule
 % Separation of columns with vertical rules is achieved by setting the
 % parameter |\columnseprule| to some positive value.  In this
-% article a value of {\sf.4pt} was used.
+% article a value of \textsf{.4pt} was used.
 %
 % \DescribeMacro\columnseprulecolor
 % The color of the rules separating the columns can be specified through
@@ -410,7 +412,7 @@
 % is 9999 which is less than infinity but `bad' enough for most
 % paragraphs in a multicolumn environment. Changing its value should
 % be done outside the \mc{} environment.  Since |\tolerance| is set
-% to |\multicoltolerance| at the beginning of every {\sf multicols}
+% to |\multicoltolerance| at the beginning of every \textsf{multicols}
 % environment one can locally overwrite this default by assigning
 % \verb*+\tolerance = +\meta{desired value}. There also exists a
 % |\multicolpretolerance| parameter holding the value for
@@ -445,7 +447,7 @@
 % actually going wrong are very slim, but if this happens you can help
 % \TeX{} by using a |\pagebreak| command in the final document.
 % Another way to influence the behavior of \TeX{} in this respect is
-% given by the counter variable `{\sf collectmore}'. If you use the
+% given by the counter variable `\textsf{collectmore}'. If you use the
 % |\setcounter| declaration to set this counter to \meta{number},
 % \TeX{} will consider \meta{number} more (or less) lines before
 % making its final decision. So a value of $-1$ may solve all your
@@ -459,16 +461,27 @@
 % make both
 % the top and bottom baselines of all columns align.
 %
-% Additionally you can set another counter, the `{\sf unbalance}'
+% If there is only a small amount of material available for balancing
+% then you may end up with very few lines per column. In an extreme
+% case there may be only one line which looks distinctly odd. In that
+% case it might be better to have more material distributed to the
+% earlier columns even if that means that later columns are empty or
+% partially empty. This is controlled through the counter
+% `\textsf{minrows}' (default 1). If set to a higher value then the
+% balancing will have at least that many rows in the first column (and
+% also all further columns until it runs outs of material).
+%          
+% Additionally you can set another counter, the `\textsf{unbalance}'
 % counter, to some positive \meta{number}. This will make all but the
 % right-most column \meta{number} of lines longer than they would
 % normally have been. `Lines' in this context refer to normal text
 % lines (i.e.\ one |\baselineskip| apart); thus, if your columns
 % contain displays,
 % for example, you may need a higher \meta{number}
-% to shift something from one column into another.
+% to shift something from one column into another. A negative value can make sense if
+% you have set \textsf{minrows} and want to locally adjust that.
 %
-% Unlike `{\sf collectmore},' the `{\sf unbalance}' counter is reset
+% Unlike `\textsf{collectmore},' the `\textsf{unbalance}' counter is reset
 % to zero at the end of the environment so it only applies to one
 % \mc{} environment.
 %
@@ -485,7 +498,7 @@
 %
 % The new release now measures every generated column and ignores
 % solutions where at least one column has a badness being larger than
-% the value of the counter {\sf columnbadness}. The default value for
+% the value of the counter \textsf{columnbadness}. The default value for
 % this counter is 10000, thus \TeX{} will accept all solutions except
 % those being overfull.
 % By setting the counter to a smaller value you can force the algorithm
@@ -505,7 +518,7 @@
 %
 % In the new release this stretching is only done if the badness of
 % the final column is not larger than the value of the counter
-% {\sf finalcolumnbadness}. The default setting is 9999, thus preventing
+% \textsf{finalcolumnbadness}. The default setting is 9999, thus preventing
 % the stretching for all columns that \TeX{} would consider infinitely
 % bad. In that case the final column is allowed to run short which gives
 % a much better result.
@@ -555,13 +568,13 @@
 %
 % Within the \mc{} environment the usual star float commands are
 % available but their function is somewhat different as in the
-% two-column mode of standard \LaTeX. Stared floats, e.g., {\tt
-% figure*}, denote page wide floats that are handled in a similar
+% two-column mode of standard \LaTeX. Stared floats, e.g.,
+% \texttt{figure*}, denote page wide floats that are handled in a similar
 % fashion as normal floats outside the \mc{} environment. However,
 % they will never show up on the page where they are encountered. In
 % other words, one can influence their placement by specifying a
-% combination of {\tt t}, {\tt b}, and/or {\tt p} in their optional
-% argument, but {\tt h} doesn't work because the first possible place
+% combination of \texttt{t}, \texttt{b}, and/or \texttt{p} in their optional
+% argument, but \texttt{h} doesn't work because the first possible place
 % is the top of the next page. One should also note, that this means
 % that their placement behavior is determined by the values of
 % |\topfraction|, etc.\ rather than by |\dbl...|.
@@ -615,7 +628,7 @@
 %  inside `multicols' environment!}
 %
 %  This message appears if you try to use the |\marginpar| command or
-%  an unstarred version of the {\sf figure} or {\sf table} environment.
+%  an unstarred version of the \textsf{figure} or \textsf{table} environment.
 %  Such floats will disappear!
 %
 % \item[] {\hspace*{-\labelsep}\tt Very deep columns!
@@ -649,7 +662,7 @@
 %    In this case you also get information from the balancing routine:
 %    the heights tried for the left and right-most columns,
 %    information about shrinking if the |\raggedcolumns|
-%    declaration is in force and the value of the `{\sf unbalance}'
+%    declaration is in force and the value of the `\textsf{unbalance}'
 %    counter if positive.
 % \item[$\meta{number}= 3$.]  Setting \meta{number}\pagebreak[2] to
 %    this value will additionally trace the mark handling
@@ -670,12 +683,12 @@
 % \begin{multicols}{3}[\section{Prefaces to older versions}
 %                      \subsection{Preface to version 1.4}]
 %   \hbadness=10000
-%   Beside fixing some bugs as mentioned in the {\sf multicol.bug} file
+%   Beside fixing some bugs as mentioned in the \textsf{multicol.bug} file
 %   this new release enhances the \mc{} environment by allowing for
 %   balancing in arbitrary contexts. It is now, for example, possible
-%   to balance text within a \mc{} or a {\sf minipage} as shown in
-%   \ref{tab:newcmds} where a {\sf multicols} environment within a
-%   {\sf quote} environment was used. It is now even possible to nest
+%   to balance text within a \mc{} or a \textsf{minipage} as shown in
+%   \ref{tab:newcmds} where a \textsf{multicols} environment within a
+%   \textsf{quote} environment was used. It is now even possible to nest
 %   \mc{} environments.
 %
 %   The only restriction to such inner \mc{} environments (nested, or
@@ -699,7 +712,7 @@
 %   |\badness| function of \TeX3, define a faster algorithm for finding
 %   the right column height, etc. If somebody thinks he/she has an
 %   enhancement I would be pleased to learn about it. But please obey
-%   the copyright notice and don't change {\sf multicol.dtx} directly!
+%   the copyright notice and don't change \textsf{multicol.dtx} directly!
 %   \begin{table*}
 %    \begin{quote}
 %    \begin{multicols}{2}
@@ -772,7 +785,7 @@
 %   forbidden floats was their ultimate removal from \LaTeX{}s
 %   |\@freelist| so that after a few |\marginpar|s inside the \mc{}
 %   environment floats where disabled forever.  (Thanks to Chris
-%   Rowley for pointing this out.) I removed this misbehaviour and at
+%   Rowley for pointing this out.) I removed this misbehavior and at
 %   the same time decided to allow at least floats spanning all
 %   columns, e.g., generated by the |figure*| environment.  You can
 %   see the new functionality in table~\ref{tab:newcmds} which was
@@ -787,7 +800,7 @@
 %      |\emergencystretch| \meta{dimen} register provided in the
 %      new \TeX{} 3.0. The first argument is the number of columns and
 %      the second one is the current |\hsize|. At the moment the
-%      default definition is $4\mbox{\tt pt} \times |#1|$, i.e.\ the
+%      default definition is $4\texttt{pt} \times |#1|$, i.e.\ the
 %      |\hsize| isn't used at all. But maybe there are better
 %      formulae.
 %
@@ -799,7 +812,7 @@
 %   \end{quote}
 %   \vspace*{-1ex}
 %   \vspace*{-0ex}
-%   \caption[]{The new commands of {\sf multicol.sty} version 1.2.
+%   \caption[]{The new commands of \textsf{multicol.sty} version 1.2.
 %            Both commands might be removed if good solutions to these
 %            open problems are found. I hope that these commands will
 %            prevent that nearly identical style files derived from
@@ -845,8 +858,7 @@
 %
 % The next bit of code contains the documentation driver file for
 % \TeX{}, i.e., the file that will produce the documentation you are
-% currently reading. It will be extracted from this file by the {\tt
-% docstrip} program.
+% currently reading. It will be extracted from this file by the \texttt{docstrip} program.
 % Since this is the first code in this file one can produce the
 % documentation
 % simply by running \LaTeX{} on the \texttt{.dtx} file.
@@ -1149,7 +1161,7 @@
 %    \end{macrocode}
 %    Now we output the first argument and produce vertical space
 %    above the columns. (Note that this argument corresponds to the
-%    first optional argument of the {\sf multicols} environment.)
+%    first optional argument of the \textsf{multicols} environment.)
 %    For many releases this argument was typeset in a group to get
 %    a similar effect as |\twocolumn[..]| where the argument is
 %    also implicitly surrounded by braces. However, this conflicts
@@ -1465,7 +1477,7 @@
 %    Finally we handle the footnote insertions. We have to multiply
 %    the magnification factor and the extra skip by the number of
 %    columns since each footnote reduces the space for every column
-%    (remember that we have pagewide footnotes).  If, on the other
+%    (remember that we have page-wide footnotes).  If, on the other
 %    hand, footnotes are typeset at the very end of the document, our
 %    scheme still works since |\count\footins| is zero then, so it
 %    will not change.
@@ -1475,7 +1487,7 @@
 %    \begin{macrocode}
     \init@mult@footins
 %    \end{macrocode}
-%    For the same reason (pagewide footnotes), the \meta{dimen}
+%    For the same reason (page-wide footnotes), the \meta{dimen}
 %    register controlling the maximum space used for footnotes isn't
 %    changed.  Having done this, we must reinsert all the footnotes
 %    which are already present (i.e.\ those encountered when the
@@ -1489,7 +1501,7 @@
 %    Inside \mc{} a |\clearpage| is fairly useless as we aren't supporting
 %    floats. In fact, it can cause harm as it doesn't know about the
 %    |\partial@page| and may therefore result in making columns too long.
-%    So we change that to bahve like |\newpage| but also check if there
+%    So we change that to behave like |\newpage| but also check if there
 %    are any deferred floats. If so, perhaps the user tried to place them through
 %    that |\clearpage| (but that needs to be done before starting the \mc{}
 %    environment.
@@ -1582,8 +1594,8 @@
 %    |\columnwidth| was left unchanged. This is inconsistent,
 %    but |\columnwidth| is used only by floats (which
 %    aren't allowed in their current implementation) and by the
-%    |\footnote| macro. Since we want pagewide
-% footnotes\footnote{I'm not sure that I really want pagewide
+%    |\footnote| macro. Since we want page-wide
+% footnotes\footnote{I'm not sure that I really want page-wide
 %                       footnotes. But balancing of the last page can
 %                       only be achieved with this approach or with a
 %                       multi-path algorithm which is complicated and
@@ -1836,7 +1848,7 @@
   \@checkend{multicols}%
   \endgroup
 %    \end{macrocode}
-%    We also set the `{\sf unbalance}' counter to its default. This is
+%    We also set the `\textsf{unbalance}' counter to its default. This is
 %    done globally since \LaTeX{} counters are always changed this
 %    way.\footnote{Actually, we are still in a group started by the
 %    \cs{begin} macro, so \cs{global} must be used
@@ -2113,7 +2125,7 @@
 %    that this value is likely to be wrong. We therefore normalize the
 %    situation by pretending that the depth is zero. However, if |\page@sofar|
 %   is being called inside the OR then setting |\prevdepth| here has
-%   no longlasting effect, we therefore have to repeat this once we
+%   no long-lasting effect, we therefore have to repeat this once we
 %   return to the main vertical list. Here we set it only for those
 %   cases where the command is used within a list and then followed by
 %   something else.
@@ -2176,7 +2188,7 @@
 %
 % \begin{macro}{\vfilmaxdepth}
 %    This curious definition is used as the space at the bottom of a
-%   column if we implement |\raggedcolumns|. Normlly one only appends
+%   column if we implement |\raggedcolumns|. Normally one only appends
 %   |\vfill| in that case but this is actually wrong for columns that
 %   are more or less full: by adding a glue at the bottom such a
 %   column doesn't have any depth any more but without it the material
@@ -2269,8 +2281,8 @@
 
 %    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 theorey there is a possibility to sneak
-%   in a whoe multicols environment into the running header
+%   reestablished. However, in theory there is a possibility to sneak
+%   in a whole multicols environment into the running header
 %   definition. If that happens then it will also be affected by this
 %   change---too bad I think.   
 % \changes{v1.8a}{2011/12/20}{Support for \cs{enlargethispage}}
@@ -2306,7 +2318,7 @@
 %    But we need to unbox anyway to ensure that at the end of the box
 %    we do not have unwanted space. This can sneak in in certain
 %    situations, for example, if two lists follow each other and we
-%    break between them. While sich space is usually zero it still has
+%    break between them. While such space is usually zero it still has
 %    an effect because it hides depth of the last line in the column
 %    and that will result in incorrect placement.
 % \changes{v1.3c}{1990/03/03}{\cs{unbox}ing avoided.}
@@ -2365,7 +2377,7 @@
            \thepage\space might be wrong}%
        \fi
 %    \end{macrocode}
-%    If the `{\sf tracingmulticols}' counter is 4 or higher we also
+%    If the `\textsf{tracingmulticols}' counter is 4 or higher we also
 %    add a rule.
 %    \begin{macrocode}
        \ifnum \c@tracingmulticols>\thr@@
@@ -2390,7 +2402,7 @@
       \let\botmark\kept@botmark
    \fi
 %    \end{macrocode}
-%    We also initalize |\topmark| with |\kept@topmark|. This will make
+%    We also initialize |\topmark| with |\kept@topmark|. This will make
 %    this mark okay for all middle pages of the \mc{} environment.
 % \changes{v1.5d}{1993/09/15}{reinit \cs{topmark}}
 %    \begin{macrocode}
@@ -2465,7 +2477,7 @@
 %    Now we reset |\@colroom| to |\@colht| which is \LaTeX's
 %    saved value of |\textheight|.
 %    We also have to reset the recorded position of the last
-%   |\marginpar| as well as the recorded size of intext floats 
+%   |\marginpar| as well as the recorded size of in-text floats 
 %    as we are now on a new page.
 % \changes{v1.8d}{2014/04/23}{Reset \cs{@mparbottom} after page finishes}
 % \changes{v1.8n}{2015/08/19}{Reset \cs{@textfloatsheight} after page finishes}
@@ -2580,7 +2592,7 @@
 %   |\colbreak@box| and then back up by this depth. This will position
 %   the bottom of the box at its natural baseline which is useful for
 %   balancing later on.
-% \changes{v1.8k}{2015/03/21}{Remove discarable items just before a
+% \changes{v1.8k}{2015/03/21}{Remove discardable items just before a
 %   forced break}
 %    \begin{macrocode}
               \boxmaxdepth\maxdepth
@@ -2595,7 +2607,7 @@
      \else
 %    \end{macrocode}
 %    Another special case is reaching the end of the \mc{}
-%    environment which is signalled by |-\@Mvi|.
+%    environment which is signaled by |-\@Mvi|.
 % \changes{v1.8r}{2018/01/28}{Handling end of env through special penalty}
 %    \begin{macrocode}
        \ifnum\outputpenalty = -\@Mvi
@@ -2694,8 +2706,8 @@
 %    \begin{macrocode}
 \newif\ifshr@nking
 %    \end{macrocode}
-%    The actual definitions are simple: we just switch to {\sf true}
-%    or {\sf false} depending on the desired action. To avoid extra
+%    The actual definitions are simple: we just switch to \textsf{true}
+%    or \textsf{false} depending on the desired action. To avoid extra
 %    spaces in the output we enclose these changes in
 %    |\@bsphack|\ldots{}\allowbreak|\@esphack|.
 %    \begin{macrocode}
@@ -2723,7 +2735,7 @@
 %   support} For the next block of code see also comments in
 %   section~\ref{sec:colbreak}.  All forced breaks except the last are
 %   inside |\colbreak@box| so all we have to do is to concatenate this
-%   box with box |\@cclv| and put a penalty inbetween. Here we test if
+%   box with box |\@cclv| and put a penalty in between. Here we test if
 %   |\colbreak@box| is void so that the message is only generated if
 %   we really add forced breaks and the penalty.
 % \changes{v1.8k}{2015/03/21}{Use \cs{@Mv} and not \cs{break} in case
@@ -2891,7 +2903,7 @@
 %    unpredictable point depending on the height of the largest
 %    character in this line. But of course we want all columns to
 %    align properly at the baselines of their first lines. For this
-%    reason we have opened |\mult@box| with a |\penalty| {\sf -10000}.
+%    reason we have opened |\mult@box| with a |\penalty| \textsf{-10000}.
 %    This will now allow us to split off from |\mult@box| a tiny bit
 %    (in fact nothing since the first possible break-point is the
 %    first item in the box). The result is that |\splittopskip| is
@@ -2936,6 +2948,21 @@
      \advance\dimen@-\baselineskip
    \fi
 %    \end{macrocode}
+%    As a further restriction we want to see a minimum number of
+%    rows in the balanced result based on the setting of the counter
+%    |minrows|. If the starting value is lower we adjust.
+% \changes{v1.8w}{2019/03/01}{Provide minrows counter for balancing}
+%    \begin{macrocode}
+   \@tempdima\dimexpr
+       \topskip +\c@minrows\baselineskip-\baselineskip\relax
+   \ifnum\dimen@<\@tempdima
+     \mult@info\@ne
+       {Start value
+          \the\dimen@  \space ->
+          \the\@tempdima \space (corrected for minrows)}%
+     \dimen@\@tempdima
+   \fi
+%    \end{macrocode}
 %    At the user's request we start with a higher value (or lower, but
 %    this usually only increases the number of tries).
 %    \begin{macrocode}
@@ -3608,7 +3635,7 @@
                ht \the\ht#1, dp \the\dp#1}%
 %</debug>
 %    \end{macrocode}
-%    Now we open a new group an locally copy the box to itself. As a
+%    Now we open a new group and locally copy the box to itself. As a
 %    result any operation, i.e.\ |\vsplit|, will only have a local
 %    effect. Without this trick the box content would get lost up to
 %    the level where the last assignment to the box register was done.
@@ -3719,7 +3746,7 @@
 %  \begin{macro}{\remove@discardable@items}
 %    There are situations when we may have some space at the end of a
 %    column and this macro here will attempt to get rid of it. The
-%    typical \LaTeX{} sequence is a series of selfcanceling glues so
+%    typical \LaTeX{} sequence is a series of self-canceling glues so
 %    if we remove them recursively we are usually fine.
 %
 %    Special care is needed with handling |\vspace*| as that
@@ -3760,7 +3787,7 @@
        \else
 %    \end{macrocode}
 %    Otherwise we remove this ``real'' skip. Then we look if it was
-%    preceeded by a penalty of 10000 (i.e., a |\nobreak|)
+%    preceded by a penalty of 10000 (i.e., a |\nobreak|)
 %    \begin{macrocode}
          \unskip
 %\typeout{p=\lastpenalty}%
@@ -3797,6 +3824,14 @@
 \newif\ifforcedbreak@leftover
 %    \end{macrocode}
 %
+%  \begin{macro}{\c@minrows}
+% \changes{v1.8w}{2019/03/01}{Provide minrows counter for balancing}
+%    \begin{macrocode}
+\newcount\c@minrows
+\c@minrows=1
+%    \end{macrocode}
+%  \end{macro}
+%
 % \begin{macro}{\c@columnbadness}
 % \begin{macro}{\c@finalcolumnbadness}
 %    \begin{macrocode}
@@ -4002,7 +4037,7 @@
 %
 %  \begin{macro}{\columnbreak}
 % \changes{v1.5u}{1999/05/25}{Macro added}
-%    |\columnbreak| is modelled after |\pagebreak| except that we
+%    |\columnbreak| is modeled after |\pagebreak| except that we
 %    generate a penalty -10005.
 %    \begin{macrocode}
 \mathchardef\@Mv=10005
-- 
cgit v1.2.3

