From 70aaae3b3c98fb6357c846ad54ce2367e9682f50 Mon Sep 17 00:00:00 2001 From: Karl Berry 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 @@ % \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}% % % \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