summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/tools/multicol.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2014-11-04 23:35:12 +0000
committerKarl Berry <karl@freefriends.org>2014-11-04 23:35:12 +0000
commita60e31b8abec7099c8e6dc5004b173897e28f34f (patch)
tree8c27c6351041ec3a1b3d176f8246e9e4fd10f813 /Master/texmf-dist/source/latex/tools/multicol.dtx
parentdbe0dfa8444b80708600bb095b9506d3c471a4a9 (diff)
latex2e multicol+doc (4nov14)
git-svn-id: svn://tug.org/texlive/trunk@35512 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.dtx133
1 files changed, 96 insertions, 37 deletions
diff --git a/Master/texmf-dist/source/latex/tools/multicol.dtx b/Master/texmf-dist/source/latex/tools/multicol.dtx
index 786517c0011..4e0fb6b16ab 100644
--- a/Master/texmf-dist/source/latex/tools/multicol.dtx
+++ b/Master/texmf-dist/source/latex/tools/multicol.dtx
@@ -69,7 +69,7 @@
%% - multicol is used for non-commercial purposes
%%
%%
-%% Determinating a license fee might result in a license fee of zero
+%% Determining a license fee might result in a license fee of zero
%% (i.e., no payment) in case a producer has determined that the use
%% of multicol has no enhancing effect on the product. This is a
%% plausible scenario, i.e., in the above two cases the producer is
@@ -91,10 +91,10 @@
%<driver> \ProvidesFile{multicol.drv}
% \fi
% \ProvidesFile{multicol.dtx}
- [2014/08/24 v1.8g multicolumn formatting (FMi)]
+ [2014/10/28 v1.8i multicolumn formatting (FMi)]
%
%
-%% \CheckSum{1840}
+%% \CheckSum{1853}
%% \CharacterTable
%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
@@ -197,7 +197,7 @@
% over to next page.
%
% Also added was support for |\enlargethispage|. This means it is
-% now possible to request a page to be artifically enlarged or
+% 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
% ensure that enough material is being picked up.
@@ -246,7 +246,7 @@
% \begin{multicols}{3}
% Right-to-left typesetting will only reverse the column orders. Any
% other support needed will have to be provided by other means,
-% e.g., using apprpriate fonts and reversing the writing directions
+% e.g., using appropriate fonts and reversing the writing directions
% within the columns. As footnotes are typeset in full measure the
% footnote rule needs to be redefined as if they are below a single
% column, i.e., using |\textwidth| not |\columnwidth|. For example:
@@ -267,7 +267,7 @@
% been added to the balancing routine. The balancing routine now
% checks the badness
% of the resulting columns and rejects solutions that are larger
-% than a certain treshold.
+% than a certain threshold.
% At the same time \mc{} has been upgraded to run under \LaTeXe{}.
%
% Later changes to 1.5 include |\columnbreak| and |multicols*|.
@@ -621,7 +621,7 @@
% inside `multicols' environment!}
%
% This message appears if you try to use the |\marginpar| command or
-% an unstared version of the {\sf figure} or {\sf table} environment.
+% an unstarred version of the {\sf figure} or {\sf table} environment.
% Such floats will disappear!
%
% \item[] {\hspace*{-\labelsep}\tt Very deep columns!
@@ -938,7 +938,7 @@
%<*package>
% \NeedsTeXFormat{LaTeX2e}
% \ProvidesPackage{multicol}[..../../..
-% v... multicolum formatting]
+% v... multicolumn formatting]
% \end{macrocode}
%
%^^A \subsection{Option processing}
@@ -1451,7 +1451,7 @@
% \begin{macrocode}
\advance\@colroom-\ht\partial@page
% \end{macrocode}
-% Then we have to calulate the |\vsize| value to use during column
+% Then we have to calculate the |\vsize| value to use during column
% assembly. |\set@mult@vsize| takes an argument which allows to
% make the setting local (|\relax|) or global (|\global|). The
% latter variant is used inside the output routine below. At this
@@ -1583,7 +1583,7 @@
% has the disadvantage that the resulting
% program cannot be called \TeX{} thereafter.}
% this simple trick saved us from rewriting the |\footnote|
-% macros. However, some applications refered to |\columnwidth| as
+% macros. However, some applications referred to |\columnwidth| as
% the ``width of the current column'' to typeset displays
% (the \texttt{amsmath} package, for example) and to allow the use
% of such applications together with \texttt{multicol} this is now
@@ -1718,7 +1718,7 @@
% \end{macrocode}
% If there was a |\columnbreak| on the very last line all material
% will have been moved to the |\colbreak@box|. Thus the the galley
-% will be ampty and no output routine gets called so that the text
+% will be empty and no output routine gets called so that the text
% is lost. To avoid this problem (though unlikely) we check if the
% current galley is empty and the |\colbreak@box| contains text and
% if so return that to the galley. If the galley is non-empty any
@@ -1772,7 +1772,7 @@
% case that the |\eject| will have no effect (since the main
% vertical list is empty)---thus no output routine is called at
% all. As a result the material preceding the \mc{} (stored in
-% |\partial@page| will get lost if we don't take of this by hand.
+% |\partial@page| will get lost if we don't put this back by hand.
% \changes{v1.4m}{1992/09/04}{Check \cs{partial@page} being emptied}
% \begin{macrocode}
\ifvbox\partial@page
@@ -1830,7 +1830,7 @@
% which can happen if there is a break point just before it (such
% as end ending environment) which was chosen. In that case we
% would do the next page using the internal |\vsize| for multicol
-% collection which is a desaster. So we better catch this
+% collection which is a disaster. So we better catch this
% case. Fortunately we can detect it by looking at |\pagegoal|.
% \changes{v1.5x}{2000/05/05}{Detect and fix problem if a multicols
% ends at the top of a page}
@@ -1843,6 +1843,19 @@
\fi
\addvspace\multicolsep
% \end{macrocode}
+% There is one more thing to do: the balanced result of the
+% environment is supposed to have a |\prevdepth| of zero as we
+% backed up by its real prevdepth within |\page@sofar|. However if
+% the balancing happened in the output routine then \TeX{} reverts
+% to the |\prevdepth| that was current before the OR once the OR has
+% finished. In short |\prevdepth| is something you can't set
+% globally it is alway local to the current list being built. Thus
+% we need to set it back to zero here to avoid incorrect spacing.
+% \changes{v1.8h}{2014/09/12}{Set \cs{prevdepdth} for current vlist
+% when returning from multicols environment}
+% \begin{macrocode}
+ \prevdepth\z@
+% \end{macrocode}
% If statistics are required we finally report that we have
% finished everything.
% \begin{macrocode}
@@ -2051,16 +2064,21 @@
% The depths of the columns depend on their last lines. To ensure
% that we will always get a similar look as far as the rules are
% concerned we force the depth to be at least the depth of a
-% letter~`p' (which is what we initialized |\dimen2| to above).
+% letter~`p' (which is what we set |\dimen2| to above).
% \begin{macrocode}
\rlap{\phantom p}%
}%
% \end{macrocode}
% The processed material might consist of a last line with a
-% decender in which case the |\prevdepth| will be
+% descender in which case the |\prevdepth| will be
% non-zero. However, this material is getting reformatted now so
% that this value is likely to be wrong. We therefore normalize the
-% situation by pretending that the depth is zero.
+% 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
+% 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.
% \changes{v1.8g}{2014/08/24}{Resetting \cs{prevdepth} in the right place}
% \begin{macrocode}
\prevdepth\z@
@@ -2118,6 +2136,23 @@
% \end{macro}
%
%
+% \begin{macro}{\vfillmaxdepth}
+% This curious definition is used as the space at the bottom of a
+% column if we implement |\raggedcolumns|. Normlly 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
+% would be allowed a depth of |\maxdepth|. So we allow shrinking by
+% that amount. This only makes a difference if the box would
+% otherwise become overfull and shrinking never exceeds the
+% specified value, so we should be fine.
+% \changes{v1.8h}{2014/09/12}{Macro added (pr/4395)}
+% \begin{macrocode}
+\def\vfillmaxdepth{\vskip \z@ \@plus 1fill \@minus \maxdepth}
+% \end{macrocode}
+% \end{macro}
+%
+%
% \begin{macro}{\multi@column@out}
% Now we can't postpone the difficulties any longer. The
% |\multi@column@out| routine will be called in two situations.
@@ -2229,18 +2264,20 @@
% this was wrong and unboxing is always needed.}
% \changes{v1.8b}{2013/08/28}{Remove discardable items at the
% end of split boxes}
+% \changes{v1.8h}{2014/09/12}{Use \cs{vfillmaxdepth}}
% \begin{macrocode}
\setbox\count@
\vbox to\dimen@
{\unvbox\count@
\remove@discardable@items
- \ifshr@nking\vfill\fi}%
+ \ifshr@nking\vfillmaxdepth\fi}%
}%
% \end{macrocode}
% Then the last column follows.
% \changes{v1.5a}{1992/11/04}{New box mechanism}
% \changes{v1.8b}{2013/08/28}{Remove discardable items at the
% end of split boxes}
+% \changes{v1.8h}{2014/09/12}{Use \cs{vfillmaxdepth}}
% \begin{macrocode}
\setbox\mult@rightbox
\vsplit\@cclv to\dimen@
@@ -2248,7 +2285,7 @@
\setbox\mult@rightbox\vbox to\dimen@
{\unvbox\mult@rightbox
\remove@discardable@items
- \ifshr@nking\vfill\fi}%
+ \ifshr@nking\vfillmaxdepth\fi}%
% \end{macrocode}
% Now that we are done with the boxes, we restored the current
% setting for shrinking in case it got changed:
@@ -2258,7 +2295,7 @@
% Having done this we hope that box 255 is emptied. If not, we
% reinsert its contents.
% \changes{v1.8a}{2011/12/20}{Only re-add output penalty if it was
-% explictly set}
+% explicitly set}
% \begin{macrocode}
\ifvoid\@cclv \else
\unvbox\@cclv
@@ -2360,7 +2397,7 @@
% \end{macrocode}
% After the page is shipped out we have to prepare the kept marks
% for the following page. |\kept@firstmark| and |\kept@botmark|
-% reinitilized by setting them to |\@empty|. The value of
+% reinitialized by setting them to |\@empty|. The value of
% |\botmark| is then assigned to |\kept@topmark|.
% \changes{v1.4g}{1992/06/03}{Only change \cs{kept@topmark} if
% \cs{kept@botmark} non-empty}
@@ -2378,7 +2415,7 @@
% \end{macrocode}
% Now we reset |\@colroom| to |\@colht| which is \LaTeX's
% saved value of |\textheight|.
-% We also ahve to reset the recorded position of the last
+% We also have to reset the recorded position of the last
% |\marginpar| as we are now on a new page.
% \changes{v1.8d}{2014/04/23}{Reset \cs{@mparbottom} after page finishes}
% \begin{macrocode}
@@ -2699,7 +2736,7 @@
% \begin{macrocode}
\get@keptmarks\mult@box
% \end{macrocode}
-% We then contine by resetting trying to remove any discardable
+% We then continue by resetting trying to remove any discardable
% stuff at the end of |\mult@box|. This is rather experimental. We
% also add a forced break point at the very beginning, so that we
% can split the box to height zero later on, thereby adding a known
@@ -2723,6 +2760,16 @@
\@minus\multicolovershoot
\splitmaxdepth\maxdepth
% \end{macrocode}
+% We also have to set |\boxmaxdepth| which normally allows to
+% build boxes with arbitrary depth, but as we are building text
+% columns we really want to restrict the depth. This is necessary as
+% we sometimes rebox the boxes generated by |\vsplit| and then the
+% restriction posed by |\splitmaxdepth| gets lost.
+% \changes{v1.8h}{2014/09/12}{All column boxes should obey
+% \cs{maxdepth} (pr/4395)}
+% \begin{macrocode}
+ \boxmaxdepth\maxdepth
+% \end{macrocode}
% The next step is a bit tricky: when \TeX{} assembles material in
% a box, the first line isn't preceded by interline glue, i.e.
% there is no parameter like |\boxtopskip| in \TeX{}. This means
@@ -2812,9 +2859,10 @@
\vbadness\@M
% \end{macrocode}
% We also allow for overfull boxes while we trying to split the
-% columns.
+% columns. They can easily happen if we have objects with unusual depth.
+% \changes{v1.8h}{2014/09/12}{Do not report overfull}
% \begin{macrocode}
- \vfuzz \col@number\baselineskip
+ \vfuzz \maxdimen
% \end{macrocode}
% The variable |\last@try| will hold the dimension used in the
% previous trial splitting. We initialize it with a negative value.
@@ -2899,7 +2947,8 @@
}}%
% \end{macrocode}
% There is one subtle point here: while all other constructed boxes
-% have a depth that is determined by |\splitmaxdepth| the last box
+% have a depth that is determined by |\splitmaxdepth| and/or
+% |\boxmaxdepth| the last box
% will get a natural depth disregarding the original setting and
% the value of |\splitmaxdepth| or |\boxmaxdepth|. This means that
% we may end up with a very large depth in box |\mult@grightbox|
@@ -2907,7 +2956,6 @@
% make the result of the testing incorrect. So we change the value
% by unboxing the box into itself.
% \begin{macrocode}
- \boxmaxdepth\maxdepth
\global\setbox\mult@grightbox
\vbox{\unvbox\mult@grightbox}%
% \end{macrocode}
@@ -2991,7 +3039,7 @@
% If the height of the last box is too large we mark this trial as
% unsuccessful.
% \changes{v1.5v}{1999/07/18}{Added tracing statements for
-% trial unsuccesful}
+% trial unsuccessful}
% \begin{macrocode}
%<*badness>
\too@badtrue
@@ -3038,11 +3086,12 @@
% We then compare this badness with the allowed badness for the final
% column. If it does not exceed this value we use the box, otherwise
% we rebox it once more and add some glue at the bottom.
+% \changes{v1.8h}{2014/09/12}{Use \cs{vfillmaxdepth}}
% \begin{macrocode}
\ifnum\badness>\c@finalcolumnbadness
\global\setbox\mult@grightbox
\vbox to\dimen@
- {\unvbox\mult@grightbox\vfill}%
+ {\unvbox\mult@grightbox\vfillmaxdepth}%
\ifnum\c@tracingmulticols>\@ne
\message{ setting natural
(> \the\c@finalcolumnbadness)}%
@@ -3066,7 +3115,7 @@
% \end{macrocode}
% If the natural height of the first box is smaller than the
% current trial size but is larger than the previous trial size it
-% is likely that we have missed a potientially better
+% is likely that we have missed a potentially better
% solution. (This could have happened if for some reason our first
% trial size was too high.) In that case we dismiss this trial and
% restart using the natural height for the next trial.
@@ -3096,7 +3145,7 @@
% At that point |\dimen@| holds the height that was determined by
% the balancing loop.
% If that height for the columns turns out to be larger
-% than the available space (which is |\@colroom|) we sqeeze the
+% than the available space (which is |\@colroom|) we squeeze the
% columns into the space assuming that they will have enough
% shrinkability to allow this.\footnote{This might be wrong, since
% the shrinkability that accounts for the amount of material might
@@ -3139,12 +3188,13 @@
{%
% \end{macrocode}
%
+% \changes{v1.8h}{2014/09/12}{Use \cs{vfillmaxdepth}}
% \begin{macrocode}
\vskip \z@
\@plus-\multicolundershoot
\@minus-\multicolovershoot
\unvbox\@tempcnta
- \ifshr@nking\vfill\fi
+ \ifshr@nking\vfillmaxdepth\fi
}%
% \end{macrocode}
% If the resulting box is overfull there was too much material to
@@ -3280,7 +3330,7 @@
\@largefloatcheck
\outer@nobreak
% \end{macrocode}
-% This is cheap (defering the floats until after the current page)
+% This is cheap (deferring the floats until after the current page)
% but any other solution would go deep into \LaTeX's output
% routine and I don't like to work on it until I know which parts
% of the output routine have to be reimplemented anyway for
@@ -3510,7 +3560,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. This
-% will not remove an extremly long sequence of spaces and
+% will not remove an extremely long sequence of spaces and
% penalties, but in nearly all cases this will be enough.
% \begin{macrocode}
\def\remove@discardable@items{%
@@ -3609,7 +3659,7 @@
% definition.
%
% Starting with version v1.5r this is now done in a way that the original
-% definition is still used, execpt that locally |\columnwidth| is set to
+% definition is still used, except that locally |\columnwidth| is set to
% |\textwidth|.
%
% This solves two problems: first redefinitions of |\@footnotetext|
@@ -3667,10 +3717,19 @@
% When ending the environment we simply end the inner
% \texttt{multicols} environment, except that we better also stick
% in some stretchable vertical glue so that the last column still
-% containing text is not vertically stretched out.
+% containing text is not vertically stretched out. The final |\null| hides this space
+% so that it doesn't get removed again when the columns are assembled.
+% However, we only do this if we aren't already doing |\raggedcolumns|
+% because it would be a mistake to add such glue twice. After all it contains
+% a minus component of |\maxdepth| and that would then be applied twice!
% \changes{v1.5q}{1998/01/19}{Macro added}
+% \changes{v1.8h}{2014/09/12}{Use \cs{vfillmaxdepth}}
+% \changes{v1.8i}{2014/10/28}{Add \cs{null} to hide the final fill and only add
+% vertical space if not doing \cs{raggedcolumns}}
% \begin{macrocode}
- \@namedef{endmulticols*}{\vfill
+ \@namedef{endmulticols*}{\ifshr@nking\else
+ \vfillmaxdepth\nointerlineskip\null
+ \fi
\end{multicols}}
%</nobalance>
% \end{macrocode}
@@ -4013,7 +4072,7 @@
%\mc@set@col@status{lcol-4}{0}
%\end{verbatim}
% The \verb=\mc@col@status= line denotes the column type and has been
-% writting out just before corresponding the column box was placed
+% written out just before corresponding the column box was placed
% onto the page.
% The\verb=\mc@set@col@status= lines have been written out as part
% of shipping the column boxes out, e.g.,