summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/tools/multicol.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2019-10-04 20:57:14 +0000
committerKarl Berry <karl@freefriends.org>2019-10-04 20:57:14 +0000
commit70aaae3b3c98fb6357c846ad54ce2367e9682f50 (patch)
treef0446e015c31510a11ada780ad4978dce03ad104 /Master/texmf-dist/source/latex/tools/multicol.dtx
parentbe53f9d0af947622afca67b99c89a90d5c08dbd4 (diff)
latex2e (4oct19)
git-svn-id: svn://tug.org/texlive/trunk@52286 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/tools/multicol.dtx')
-rw-r--r--Master/texmf-dist/source/latex/tools/multicol.dtx147
1 files changed, 91 insertions, 56 deletions
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