Update LuaTeX testfiles for ^@ change
[latex2e.git] / latex2e-20170101 / required / tools / multicol.dtx
blobc64c9901e89ea793b97c538e6c47e6dec9082920
1 % \iffalse meta-comment
4 % This file is part of the Standard LaTeX `Tools Bundle'.
5 % -------------------------------------------------------
7 % It may be distributed and/or modified under the
8 % conditions of the LaTeX Project Public License, either version 1.3c
9 % of this license or (at your option) any later version.
10 % The latest version of this license is in
11 %    http://www.latex-project.org/lppl.txt
12 % and version 1.3c or later is part of all distributions of LaTeX
13 % version 2005/12/01 or later.
15 % The list of all files belonging to the LaTeX `Tools Bundle' is
16 % given in the file `manifest.txt'.
18 % \fi
20 % \iffalse    This is a METACOMMENT
22 %% Package `multicol' to use with LaTeX2e
23 %% Copyright 1989-2016 Frank Mittelbach
25 %%  In addition to the terms of LPPL any distributed version
26 %%  (unchanged or modified) of multicol has to keep the statement
27 %%  about the moral obligation for using multicol. In case of major
28 %%  changes where this would not be appropriate the author of the
29 %%  changed version should contact the copyright holder.
32 %%  Moral obligation for using multicol:
33 %%  ------------------------------------
35 %%  Users of multicol who wish to include or use multicol or a modified
36 %%  version in a proprietary and commercially market product are asked
37 %%  under certain conditions (see below) for the payment of a license
38 %%  fee.  The size of this fee is to be determined, in each instance,
39 %%  by the commercial user, depending on his/her judgment of the value of
40 %%  multicol for his/her product.
43 %%  The conditions for this are as follows:
45 %%   The producer of a proprietary and commercially market product
46 %%   that involves typesetting using multicol is asked to determine
47 %%   the value of a license fee for using multicol if
49 %%   - the product is a document and the producer has decided to
50 %%     include multicol to typeset (parts of) the document or has
51 %%     directed the author of the document to include multicol (for
52 %%     example, by providing a class file to be used by the author)
54 %%   - the product is a LaTeX class or package that includes multicol
57 %%   There is no moral obligation in case
59 %%   - the product is a document but producer has not directed
60 %%     the author to include multicol (in that case the moral obligation
61 %%     lies with the author of the document)
63 %%   - the product does not involve typesetting, e.g., consists, for
64 %%     example, of distributing multicol and its documentation.
66 %%   - the product is not proprietary, i.e., is made available as free
67 %%     software itself (which doesn't prohibit its commercial marketing)
69 %%   - multicol is used for non-commercial purposes
72 %% Determining a license fee might result in a license fee of zero
73 %% (i.e., no payment) in case a producer has determined that the use
74 %% of multicol has no enhancing effect on the product. This is a
75 %% plausible scenario, i.e., in the above two cases the producer is
76 %% only asked to evaluate the value of multicol for the product
77 %% not for the payment of a license fee per se (which might or might
78 %% not follow from this evaluation).
80 %% The license fee, if any, can be payed either to the LaTeX3 fund
81 %% (see ltx3info.txt in the base LaTeX distribution) or to the author of
82 %% the program who can be contacted at
84 %%     Frank.Mittelbach@latex-project.org
86 %<*dtx>
87           \ProvidesFile{multicol.dtx}
88 %</dtx>
89 %<package>\NeedsTeXFormat{LaTeX2e}[1997/12/01]
90 %<package>\ProvidesPackage{multicol}
91 %<driver> \ProvidesFile{multicol.drv}
92 % \fi
93 %         \ProvidesFile{multicol.dtx}
94           [2016/04/07 v1.8p  multicolumn formatting (FMi)]
99 % \changes{v1.5n}{1997/06/05}{Applied improvement of documentation,
100 %          kindly done by Robin Fairbairns.}
101 % \changes{v1.4h}{1992/06/04}{Added mark tracing with
102 %                           tracingmulticols$\ge2$}
103 % \changes{v1.4a}{1992/02/11}{Added support for multicol in inner mode}
104 % \changes{v1.0d}{1989/05/17}{All lines shortened to 72 or less.}
105 % \changes{v1.0e}{1989/06/21}{Redefinition of description env. to use
106 %                           \cs{descriptionmargin}\quotechar=5pt
107 %                           in documentation.}
108 % \changes{v1.0f}{1989/07/11}{Changed \cs{z@} to 0pt in redefinition of
109 %                           description.}
110 % \changes{v1.1a}{1989/09/20}{\cs{multicolssep} changed to \cs{multicolsep}.}
112 % \def\description{\list{}{\labelwidth 0pt \leftmargin\descriptionmargin
113 %    \itemindent-\leftmargin \let\makelabel\descriptionlabel}}
114 % \newdimen\descriptionmargin \descriptionmargin=5pt
116 % \DoNotIndex{\@M,\@Mi,\@bsphack,\@cclv,\@colht,\@currlist,\@deferlist}
117 % \DoNotIndex{\@elt,\@esphack,\@floatplacement}
118 % \DoNotIndex{\@ifundefined,\@ifnextchar,\@makecol}
119 % \DoNotIndex{\@ne,\@outputpage,\@scolelt,\@spaces,\@tempb,\@tempcnta}
120 % \DoNotIndex{\@width}
121 % \DoNotIndex{\addvspace,\advance,\allowbreak}
122 % \DoNotIndex{\baselineskip,\begingroup,\box,\columnsep,\copy,\count}
123 % \DoNotIndex{\count@,\def,\dimen@,\divide,\docdate}
124 % \DoNotIndex{\edef,\eject,\egroup,\else,\endgroup,\endinput}
125 % \DoNotIndex{\fi,\fileversion,\filedate}
126 % \DoNotIndex{\gdef,\global}
127 % \DoNotIndex{\hbox,\hfil,\hrule,\ht,\hss}
128 % \DoNotIndex{\ifdim,\ifnum,\ifvoid,\ignorespaces,\insert,\immediate}
129 % \DoNotIndex{\let,\loop}
130 % \DoNotIndex{\maxdepth,\message,\multiply}
131 % \DoNotIndex{\newbox,\newcount,\newdimen,\newskip,\number,\newpage}
132 % \DoNotIndex{\outputpenalty,\p@,\penalty}
133 % \DoNotIndex{\relax,\repeat,\setbox,\skip,\space,\splitmaxdepth}
134 % \DoNotIndex{\splittopskip,\string,\sixt@@n}
135 % \DoNotIndex{\the,\thepage,\thr@@,\topskip,\tw@,\typeout}
136 % \DoNotIndex{\unvbox,\vbox,\vfill,\vsplit,\voidb@x,\vrule}
137 % \DoNotIndex{\write,\wd}
138 % \DoNotIndex{\z@}
140 % \MakeShortVerb{\|}
141 % \newcommand{\mc}{{\sf multicols}}
142 % \newcommand{\TUB}{{\sl TUGboat\/}}
143 % \newcommand{\TB}{{\sl\TeX book\/}}
146 % \setcounter{StandardModuleDepth}{2}
147 % \setcounter{collectmore}{3}
149 % \GetFileInfo{multicol.dtx}
150 % \title{An environment for multicolumn output\thanks{This file
151 %        has version number \fileversion, last
152 %        revised \filedate.}%
153 %       \thanks{Note: This package is released under terms which affect
154 %       its use in commercial applications. Please see the details at
155 %       the top of the source file.}}
156 % \author{Frank Mittelbach\\
157 %       {\rm Email:} see top of the source file}
158 % \date{Printed \today}
160 % \MaintainedByLaTeXTeam{tools}
161 % \maketitle
163 % \begin{abstract}
164 %   This article describes the use and the implementation of the \mc{}
165 %   environment. This environment allows switching between
166 %   one and multicolumn format on the same page. Footnotes are handled
167 %   correctly (for the most part), but will be placed at the bottom of
168 %   the page and not under each column.  \LaTeX{}'s float mechanism,
169 %   however, is partly disabled in this implementation.  At the
170 %   moment only page-wide floats (i.e., star-forms) can be used within
171 %   the scope of the environment.
172 % \end{abstract}
174 % \begin{multicols}{3}[\section*{Preface to version 1.8}]
175 %    The 1.8 release improves on the balancing approach. If due to a
176 %    limited number of break points (e.g., due to large objects) the
177 %    balanced columns exceed the available vertical space, then
178 %    balancing is canceled and a normal page is produced first. Some
179 %    overflow is allowed (controlled by the parameter
180 %    |\maxbalancingoverflow| which defaults to 12pt). This ensures
181 %    that we only cut a normal page if we get enough material carried
182 %    over to next page.
184 %    Also added was support for |\enlargethispage|. This means it is
185 %    now possible to request a page to be artificially  enlarged or
186 %    shortened. Note that if you enlarge pages by more than one line
187 %    you may have to increase the {\sf collectmore} counter value to
188 %    ensure that enough material is being picked up.
190 %    This command was used on the second page of this manual to shorten
191 %    it by one line, in order to get rid of a number of widow lines on
192 %    the following pages.
195 %    Finally, version 1.8 adds the command |\docolaction| to help with
196 %   more complicated actions that depend on the current column. This
197 %   command expects 3 arguments: code that is executed if we are in
198 %   the ``first'' column, code to execute if we end up in any
199 %   ``middle'' column (if there are more than two) and finally code to
200 %   execute if we are in the ``last'' column. Thus
201 %\begin{verbatim}
202 %  \docolaction{first}
203 %              {middle}{last}
204 %\end{verbatim}
205 %   would typeset a different word depending the type of column this
206 %   code is executed. Using it like this is probably pointless, but
207 %   you can imagine applications like writing something into the
208 %   nearest margin, etc.
210 %   As this feature needs at least two \LaTeX{} runs to produce correct
211 %   results and as it adds to the processing complexity it is only
212 %   made available if one add the option \texttt{colaction} when
213 %   loading the package.
215 % \end{multicols}
218 % \begin{multicols}{3}[\section*{Preface to version 1.7
219 %                         (right to left support)}]
220 %    The 1.7 release adds support for languages that are typeset
221 %    right-to-left. For those languages the order of the columns on the page
222 %    also need to be reversed---something that wasn't supported before. The next
223 %    paragraph demonstrates the result (as it is typeset as if we are writing
224 %    in a left-to-right language--- so read the rightmost column
225 %    first). The change is initialized via
226 %    |\RLmulticolcolumns| and returning to left-right (default)
227 %    is done via |\LRmulticolcolumns|.
228 % \end{multicols}
230 % \RLmulticolcolumns
232 % \begin{multicols}{3}
233 %    Right-to-left typesetting will only reverse the column orders. Any
234 %    other support needed will have to be provided by other means,
235 %    e.g., using appropriate fonts and reversing the writing directions
236 %    within the columns. As footnotes are typeset in full measure the
237 %    footnote rule needs to be redefined as if they are below a single
238 %    column, i.e., using |\textwidth| not |\columnwidth|. For example:
239 %\begin{verbatim}
240 %\renewcommand \footnoterule{%
241 %  \kern-3pt\hbox to\textwidth
242 %    {\hskip .6\textwidth
243 %     \hrulefill }%
244 %  \kern2.6pt}
245 %\end{verbatim}
246 % \end{multicols}
248 % \LRmulticolcolumns
250 % \begin{multicols}{3}[\section*{Preface to version 1.5 + 1.6}]
251 %   \hbadness=10000
252 %   The 1.5 release contains two major changes: \mc{} will now
253 %   support up to 10 columns and two more tuning possibilities have
254 %   been added to the balancing routine. The balancing routine now
255 %   checks the badness
256 %   of the resulting columns and rejects solutions that are larger
257 %   than a certain threshold.
258 %   At the same time \mc{} has been upgraded to run under \LaTeXe{}.
260 %   Later changes to 1.5 include |\columnbreak| and |multicols*|.
262 %   For version 1.6 micro-spacing around the boxes produced by \mc{}
263 %   has been improved to allow for baseline-grid typesetting.
264 % \end{multicols}
267 % \setcounter{collectmore}{2}
268 % \begin{multicols}{3}[\section{Introduction}]
269 %   \hbadness=10000
270 %   Switching between two-column and one-column layout is possible in
271 %   \LaTeX{}, but every use of |\twocolumn| or |\onecolumn|
272 %   starts a new page. Moreover, the last page of two-column output
273 %   isn't balanced and this often results in an empty, or nearly
274 %   empty, right column. When I started to write macros for {\sf
275 %   doc.sty} (see ``The {\tt doc}--Option'', \TUB\
276 %   volume 10~\#2, pp.~245--273) I thought that it would be nice to
277 %   place the index
278 %   on the same page as the bibliography. And balancing the last page
279 %   would not only look better, it also would save space; provided of
280 %   course that it is also possible to start the next article on the
281 %   same page. Rewriting the index environment was comparatively easy,
282 %   but the next goal, designing an environment which takes care of
283 %   footnotes, floats, etc., was a harder task. It took me a whole
284 %   weekend\footnote{I started with the algorithm given in the \TeX
285 %   book on page 417. Without this help a weekend would not have been
286 %   enough. (This remark was made in the documentation of the initial
287 %    release, since then several hundreds more hours went into
288 %    improving the original code.)} to get together the few lines of
289 %    code below and there is
290 %   still a good chance that I missed something after all.
292 %   Try it and, hopefully, enjoy it; and {\em please\/} direct bug
293 %   reports and suggestions back to Mainz.
294 % \end{multicols}
297 % \setcounter{collectmore}{0}
298 % \begin{multicols}{3}[\section{The User Interface}]
299 %   \hbadness=10000
300 %   To use the environment one simply says\\*[2mm]
301 %     \hspace*{2mm}|\begin{multicols}{|\meta{number}|}|
302 %     \hspace*{12mm}\meta{multicolumn text}\\
303 %     \hspace*{2mm}|\end{multicols}|\\[2mm]
304 %   where \meta{number} is the required number of columns and
305 %^^A\meta{multicolumn text}
306 %   $\langle${\it multi\-column text\/}$\rangle$ may contain arbitrary
307 %   \LaTeX{} commands, except that floats and marginpars are not
308 %   allowed in the current implementation\footnote{This is dictated by
309 %   lack of time.  To implement floats one has to reimplement the
310 %   whole \LaTeX{} output routine.}.
312 % \enlargethispage{-1\baselineskip}
314 % \DescribeMacro\premulticols
315 % As its first action, the {\sf multicols} environment measures the
316 % current page to determine whether there is enough room for some
317 % portion of multicolumn output. This is controlled by the
318 % \meta{dimen} variable |\premulticols| which can be changed by
319 % the user with ordinary \LaTeX{} commands.
320 % \DescribeMacro\multicolsep
321 % If the space is less than |\premulticols|, a new page is
322 % started.  Otherwise, a |\vskip| of |\multicolsep| is
323 % added.\footnote{Actually the added space may be less because we use
324 % \cs{addvspace} (see the \LaTeX{} manual for further
325 % information about this command).}
327 % \DescribeMacro\postmulticols
328 % When the end of the \mc{} environment is encountered, an
329 % analogous mechanism is employed, but now we test whether there is a
330 % space larger than |\postmulticols| available. Again we add
331 % |\multicolsep| or start a new page.
333 % It is often convenient to spread some text over all columns, just
334 % before the multicolumn output, without any page break in between. To
335 % achieve this the \mc{} environment has an optional second
336 % argument which can be used for this purpose. For example, the text
337 % you are now reading was started with
338 % \begin{verbatim}
339 % \begin{multicols}{3}
340 %   [\section{The User
341 %             Interface}] ...
342 %\end{verbatim}
343 % If such text is unusually long (or short) the value of
344 % |\premulticols| might need adjusting to prevent a bad page
345 % break.  We therefore provide a third argument which can be used to
346 % overwrite the default value of |\premulticols| just for this
347 % occasion. So if you want to combine some longer single column text
348 % with a multicols environment you could write
349 % \begin{verbatim}
350 % \begin{multicols}{3}
351 %     [\section{Index}
352 %      This index contains ...]
353 %     [6cm]
354 %  ...
355 %\end{verbatim}
358 % \DescribeMacro\columnsep
359 % The space between columns is controlled by the length parameter
360 % |\columnsep|. The width for the individual columns is automatically
361 % calculated from this parameter and the current |\linewidth|. In this
362 % article a value of \textsf{\the\columnsep} was used.
365 % \DescribeMacro\columnseprule
366 % Separation of columns with vertical rules is achieved by setting the
367 % parameter |\columnseprule| to some positive value.  In this
368 % article a value of {\sf.4pt} was used.
370 % \DescribeMacro\columnseprulecolor
371 % The color of the rules separating the columns can be specified through
372 % |\columnseprulecolor|. The default value is |\normalcolor|.
374 % \DescribeMacro\multicolbaselineskip
375 % Since narrow columns tend to need adjustments in interline spacing
376 % we also provide a \meta{skip} parameter called
377 % |\multicolbaselineskip| which is added to the
378 % |\baselineskip| parameter inside the \mc{}
379 % environment.  Please use this parameter with care or leave it alone;
380 % it is intended only for package file designers since even small
381 % changes might produce totally unexpected changes to your document.
384 %    \subsection{Balancing columns}
387 % Besides the previously mentioned parameters, some others are
388 % provided to influence the layout of the columns generated.
390 % Paragraphing in \TeX{} is controlled by several parameters. One of
391 % the most important is called |\tolerance|: this controls the
392 % allowed `looseness' (i.e.\ the amount of blank space between words).
393 % Its default value is 200 (the \LaTeX{} |\fussy|) which is too
394 % small for narrow columns. On the other hand the |\sloppy|
395 % declaration (which sets |\tolerance| to $10000=\infty$) is too
396 % large, allowing really bad spacing.\footnote{Look at the next
397 % paragraph, it was set with the \cs{sloppy} declaration.}
399 % \begin{sloppypar}
400 % \DescribeMacro\multicoltolerance \DescribeMacro\multicolpretolerance
401 %  We therefore use a |\multicoltolerance| parameter for the
402 % |\tolerance| value inside the \mc{} environment.  Its default value
403 % is 9999 which is less than infinity but `bad' enough for most
404 % paragraphs in a multicolumn environment. Changing its value should
405 % be done outside the \mc{} environment.  Since |\tolerance| is set
406 % to |\multicoltolerance| at the beginning of every {\sf multicols}
407 % environment one can locally overwrite this default by assigning
408 % \verb*+\tolerance = +\meta{desired value}. There also exists a
409 % |\multicolpretolerance| parameter holding the value for
410 % |\pretolerance| within a \mc{} environment. Both parameters are
411 % usually used only by package designers.
412 % \end{sloppypar}
414 % Generation of multicolumn output can be divided into two parts.  In
415 % the first part we are collecting material for a page, shipping it
416 % out, collecting material for the next page, and so on.  As a second
417 % step, balancing will be done when the end of the \mc{} environment
418 % is reached.
419 % In the first step \TeX{} might consider more material whilst
420 % finding the final column content than it actually uses when shipping out the
421 % page. This might cause a problem if a footnote is encountered in
422 % the part of the input considered, but not used, on the current page.
423 % In this case the footnote might show up on the current page, while the
424 % footnotemark corresponding to this footnote might be set on the next
425 % one.\footnote{The reason behind this behavior is the asynchronous
426 %               character of the \TeX{} {\it page\_builder}.
427 %               However, this
428 %               could be avoided by defining very complicated output
429 %               routines which don't use \TeX{} primitives like
430 %               \cs{insert} but do everything by hand.
431 %               This is clearly beyond the scope of a weekend problem.}
432 % Therefore the \mc{} environment gives a warning
433 % message\footnote{This message will be generated even if there are no
434 % footnotes in this part of the text.} whenever it is unable to use
435 % all the material considered so far.
437 % If you don't use footnotes too often the chances of something
438 % actually going wrong are very slim, but if this happens you can help
439 % \TeX{} by using a |\pagebreak| command in the final document.
440 % Another way to influence the behavior of \TeX{} in this respect is
441 % given by the counter variable `{\sf collectmore}'. If you use the
442 % |\setcounter| declaration to set this counter to \meta{number},
443 % \TeX{} will consider \meta{number} more (or less) lines before
444 % making its final decision. So a value of $-1$ may solve all your
445 % problems at the cost of slightly less optimal columns.
448 % In the second step (balancing columns) we have other bells and
449 % whistles. First of all you can say |\raggedcolumns| if you
450 % don't want the bottom lines to be aligned.
451 % The default is |\flushcolumns|, so \TeX{} will normally try to
452 % make both
453 % the top and bottom baselines of all columns align.
455 % Additionally you can set another counter, the `{\sf unbalance}'
456 % counter, to some positive \meta{number}. This will make all but the
457 % right-most column \meta{number} of lines longer than they would
458 % normally have been. `Lines' in this context refer to normal text
459 % lines (i.e.\ one |\baselineskip| apart); thus, if your columns
460 % contain displays,
461 % for example, you may need a higher \meta{number}
462 % to shift something from one column into another.
464 % Unlike `{\sf collectmore},' the `{\sf unbalance}' counter is reset
465 % to zero at the end of the environment so it only applies to one
466 % \mc{} environment.
468 % The two methods may be combined but I suggest using these features
469 % only when fine tuning important publications.
471 % Two more general tuning possibilities were added with version~1.5.
472 % \TeX{} allows to measure the badness of a column in terms of an
473 % integer value, where 0 means optimal and any higher value means a
474 % certain amount of extra white space. 10000 is considered to be
475 % infinitely bad (\TeX{} does not distinguish any further). In addition
476 % the special value 100000 means overfull (i.e., the column contains
477 % more text than could possibly fit into it).
479 % The new release now measures every generated column and ignores
480 % solutions where at least one column has a badness being larger than
481 % the value of the counter {\sf columnbadness}. The default value for
482 % this counter is 10000, thus \TeX{} will accept all solutions except
483 % those being overfull.
484 % By setting the counter to a smaller value you can force the algorithm
485 % to search for solutions that do not have columns with a lot of white
486 % space.
488 % However, if the setting is too low, the algorithm may not find any
489 % acceptable solution at all and will then finally choose the extreme
490 % solution of placing all text into the first column.
492 % Often, when columns are balanced, it is impossible to find a solution
493 % that distributes the text evenly over all columns. If that is the case
494 % the last column usually has less text than the others. In the earlier
495 % releases this text was stretched to produce a column with the same
496 % height as all others, sometimes resulting in really ugly looking
497 % columns.
499 % In the new release this stretching is only done if the badness of
500 % the final column is not larger than the value of the counter
501 % {\sf finalcolumnbadness}. The default setting is 9999, thus preventing
502 % the stretching for all columns that \TeX{} would consider infinitely
503 % bad. In that case the final column is allowed to run short which gives
504 % a much better result.
506 % And there are two more parameters of some experimental nature, one
507 % called |\multicolovershoot| the other |\multicolundershoot|.  They
508 % control the amount of space a column within the \mc{} environment is
509 % allowed to be ``too full'' or ``too short'' without affecting the
510 % column badness. They are set to 0pt and 2pt, respectively.
512 % Finally, when doing the balancing at the end, columns may become
513 % higher than the remaining available space. In that case the
514 % algorithm aborts and instead generates a normal page. However, if the
515 % amount is not too large, e.g., a line or so, then it might be better to
516 % keep everything on the same page instead of starting a new page with
517 % just one line after balancing. So the parameter
518 % |\maxbalancingoverflow| governs this process: only when the excess
519 % gets larger than its value balancing is aborted.
521 % \subsection{Not balancing the columns}
523 % Although this package was written to solve the problem of balancing
524 % columns, I got repeated requests to provide a version where all
525 % white space is automatically placed in the last column or
526 % columns. Since version v1.5q this now exists: if you use
527 % \texttt{multicols*} instead of the usual environment the columns on
528 % the last page are not  balanced. Of course, this environment only
529 % works on top-level, e.g., inside a box one has to balance to
530 % determine a column height in absence of a fixed value.
533 % \subsection{Manually breaking columns}
535 % Another request often voiced was: ``How do I tell \LaTeX{} that it
536 % should break the first column after this particular line?''. The
537 % |\pagebreak| command (which works with the two-column option of
538 % \LaTeX{}) is of no use here since it would end the collection phase
539 % of \mc{} and thus all columns on that page. So with version 1.5u
540 % the |\columnbreak| command was added. If used within a paragraph it
541 % marks the end of the current line as the desired breakpoint. You can
542 % observe its effect on
543 % the previous page where three lines of text have been artificially
544 % forced into the second column  (resulting in some white
545 % space between paragraphs in the first column).
547 % \subsection{Floats inside a \mc{} environment}
549 % Within the \mc{} environment the usual star float commands are
550 % available but their function is somewhat different as in the
551 % two-column mode of standard \LaTeX. Stared floats, e.g., {\tt
552 % figure*}, denote page wide floats that are handled in a similar
553 % fashion as normal floats outside the \mc{} environment. However,
554 % they will never show up on the page where they are encountered. In
555 % other words, one can influence their placement by specifying a
556 % combination of {\tt t}, {\tt b}, and/or {\tt p} in their optional
557 % argument, but {\tt h} doesn't work because the first possible place
558 % is the top of the next page. One should also note, that this means
559 % that their placement behavior is determined by the values of
560 % |\topfraction|, etc.\ rather than by |\dbl...|.
563 % \subsection{Support for right-to-left typesetting}
565 %    In right-to-left typesetting the order of the columns on the page
566 %    also need to be reversed, i.e., the first column has to appear on the far
567 %    right and the last column on the left. This is supported through the
568 %    commands |\RLmulticolcolumns| (switching to right-to-left typesetting)
569 %    and |\LRmulticolcolumns| (switching to left-to-right typesetting) the
570 %    latter being the default.
572 % \subsection{Warnings}
574 % Under certain circumstances the use of the \mc{} environment may
575 % result in some
576 % warnings from \TeX{} or \LaTeX{}. Here is a list
577 % of the important ones and the possible cause:
578 % \begin{description}
580 % \item[] {\hspace*{-\labelsep}\tt Underfull \string\hbox\space
581 %  (badness ...)}
583 %  As the columns are often very narrow \TeX{} wasn't able to find a
584 %  good way to break the paragraph. Underfull denotes a loose line but
585 %  as long as the badness value is below $10000$ the result is probably
586 %  acceptable.
588 % \item[]
589 % {\hspace*{-\labelsep}\tt Underfull \string\vbox\space ...  while
590 %  \string\output\space is active}
592 %  If a column contains a character with an unusual depth, for
593 %  example a `(', in the bottom line then this message may show up. It
594 %  usually has no significance as long as the value is not more than a
595 %  few points.
597 % \item[] {\hspace*{-\labelsep}\tt LaTeX Warning: I moved some lines
598 %  to the next page}
600 %  As mentioned above, \mc{} sometimes screws up the footnote
601 %  numbering. As a precaution, whenever there is a footnote on a
602 %  page where \mc{} had to leave a remainder for the following
603 %  page this warning appears. Check the footnote numbering on this
604 %  page. If it turns out that it is wrong, you have to manually break
605 %  the page using |\newpage| or |\pagebreak[..]|.
607 % \item[] {\hspace*{-\labelsep}\tt Floats and marginpars not allowed
608 %  inside `multicols' environment!}
610 %  This message appears if you try to use the |\marginpar| command or
611 %  an unstarred version of the {\sf figure} or {\sf table} environment.
612 %  Such floats will disappear!
614 % \item[] {\hspace*{-\labelsep}\tt Very deep columns!
615 %          Grid alignment might be broken}
617 % This message can only appear if the option \texttt{grid} was
618 %    chosen. In that case it will show up if a column has a very large
619 %    depth so that \mc{} is unable to back up to its baseline. This
620 %    is only relevant if one tries to produce a document where all
621 %    text lines are aligned at an invisible grid, something that
622 %    requires careful adjustment of many parameters and macros, e.g.,
623 %    heading definitions.
625 % \end{description}
628 % \subsection{Tracing the output}
630 % To understand the reasoning behind the decisions \TeX{} makes when
631 % processing a \mc{} environment, a tracing mechanism is provided.
632 % If you set the counter `\texttt{tracingmulticols}'
633 % to a positive \meta{number} you then
634 % will get some tracing information on the terminal and in the
635 % transcript file:
636 % \begin{description}
637 % \item[$\meta{number}=1$.]  \TeX{} will now tell you, whenever it
638 %    enters or leaves a \mc{} environment, the number of columns it
639 %    is working on and its decision about starting a new page before
640 %    or after the environment.
641 % \item[$\meta{number}=2$.]
642 %    In this case you also get information from the balancing routine:
643 %    the heights tried for the left and right-most columns,
644 %    information about shrinking if the |\raggedcolumns|
645 %    declaration is in force and the value of the `{\sf unbalance}'
646 %    counter if positive.
647 % \item[$\meta{number}= 3$.]  Setting \meta{number}\pagebreak[2] to
648 %    this value will additionally trace the mark handling
649 %    algorithm. It will show what marks are found, what marks are
650 %    considered, etc. To fully understand this information you will
651 %    probably have to read carefully trough the implementation.
652 % \item[$\meta{number}\geq 4$.]  Setting \meta{number}\pagebreak[2] to
653 %    such a high value will additionally place an |\hrule| into your
654 %    output, separating the part of text which had already been
655 %    considered on the previous page from the rest.  Clearly this
656 %    setting should {\em not\/} be used for the final output.  It will
657 %    also activate even more debugging code for mark handling.
658 % \end{description}
661 % \end{multicols}
663 % \begin{multicols}{3}[\section{Prefaces to older versions}
664 %                      \subsection{Preface to version 1.4}]
665 %   \hbadness=10000
666 %   Beside fixing some bugs as mentioned in the {\sf multicol.bug} file
667 %   this new release enhances the \mc{} environment by allowing for
668 %   balancing in arbitrary contexts. It is now, for example, possible
669 %   to balance text within a \mc{} or a {\sf minipage} as shown in
670 %   \ref{tab:newcmds} where a {\sf multicols} environment within a
671 %   {\sf quote} environment was used. It is now even possible to nest
672 %   \mc{} environments.
674 %   The only restriction to such inner \mc{} environments (nested, or
675 %   within \TeX's internal vertical mode) is that such variants will
676 %   produce a box with the balanced material in it, so that they can
677 %   not be broken across pages or columns.
679 %   Additionally I rewrote the algorithm for balancing so that it will
680 %   now produce slightly better results.
682 %   I updated the source documentation but like to apologize in
683 %   advance for some `left over' parts that slipped through the
684 %   revision.
686 %   A note to people who like to improve the balancing algorithm of
687 %   \mc{}: The balancing routine is now placed into a single macro
688 %   which is called |\balance@columns|. This means that one can easily
689 %   try different balancing routines by rewriting this macro. The
690 %   interface for it is explained in table \ref{tab:balance}. There are
691 %   several improvements possible, one can think of integrating the
692 %   |\badness| function of \TeX3, define a faster algorithm for finding
693 %   the right column height, etc. If somebody thinks he/she has an
694 %   enhancement I would be pleased to learn about it. But please obey
695 %   the copyright notice and don't change {\sf multicol.dtx} directly!
696 %   \begin{table*}
697 %    \begin{quote}
698 %    \begin{multicols}{2}
699 %     \raggedcolumns
700 %     The macro |\balance@columns| that contains the code for balancing
701 %     gathered material is a macro without parameters. It assumes that
702 %     the material for balancing is stored in the box |\mult@box| which
703 %     is a |\vbox|. It also ``knows'' about all parameters set up by the
704 %     \mc{} environment, like |\col@number|, etc. It can also assume
705 %     that |\@colroom| is the still available space on the current page.
707 %     When it finishes it must return the individual columns in boxes
708 %     suitable for further processing with |\page@sofar|. This means
709 %     that the left column should be stored in box register
710 %     |\mult@gfirstbox|, the next
711 %     in register |\mult@firstbox|${}+2$, \ldots,
712 %     only the last one as an exception in
713 %     register |\mult@grightbox|. Furthermore it has to set up
714 %     the two macros
715 %     |\kept@firstmark| and |\kept@botmark| to hold the values for the
716 %     first and bottom mark as found in the individual columns. There
717 %     are some helper functions defined in section \ref{sec:v14} which
718 %     may be used for this. Getting the marks right ``by hand'' is
719 %     non-trivial and it may pay off to first take a look at the
720 %     documentation and implementation of |\balance@columns| below
721 %     before trying anew.
722 %    \end{multicols}
723 %    \end{quote}
724 %    \vspace*{-3ex}
725 %    \vspace*{-0ex}
726 %    \caption{Interface description for \cs{balance@columns}}
727 %    \label{tab:balance}
728 %   \end{table*}
729 % \end{multicols}
731 % \begin{multicols}{3}[\subsection{Preface to version 1.2}]
732 %   \hbadness=10000
733 %   After the article about the \mc{} environment was published in
734 %   \TUB\ 10\#3, I got numerous requests for these macros. However, I
735 %   also got a changed version of my style file, together with a
736 %   letter asking me if I would include the changes to get better
737 %   paragraphing results in the case of narrow lines. The main
738 %   differences to my original style option were additional parameters
739 %   (like |\multicoladjdemerits| to be used for |\adjdemerits|, etc.)
740 %   which would influence the line breaking algorithm.
742 %   But actually resetting such parameters to zero or even worse to a
743 %   negative value won't give better line breaks inside the \mc{}
744 %   environment. \TeX{}s line breaking algorithm will only look at
745 %   those possible line breaks which can be reached without a badness
746 %   higher than the current value of |\tolerance| (or |\pretolerance|
747 %   in the first pass). If this isn't possible, then, as a last
748 %   resort, \TeX{} will produce overfull boxes. All those (and only
749 %   those) possible break points will be considered and finally the
750 %   sequence which results in the fewest demerits will be chosen. This
751 %   means that a value of $-1000$ for |\adjdemerits| instructs \TeX{}
752 %   to prefer visibly incompatible lines instead of producing better
753 %   line breaks.
755 %   However, with \TeX{} 3.0 it is possible to get decent line breaks
756 %   even in small columns by setting |\emergencystretch| to an
757 %   appropriate value. I implemented a version which is capable of
758 %   running both in the old and the new \TeX{} (actually it will
759 %   simply ignore the new feature if it is not available). The
760 %   calculation of |\emergencystretch| is probably incorrect. I
761 %   made a few tests but of course one has to have much more experience
762 %   with the new possibilities to achieve the maximum quality.
764 %   Version 1.1a had a nice `feature': the penalty for using the
765 %   forbidden floats was their ultimate removal from \LaTeX{}s
766 %   |\@freelist| so that after a few |\marginpar|s inside the \mc{}
767 %   environment floats where disabled forever.  (Thanks to Chris
768 %   Rowley for pointing this out.) I removed this misbehaviour and at
769 %   the same time decided to allow at least floats spanning all
770 %   columns, e.g., generated by the |figure*| environment.  You can
771 %   see the new functionality in table~\ref{tab:newcmds} which was
772 %   inserted at this very point.
773 %   \begin{table*}
774 %    \small
775 %    \setlength{\multicolsep}{0pt}
776 %    \begin{quote}
777 %     \begin{multicols}{2}
778 %      |\setemergencystretch|: This is a hook for people who like
779 %      to play around. It is supposed to set the
780 %      |\emergencystretch| \meta{dimen} register provided in the
781 %      new \TeX{} 3.0. The first argument is the number of columns and
782 %      the second one is the current |\hsize|. At the moment the
783 %      default definition is $4\mbox{\tt pt} \times |#1|$, i.e.\ the
784 %      |\hsize| isn't used at all. But maybe there are better
785 %      formulae.
787 %      \setlength{\emergencystretch}{20pt} |\set@floatcmds|: This is
788 %      the hook for the experts who like to implement a full float
789 %      mechanism for the \mc{} environment. The |@| in the name
790 %      should signal that this might not be easy.
791 %    \end{multicols}
792 %   \end{quote}
793 %   \vspace*{-1ex}
794 %   \vspace*{-0ex}
795 %   \caption[]{The new commands of {\sf multicol.sty} version 1.2.
796 %            Both commands might be removed if good solutions to these
797 %            open problems are found. I hope that these commands will
798 %            prevent that nearly identical style files derived from
799 %            this one are floating around.}
800 %   \label{tab:newcmds}
801 %   \end{table*}
802 %   However single column floats are still forbidden and I don't think
803 %   I will have time to tackle this problem in the near future. As an
804 %   advice for all who want to try: wait for \TeX{} 3.0. It has a few
805 %   features which will make life much easier in multi-column
806 %   surroundings. Nevertheless we are working here at the edge of
807 %   \TeX{}s capabilities, really perfect solutions would need a
808 %   different approach than it was done in \TeX{}s page builder.
810 %   The text below is nearly unchanged, I only added documentation at
811 %   places where new code was added.
812 % \end{multicols}
814 % \changes{v1.5l}{1996/01/13}{Try hard to explain unresolved reference
815 %                that happens if \cs{OnlyDescription} is used}
817 % \StopEventually{\PrintIndex \PrintChanges
818 %   \ifx\Finale\relax
819 %    \typeout{**********************************}
820 %    \typeout{* Info: Typesetting this document with
821 %                     \protect\OnlyDescription\space will}
822 %    \typeout{* Info: result in one unresolved
823 %                     reference to `sec:v14'.}
824 %    \typeout{* Info: --- tough, it's just not there in this case!}
825 %    \typeout{**********************************}
826 %   \fi
827 %  }
830 % \begin{multicols}{2}[\section{The Implementation}
831 %         We are now switching to two-column output to show the
832 %         abilities of this environment (and bad layout decisions).
833 %      \subsection{The documentation driver file}
834 %         ][10\baselineskip]
836 %   \hbadness=10000
839 % The next bit of code contains the documentation driver file for
840 % \TeX{}, i.e., the file that will produce the documentation you are
841 % currently reading. It will be extracted from this file by the {\tt
842 % docstrip} program.
843 % Since this is the first code in this file one can produce the
844 % documentation
845 % simply by running \LaTeX{} on the \texttt{.dtx} file.
846 %    \begin{macrocode}
847 %<*driver>
848 \documentclass{ltxdoc}
849 %    \end{macrocode}
850 %    We use the \texttt{balancingshow} option when loading \mc{} so
851 %    that full tracing is produced. This has to be done before the
852 %    \texttt{doc} package is loaded, since \texttt{doc} otherwise
853 %    requires \mc{} without any options.
854 %    \begin{macrocode}
855 \usepackage{multicol}[1999/05/25]
856 \usepackage{doc}
857 %    \end{macrocode}
858 %    First we set up the page layout suitable for
859 %    this article.
860 %    \begin{macrocode}
861 \setlength{\textwidth}{39pc}
862 \setlength{\textheight}{54pc}
863 \setlength{\parindent}{1em}
864 \setlength{\parskip}{0pt plus 1pt}
865 \setlength{\oddsidemargin}{0pc}
866 \setlength{\marginparwidth}{0pc}
867 \setlength{\topmargin}{-2.5pc}
868 \setlength{\headsep}{20pt}
869 \setlength{\columnsep}{1.5pc}
870 %    \end{macrocode}
871 %    We want a rule between columns.
872 %    \begin{macrocode}
873 \setlength\columnseprule{.4pt}
874 %    \end{macrocode}
875 %    We also want to ensure that a new \mc{} environment finds enough
876 %    space at the bottom of the page.
877 %    \begin{macrocode}
878 \setlength\premulticols{6\baselineskip}
879 %    \end{macrocode}
880 %    When balancing columns we disregard solutions that
881 %    are too bad. Also, if the last column is too bad
882 %    we typeset it without stretch.
883 %    \begin{macrocode}
884 \setcounter{columnbadness}{7000}
885 \setcounter{finalcolumnbadness}{7000}
886 %    \end{macrocode}
887 %    The index is supposed to come out in four columns.
888 %    And we don't show macro names in the margin.
889 %    \begin{macrocode}
890 \setcounter{IndexColumns}{4}
891 \let\DescribeMacro\SpecialUsageIndex
892 \let\DescribeEnv\SpecialEnvIndex
893 \renewcommand\PrintMacroName[1]{}
894 \CodelineIndex
895 %\DisableCrossrefs           % Partial index
896 \RecordChanges               % Change log
897 %    \end{macrocode}
898 %    Line numbers are very small for this article.
899 %    \begin{macrocode}
900 \renewcommand{\theCodelineNo}
901   {\scriptsize\rm\arabic{CodelineNo}}
902 \settowidth\MacroIndent{\scriptsize\rm 00\ }
904 \begin{document}
905   \typeout
906    {****************************************
907  ^^J* Expect some Under- and overfull boxes.
908  ^^J****************************************}
909    \DocInput{multicol.dtx}
910 \end{document}
911 %</driver>
912 %    \end{macrocode}
915 % \end{multicols}
917 % \begin{multicols}{2}[\subsection{Identification and
918 %                      option processing}]
921 % We start by identifying the package. Since it makes use of features
922 % only available in \LaTeXe{} we ensure that this format is available.
923 % (Now this is done earlier in the file.)
924 %    \begin{macrocode}
925 %<*package>
926 % \NeedsTeXFormat{LaTeX2e}
927 % \ProvidesPackage{multicol}[..../../..
928 %    v... multicolumn formatting]
929 %    \end{macrocode}
931 %^^A \subsection{Option processing}
933 %    Next we declare options supported by \mc{}. Two-column mode
934 %    and \mc{} do not work together so we warn about possible
935 %    problems. However, since you can revert to |\onecolumn|
936 %    in which case \mc{} does work, we don't make this an error.
937 %    \begin{macrocode}
938 \DeclareOption{twocolumn}
939    {\PackageWarning{multicol}{May not work
940              with the twocolumn option}}
941 %    \end{macrocode}
942 %    Tracing is done using a counter. However
943 %    it is also possible to invoke the tracing
944 %    using the options declared below.
945 %    \begin{macrocode}
946 \newcount\c@tracingmulticols
947 \DeclareOption{errorshow}
948     {\c@tracingmulticols\z@}
949 \DeclareOption{infoshow}
950     {\c@tracingmulticols\@ne}
951 \DeclareOption{balancingshow}
952     {\c@tracingmulticols\tw@}
953 \DeclareOption{markshow}
954     {\c@tracingmulticols\thr@@}
955 \DeclareOption{debugshow}
956     {\c@tracingmulticols5\relax}
957 %    \end{macrocode}
958 %    The next option is intended for typesetting on a |\baselineskip|
959 %    grid. Right now it doesn't do anything other than warning if it
960 %    thinks that the grid got lost.
961 % \changes{v1.6a}{2003/03/15}{New option grid}
962 %    \begin{macrocode}
963 \let\mc@gridwarn\maxdimen
964 \DeclareOption{grid}{\def\mc@gridwarn{\maxdepth}}
965 %    \end{macrocode}
967 % \changes{v1.8e}{2014/04/23}{Support \cs{docolaction}}
968 %    Next option enables the |\docolaction| command. As this changes
969 %   the \texttt{.aux} file content this is not automatically enabled.
970 %    \begin{macrocode}
971 \DeclareOption{colaction}{%
972   \def\mc@col@status@write{%
973          \protected@write\@auxout{}%
974               {\string\mc@col@status
975               {\ifmc@firstcol 1\else 2\fi}}%
976          \mc@firstcolfalse}%
977   \def\mc@lastcol@status@write{%
978          \protected@write\@auxout{}%
979               {\string\mc@col@status{3}}}%
981 \let\mc@col@status@write\relax
982 \let\mc@lastcol@status@write\relax
983 %    \end{macrocode}
985 %    \begin{macrocode}
986 \ProcessOptions
987 %    \end{macrocode}
990 % \end{multicols}
992 % \begin{multicols}{2}[\subsection{Starting and
993 %                      Ending the \mc{} Environment}]
995 % \begin{macro}{\multicols}
996 %    As mentioned before, the \mc{} environment has one mandatory
997 %    argument (the number of columns) and up to two optional ones.  We
998 %    start by reading the number of columns into the |\col@number|
999 %    register.
1000 %    \begin{macrocode}
1001 \def\multicols#1{\col@number#1\relax
1002 %    \end{macrocode}
1003 %    If the user forgot the argument, \TeX{} will complain about a
1004 %    missing number at this point. The error recovery mechanism will
1005 %    then use zero, which isn't a good choice in this case. So we
1006 %    should now test whether everything is okay. The minimum is two
1007 %    columns at the moment.
1008 % \changes{v1.3b}{1990/10/09}{Minimum of two columns}
1009 %    \begin{macrocode}
1010   \ifnum\col@number<\tw@
1011      \PackageWarning{multicol}%
1012       {Using `\number\col@number'
1013        columns doesn't seem a good idea.^^J
1014        I therefore use two columns instead}%
1015      \col@number\tw@ \fi
1016 %    \end{macrocode}
1017 %    We have only enough box registers for ten columns, so we need to
1018 %    check that the user hasn't asked for more.
1019 % \changes{v1.4k}{1992/06/27}{Maximum of 5 columns (temp)}
1020 % \changes{v1.5a}{1992/11/04}{Allow 10 columns again}
1021 %    \begin{macrocode}
1022   \ifnum\col@number>10
1023      \PackageError{multicol}%
1024       {Too many columns}%
1025       {Current implementation doesn't
1026        support more than 10 columns.%
1027        \MessageBreak
1028        I therefore use 10 columns instead}%
1029      \col@number10 \fi
1030 %    \end{macrocode}
1031 %    Within the environment we need a special version of the
1032 %    kernel |\@footnotetext| command since the original sets the
1033 %    the |\hsize| to |\columnwidth| which is not correct in the
1034 %    multicol environment. Here |\columnwidth| refers to the width of
1035 %    the individual column and the footnote should be in |\textwidth|.
1036 %    Since |\@footnotetext| has a different definition inside a
1037 %    minipage environment we do not redefine it directly. Instead we
1038 %    locally set |\columnwidth| to |\textwidth| and call the original
1039 %    (current) definition stored in |\orig@footnotetext|.
1040 % \changes{v1.5p}{1997/12/14}{Redefinition of \cs{@footnotetext}
1041 %                           only within env pr/2689.}
1042 % \changes{v1.5r}{1998/08/17}{Use \cs{@footnotetext} but with
1043 %                             local change to \cs{columnwidth}.}
1044 % \changes{v1.5w}{1999/10/21}{Make \cs{@footnotetext} long to allow
1045 %                             multi-paragraph footnotes.}
1046 %    If the \mc{} environment is nested inside another \mc{}
1047 %    environment then the redefinition has already happened. So be
1048 %    better test for this situation. Otherwise, we will get a \TeX{}
1049 %    stack overflow as this would generate a self-referencing definition.
1050 % \changes{v1.6e}{2004/02/14}{Avoid self-referencing definition of
1051 %    \cs{@footnotetext} (pr/3618)}.
1052 %    \begin{macrocode}
1053      \ifx\@footnotetext\mult@footnotetext\else
1054        \let\orig@footnotetext\@footnotetext
1055        \let\@footnotetext\mult@footnotetext
1056      \fi
1057 %    \end{macrocode}
1058 %    Now we can safely look for the optional arguments.
1059 %    \begin{macrocode}
1060   \@ifnextchar[\mult@cols{\mult@cols[]}}
1061 %    \end{macrocode}
1062 % \end{macro}
1066 % \begin{macro}{\mult@footnotetext}
1068 %    \begin{macrocode}
1069 \long\def\mult@footnotetext#1{\begingroup
1070          \columnwidth\textwidth
1071          \orig@footnotetext{#1}\endgroup}
1072 %    \end{macrocode}
1073 % \end{macro}
1075 % \begin{macro}{\mult@cols}
1076 %    The |\mult@cols| macro grabs the first optional argument
1077 %    (if any) and looks for the second one.
1078 %    \begin{macrocode}
1079 \def\mult@cols[#1]{\@ifnextchar[%
1080 %    \end{macrocode}
1081 %    This argument should be a \meta{dimen} denoting the minimum free
1082 %    space needed on the current page to start the environment. If the
1083 %    user didn't supply one, we use |\premulticols| as a
1084 %    default.
1085 %    \begin{macrocode}
1086   {\mult@@cols{#1}}%
1087   {\mult@@cols{#1}[\premulticols]}}
1088 %    \end{macrocode}
1089 % \end{macro}
1092 % \begin{macro}{\mult@@cols}
1093 %    After removing all arguments from the input we are able
1094 %    to start with |\mult@@cols|.
1095 %    \begin{macrocode}
1096 \def\mult@@cols#1[#2]{%
1097 %    \end{macrocode}
1098 %    First thing we do is to decide whether or not this is an
1099 %    unbounded multicols environment, i.e. one that may split across
1100 %    pages, or one that has to be typeset into a box. If we are in
1101 %    \TeX's ``inner'' mode (e.g., inside a box already) then we have a
1102 %    boxed version of multicols therefore we set the |@boxedmulticols|
1103 %    switch to true.  The \mc{} should start in vertical mode. If we
1104 %    are not already there we now force it with |\par| since otherwise
1105 %    the test for ``inner'' mode wouldn't show if we are in a box.
1106 % \changes{v1.4f}{1992/04/28}{\cs{par} added to allow for correct inner test}
1107 %    \begin{macrocode}
1108   \par
1109   \ifinner \@boxedmulticolstrue
1110 %    \end{macrocode}
1111 %    Otherwise we check |\doublecol@number|. This counter is zero
1112 %    outside a multicols environment but positive inside (this happens
1113 %    a little later on). In the second case we need to process the
1114 %    current multicols also in ``boxed mode'' and so change the switch
1115 %    accordingly.
1116 %    \begin{macrocode}
1117   \else
1118     \ifnum \doublecol@number>\z@
1119        \@boxedmulticolstrue
1120     \fi
1121   \fi
1122 %    \end{macrocode}
1123 %    Then we look to see if statistics are requested:
1124 %    \begin{macrocode}
1125   \mult@info\z@
1126       {Starting environment with
1127        \the\col@number\space columns%
1128 %    \end{macrocode}
1129 %    In boxed mode we add some more info.
1130 % \changes{v1.4f}{1992/04/28}{\cs{on@line} added to tracing info}
1131 %    \begin{macrocode}
1132         \if@boxedmulticols\MessageBreak
1133            (boxed mode)\fi
1134       }%
1135 %    \end{macrocode}
1136 %    Then we measure the current page to see whether a useful portion
1137 %    of the multicolumn environment can be typeset.  This routine
1138 %    might start a new page.
1139 % \changes{v1.4a}{1992/02/14}{Forgotten braces added}
1140 %    \begin{macrocode}
1141    \enough@room{#2}%
1142 %    \end{macrocode}
1143 %    Now we output the first argument and produce vertical space
1144 %    above the columns. (Note that this argument corresponds to the
1145 %    first optional argument of the {\sf multicols} environment.)
1146 %    For many releases this argument was typeset in a group to get
1147 %    a similar effect as |\twocolumn[..]| where the argument is
1148 %    also implicitly surrounded by braces. However, this conflicts
1149 %    with local changes done by things like sectioning commands (which
1150 %    account for the majority of commands used in that argument)
1151 %    messing up vertical spacing etc.\ later in the document so that
1152 %    from version v1.5q on this argument is again typeset at the outer
1153 %    level.
1154 % \changes{v1.4e}{1992/03/16}{Typeset optional arg inside group}
1155 % \changes{v1.5q}{1998/01/19}{And removed the group again six years later}
1156 %    \begin{macrocode}
1157    #1\par\addvspace\multicolsep
1158 %    \end{macrocode}
1159 %    When the last line of a paragraph had a positive depth then this
1160 %    depth normally taken into account by the baselineskip calculation
1161 %    for the next line. However, the columns produced by a following
1162 %    \texttt{multicol} are rigid and thus the distance from the
1163 %    baseline of a previous text line to the first line in a
1164 %    \texttt{multicol} would differ depending on the depth of the
1165 %    previous line. To account for this we add a negative space unless
1166 %    the depth is \texttt{-1000pt} which signals something special to
1167 %    \TeX and is not supposed to be a real depth.
1168 % \changes{v1.5z1}{2003/02/17}{Add a kern to cancel potential depth of
1169 %    previous line}
1170 %    \begin{macrocode}
1171    \ifdim \prevdepth = -\@m\p@
1172    \else
1173 %    \end{macrocode}
1174 %    The actual generation of this corrective space is a little bit
1175 %    more complicated as it doesn't make sense to always back up to
1176 %    the previous baseline (in case an object with a very large depth
1177 %    was placed there, e.g., a centered tabular). So we only back up
1178 %    to the extend that we are within the |\baselineskip| grid. We
1179 %    know that the box produced by \mc{} has |\topskip| at its top so
1180 %    that also needs to be taken into account.
1181 % \changes{v1.6a}{2003/03/15}{Adjust spacing}
1182 %    \begin{macrocode}
1183      \@tempcnta\prevdepth
1184      \@tempcntb\baselineskip
1185      \divide\@tempcnta\@tempcntb
1186      \advance\@tempcnta\@ne
1187      \dimen@\prevdepth
1188      \advance\dimen@ -\@tempcnta\baselineskip
1189      \advance\dimen@ \topskip
1190      \kern-\dimen@
1191    \fi
1192 %    \end{macrocode}
1193 %    We start a new grouping level to hide all subsequent changes
1194 %    (done in |\prepare@multicols| for example).
1195 %    \begin{macrocode}
1196    \begingroup
1197      \prepare@multicols
1198 %    \end{macrocode}
1199 %    If we are in boxed mode we now open a box to typeset all material
1200 %    from the multicols body into it, otherwise we simply go ahead.
1201 % \changes{v1.4g}{1992/05/07}{\cs{global} was probably wrong but at least
1202 %                           unnecessary}
1203 %    \begin{macrocode}
1204      \if@boxedmulticols
1205        \setbox\mult@box\vbox\bgroup
1206 %    \end{macrocode}
1208 % \changes{v1.8c}{2013/11/03}{Add \cs{color@setgroup} to prevent color leak}
1209 %    \begin{macrocode}
1210                             \color@setgroup
1211 %    \end{macrocode}
1212 % \changes{v1.5?}{1994/?/?}{Penalty moved to later point}
1213 %    We may have to reset some parameters at this point,
1214 %    perhaps |\@parboxrestore|
1215 %    would be the right action but I leave it for the moment.
1216 % \changes{v1.4l}{1992/08/17}{\cs{@totalleftmargin} now in
1217 %                             \cs{prepare@multicols}}
1218 %    \begin{macrocode}
1219      \fi
1220 %    \end{macrocode}
1221 %    We finish by suppressing initial spaces.
1222 %    \begin{macrocode}
1223      \ignorespaces}
1224 %    \end{macrocode}
1225 % \end{macro}
1227 %  \begin{macro}{\if@boxedmulticols}
1228 %    Here is the switch and the box for ``boxed'' multicols code.
1229 %    \begin{macrocode}
1230 \newif\if@boxedmulticols
1231 \@boxedmulticolsfalse
1232 \newbox\mult@box
1233 %    \end{macrocode}
1234 %  \end{macro}
1236 % \begin{macro}{\enough@room}
1237 % \changes{v1.0c}{1989/05/12}{Penalty 0 added to empty the contribution
1238 %                           list.}
1239 %    The |\enough@room| macro used
1240 %    above isn't perfect but works reasonably well in this context. We
1241 %    measure the free space on the current page by subtracting
1242 %    |\pagetotal| from |\pagegoal|. This isn't entirely
1243 %    correct since it doesn't take the `shrinking' (i.e.\
1244 %    |\pageshrink|) into account.  The `recent contribution list'
1245 %    might be nonempty so we start with |\par| and an explicit
1246 %    |\penalty|.\footnote{See the documentation of
1247 %    \cs{endmulticols} for further details.}
1248 %    Actually, we use |\addpenalty| to ensure that a following
1249 %    |\addvspace| will `see' the vertical space that might be
1250 %    present.
1251 %    The use of |\addpenalty| will have the effect that all items from
1252 %    the recent contributions will be moved to the main vertical list
1253 %    and the |\pagetotal| value will be updated correctly. However,
1254 %    the penalty will be placed in front of any dangling glue item
1255 %    with the result that the main vertical list may already be
1256 %    overfull even if \TeX{} is not invoking the output routine.
1257 % \changes{v1.3b}{1990/10/09}{Do \cs{penalty} with \cs{addpenalty}}
1258 % \changes{v1.4e}{1992/03/16}{But ignore \cs{@nobreak} in \cs{addpenalty}}
1259 %    \begin{macrocode}
1260 \def\enough@room#1{%
1261 %    \end{macrocode}
1262 %    Measuring makes only sense when we are not in ``boxed mode'' so
1263 %    the routine does nothing if the switch is true.
1264 %    \begin{macrocode}
1265    \if@boxedmulticols\else
1266    \par
1267 %    \end{macrocode}
1268 %    \label{mac:enoughroom}
1269 %    To empty the contribution list the first release contained a
1270 %    penalty zero but this had the result that |\addvspace| couldn't
1271 %    detect preceding glue. So this was changed to |\addpenalty|. But
1272 %    this turned out to be not enough as |\addpenalty| will not add a
1273 %    penalty when |@nobreak| is true. Therefore we force this switch
1274 %    locally to false. As a result there may be a break between
1275 %    preceding text and the start of a multicols environment, but this
1276 %    seems acceptable since there is the optional argument for exactly
1277 %    this reason.
1278 %    \begin{macrocode}
1279    \bgroup\@nobreakfalse\addpenalty\z@\egroup
1280    \page@free \pagegoal
1281    \advance \page@free -\pagetotal
1282 %    \end{macrocode}
1283 %    To be able to output the value we need to assign it to a register
1284 %    first since it might be a register (default) in which case we
1285 %    need to use |\the| or it might be a plain value in which case
1286 %    |\the| would be wrong.
1287 % \changes{v1.5e}{1994/05/26}{Assign arg to skip register to be able
1288 %                             to output value}
1289 %    \begin{macrocode}
1290      \@tempskipa#1\relax
1291 %    \end{macrocode}
1292 %    Now we test whether tracing information is required:
1293 %    \begin{macrocode}
1294    \mult@info\z@
1295        {Current page:\MessageBreak
1296         height=%
1297         \the\pagegoal: used \the\pagetotal
1298         \space -> free=\the\page@free
1299         \MessageBreak
1300         needed \the\@tempskipa
1301               \space(for #1)}%
1302 %    \end{macrocode}
1303 %    Our last action is to force a page break if there isn't enough
1304 %    room left.
1305 %    \begin{macrocode}
1306    \ifdim \page@free <#1\newpage \fi
1307   \fi}
1308 %    \end{macrocode}
1309 % \end{macro}
1311 % \begin{macro}{\prepare@multicols}
1312 %    When preparing for multicolumn output several things must
1313 %    be done.
1314 %    \begin{macrocode}
1315 \def\prepare@multicols{%
1316 %    \end{macrocode}
1317 %    We start saving the current |\@totalleftmargin| and then
1318 %    resetting the |\parshape| in case we are inside some list
1319 %    environment. The correct indentation for the \mc{} environment in
1320 %    such a case will be produced by moving the result to the right by
1321 %    |\multicol@leftmargin| later on. If we would use the value of of
1322 %    |\@totalleftmargin| directly then lists inside the \mc{}
1323 %    environment could cause a shift of the output.
1324 % \changes{v1.4l}{1992/08/17}{saved \cs{@totalleftmargin}}
1325 %    \begin{macrocode}
1326   \multicol@leftmargin\@totalleftmargin
1327   \@totalleftmargin\z@
1328   \parshape\z@
1329 %    \end{macrocode}
1330 %    We also set the register |\doublecol@number| for later use.  This
1331 %    register should contain $2\times |\col@number|$.  This is also an
1332 %    indicator that we are within a \mc{} environment as mentioned
1333 %    above.
1334 % \changes{v1.5a}{1992/11/04}{Add offset to \cs{doublecolnumber}}
1335 %    \begin{macrocode}
1336   \doublecol@number\col@number
1337   \multiply\doublecol@number\tw@
1338   \advance\doublecol@number\mult@rightbox
1339 %    \end{macrocode}
1341 %    \begin{macrocode}
1342   \if@boxedmulticols
1343     \let\l@kept@firstmark\kept@firstmark
1344     \let\l@kept@botmark\kept@botmark
1345     \global\let\kept@firstmark\@empty
1346     \global\let\kept@botmark\@empty
1347   \else
1348 %    \end{macrocode}
1349 %    We add an empty box to the main vertical list to ensure that we
1350 %    catch any insertions (held over or inserted at the top of the
1351 %    page). Otherwise it might happen that the |\eject| is discarded
1352 %    without calling the output routine. Inside the output routine we
1353 %    remove this box again.  Again this code applies only if we are on
1354 %    the main vertical list and not within a box.
1355 %    However, it is not enough to turn off interline spacing, we also
1356 %    have to clear |\topskip| before adding this box, since |\topskip|
1357 %    is always inserted before the first box on a page which would
1358 %    leave us with an extra space of |\topskip| if \mc{} start on a
1359 %    fresh sheet.
1360 % \changes{v1.3c}{1991/03/03}{\cs{null} inserted and removed in output}
1361 % \changes{v1.4a}{1992/02/11}{Conditional code for boxed mode added.}
1362 % \changes{v1.4o}{1992/11/22}{\cs{topskip} locally zeroed.}
1363 %    \begin{macrocode}
1364     \nointerlineskip {\topskip\z@\null}%
1365     \output{%
1366       \global\setbox\partial@page\vbox
1367         {%
1368 %    \end{macrocode}
1369 %    Now we have to make sure that we catch one special situation which
1370 %    may result in loss of text! If the user has a huge amount of
1371 %    vertical material within the first optional argument that is larger
1372 %    then |\premulticols| and we are near the bottom of the page then it
1373 %    can happen that not the |\eject| is triggering this special output
1374 %    routine but rather the overfull main vertical list.  In that case
1375 %    we get another breakpoint through the |\eject| penalty. As a result
1376 %    this special output routine would be called twice and the contents
1377 %    of |\partial@page|, i.e.\ the material before the \mc{}
1378 %    environment gets lost. There are several solutions to avoid this
1379 %    problem, but for now we will simply detect this and inform the user
1380 %    that he/she has to enlarge the |\premulticols| by using a suitable
1381 %    value for the second argument.
1382 % \changes{v1.4a}{1992/02/11}{Checking for text losses.}
1383 %    \begin{macrocode}
1384 %<*check>
1385          \ifvoid\partial@page\else
1386            \PackageError{multicol}%
1387             {Error saving partial page}%
1388             {The part of the page before
1389              the multicols environment was
1390              nearly full with^^Jthe result
1391              that starting the environment
1392              will produce an overfull
1393              page.  Some^^Jtext may be lost!
1394              Please increase \premulticols
1395              either generally or for this%
1396              ^^Jenvironment by specifying a
1397              suitable value in the second
1398              optional argument to^^Jthe
1399              multicols environment.}
1400            \unvbox\partial@page
1401            \box\last@line
1402          \fi
1403 %</check>
1404          \unvbox\@cclv
1405          \global\setbox\last@line\lastbox
1406         }%
1407 %    \end{macrocode}
1408 %    Finally we need to record the marks that are present within the
1409 %    |\partial@page| so that we can construct correct first and bottom
1410 %    marks later on. This is done by the following code.
1411 % \changes{v1.4a}{1992/02/14}{kept marks initiated}
1412 %    \begin{macrocode}
1413            \prep@keptmarks
1414 %    \end{macrocode}
1415 %    Finally we have to initialize |\kept@topmark| which should
1416 %    ideally be initialized with the mark that is current on ``top''
1417 %    of this page. Unfortunately we can't use |\topmark| because this
1418 %    register will not always contain what its name promises because
1419 %    \LaTeX{} sometimes calls the output routine for float
1420 %    management.\footnote{During such a call the \cs{botmark}
1421 %    gets globally copied to \cs{topmark} by the \TeX{}
1422 %    program.} Therefore we use the second best solution by
1423 %    initializing it with |\firstmark|. In fact, for our purpose this
1424 %    doesn't matter as we use |\kept@topmark| only to initialize
1425 %    |\firstmark| and |\botmark| of a following page if we don't find
1426 %    any marks on the current one.
1427 % \changes{v1.4i}{1992/06/18}{\cs{kept@topmark} initialized.}
1428 %    \begin{macrocode}
1429            \global\let\kept@topmark\firstmark
1430           }\eject
1431 %    \end{macrocode}
1432 %    The next thing to do is to assign a new value to |\vsize|.
1433 %    \LaTeX{} maintains the free room on the page (i.e.\ the page
1434 %    height without the space for already contributed floats) in the
1435 %    register |\@colroom|. We must subtract the height of
1436 %    |\partial@page| to put the actual free room into this
1437 %    variable.
1438 %    \begin{macrocode}
1439     \advance\@colroom-\ht\partial@page
1440 %    \end{macrocode}
1441 %    Then we have to calculate the |\vsize| value to use during column
1442 %    assembly. |\set@mult@vsize| takes an argument which allows to
1443 %    make the setting local (|\relax|) or global (|\global|). The
1444 %    latter variant is used inside the output routine below. At this
1445 %    point here we have to make a local change to |\vsize| because we
1446 %    want to get the original value for |\vsize| restored in case
1447 %    this \mc{} environment ends on the same page where it has started.
1448 % \changes{v1.4p}{1992/11/26}{Use different \cs{vsize} setting}
1449 % \changes{v1.4p}{1992/11/26}{Code moved to \cs{set@mult@vsize}}
1450 %    \begin{macrocode}
1451     \set@mult@vsize\relax
1452 %    \end{macrocode}
1453 %    Now we switch to a new |\output| routine which will be used
1454 %    to put the gathered column material together.
1455 %    \begin{macrocode}
1456     \output{\multi@column@out}%
1457 %    \end{macrocode}
1458 %    Finally we handle the footnote insertions. We have to multiply
1459 %    the magnification factor and the extra skip by the number of
1460 %    columns since each footnote reduces the space for every column
1461 %    (remember that we have pagewide footnotes).  If, on the other
1462 %    hand, footnotes are typeset at the very end of the document, our
1463 %    scheme still works since |\count\footins| is zero then, so it
1464 %    will not change.
1465 %    To allow even further customization the setting of the |\footins|
1466 %    parameters is done in a separate macro.
1467 % \changes{v1.5?}{1994/?/?}{Use \cs{init@mult@footins}}
1468 %    \begin{macrocode}
1469     \init@mult@footins
1470 %    \end{macrocode}
1471 %    For the same reason (pagewide footnotes), the \meta{dimen}
1472 %    register controlling the maximum space used for footnotes isn't
1473 %    changed.  Having done this, we must reinsert all the footnotes
1474 %    which are already present (i.e.\ those encountered when the
1475 %    material saved in |\partial@page| was first processed). This
1476 %    will reduce the free space (i.e.\ |\pagetotal|) by the
1477 %    appropriate amount since we have changed the magnification
1478 %    factor, etc.\ above.
1479 %    \begin{macrocode}
1480     \reinsert@footnotes
1481 %    \end{macrocode}
1482 %    All the code above was only necessary for the unrestricted \mc{}
1483 %    version, i.e.\ the one that allows page breaks. If we are within
1484 %    a box there is no point in setting up special output routines or
1485 %    |\vsize|, etc.
1486 %    \begin{macrocode}
1487   \fi
1488 %    \end{macrocode}
1489 %    But now we are coming to code that is necessary in all cases.  We
1490 %    assign new values to |\vbadness|, |\hbadness| and |\tolerance|
1491 %    since it's rather hard for \TeX{} to produce `good' paragraphs
1492 %    within narrow columns.
1493 % \changes{v1.2a}{1990/02/05}{\cs{vbadness} 10001 now.}
1494 %    \begin{macrocode}
1495   \vbadness\@Mi \hbadness5000
1496   \tolerance\multicoltolerance
1497 %    \end{macrocode}
1498 %    Since nearly always the first pass will fail we ignore it
1499 %    completely telling \TeX{} to hyphenate directly.  In fact, we now
1500 %    use another register to keep the value for the multicol
1501 %    pre-tolerance, so that a designer may allow to use
1502 %    |\pretolerance|.
1503 % \changes{v1.2a}{1990/02/05}{\cs{pretolerance} -1 because it nearly never
1504 %                            succeeds.}
1505 % \changes{v1.4e}{1992/03/20}{Using}
1506 %    \begin{macrocode}
1507   \pretolerance\multicolpretolerance
1508 %    \end{macrocode}
1509 %    For use with the new \TeX{} we set |\emergencystretch| to
1510 %    $|\col@number| \times 4pt$. However this is only a guess
1511 %    so at the moment this is done in a macro
1512 %    |\setemergencystretch| which gets the current |\hsize|
1513 %    and the number of columns as arguments. Therefore users are able
1514 %    to figure out their own formula.
1515 % \changes{v1.2a}{1990/02/05}{\cs{setemergencystretch} added.}
1516 %    \begin{macrocode}
1517   \setemergencystretch\col@number\hsize
1518 %    \end{macrocode}
1519 %    Another hook to allow people adding their own extensions without
1520 %    making a new package is |\set@floatcmds| which handles any
1521 %    redefinitions of \LaTeX{}s internal float commands to work with
1522 %    the \mc{} environment. At the moment it is only used to redefine
1523 %    |\@dblfloat| and |\end@dblfloat|.
1524 % \changes{v1.2a}{1990/02/05}{\cs{set@floatcmds} added.}
1525 %    \begin{macrocode}
1526   \set@floatcmds
1527 %    \end{macrocode}
1528 %    Additionally, we advance |\baselineskip| by
1529 %    |\multicolbaselineskip| to allow corrections for narrow
1530 %    columns.
1531 %    \begin{macrocode}
1532   \advance\baselineskip\multicolbaselineskip
1533 %    \end{macrocode}
1534 % \changes{v1.0e}{1989/06/21}{\cs{textwidth} changed to \cs{linewidth}.}
1535 % \changes{v1.0e}{1989/06/21}{So this file will
1536 %                           work with the `twocolumn' command.}
1537 %    The |\hsize| of the columns is given by the formula:
1538 %    \[
1539 %       { |\linewidth| - (|\col@number|-1)
1540 %                             \times
1541 %                             |\columnsep|
1542 %        \over
1543 %        |\col@number|}
1544 %    \]
1545 %    The formula above has changed from release to release. We now
1546 %    start with the current value of |\linewidth| so that the column
1547 %    width is properly calculated when we are inside a minipage or a
1548 %    list or some other environment.
1549 %    This will be achieved with:
1550 %    \begin{macrocode}
1551   \hsize\linewidth \advance\hsize\columnsep
1552   \advance\hsize-\col@number\columnsep
1553   \divide\hsize\col@number
1554 %    \end{macrocode}
1555 %    We also set |\linewidth| and |\columnwidth| to |\hsize| In the past
1556 %    |\columnwidth| was left unchanged. This is inconsistent,
1557 %    but |\columnwidth| is used only by floats (which
1558 %    aren't allowed in their current implementation) and by the
1559 %    |\footnote| macro. Since we want pagewide
1560 % footnotes\footnote{I'm not sure that I really want pagewide
1561 %                       footnotes. But balancing of the last page can
1562 %                       only be achieved with this approach or with a
1563 %                       multi-path algorithm which is complicated and
1564 %                       slow. But it's a challenge to everybody to
1565 %                       prove me wrong!  Another possibility is to
1566 %                       reimplement a small part of the {\it
1567 %                       fire\_up\/} procedure in \TeX{} (the program).
1568 %                       I think that this is the best solution if you
1569 %                       are interested in complex page makeup, but it
1570 %                       has the disadvantage that the resulting
1571 %                       program cannot be called \TeX{} thereafter.}
1572 %    this simple trick saved us from rewriting the |\footnote|
1573 %    macros. However, some applications referred to |\columnwidth| as
1574 %    the ``width of the current column'' to typeset displays
1575 %    (the \texttt{amsmath} package, for example) and to allow the use
1576 %    of such applications together with \texttt{multicol} this is now
1577 %    changed.
1579 %    Before we change |\linewidth| to the new value we record its old
1580 %    value in some register called |\full@width|. This value is
1581 %    used later on when we package all columns together.
1582 % \changes{v1.0e}{1989/06/21}{Setting of \cs{columnwidth} removed.}
1583 % \changes{v1.5o}{1997/11/16}{Setting of \cs{columnwidth} added again
1584 %                           pr/2664.}
1585 %    \begin{macrocode}
1586   \full@width\linewidth
1587   \linewidth\hsize
1588   \columnwidth\hsize
1590 %    \end{macrocode}
1591 % \end{macro}
1593 %  \begin{macro}{\init@mult@footins}
1594 %    This macro is used to set up the parameters associated
1595 %    with footnote floats. It can be redefined by applications that
1596 %    require different amount of spaces when typesetting footnotes.
1597 %    \begin{macrocode}
1598 \def\init@mult@footins{%
1599     \multiply\count\footins\col@number
1600     \multiply\skip \footins\col@number
1602 %    \end{macrocode}
1603 % \end{macro}
1605 %  \begin{macro}{\set@mult@vsize}
1607 %    Since we have to set |\col@umber| columns on one page,
1608 %    each with a height of |\@colroom|, we have to assign
1609 %    $
1610 %      |\vsize|  = |\col@number| \times |\@colroom|
1611 %    $
1612 %    in order to collect enough material before entering the
1613 %    |\output| routine again. In fact we have to add another
1614 %    $
1615 %       (|\col@number|-1) \times (|\baselineskip|-|\topskip|)
1616 %    $
1617 %    if you think about it.
1618 % \changes{v1.4p}{1992/11/26}{Macro added.}
1619 %    \begin{macrocode}
1620 \def\set@mult@vsize#1{%
1621     \vsize\@colroom
1622     \@tempdima\baselineskip
1623     \advance\@tempdima-\topskip
1624     \advance\vsize\@tempdima
1625     \vsize\col@number\vsize
1626     \advance\vsize-\@tempdima
1627 %    \end{macrocode}
1628 %    But this might not be enough since we use |\vsplit| later to
1629 %    extract the columns from the gathered material. Therefore we add
1630 %    some `extra lines,' one for each column plus a corrective action
1631 %    depending on the value of the `\texttt{collectmore}' counter.
1632 %    The final value is assigned globally if |#1| is |\global| because
1633 %    we want to use this macro later inside the output routine too.
1634 % \changes{v1.6c}{2003/04/08}{Collect one line per column more}
1635 %    \begin{macrocode}
1636     \advance\vsize\col@number\baselineskip
1637     #1\advance\vsize
1638         \c@collectmore\baselineskip}
1639 %    \end{macrocode}
1640 %  \end{macro}
1643 %  \begin{macro}{\multicol@leftmargin}
1644 %    Here is the dimen register we need for saving away the outer
1645 %    value of |\@totalleftmargin|.
1646 %    \begin{macrocode}
1647 \newdimen\multicol@leftmargin
1648 %    \end{macrocode}
1649 %  \end{macro}
1651 % \begin{macro}{\endmulticols}
1652 %    When the end of the \mc{} environment is sensed we have to
1653 %    balance the gathered material. Depending on whether or not we are
1654 %    inside a boxed multicol different things must happen. But first
1655 %    we end the current paragraph with a |\par| command.
1656 %    \begin{macrocode}
1657 \def\endmulticols{\par
1658   \if@boxedmulticols
1659 %    \end{macrocode}
1660 %    In boxed mode we have to close the box in which we have gathered
1661 %    all material for the columns. But before we do this we need to
1662 %    remove any space at the end of the box as we don't want to use
1663 %    this in balancing. Because of the |\color@endgroup| this can't be
1664 %    done later in |\balance@columns| as the color command will hide
1665 %    it. 
1666 % \changes{v1.8c}{2013/11/03}{Add \cs{color@endgroup} to prevent color leak}
1667 % \changes{v1.8f}{2014/06/19}{Discard spaces before adding \cs{color@endgroup}}
1668 %    \begin{macrocode}
1669     \remove@discardable@items\color@endgroup\egroup
1670 %    \end{macrocode}
1671 %    Now we call |\balance@columns| the routine that balances material
1672 %    stored in the box |\mult@box|.
1673 % \changes{v1.5?}{1994/?/?}{Splitting off zero box moved to
1674 %                           \cs{balance@columns}}
1675 %    \begin{macrocode}
1676     \balance@columns
1677 %    \end{macrocode}
1678 %    After balancing the result has to be returned by the command
1679 %    |\page@sofar|. But before we do this we reinsert any marks found
1680 %    in box |\mult@box|.
1681 %    \begin{macrocode}
1682     \return@nonemptymark{first}%
1683                  \kept@firstmark
1684     \return@nonemptymark{bot}%
1685                   \kept@botmark
1686     \page@sofar
1687 %    \end{macrocode}
1689 %    \begin{macrocode}
1690     \global\let\kept@firstmark
1691                \l@kept@firstmark
1692     \global\let\kept@botmark
1693             \l@kept@botmark
1694 %<*marktrace>
1695     \mult@info\tw@
1696       {Restore kept marks to\MessageBreak
1697        first: \meaning\kept@firstmark
1698        \MessageBreak bot\space\space:
1699                      \meaning\kept@botmark }%
1700 %</marktrace>
1701 %    \end{macrocode}
1702 %    This finishes the code for the ``boxed'' case.
1703 %    \begin{macrocode}
1704   \else
1705 %    \end{macrocode}
1706 %    If there was a |\columnbreak| on the very last line all material
1707 %    will have been moved to the |\colbreak@box|. Thus the the galley
1708 %    will be empty and no output routine gets called so that the text
1709 %    is lost. To avoid this problem (though unlikely) we check if the
1710 %    current galley is empty and the |\colbreak@box| contains text and
1711 %    if so return that to the galley. If the galley is non-empty any
1712 %    material in  |\colbreak@box| is added in the output routine since
1713 %    it needs to be put in front.
1714 % \changes{v1.6d}{2003/04/17}{Catch problem with \cs{columnbreak} in
1715 %    last line}
1716 %    \begin{macrocode}
1717     \ifdim\pagegoal=\maxdimen
1718       \ifvoid\colbreak@box\else
1719         \mult@info\@ne{Re-adding forced
1720                  break(s) for splitting}%
1721         \unvbox\colbreak@box\fi
1722     \fi
1723 %    \end{macrocode}
1724 %    If we are in an unrestricted \mc{} environment we end the current
1725 %    paragraph above with |\par| but this isn't sufficient since \TeX{}s
1726 %    {\it page\_builder} will not totally empty the contribution
1727 %    list.\footnote{This once caused a puzzling bug where some of the
1728 %    material was balanced twice, resulting in some overprints.  The
1729 %    reason was the \cs{eject} which was placed at the end of
1730 %    the contribution list. Then the {\it page\_builder} was called
1731 %    (an explicit \cs{penalty} will empty the contribution
1732 %    list), but the line with the \cs{eject} didn't fit onto
1733 %    the current page.  It was then reconsidered after the output
1734 %    routine had ended, causing a second break after one line.}
1735 %    Therefore we must also add an explicit |\penalty|.  Now the
1736 %    contribution list will be emptied and, if its material doesn't
1737 %    all fit onto the current page then the output routine will be
1738 %    called before we change it.
1739 % \changes{v1.3b}{1990/10/09}{Do \cs{penalty} with \cs{addpenalty}}
1740 % \changes{v1.4e}{1992/03/16}{But ignore \cs{@nobreak} in \cs{addpenalty}}
1741 % \changes{v1.5c}{1993/04/18}{Again use \cs{penalty}}
1742 %    At this point we need to use |\penalty| not |\addpenalty| to
1743 %    ensure that a) the recent contributions are emptied and b) that
1744 %    the very last item on the main vertical list is a valid break
1745 %    point so that \TeX{} breaks the page in case it is overfull.
1746 %    \begin{macrocode}
1747    \penalty\z@
1748 %    \end{macrocode}
1749 %    Now it's safe to change the output routine in order to balance
1750 %    the columns.
1751 %    \begin{macrocode}
1752    \output{\balance@columns@out}%
1753    \eject
1754 %    \end{macrocode}
1755 %    If the \mc{} environment body was completely empty or if a
1756 %    multi-page \mc{} just ends at a page boundary we have the unusual
1757 %    case that the |\eject| will have no effect (since the main
1758 %    vertical list is empty)---thus no output routine is called at
1759 %    all. As a result the material preceding the \mc{} (stored in
1760 %    |\partial@page| will get lost if we don't put this back by hand.
1761 % \changes{v1.4m}{1992/09/04}{Check \cs{partial@page} being emptied}
1762 %    \begin{macrocode}
1763     \ifvbox\partial@page
1764          \unvbox\partial@page\fi
1765 %    \end{macrocode}
1766 %    After the output routine has acted we restore
1767 %    the kept marks to their initial value.
1768 %    \begin{macrocode}
1769      \global\let\kept@firstmark\@empty
1770      \global\let\kept@botmark\@empty
1771 %<*marktrace>
1772      \mult@info\tw@
1773        {Make kept marks empty}%
1774 %</marktrace>
1775   \fi
1776 %    \end{macrocode}
1777 %    The output routine above will take care of the |\vsize| and
1778 %    reinsert the balanced columns, etc. But it can't reinsert the
1779 %    |\footnotes| because we first have to restore the
1780 %    |\footins| parameter since we are returning to one column
1781 %    mode. This will be done in the next line of code; we simply close
1782 %    the group started in |\multicols|.
1784 %    To fix an obscure bug which is the result of the current
1785 %    definition of the |\begin| \ldots\ |\end| macros, we check that
1786 %    we are still (logically speaking) in the \mc{} environment. If,
1787 %    for example, we forget to close some environment inside the
1788 %    \mc{} environment, the following |\endgroup| would be
1789 %    incorrectly considered to be the closing of this environment.
1790 % \changes{v1.3c}{1991/03/14}{Check closing env.}
1791 %    \begin{macrocode}
1792   \@checkend{multicols}%
1793   \endgroup
1794 %    \end{macrocode}
1795 %    We also set the `{\sf unbalance}' counter to its default. This is
1796 %    done globally since \LaTeX{} counters are always changed this
1797 %    way.\footnote{Actually, we are still in a group started by the
1798 %    \cs{begin} macro, so \cs{global} must be used
1799 %    anyway.}
1800 %    \begin{macrocode}
1801   \global\c@unbalance\z@
1802 %    \end{macrocode}
1803 %    Now it's time to return any footnotes if we are in unrestricted
1804 %    mode:
1805 %    \begin{macrocode}
1806   \if@boxedmulticols\else
1807     \reinsert@footnotes
1808 %    \end{macrocode}
1809 %    We also take a look at the amount of free space on the current
1810 %    page to see if it's time for a page break.  The vertical space
1811 %    added thereafter will vanish if |\enough@room| starts a new
1812 %    page.
1814 %    But there is one catch. If the |\end{multicols}| is at the top of
1815 %    which can happen if there is a break point just before it (such
1816 %    as end ending environment) which was chosen. In that case we
1817 %    would do the next page using the internal |\vsize| for multicol
1818 %    collection which is a disaster. So we better catch this
1819 %    case. Fortunately we can detect it by looking at |\pagegoal|.
1820 % \changes{v1.5x}{2000/05/05}{Detect and fix problem if a multicols
1821 %    ends at the top of a page}
1822 %    \begin{macrocode}
1823     \ifdim \pagegoal=\maxdimen
1824       \global\vsize\@colroom
1825     \else
1826       \enough@room\postmulticols
1827     \fi
1828   \fi
1829   \addvspace\multicolsep
1830 %    \end{macrocode}
1831 %    There is one more thing to do: the balanced result of the
1832 %   environment is supposed to have a |\prevdepth| of zero as we
1833 %   backed up by its real prevdepth within |\page@sofar|. However if
1834 %   the balancing happened in the output routine then \TeX{} reverts
1835 %   to the |\prevdepth| that was current before the OR once the OR has
1836 %   finished. In short |\prevdepth| is something you can't set
1837 %   globally it is alway local to the current list being built. Thus
1838 %   we need to set it back to zero here to avoid incorrect spacing.
1839 % \changes{v1.8h}{2014/09/12}{Set \cs{prevdepdth} for current vlist
1840 %   when returning from multicols environment}
1841 %    \begin{macrocode}
1842  \prevdepth\z@
1843 %    \end{macrocode}
1844 %    If statistics are required we finally report that we have
1845 %    finished everything.
1846 %    \begin{macrocode}
1847   \mult@info\z@
1848      {Ending environment
1849              \if@boxedmulticols
1850                 \space(boxed mode)\fi
1851               }}
1852 %    \end{macrocode}
1853 % \end{macro}
1856 % \begin{macro}{\c@unbalance}
1857 % \SpecialMainIndex{\c@collectmore}
1858 % \SpecialMainIndex{\col@number}
1859 % \SpecialMainIndex{\doublecol@number}
1860 % \SpecialMainIndex{\premulticols}
1861 % \SpecialMainIndex{\multicoltolerance}
1862 % \SpecialMainIndex{\multicolpretolerance}
1863 % \SpecialMainIndex{\page@free}
1864 % \SpecialMainIndex{\premulticols}
1865 % \SpecialMainIndex{\postmulticols}
1866 % \SpecialMainIndex{\multicolsep}
1867 % \SpecialMainIndex{\multicolbaselineskip}
1868 % \SpecialMainIndex{\partial@page}
1869 %    Let us end this section by allocating all the registers used so
1870 %    far.
1871 %    \begin{macrocode}
1872 \newcount\c@unbalance
1873 \newcount\c@collectmore
1874 %    \end{macrocode}
1875 %    In the new \LaTeX{} release |\col@number| is already allocated by
1876 %    the kernel, so we don't allocate it again.
1877 %    \begin{macrocode}
1878 %\newcount\col@number
1879 \newcount\doublecol@number
1880 \newcount\multicoltolerance
1881 \newcount\multicolpretolerance
1882 \newdimen\full@width
1883 \newdimen\page@free
1884 \newdimen\premulticols
1885 \newdimen\postmulticols
1886 \newskip\multicolsep
1887 \newskip\multicolbaselineskip
1888 \newbox\partial@page
1889 \newbox\last@line
1890 %    \end{macrocode}
1891 %    And here are their default values:
1892 %    \begin{macrocode}
1893 \c@unbalance   = 0
1894 \c@collectmore = 0
1895 %    \end{macrocode}
1896 %    To allow checking whether some macro is used within the \mc{}
1897 %    environment the counter |\col@number| gets a default of |1|
1898 %    outside the the environment.
1899 % \changes{v1.3d}{1991/10/23}{\cs{col@number} set to one}
1900 % \changes{v1.8o}{2016/02/08}{\cs{col@number} already initialized in the 
1901 %    kernel, so not initializing it in the package 
1902 %    in case the document is in two-column (pr/4435)}
1903 %    \begin{macrocode}
1904 %\col@number = 1
1905 \multicoltolerance = 9999
1906 \multicolpretolerance = -1
1907 \premulticols = 50pt
1908 \postmulticols= 20pt
1909 \multicolsep = 12pt plus 4pt minus 3pt
1910 \multicolbaselineskip=0pt
1911 %    \end{macrocode}
1912 % \end{macro}
1914 % \end{multicols}
1916 % \begin{multicols}{2}[\subsection{The output routines}]
1918 % We first start with some simple macros. When typesetting the page we
1919 % save the columns either in the box registers 0, 2, 4,\ldots\
1920 % (locally) or 1, 3, 5,\ldots\ (globally). This is \PlainTeX{} policy
1921 % to avoid an overflow of the save stack.
1923 % \begin{macro}{\process@cols}
1924 %    Therefore we define a |\process@cols| macro to help us in
1925 %    using these registers in the output routines below. It has two
1926 %    arguments: the first one is a number; the second one is the
1927 %    processing information.  It loops starting with |\count@=#1|
1928 %    (|\count@| is a scratch register defined in \PlainTeX),
1929 %    processes argument |#2|, adds two to |\count@|,
1930 %    processes argument |#2| again, etc.\ until |\count@| is
1931 %    higher than |\doublecol@number|.  It might be easier to
1932 %    understand it through an example, so we define it now and
1933 %    explain its usage afterwards.
1934 %    \begin{macrocode}
1935 \def\process@cols#1#2{\count@#1\relax
1936      \loop
1937 %<*debug>
1938      \typeout{Looking at box \the\count@}
1939 %</debug>
1940       #2%
1941      \advance\count@\tw@
1942      \ifnum\count@<\doublecol@number
1943    \repeat}
1944 %    \end{macrocode}
1945 % \end{macro}
1948 % \begin{macro}{\page@sofar}
1949 %    We now define |\page@sofar| to give an example of the
1950 %    |\process@cols| macro. |\page@sofar| should output everything
1951 %    prepared by the balancing routine |\balance@columns|.
1952 %    \begin{macrocode}
1953 \def\page@sofar{%
1954 %    \end{macrocode}
1955 %    |\balance@columns| prepares its output in the even numbered
1956 %    scratch box registers.
1957 %    Now we output the columns gathered assuming that they are saved
1958 %    in the box registers 2 (left column), 4 (second column), \ldots\
1959 %    However, the last column (i.e.\ the right-most) should be saved in
1960 %    box register 0.\footnote{You will see the reason for this numbering
1961 %                             when we look at the output routines
1962 %                             \cs{multi@column@out} and
1963 %                             \cs{balance@columns@out}.}
1964 %    First we ensure that the columns have equal width. We use
1965 %    |\process@cols| for this purpose, starting with
1966 %    $|\count@|=|\mult@rightbox|$. Therefore |\count@| loops through
1967 %    |\mult@rightbox|, $|\mult@rightbox| + 2$,\ldots
1968 %                                  (to |\doublecol@number|).
1969 % \changes{v1.5a}{1992/11/04}{New box mechanism}
1970 %    \begin{macrocode}
1971    \process@cols\mult@rightbox
1972 %    \end{macrocode}
1973 %    We have to check if the box in question is void, because the
1974 %    operation |\wd|\meta{number} on a void box will \emph{not} change
1975 %    its dimension (sigh).
1976 % \changes{v1.5h}{1994/08/26}{Check for void boxes}
1977 % \changes{v1.5i}{1994/10/02}{But don't remove original code.}
1978 %    \begin{macrocode}
1979        {\ifvoid\count@
1980           \setbox\count@\hbox to\hsize{}%
1981         \else
1982           \wd\count@\hsize
1983         \fi}%
1984 %    \end{macrocode}
1985 %    Now we give some tracing information.
1986 % \changes{v1.4l}{1992/08/17}{use \cs{multicol@leftmargin} instead of
1987 %                           \cs{@totalleftmargin}}
1988 % \changes{v1.6b}{2003/03/15}{Different info display}
1989 %    \begin{macrocode}
1990    \count@\col@number \advance\count@\m@ne
1991    \mult@info\z@
1992     {Column spec: \the\full@width\space = indent
1993                   + columns + sep =\MessageBreak
1994         \the\multicol@leftmargin\space
1995         + \the\col@number\space
1996         x \the\hsize\space
1997         + \the\count@\space
1998         x \the\columnsep
1999      }%
2000 %    \end{macrocode}
2001 %    At this point we should always be in vertical mode.
2002 %    \begin{macrocode}
2003 \ifvmode\else\errmessage{Multicol Error}\fi
2004 %    \end{macrocode}
2005 %    Now we put all columns together in an |\hbox| of width
2006 %    |\full@width| (shifting it by |\multicol@leftmargin| to the right
2007 %    so that it will be placed correctly if we are within a list
2008 %    environment)
2009 %    and separating the columns with a rule if desired.
2010 % \changes{v1.5a}{1992/11/04}{New box mechanism}
2011 % \changes{v1.5z}{2000/07/10}{Ensure that column rule has always
2012 %                             \cs{normalcolor}}
2013 % \changes{v1.6f}{2006/09/19}{Make the color of the rule a hook}
2014 % \changes{v1.4l}{1992/08/17}{use \cs{multicol@leftmargin} instead of
2015 %                           \cs{@totalleftmargin}}
2017 %    The box containing the columns has  a large height and thus will
2018 %    always result in using |\lineskip| if the normal |\baselineskip|
2019 %    calculations are used. We therefore better cancel that process.
2020 % \changes{v1.5z1}{2003/02/17}{Suppress interline glue at this point}
2021 %    \begin{macrocode}
2022    \nointerlineskip
2023 %    \end{macrocode}
2024 %    As mentioned earlier we want to have the reference point of the
2025 %    box we put on the page being at the baseline of the last line of
2026 %    the columns but we also want to ensure that the box has no depth
2027 %    so that any following skip is automatically starting from that
2028 %    baseline.
2029 %    We achieve this by recording the depths of all columns and then
2030 %    finally backing up by the maximum. (perhaps a simpler method
2031 %    would be to assemble the box in a register and set the depth of
2032 %    that box to zero (not checked).
2034 %    We need a global scratch register for this; using standard \TeX{}
2035 %    conventions we choose |\dimen2| and initialize it with the depth
2036 %    of the character ``p'' since that is one of the depths that
2037 %    compete for the maximum.
2038 % \changes{v1.6a}{2003/03/15}{Preparing for adjusting \cs{prevdepth}}
2039 %    \begin{macrocode}
2040    \setbox\z@\hbox{p}\global\dimen\tw@\dp\z@
2041    \moveright\multicol@leftmargin
2042     \hbox to\full@width{%
2043 %    \end{macrocode}
2044 %    If the document is written in a language that is typeset right-to-left
2045 %    then, of course, the multicol columns should be also typeset
2046 %    right-to-left. To support this we call |\mc@align@columns| which
2047 %    with execute different code depending on the typesetting direction.
2048 % \changes{v1.7b}{2011/12/18}{RL language support fixed}
2049 %    \begin{macrocode}
2050        \mc@align@columns
2051 %    \end{macrocode}
2052 %    The depths of the columns depend on their last lines. To ensure
2053 %    that we will always get a similar look as far as the rules are
2054 %    concerned we force the depth to be at least the depth of a
2055 %    letter~`p' (which is what we set |\dimen2| to above).
2056 %    \begin{macrocode}
2057        \rlap{\phantom p}%
2058     }%
2059 %    \end{macrocode}
2060 %    The processed material might consist of a last line with a
2061 %    descender in which case the |\prevdepth| will be
2062 %    non-zero. However, this material is getting reformatted now so
2063 %    that this value is likely to be wrong. We therefore normalize the
2064 %    situation by pretending that the depth is zero. However, if |\page@sofar|
2065 %   is being called inside the OR then setting |\prevdepth| here has
2066 %   no longlasting effect, we therefore have to repeat this once we
2067 %   return to the main vertical list. Here we set it only for those
2068 %   cases where the command is used within a list and then followed by
2069 %   something else.
2070 % \changes{v1.8g}{2014/08/24}{Resetting \cs{prevdepth} in the right place}
2071 %    \begin{macrocode}
2072    \prevdepth\z@
2073 %    \end{macrocode}
2074 %    Now after typesetting the box we back up to its baseline by using
2075 %    the value stored in |\dimen2| (which will hold the largest depth
2076 %    found on any column).
2077 % \changes{v1.8g}{2003/03/15}{Now adjusting \cs{prevdepth}}
2078 %    \begin{macrocode}
2079  \kern-\dimen\tw@
2080 %    \end{macrocode}
2081 %    However, in case one of the columns was unusually deep \TeX{} may
2082 %    have tried some corrective actions in which case backing up by
2083 %    the saved value will not bring us back to the baseline. A good
2084 %    indication for this is a depth of |\maxdepth| though it is not an
2085 %    absolute proof. If the option \texttt{grid} is used
2086 %    |\mc@gridwarn| will expand to this, otherwise to |\maxdimen| in
2087 %    which case this warning will not show up.
2088 % \changes{v1.8g}{2014/08/24}{Warn if value is exceeded not when equal}
2089 %    \begin{macrocode}
2090  \ifdim\dimen\tw@ > \mc@gridwarn
2091    \PackageWarning{multicol}%
2092      {Very deep columns!\MessageBreak
2093       Grid alignment might be broken}%
2094  \fi
2096 %    \end{macrocode}
2097 % \end{macro}
2099 % \begin{macro}{\columnseprulecolor}
2100 % \changes{v1.6f}{2006/09/19}{Make the color of the rule a hook}
2101 %    By default the vertical rule between columns will be in |\normalcolor|.
2102 %    \begin{macrocode}
2103 \def\columnseprulecolor{\normalcolor}
2104 %    \end{macrocode}
2105 % \end{macro}
2107 % \begin{macro}{\reinsert@footnotes}
2108 %    Before we tackle the bigger output routines we define just one
2109 %    more macro which will help us to find our way through the
2110 %    mysteries later. |\reinsert@footnotes| will do what its name
2111 %    indicates: it reinserts the footnotes present in
2112 %    |\footinbox| so that they will be reprocessed by \TeX{}'s
2113 %    {\it page\_builder}.
2115 %    Instead of actually reinserting the footnotes we insert an empty
2116 %    footnote. This will trigger insertion mechanism as well and since
2117 %    the old footnotes are still in their box and we are on a fresh page
2118 %    |\skip| |footins| should be correctly taken into account.
2119 % \changes{v1.3c}{1990/03/03}{\cs{unbox}ing avoided.}
2120 %    \begin{macrocode}
2121 \def\reinsert@footnotes{\ifvoid\footins\else
2122          \insert\footins{}\fi}
2123 %    \end{macrocode}
2124 % \end{macro}
2127 % \begin{macro}{\vfilmaxdepth}
2128 %    This curious definition is used as the space at the bottom of a
2129 %   column if we implement |\raggedcolumns|. Normlly one only appends
2130 %   |\vfill| in that case but this is actually wrong for columns that
2131 %   are more or less full: by adding a glue at the bottom such a
2132 %   column doesn't have any depth any more but without it the material
2133 %   would be allowed a depth of |\maxdepth|. So we allow shrinking by
2134 %   that amount. This only makes a difference if the box would
2135 %   otherwise become overfull and shrinking never exceeds the
2136 %   specified value, so we should be fine. 
2137 % \changes{v1.8h}{2014/09/12}{Macro added  (pr/4395)}
2138 % \changes{v1.8j}{2015/03/07}{Use only `0.0001fil' for stretching}
2139 %    \begin{macrocode}
2140 \def\vfilmaxdepth{\vskip \z@ \@plus .0001fil 
2141                            \@minus \maxdepth}
2142 %    \end{macrocode}
2143 % \end{macro}
2146 % \begin{macro}{\multi@column@out}
2147 %    Now we can't postpone the difficulties any longer.  The
2148 %    |\multi@column@out| routine will be called in two situations.
2149 %    Either the page is full (i.e., we have collected enough material
2150 %    to generate all the required columns) or a float or marginpar or
2151 %    a |\clearpage| is
2152 %    sensed.  In the latter case the |\outputpenalty| is less
2153 %    than $-10000$, otherwise the penalty which triggered the output
2154 %    routine is higher.  Therefore it's easy to distinguish both
2155 %    cases: we simply test this register.
2156 % \changes{v1.5c}{1993/04/18}{Support \cs{clearpage}}
2157 %    \begin{macrocode}
2158 \def\multi@column@out{%
2159    \ifnum\outputpenalty <-\@M
2160 %    \end{macrocode}
2161 %    If this was a |\clearpage|, a float or a marginpar we call
2162 %    |\speci@ls|
2163 %    \begin{macrocode}
2164     \speci@ls \else
2165 %    \end{macrocode}
2166 %    otherwise we construct the final page.
2167 % \changes{v1.5u}{1999/05/25}{Support \cs{columnbreak}}
2168 % \changes{v1.5v}{1999/07/18}{Added debug statements for
2169 %                             column break support}
2170 %    For the next block of code see comments in section~\ref{sec:colbreak}.
2171 %    \begin{macrocode}
2172     \ifvoid\colbreak@box\else
2173       \mult@info\@ne{Re-adding forced
2174                 break(s) for splitting}%
2175       \setbox\@cclv\vbox{%
2176        \unvbox\colbreak@box
2177        \penalty-\@Mv
2178        \unvbox\@cclv}%
2179     \fi
2180 %    \end{macrocode}
2181 %    Let us now consider the
2182 %    normal case. We have to |\vsplit| the columns from the
2183 %    accumulated material in box 255.  Therefore we first assign
2184 %    appropriate values to |\splittopskip| and |\splitmaxdepth|.
2185 %    \begin{macrocode}
2186    \splittopskip\topskip
2187    \splitmaxdepth\maxdepth
2188 %    \end{macrocode}
2189 %    We also need to restrict |\boxmaxdepth| so that re-boxing is not
2190 %    generating boxes with arbitrary depth.   
2191 % \changes{v1.8j}{2015/03/07}{Set \cs{boxmaxdepth}}
2192 %    \begin{macrocode}
2193    \boxmaxdepth\maxdepth
2194 %    \end{macrocode}
2195 %    Then we calculate the current column height (in |\dimen@|).
2196 %    Note that the height of |\partial@page| is already
2197 %    subtracted from |\@colroom| so we can use its value as a
2198 %    starter.
2199 %    \begin{macrocode}
2200    \dimen@\@colroom
2201 %    \end{macrocode}
2202 %    But we must also subtract the space occupied by footnotes on the
2203 %    current page. Note that we first have to reset the skip register
2204 %    to its normal value.
2205 %    Again, the actual action is carried out in a utility macro, so that
2206 %    other applications can modify it.
2207 % \changes{v1.5?}{1994/?/?}{Use \cs{leave@mult@footins}}
2208 %    \begin{macrocode}
2209    \divide\skip\footins\col@number
2210    \ifvoid\footins \else
2211       \leave@mult@footins
2212    \fi
2213 %    \end{macrocode}
2214 %    And there is one more adjustment that we have to make: if the
2215 %    user has issue a |\enlargethispage| command then the height the
2216 %    |\@kludgeins| box will be the negation of the size by which the
2217 %    page should be enlarged. If the star form of this command has
2218 %    been used then we also need to shrink the resulting column. As we
2219 %    don't know whether or not shrinking is already generally
2220 %    requested with save the current value of |\ifshr@king| and
2221 %    restore it afterwards.
2222 % \changes{v1.8a}{2011/12/20}{Support for \cs{enlargethispage}}
2223 %    \begin{macrocode}
2224    \let\ifshr@kingsaved\ifshr@king
2225    \ifvbox \@kludgeins
2226      \advance \dimen@ -\ht\@kludgeins
2227 %    \end{macrocode}
2228 %    The star form of  |\enlargethispage| makes the width of the box
2229 %    greater than zero (sneaky isn't it?).
2230 %    \begin{macrocode}
2231      \ifdim \wd\@kludgeins>\z@
2232         \shr@nkingtrue
2233      \fi
2234    \fi
2235 %    \end{macrocode}
2236 %    Now we are able to |\vsplit| off all but the last column.
2237 %    Recall that these columns should be saved in the box registers 2,
2238 %    4,\ldots\ (plus offset).
2239 % \changes{v1.5a}{1992/11/04}{New box mechanism}
2240 %    \begin{macrocode}
2241    \process@cols\mult@gfirstbox{%
2242         \setbox\count@
2243             \vsplit\@cclv to\dimen@
2244 %    \end{macrocode}
2245 %    After splitting we update the kept marks.
2246 %    \begin{macrocode}
2247             \set@keptmarks
2248 %    \end{macrocode}
2249 %    If |\raggedcolumns| is in force we add a |vfill| at the bottom by
2250 %    unboxing the split box.
2251 %    But we need to unbox anyway to ensure that at the end of the box
2252 %    we do not have unwanted space. This can sneak in in certain
2253 %    situations, for example, if two lists follow each other and we
2254 %    break between them. While sich space is usually zero it still has
2255 %    an effect because it hides depth of the last line in the column
2256 %    and that will result in incorrect placement.
2257 % \changes{v1.3c}{1990/03/03}{\cs{unbox}ing avoided.}
2258 % \changes{v1.8b}{2013/08/28}{And 20odd years later conclude that
2259 %         this was wrong and unboxing is always needed.}
2260 % \changes{v1.8b}{2013/08/28}{Remove discardable items at the
2261 %                             end of split boxes}
2262 % \changes{v1.8h}{2014/09/12}{Use \cs{vfilmaxdepth}}
2263 % \changes{v1.8k}{2015/03/22}{\cs{remove@discardable@items} removed}
2264 %    \begin{macrocode}
2265             \setbox\count@
2266                  \vbox to\dimen@
2267                   {\unvbox\count@
2268                    \ifshr@nking\vfilmaxdepth\fi}%
2269            }%
2270 %    \end{macrocode}
2271 %    Then the last column follows.
2272 % \changes{v1.5a}{1992/11/04}{New box mechanism}
2273 % \changes{v1.8b}{2013/08/28}{Remove discardable items at the
2274 %                             end of split boxes}
2275 % \changes{v1.8h}{2014/09/12}{Use \cs{vfilmaxdepth}}
2276 % \changes{v1.8k}{2015/03/22}{\cs{remove@discardable@items} removed}
2277 %    \begin{macrocode}
2278    \setbox\mult@rightbox
2279        \vsplit\@cclv to\dimen@
2280    \set@keptmarks
2281    \setbox\mult@rightbox\vbox to\dimen@
2282           {\unvbox\mult@rightbox
2283            \ifshr@nking\vfilmaxdepth\fi}%
2284 %    \end{macrocode}
2285 %    Now that we are done with the boxes, we restored the current
2286 %    setting for shrinking in case it got changed:
2287 %    \begin{macrocode}
2288    \let\ifshr@king\ifshr@kingsaved
2289 %    \end{macrocode}
2290 %    Having done this we hope that box 255 is emptied. If not, we
2291 %    reinsert its contents.
2292 % \changes{v1.8a}{2011/12/20}{Only re-add output penalty if it was
2293 %    explicitly set}
2294 %    \begin{macrocode}
2295    \ifvoid\@cclv \else
2296        \unvbox\@cclv
2297        \ifnum\outputpenalty=\@M
2298        \else
2299           \penalty\outputpenalty
2300        \fi
2301 %    \end{macrocode}
2302 %    In this case a footnote that happens to fall into the leftover
2303 %    bit will be typeset on the wrong page. Therefore we warn the user
2304 %    if the current page contains footnotes. The older versions of
2305 %    \mc{} produced this warning regardless of whether or not
2306 %    footnotes were present, resulting in many unnecessary warnings.
2307 % \changes{v1.3c}{1991/02/17}{Check if footnotes are actually present
2308 %                           before issuing a warning.}
2309 %    \begin{macrocode}
2310        \ifvoid\footins\else
2311          \PackageWarning{multicol}%
2312           {I moved some lines to
2313            the next page.\MessageBreak
2314            Footnotes on page
2315            \thepage\space might be wrong}%
2316        \fi
2317 %    \end{macrocode}
2318 %    If the `{\sf tracingmulticols}' counter is 4 or higher we also
2319 %    add a rule.
2320 %    \begin{macrocode}
2321        \ifnum \c@tracingmulticols>\thr@@
2322                     \hrule\allowbreak \fi
2323    \fi
2324 %    \end{macrocode}
2325 %    To get a correct marks for the current page we have to (locally)
2326 %    redefine |\firstmark| and |\botmark|.
2327 %    If |\kept@firstmark| is non-empty then |\kept@botmark| must be
2328 %    non-empty too so we can use their values. Otherwise we use the
2329 %    value of |\kept@topmark| which was first initialized when we
2330 %    gathered the |\partical@page| and later on was updated to the
2331 %    |\botmark| for the preceding page.
2333 % \changes{v1.4a}{1992/02/14}{\cs{botmark} set to \cs{splitbotmark}}
2334 %    \begin{macrocode}
2335    \ifx\@empty\kept@firstmark
2336       \let\firstmark\kept@topmark
2337       \let\botmark\kept@topmark
2338    \else
2339       \let\firstmark\kept@firstmark
2340       \let\botmark\kept@botmark
2341    \fi
2342 %    \end{macrocode}
2343 %    We also initalize |\topmark| with |\kept@topmark|. This will make
2344 %    this mark okay for all middle pages of the \mc{} environment.
2345 % \changes{v1.5d}{1993/09/15}{reinit \cs{topmark}}
2346 %    \begin{macrocode}
2347    \let\topmark\kept@topmark
2348 %<*marktrace>
2349    \mult@info\tw@
2350         {Use kept top mark:\MessageBreak
2351           \meaning\kept@topmark
2352          \MessageBreak
2353          Use kept first mark:\MessageBreak
2354           \meaning\kept@firstmark
2355         \MessageBreak
2356          Use kept bot mark:\MessageBreak
2357           \meaning\kept@botmark
2358         \MessageBreak
2359          Produce first mark:\MessageBreak
2360           \meaning\firstmark
2361         \MessageBreak
2362         Produce bot mark:\MessageBreak
2363           \meaning\botmark
2364          \@gobbletwo}%
2365 %</marktrace>
2366 %    \end{macrocode}
2367 %    With a little more effort we could have done better. If we had,
2368 %    for example, recorded the shrinkage of the material in
2369 %    |\partial@page| it would be now possible to try higher
2370 %    values for |\dimen@| (i.e.\ the column height) to overcome
2371 %    the problem with the nonempty box 255. But this would make the
2372 %    code even more complex so I skipped it in the current
2373 %    implementation.
2375 %    Now we use \LaTeX{}'s standard output
2376 %    mechanism.\footnote{This will produce a lot of overhead since both
2377 %                       output routines are held in memory. The correct
2378 %                       solution would be to redesign the whole output
2379 %                       routine used in \LaTeX.}
2380 %    Admittedly this is a funny way to do it.
2382 %    Within the OR |\boxmaxdepth| needs to be unrestricted so we set it back
2383 %    now as it was changed above.
2384 % \changes{v1.8p}{2016/04/07}{Reset \cs{boxmaxdepth}} 
2385 %    \begin{macrocode}
2386    \boxmaxdepth\maxdimen
2387    \setbox\@cclv\vbox{\unvbox\partial@page
2388                       \page@sofar}%
2389 %    \end{macrocode}
2390 %    The macro |\@makecol| adds all floats assigned for the current
2391 %    page to this page.  |\@outputpage| ships out the resulting box.
2392 %    Note that it is just possible that such floats are present even
2393 %    if we do not allow any inside a \mc{} environment.
2394 %    \begin{macrocode}
2395    \@makecol\@outputpage
2396 %    \end{macrocode}
2397 %    After the page is shipped out we have to prepare the kept marks
2398 %    for the following page. |\kept@firstmark| and |\kept@botmark|
2399 %    reinitialized by setting them to |\@empty|.  The value of
2400 %    |\botmark| is then assigned to |\kept@topmark|.
2401 % \changes{v1.4g}{1992/06/03}{Only change \cs{kept@topmark} if
2402 %                            \cs{kept@botmark} non-empty}
2403 % \changes{v1.4i}{1992/06/18}{Set \cs{kept@topmark} to \cs{botmark}}
2404 %    \begin{macrocode}
2405      \global\let\kept@topmark\botmark
2406      \global\let\kept@firstmark\@empty
2407      \global\let\kept@botmark\@empty
2408 %<*marktrace>
2409      \mult@info\tw@
2410         {(Re)Init top mark:\MessageBreak
2411          \meaning\kept@topmark
2412          \@gobbletwo}%
2413 %</marktrace>
2414 %    \end{macrocode}
2415 %    Now we reset |\@colroom| to |\@colht| which is \LaTeX's
2416 %    saved value of |\textheight|.
2417 %    We also have to reset the recorded position of the last
2418 %   |\marginpar| as well as the recorded size of intext floats 
2419 %    as we are now on a new page.
2420 % \changes{v1.8d}{2014/04/23}{Reset \cs{@mparbottom} after page finishes}
2421 % \changes{v1.8n}{2015/08/19}{Reset \cs{@textfloatsheight} after page finishes}
2422 %    \begin{macrocode}
2423    \global\@colroom\@colht
2424    \global \@mparbottom \z@
2425    \global \@textfloatsheight \z@
2426 %    \end{macrocode}
2427 %    Then we process deferred floats waiting for their chance to be
2428 %    placed on the next page.
2429 %    \begin{macrocode}
2430    \process@deferreds
2431    \@whilesw\if@fcolmade\fi{\@outputpage
2432       \global\@colroom\@colht
2433       \process@deferreds}%
2434 %    \end{macrocode}
2435 %    If the user is interested in statistics we inform him about the
2436 %    amount of space reserved for floats.
2437 %    \begin{macrocode}
2438    \mult@info\@ne
2439      {Colroom:\MessageBreak
2440       \the\@colht\space
2441               after float space removed
2442               = \the\@colroom \@gobble}%
2443 %    \end{macrocode}
2444 %    Having done all this we must prepare to tackle the next page.
2445 %    Therefore we assign a new value to |\vsize|.  New, because
2446 %    |\partial@page| is now empty and |\@colroom| might be
2447 %    reduced by the space reserved for floats.
2448 % \changes{v1.4p}{1992/11/26}{Use different \cs{vsize} setting}
2449 %    \begin{macrocode}
2450     \set@mult@vsize \global
2451 %    \end{macrocode}
2452 %    The |\footins| skip register will be adjusted when the output
2453 %    group is closed.
2454 % \changes{v1.3c}{1991/03/03}{Unnecessary code removed}
2455 %    \begin{macrocode}
2456   \fi}
2457 %    \end{macrocode}
2458 % \end{macro}
2462 % \begin{macro}{\leave@mult@footins}
2463 %    This macro is used to subtract the amount of space
2464 %    occupied by footnotes for the current space from the
2465 %    space available for the current column. The space current column
2466 %    is stored in |\dimen@|. See above for the description of the default
2467 %    action.
2468 % \changes{v1.5?}{1994/?/?}{Macro added}
2469 %    \begin{macrocode}
2470 \def\leave@mult@footins{%
2471    \advance\dimen@-\skip\footins
2472    \advance\dimen@-\ht\footins
2474 %    \end{macrocode}
2475 % \end{macro}
2479 % \begin{macro}{\speci@ls}
2480 %    We left out two macros: |\process@deferreds| and
2481 %    |\speci@ls|.
2482 % \changes{v1.5c}{1993/04/18}{Support \cs{clearpage}}
2483 %    \begin{macrocode}
2484 \def\speci@ls{%
2485  \ifnum\outputpenalty <-\@Mi
2486 %    \end{macrocode}
2487 %    If the document ends in the middle of a multicols environment, e.g.,
2488 %    if the user forgot the |\end{multicols}|, \TeX{} adds a very
2489 %    negative penalty to the end of the galley which is intended to signal
2490 %    the output routine that it is time to prepare for shipping out
2491 %    everything remaining. Since inside multicols the output routine of
2492 %    \LaTeX{} is disabled sometimes we better check for this case: if we
2493 %    find a very negative penalty we produce an error message and run
2494 %    the default output routine for this case.
2495 % \changes{v1.5s}{1998/09/10}{check for \cs{stop} penalty pr/2873}
2496 %    \begin{macrocode}
2497   \ifnum \outputpenalty<-\@MM
2498    \PackageError{multicol}{Document end
2499            inside multicols environment}\@ehd
2500    \@specialoutput
2501   \else
2502 %    \end{macrocode}
2503 % \changes{v1.5u}{1999/05/25}{Support \cs{columnbreak}}
2504 % \changes{v1.5v}{1999/07/18}{Added debug statements for
2505 %                             column break support}
2506 %    For the next block of code see comments in section~\ref{sec:colbreak}.
2507 %    \begin{macrocode}
2508      \ifnum\outputpenalty = -\@Mv
2509          \mult@info\@ne{Forced column
2510                         break seen}%
2511          \global\advance\vsize-\pagetotal
2512          \global\setbox\colbreak@box
2513            \vbox{%
2514               \ifvoid\colbreak@box
2515               \else
2516                 \unvbox\colbreak@box
2517                 \penalty-\@Mv
2518               \fi
2519 %    \end{macrocode}
2520 %    As this is the place of a forced break we now remove vertical
2521 %   white space just in front of it (or some of it at least) as it is
2522 %   quite likely that the break is not exactly in the right place,
2523 %   e.g., after a display environment (if LaTeX would break here by
2524 %   its own it would break before the space following the display).
2526 %   Thus we rebox box 255 once (using |\maxdepth| and calling
2527 %   |\remove@discardable@items| inside). The depth of 255 will then
2528 %   give us the depth the box would have had if it would have been a
2529 %   natural break. We then unbox 255 to get it into the
2530 %   |\colbreak@box| and then back up by this depth. This will position
2531 %   the bottom of the box at its natural baseline which is useful for
2532 %   balancing later on.
2533 % \changes{v1.8k}{2015/03/21}{Remove discarable items just before a
2534 %   forced break}
2535 %    \begin{macrocode}
2536               \boxmaxdepth\maxdepth
2537               \setbox\@cclv\vbox{%
2538                  \unvbox\@cclv
2539                  \remove@discardable@items}%
2540               \dimen@\dp\@cclv
2541               \unvbox\@cclv
2542               \kern-\dimen@
2543          }%
2544          \reinsert@footnotes
2545      \else
2546 %    \end{macrocode}
2547 %    If we encounter a float or a marginpar in the current
2548 %    implementation we simply warn the user that this is not allowed.
2549 %    Then we reinsert the page and its footnotes.
2550 %    \begin{macrocode}
2551         \PackageWarningNoLine{multicol}%
2552            {Floats and marginpars not
2553             allowed inside `multicols'
2554             environment!}%
2555         \unvbox\@cclv\reinsert@footnotes
2556 %    \end{macrocode}
2557 %    Additionally we empty the |\@currlist| to avoid later error
2558 %    messages when the \LaTeX{} output routine is again in force.
2559 %    But first we have to place the boxes back onto the
2560 %    |\@freelist|. (|\@elt|s default is |\relax| so
2561 %    this is possible with |\xdef|.)
2562 % \changes{v1.2a}{1990/02/05}{Float boxes freed.}
2563 %    \begin{macrocode}
2564        \xdef\@freelist{\@freelist\@currlist}%
2565        \gdef\@currlist{}%
2566      \fi
2567   \fi
2568 %    \end{macrocode}
2569 %    If the penalty is $-10001$ it will come from a |\clearpage| and
2570 %    we will execute |\@doclearpage| to get rid of any deferred
2571 %    floats.
2572 %    \begin{macrocode}
2573  \else \@doclearpage \fi
2575 %    \end{macrocode}
2576 % \end{macro}
2578 % \begin{macro}{\process@deferreds}
2579 %    |\process@deferreds| is a simplified version of \LaTeX{}'s
2580 %    |\@startpage|.  We first call the macro
2581 %    |\@floatplacement| to save the current user parameters in
2582 %    internal registers.  Then we start a new group and save the
2583 %    |\@deferlist| temporarily in the macro |\@tempb|.
2584 %    \begin{macrocode}
2585 \def\process@deferreds{%
2586    \@floatplacement
2587    \@tryfcolumn\@deferlist
2588    \if@fcolmade\else
2589      \begingroup
2590     \let\@tempb\@deferlist
2591 %    \end{macrocode}
2592 %    Our next action is to (globally) empty |\@deferlist| and
2593 %    assign a new meaning to |\@elt|.  Here |\@scolelt| is a
2594 %    macro that looks at the boxes in a list to decide whether they
2595 %    should be placed on the next page (i.e.\ on |\@toplist| or
2596 %    |\@botlist|) or should wait for further processing.
2597 %    \begin{macrocode}
2598       \gdef\@deferlist{}%
2599       \let\@elt\@scolelt
2600 %    \end{macrocode}
2601 %    Now we call |\@tempb| which has the form
2602 %    \begin{center}
2603 %      |\@elt|\meta{box register}|\@elt|^^A
2604 %                        \meta{box register}\ldots{}
2605 %    \end{center}
2606 %    So |\@elt| (i.e.\ |\@scolelt|) will distribute the
2607 %    boxes to the three lists.
2608 %    \begin{macrocode}
2609         \@tempb \endgroup
2610    \fi}
2611 %    \end{macrocode}
2612 % \end{macro}
2616 % \begin{macro}{ifshr@nking}
2617 % \begin{macro}{\raggedcolumns}
2618 % \begin{macro}{\flushcolumns}
2619 % \changes{v1.1a}{1989/09/20}{\cs{flushedcolumns} renamed to \cs{flushcolumns}.}
2620 %    The |\raggedcolumns| and |\flushcolumns|
2621 %    declarations are defined with the help of a new |\if...|
2622 %    macro.
2623 %    \begin{macrocode}
2624 \newif\ifshr@nking
2625 %    \end{macrocode}
2626 %    The actual definitions are simple: we just switch to {\sf true}
2627 %    or {\sf false} depending on the desired action. To avoid extra
2628 %    spaces in the output we enclose these changes in
2629 %    |\@bsphack|\ldots{}\allowbreak|\@esphack|.
2630 %    \begin{macrocode}
2631 \def\raggedcolumns{%
2632    \@bsphack\shr@nkingtrue\@esphack}
2633 \def\flushcolumns{%
2634    \@bsphack\shr@nkingfalse\@esphack}
2635 %    \end{macrocode}
2636 % \end{macro}
2637 % \end{macro}
2638 % \end{macro}
2641 % \begin{macro}{\balance@columns@out}
2642 %    Now for the last part of the show: the column balancing output
2643 %    routine.  Since this code is called with an explicit penalty
2644 %    (|\eject|) there is no need to check for something special (eg
2645 %    floats).  We start by balancing the material gathered.
2646 %    \begin{macrocode}
2647 \def\balance@columns@out{%
2648 %    \end{macrocode}
2649 %    For this we need to put the contents of box 255 into |\mult@box|.
2650 % \changes{v1.5u}{1999/05/25}{Support \cs{columnbreak}}
2651 % \changes{v1.5v}{1999/07/18}{Added debug statements for column break
2652 %   support} For the next block of code see also comments in
2653 %   section~\ref{sec:colbreak}.  All forced breaks except the last are
2654 %   inside |\colbreak@box| so all we have to do is to concatenate this
2655 %   box with box |\@cclv| and put a penalty inbetween. Here we test if
2656 %   |\colbreak@box| is void so that the message is only generated if
2657 %   we really add forced breaks and the penalty.
2658 % \changes{v1.8k}{2015/03/21}{Use \cs{@Mv} and not \cs{break} in case
2659 %   this forced break is not used on this page}
2660 %    \begin{macrocode}
2661    \setbox\mult@box\vbox{%
2662        \ifvoid\colbreak@box\else
2663          \unvbox\colbreak@box
2664          \penalty-\@Mv
2665          \mult@info\@ne{Re-adding
2666            forced break(s) in balancing}%
2667        \fi
2668        \unvbox\@cclv
2669 %    \end{macrocode}
2670 %    The last column again is a forced break, so here we discard white
2671 %   space as well as that is normally unwanted.
2672 % \changes{v1.8k}{2015/03/21}{Add \cs{remove@discardable@items} at the
2673 %   end of the last column when balancing.}
2674 %    \begin{macrocode}
2675        \remove@discardable@items
2676    }%
2677    \balance@columns
2678 %    \end{macrocode}
2679 %    If during balancing the columns got too long the flag
2680 %    |\iftoo@bad| is set to true.
2681 % \changes{v1.8a}{2011/12/20}{Balancing concept improved}
2682 %    \begin{macrocode}
2683    \iftoo@bad
2684      \mult@info\@ne
2685         {Balancing failed ...
2686          cut a normal page}%
2687 %    \end{macrocode}
2688 %    In that case we put the material back in box 255 so that we can
2689 %    cut a normal page. The curious set of
2690 %    |\vskip|s we add is necessary to  cancel out the |\splittopskip|
2691 %    that got added for balancing.
2692 %    \begin{macrocode}
2693      \setbox\@cclv\vbox
2694          {\vskip\topskip
2695           \vskip-\splittopskip
2696           \unvbox\mult@box}%
2697 %    \end{macrocode}
2698 %    We then call the standard multicol output routine which will
2699 %    produce a normal page for us (remember we are still within the
2700 %    OR so some part of the code in |\multi@column@out| is actually not
2701 %    doing anything---perhaps this should be cleaned up at some point).
2702 %    This also means that if there was an |\enlargethispage| present
2703 %    it will apply to this page as |\multi@column@out| will look at
2704 %    the status of |\@kludgeins|.
2705 %    \begin{macrocode}
2706      \multi@column@out
2707 %    \end{macrocode}
2708 %    Because balancing made the columns too long we are sure that there
2709 %    will be some material remaining which was put back onto the main
2710 %    vertical list by |\multi@column@out|. This will also put the
2711 %    explicit |\eject| penalty back so the current
2712 %    |\balance@columns@out| output routine will be called again (so we
2713 %    better do not add another penalty or else the OR will be called
2714 %    twice and we may get scrambled results).
2715 % \changes{v1.8k}{2015/03/21}{No additional penalty here}
2716 %    \begin{macrocode}
2717    \else
2718 %    \end{macrocode}
2719 %    If the balancing went ok, we are in the position
2720 %    to apply |\page@sofar|.  But first we have to set |\vsize| to a
2721 %    value suitable for one column output.
2722 %    \begin{macrocode}
2723      \global\vsize\@colroom
2724      \global\advance\vsize\ht\partial@page
2725 %    \end{macrocode}
2726 %    We also have to look at |\@kludgeins| and generate a new
2727 %    |\insert| in case there was one present due to an
2728 %    |\enlargethispage| command.
2729 % \changes{v1.8a}{2011/12/20}{Support for \cs{enlargethispage}}
2730 %    \begin{macrocode}
2731      \ifvbox\@kludgeins\insert\@kludgeins
2732                         {\unvbox\@kludgeins}\fi
2733 %    \end{macrocode}
2734 %    Then we |\unvbox| the |\partial@page| (which may be void if we
2735 %    are not processing the first page of this \mc{} environment.
2736 %    \begin{macrocode}
2737      \unvbox\partial@page
2738 %    \end{macrocode}
2739 %    Then we return the first and bottom mark and the gathered
2740 %    material to the main vertical list.
2741 %    \begin{macrocode}
2742      \return@nonemptymark{first}\kept@firstmark
2743      \return@nonemptymark{bot}\kept@botmark
2744      \page@sofar
2745 %    \end{macrocode}
2746 %    We need to add a penalty at this point which allows to break at
2747 %    this point since calling the output routine may have removed the
2748 %    only permissible break point thereby ``glueing'' any following
2749 %    skip to the balanced box. In case there are any weird settings
2750 %    for |\multicolsep| etc. this could produce funny results.
2751 %  \changes{v1.5c}{1993/04/18}{added penalty at output routine exit}
2752 %    \begin{macrocode}
2753      \penalty\z@
2754   \fi
2756 %    \end{macrocode}
2757 %    As we already know, reinserting of footnotes will be done in the
2758 %    macro |\endmulticols|.
2759 % \end{macro}
2762 %  \begin{macro}{\balance@columns}
2763 %    This macro now does the actual balancing.
2764 %    \begin{macrocode}
2765 \def\balance@columns{%
2766 %    \end{macrocode}
2767 %    We start by setting the kept marks by updating them with any
2768 %    marks from this box. This has to be done \emph{before} we add a
2769 %    penalty of $-10000$ to the top of the box, otherwise only an
2770 %    empty box will be considered.
2771 % \changes{v1.5h}{1994/08/26}{Get kept marks first}
2772 %    \begin{macrocode}
2773    \get@keptmarks\mult@box
2774 %    \end{macrocode}
2775 %    We then continue by resetting trying to remove any discardable
2776 %    stuff at the end of |\mult@box|. This is rather experimental.  We
2777 %    also add a forced break point at the very beginning, so that we
2778 %    can split the box to height zero later on, thereby adding a known
2779 %    |\splittopskip| glue at the beginning.
2780 % \changes{v1.8k}{2015/03/21}{\cs{remove@discardable@items} removed}
2781 %    \begin{macrocode}
2782    \setbox\mult@box\vbox{%
2783         \penalty-\@M
2784         \unvbox\mult@box
2785         }%
2786 %    \end{macrocode}
2787 %    Then follow values assignments to get the |\vsplit|ting right.
2788 %    We use the natural part of |\topskip| as the natural part for
2789 %    |\splittopskip| and allow for a bit of undershoot and overshoot
2790 %    by adding some stretch and shrink.
2791 % \changes{v1.5?}{1994/?/?}{Allow columns to come out a bit long or short}
2792 %    \begin{macrocode}
2793    \@tempdima\topskip
2794    \splittopskip\@tempdima
2795        \@plus\multicolundershoot
2796        \@minus\multicolovershoot
2797    \splitmaxdepth\maxdepth
2798 %    \end{macrocode}
2799 %   We also have to set |\boxmaxdepth| which normally allows to
2800 %   build boxes with arbitrary depth, but as we are building text
2801 %   columns we really want to restrict the depth. This is necessary as
2802 %   we sometimes rebox the boxes generated by |\vsplit| and then the
2803 %   restriction posed by |\splitmaxdepth|  gets lost.
2804 % \changes{v1.8h}{2014/09/12}{All column boxes should obey
2805 %   \cs{maxdepth}  (pr/4395)}
2806 %    \begin{macrocode}
2807    \boxmaxdepth\maxdepth
2808 %    \end{macrocode}
2809 %    The next step is a bit tricky: when \TeX{} assembles material in
2810 %    a box, the first line isn't preceded by interline glue, i.e.
2811 %    there is no parameter like |\boxtopskip| in \TeX{}. This means
2812 %    that the baseline of the first line in our box is at some
2813 %    unpredictable point depending on the height of the largest
2814 %    character in this line. But of course we want all columns to
2815 %    align properly at the baselines of their first lines. For this
2816 %    reason we have opened |\mult@box| with a |\penalty| {\sf -10000}.
2817 %    This will now allow us to split off from |\mult@box| a tiny bit
2818 %    (in fact nothing since the first possible break-point is the
2819 %    first item in the box). The result is that |\splittopskip| is
2820 %    inserted at the top of |\mult@box| which is exactly what we like
2821 %    to achieve.
2822 % \changes{v1.5?}{1994/?/?}{Do splitting to zero here}
2823 %    \begin{macrocode}
2824    \setbox\@tempboxa\vsplit\mult@box to\z@
2825 %    \end{macrocode}
2826 %    Next we try to find a suitable starting point for the calculation
2827 %    of the column height.  It should be less than the height finally
2828 %    chosen, but large enough to reach this final value in only a few
2829 %    iterations.  The formula which is now implemented will try to
2830 %    start with the nearest value which is a multiple of
2831 %    |\baselineskip|. The coding is slightly tricky in \TeX{} and
2832 %    there are perhaps better ways \ldots
2833 % \changes{v1.4d}{1992/03/04}{New algorithm for start height}
2834 %    \begin{macrocode}
2835    \@tempdima\ht\mult@box
2836    \advance\@tempdima\dp\mult@box
2837    \divide\@tempdima\col@number
2838 %    \end{macrocode}
2839 %    The code above sets |\@tempdima| to the length of a column if we
2840 %    simply divide the whole box into equal pieces. To get to the next
2841 %    lower multiple of |\baselineskip| we convert this dimen to a
2842 %    number (the number of scaled points) then divide this by
2843 %    |\baselineskip| (also in scaled points) and then multiply this
2844 %    result with |\baselineskip| assigning the result to |\dimen@|.
2845 %    This makes |\dimen@| $\leq$ to |\@tempdimena|.
2846 %    \begin{macrocode}
2847    \count@\@tempdima
2848    \divide\count@\baselineskip
2849    \dimen@\count@\baselineskip
2850 %    \end{macrocode}
2851 %    Next step is to correct our result by taking into account the
2852 %    difference between |\topskip| and |\baselineskip|. We start by
2853 %    adding |\topskip|; if this makes the result too large then we
2854 %    have to subtract one |\baselineskip|.
2855 %    \begin{macrocode}
2856    \advance\dimen@\topskip
2857    \ifdim \dimen@ >\@tempdima
2858      \advance\dimen@-\baselineskip
2859    \fi
2860 %    \end{macrocode}
2861 %    At the user's request we start with a higher value (or lower, but
2862 %    this usually only increases the number of tries).
2863 %    \begin{macrocode}
2864    \advance\dimen@\c@unbalance\baselineskip
2865 %    \end{macrocode}
2866 %    We type out statistics if we were asked to do so.
2867 % \changes{v1.4f}{1992/04/28}{\cs{on@line} added to tracing info}
2868 %    \begin{macrocode}
2869    \mult@info\@ne
2870       {Balance columns\on@line:
2871         \ifnum\c@unbalance=\z@\else
2872        (off balance=\number\c@unbalance)\fi
2873       \@gobbletwo}%
2874 %    \end{macrocode}
2875 %    But we don't allow nonsense values for a start.
2876 %    \begin{macrocode}
2877    \ifnum\dimen@<\topskip
2878      \mult@info\@ne
2879        {Start value
2880           \the\dimen@  \space ->
2881           \the\topskip \space (corrected)}%
2882      \dimen@\topskip
2883    \fi
2884 %    \end{macrocode}
2885 %    Now we try to find the final column height.  We start by setting
2886 %    |\vbadness| to infinity (i.e.\ $10000$) to suppress
2887 %    underfull box reports while we are trying to find an acceptable
2888 %    solution.  We do not need to do it in a group since at the end of
2889 %    the output routine everything will be restored. The setting of
2890 %    the final columns will nearly always produce underfull boxes with
2891 %    badness $10000$ so there is no point in warning the user about
2892 %    it.
2893 % \changes{v1.2a}{1990/02/05}{Group around main loop removed.}
2894 %    \begin{macrocode}
2895    \vbadness\@M
2896 %    \end{macrocode}
2897 %    We also allow for overfull boxes while we trying to split the
2898 %    columns. They can easily happen if we have objects with unusual depth. 
2899 % \changes{v1.8h}{2014/09/12}{Do not report overfull}
2900 %    \begin{macrocode}
2901    \vfuzz \maxdimen
2902 %    \end{macrocode}
2903 %    The variable |\last@try| will hold the dimension used in the
2904 %    previous trial splitting. We initialize it with a negative value.
2905 % \changes{v1.5?}{1994/?/?}{Initialize \cs{last@try}}
2906 %    \begin{macrocode}
2907    \last@try-\p@
2908    \loop
2909 %    \end{macrocode}
2910 %    In order not to clutter up \TeX{}'s valuable main memory with
2911 %    things that are no longer needed, we empty all globally used box
2912 %    registers. This is necessary if we return to this point after an
2913 %    unsuccessful trial.  We use |\process@cols| for this purpose,
2914 %    starting with |\mult@grightbox|.  Note the extra braces around
2915 %    this macro call.  They are needed since \PlainTeX{}'s
2916 %    |\loop|\ldots{}\allowbreak|\repeat| mechanism cannot be nested on
2917 %    the same level of grouping.
2918 % \changes{v1.5a}{1992/11/04}{New box mechanism}
2919 %    \begin{macrocode}
2920     {\process@cols\mult@grightbox
2921            {\global\setbox\count@
2922                    \box\voidb@x}}%
2923 %    \end{macrocode}
2924 %    The contents of box |\mult@box| are now copied globally to
2925 %    box~|\mult@grightbox|.  (This will be the right-most column, as
2926 %    we shall see later.)
2927 %    \begin{macrocode}
2928     \global\setbox\mult@grightbox
2929            \copy\mult@box
2930 %    \end{macrocode}
2931 %    We start with the assumption that the trial will be successful.
2932 %    If we end up with a solution that is too bad we set
2933 %    |too@bad| to \texttt{true}. We also assume that all forced breaks
2934 %    (if any) will be used during balancing. If this is not the case
2935 %    we record this in |forcedbreak@leftover|.
2936 % \changes{v1.5b}{1992/11/05}{New badness mechanism}
2937 % \changes{v1.8k}{2015/03/21}{Init \cs{ifforcedbreak@leftover}}
2938 %    \begin{macrocode}
2939 %<*badness>
2940    \too@badfalse
2941    \forcedbreak@leftoverfalse
2942 %</badness>
2943 %    \end{macrocode}
2944 %    Using |\vsplit| we extract the other columns from box register
2945 %    |\mult@grightbox|.  This leaves box register |\mult@box|
2946 %    untouched so that we can start over again if this trial was
2947 %    unsuccessful.
2948 %    \begin{macrocode}
2949    {\process@cols\mult@firstbox{%
2950          \global\setbox\count@
2951          \vsplit\mult@grightbox to\dimen@
2952 %    \end{macrocode}
2953 %    After splitting we need to ensure that there isn't any space at
2954 %    the bottom, so we rebox once more.
2955 % \changes{v1.8b}{2013/08/28}{Remove discardable items at the
2956 %                             end of split boxes}
2957 % \changes{v1.8k}{2015/03/21}{Do not use \cs{remove@discardable@items}
2958 %    here}
2959 %    \begin{macrocode}
2960          \global\setbox\count@
2961                  \vbox to\dimen@
2962                   {\unvbox\count@}%
2963 %    \end{macrocode}
2964 %    After every split we check the badness of the resulting column,
2965 %    normally the amount of extra white in the column.
2966 %    \begin{macrocode}
2967 %<*badness>
2968          \ifnum\c@tracingmulticols>\@ne
2969            \@tempcnta\count@
2970            \advance\@tempcnta-\mult@grightbox
2971            \divide\@tempcnta \tw@
2972            \message{^^JColumn
2973               \number\@tempcnta\space
2974                badness: \the\badness\space}%
2975          \fi
2976 %    \end{macrocode}
2977 %    If this badness is larger than the allowed column badness
2978 %    we reject this solution by setting |too@bad| to \texttt{true}.
2979 %    \begin{macrocode}
2980          \ifnum\badness>\c@columnbadness
2981            \ifnum\c@tracingmulticols>\@ne
2982              \message{too bad
2983                   (>\the\c@columnbadness)}%
2984            \fi
2985            \too@badtrue
2986          \fi
2987 %</badness>
2988                         }}%
2989 %    \end{macrocode}
2990 %    There is one subtle point here: while all other constructed boxes
2991 %    have a depth that is determined by |\splitmaxdepth| and/or
2992 %   |\boxmaxdepth| the last box
2993 %    will get a natural depth disregarding the original setting and
2994 %    the value of |\splitmaxdepth| or |\boxmaxdepth|. This means that
2995 %    we may end up with a very large depth in box |\mult@grightbox|
2996 %    which would
2997 %    make the result of the testing incorrect. So we change the value
2998 %    by unboxing the box into itself.
2999 %    \begin{macrocode}
3000    \global\setbox\mult@grightbox
3001       \vbox{\unvbox\mult@grightbox}%
3002 %    \end{macrocode}
3003 %    We also save a copy |\mult@firstbox| at its ``natural'' size
3004 %    for later use.
3005 %    \begin{macrocode}
3006    \setbox\mult@nat@firstbox
3007       \vbox{\unvcopy\mult@firstbox}%
3008 %    \end{macrocode}
3009 %    After |\process@cols| has done its job we have the following
3010 %    situation:
3011 %    \begin{center}
3012 %      \begin{tabular}{r@{$\:\:\longleftarrow\:\:$}l}
3013 %        box |\mult@rightbox| & all material \\
3014 %        box |\mult@gfirstbox| & first column \\
3015 %        box |\mult@gfirstbox|${}+2$ & second column \\
3016 %        \multicolumn{1}{c}{$\vdots$} &
3017 %        \multicolumn{1}{c}{$\vdots$} \\
3018 %        box |\mult@grightbox| & last column
3019 %      \end{tabular}
3020 %    \end{center}
3021 %    We report the height of the first column, in brackets
3022 %    the natural size is given.
3023 % \changes{v1.5?}{1994/?/?}{Show natural size}
3024 %    \begin{macrocode}
3025     \ifnum\c@tracingmulticols>\@ne
3026        \message{^^JFirst column
3027            = \the\dimen@\space
3028            (\the\ht\mult@nat@firstbox)}\fi
3029 %    \end{macrocode}
3030 %    If |\raggedcolumns| is in force older releases of this file also
3031 %    shrank the first column to its natural height at this point.
3032 %    This was done so that the first column doesn't run short compared
3033 %    to later columns but it is actually producing incorrect results
3034 %    (overprinting of text) in boundary cases, so since version v1.5q
3035 %    |\raggedcolumns| means allows for all columns to run slightly short.
3036 % \changes{v1.5q}{1998/01/19}{Do not reset \cs{mult@firstbox} (pr2739)}
3037 %    \begin{macrocode}
3038 %    \ifshr@nking
3039 %      \global\setbox\mult@firstbox
3040 %             \copy\mult@nat@firstbox
3041 %    \fi
3042 %    \end{macrocode}
3043 %    Then we give information about the last column.\footnote{With
3044 %    \TeX{} version 3.141 it is now possible to use \LaTeX's
3045 %    \cs{newlinechar} in the \cs{message} command, but
3046 %    people with older \TeX{} versions will now get
3047 %    \texttt{\string^\string^J} instead of a new line on the screen.}
3048 % \changes{v1.4a}{1992/02/12}{Changed to proper \cs{endlinechar} in\cs{message}}
3049 %    \begin{macrocode}
3050     \ifnum\c@tracingmulticols>\@ne
3051       \message{<> last column =
3052                \the\ht\mult@grightbox^^J}%
3053 %    \end{macrocode}
3054 %    Some tracing code that we don't compile into the production version
3055 %    unless asked for. It will produce huge listings of the boxes
3056 %    involved in balancing in the transcript file.
3057 % \changes{v1.6f}{2004/07/03}{need to use \cs{mult@grightbox} in the loop}
3058 %    \begin{macrocode}
3059 %<*debug>
3060       \ifnum\c@tracingmulticols>4
3061          {\showoutput
3062           \batchmode
3063           \process@cols\mult@grightbox
3064            {\showbox\count@}}%
3065           \errorstopmode
3066       \fi
3067 %</debug>
3068      \fi
3069 %    \end{macrocode}
3070 %    We check whether our trial was successful.  The test used is very
3071 %    simple: we merely compare the first and the last column.  Thus
3072 %    the intermediate columns may be longer than the first if
3073 %    |\raggedcolumns| is used.  If the right-most column is
3074 %    longer than the first then we start over with a larger value for
3075 %    |\dimen@|.
3076 % \changes{v1.3c}{1991/03/03}{\cs{global}\cs{advance} left over from older code}
3077 %    \begin{macrocode}
3078     \ifdim\ht\mult@grightbox >\dimen@
3079 %    \end{macrocode}
3080 %    If the height of the last box is too large we mark this trial as
3081 %    unsuccessful.
3082 % \changes{v1.5v}{1999/07/18}{Added tracing statements for
3083 %                             trial unsuccessful}
3084 %    \begin{macrocode}
3085 %<*badness>
3086       \too@badtrue
3087       \ifnum\c@tracingmulticols>\@ne
3088          \typeout{Rejected: last
3089                  column too large!}%
3090       \fi
3091     \else
3092 %    \end{macrocode}
3093 % \changes{v1.5v}{1999/07/18}{Check last column if it contains forced
3094 %    break and reject trial if that is the case}
3096 %    To ensure that there isn't a forced break in the last column we
3097 %    try to split off a box of size |\maxdimen| from |\mult@grightbox|
3098 %    (or rather from a copy of it). This should result in a void box
3099 %    after the split, unless there was a forced break somewhere within
3100 %    the column in which case the material after the break would have
3101 %    stayed in the box.
3102 %    \begin{macrocode}
3103       \setbox\@tempboxa
3104            \copy\mult@grightbox
3105       \setbox\z@\vsplit\@tempboxa to\maxdimen
3106       \ifvoid\@tempboxa
3107 %    \end{macrocode}
3108 %    Thus if |\@tempboxa| is void we  have a valid solution.
3109 %    In this case we take a closer
3110 %    look at the last column to decide if this column should be made
3111 %    as long as all other columns or if it should be allowed to be
3112 %    shorter.
3113 %    For this we first have to rebox the column into a box of the
3114 %    appropriate height. If tracing is enabled we then display the
3115 %    badness for this box.
3116 %    \begin{macrocode}
3117         \global\setbox\mult@grightbox
3118            \vbox to\dimen@
3119               {\unvbox\mult@grightbox}%
3120         \ifnum\c@tracingmulticols>\@ne
3121           \message{Final badness:
3122                    \the\badness}%
3123         \fi
3124 %    \end{macrocode}
3125 %    We then compare this badness with the allowed badness for the final
3126 %    column. If it does not exceed this value we use the box, otherwise
3127 %    we rebox it once more and add some glue at the bottom.
3128 % \changes{v1.8h}{2014/09/12}{Use \cs{vfilmaxdepth}}
3129 % \changes{v1.8j}{2015/03/07}{Use \cs{vfil} in this case}
3130 %    \begin{macrocode}
3131         \ifnum\badness>\c@finalcolumnbadness
3132           \global\setbox\mult@grightbox
3133            \vbox to\dimen@
3134               {\unvbox\mult@grightbox\vfil}%
3135            \ifnum\c@tracingmulticols>\@ne
3136              \message{ setting natural
3137               (> \the\c@finalcolumnbadness)}%
3138            \fi
3139         \fi
3140 %    \end{macrocode}
3141 %    If |\@tempboxa| above was not void our trial was unsuccessful and
3142 %    we report this fact and try again.
3143 % \changes{v1.6f}{2004/07/03}{\texttt{/colbreak} guard in the wrong position}
3144 %    \begin{macrocode}
3145       \else
3146 %    \end{macrocode}
3147 %    If we have unprocessed forced breaks we normally reiterate with a
3148 %    larger column size to fit them in eventually. However, if there
3149 %    are simply too many of them (e.g., 3 forced breaks but only 2
3150 %    columns to balance) then this will never succeed and and we would
3151 %    continue growing the columns until we hit the largest possible
3152 %    column size. So in addition we check how big the column size is
3153 %    compared to available room and if we exceed this by
3154 %    |\maxbalancingoverflow| we give up and instead of balancing cut
3155 %    another normal page. To be indicate this case we set
3156 %    |forcedbreak@leftover| to true.
3157 % \changes{v1.8k}{2015/03/21}{Watch out for columns growing too far in
3158 %    case of forced breaks}
3159 % \changes{v1.8l}{2015/03/25}{Added additional tracing if column overflows}
3160 %    \begin{macrocode}
3161        \@tempdima\@colroom
3162        \advance\@tempdima \maxbalancingoverflow
3163        \ifdim \dimen@ < \@tempdima
3164         \too@badtrue
3165          \ifnum\c@tracingmulticols>\@ne
3166            \typeout{Rejected: unprocessed
3167              forced break(s) in last column!}%
3168          \fi
3169        \else
3170          \forcedbreak@leftovertrue
3171          \ifnum\c@tracingmulticols>\@ne
3172           \typeout{Failed: columns too large
3173             with unprocessed forced break(s)!}%
3174          \fi
3175        \fi
3176       \fi
3177     \fi
3178 %    \end{macrocode}
3179 %    If the natural height of the first box is smaller than the
3180 %    current trial size but is larger than the previous trial size it
3181 %    is likely that we have missed a potentially better
3182 %    solution. (This could have happened if for some reason our first
3183 %    trial size was too high.) In that case we dismiss this trial and
3184 %    restart using the natural height for the next trial.
3185 %    \begin{macrocode}
3186     \ifdim\ht\mult@nat@firstbox<\dimen@
3187       \ifdim\ht\mult@nat@firstbox>\last@try
3188         \too@badtrue
3189         \ifnum\c@tracingmulticols>\@ne
3190            \typeout{Retry: using natural
3191                     height of first column!}%
3192         \fi
3193         \dimen@\ht\mult@nat@firstbox
3194         \last@try\dimen@
3195         \advance\dimen@-\p@
3196       \fi
3197     \fi
3198 %    \end{macrocode}
3199 %    Finally the switch |too@bad| is tested. If it was made true
3200 %    either earlier on or due to a rightmost column being too large
3201 %    we try again with a slightly larger value for |\dimen@|.
3202 %    \begin{macrocode}
3203     \iftoo@bad
3204 %</badness>
3205       \advance\dimen@\p@
3206     \repeat
3207 %    \end{macrocode} 
3208 %    If we come out of the loop with the switch |forcedbreak@leftover|
3209 %    set to true then balancing has failed and we should cut a normal
3210 %    page. We indicate this below with |\too@badtrue| when any of the
3211 %    columns get too high, so we set this flag here too in order to
3212 %    get the same processing logic.\footnote{Should get cleaned up as
3213 %    we now have two different routes to reach this part of the
3214 %    processing.}
3215 % \changes{v1.8k}{2015/03/21}{}
3216 %    \begin{macrocode}
3217     \ifforcedbreak@leftover
3218        \too@badtrue
3219     \else
3220 %    \end{macrocode}
3221 %    At that point |\dimen@| holds the height that was determined by
3222 %    the balancing loop.
3223 %    If that height for the columns turns out to be larger
3224 %    than the available space (which is |\@colroom|) we squeeze the
3225 %    columns into the space assuming that they will have enough
3226 %    shrinkability to allow this.\footnote{This might be wrong, since
3227 %    the shrinkability that accounts for the amount of material might
3228 %    be present only in some columns. But it is better to try then to
3229 %    give up directly.}
3230 %    However, this squeezing should only be done if we are balancing
3231 %    columns on the main galley and \emph{not} if we are building a
3232 %    boxed multicol (in the latter case the current |\@colroom| is
3233 %    irrelevant since the produced box might be moved anywhere at a
3234 %    later stage).
3235 % \changes{v1.3c}{1991/03/03}{Limit column height to \cs{@colroom}}
3236 % \changes{v1.5q}{1998/01/19}{Removed setting \cs{dimen@} (pr2739)}
3237 % \changes{v1.5y}{2000/06/10}{Limit column height only in unrestricted
3238 %    mode (pr/3212)}
3239 %    \begin{macrocode}
3240      \if@boxedmulticols\else
3241        \ifdim\dimen@>\@colroom
3242          \dimen@\@colroom
3243        \fi
3244      \fi
3245 %    \end{macrocode}
3246 %    Then we move the contents of the odd-numbered box registers to
3247 %    the even-numbered ones, shrinking them if requested.
3248 %    We have to use |\vbox| not |\vtop| (as it was done in
3249 %    the first versions) since otherwise the resulting boxes will have
3250 %    no height (\TB\/ page 81). This would mean that extra
3251 %    |\topskip|  is added when the boxes are returned to the
3252 %    page-builder via |\page@sofar|.
3253 % \changes{v1.3a}{1990/05/20}{Changed \cs{vtop} to \cs{vbox}.}
3254 %    \begin{macrocode}
3255      \process@cols\mult@rightbox
3256          {\@tempcnta\count@
3257           \advance\@tempcnta\@ne
3258 %    \end{macrocode}
3259 %    when putting the final column together we want overfull
3260 %    information:
3261 %    \begin{macrocode}
3262           \vfuzz\z@
3263           \setbox\count@\vbox to\dimen@
3264              {%
3265 %    \end{macrocode}
3267 % \changes{v1.8h}{2014/09/12}{Use \cs{vfilmaxdepth}}
3268 %    \begin{macrocode}
3269               \vskip \z@
3270                 \@plus-\multicolundershoot
3271                 \@minus-\multicolovershoot
3272               \unvbox\@tempcnta
3273               \ifshr@nking\vfilmaxdepth\fi
3274              }%
3275 %    \end{macrocode}
3276 %    If the resulting box is overfull there was too much material to
3277 %    fit into the available space. The question though is how much? If
3278 %    it wasn't more than |\maxbalancingoverflow| we accept it still to
3279 %    avoid getting very little material for the next page (which we
3280 %    would then have difficulties to balance).
3281 % \changes{v1.8a}{2011/12/20}{Balancing concept improved}
3282 %    \begin{macrocode}
3283           \ifnum\badness>\@M
3284             \vfuzz\maxdimen % no overfull warning
3285             \setbox\@tempboxa \vbox to\dimen@
3286                  {\vskip-\maxbalancingoverflow
3287                   \unvcopy\count@}%
3288             \ifnum\badness>\@M
3289               \mult@info\@ne
3290                 {Balanced column more than
3291                   \the\maxbalancingoverflow\space
3292                   too large}%
3293 %    \end{macrocode}
3294 %    Fail the balancing attempt:
3295 %    \begin{macrocode}
3296               \too@badtrue
3297             \else
3298 %    \end{macrocode}
3299 %    Otherwise report that there is a problem but within the accepted
3300 %    boundary.
3301 %    \begin{macrocode}
3302               \mult@info\@ne
3303                 {Balanced column
3304                  too large, but less than
3305                  \the\maxbalancingoverflow}%
3306             \fi
3307           \fi
3308          }%
3309 %    \end{macrocode}
3310 %    Finally end the |\ifforcedbreak@leftover| conditional.
3311 % \changes{v1.8k}{2015/03/21}{Finish the new conditional}
3312 %    \begin{macrocode}
3313    \fi
3315 %    \end{macrocode}
3316 %  \end{macro}
3319 % \begin{macro}{\maxbalancingoverflow}
3320 %    Amount that balancing is allowed to overflow the available column
3321 %    space. We default to 12pt which means about one line in most
3322 %    layouts.
3323 % \changes{v1.8a}{2011/12/20}{\cs{maxbalancingoverflow} parameter added}
3324 %    \begin{macrocode}
3325 \newdimen\maxbalancingoverflow
3326 \maxbalancingoverflow=12pt
3327 %    \end{macrocode}
3328 %  \end{macro}
3330 % \end{multicols}
3332 % \begin{multicols}{2}[\subsection{The box allocations}]
3334 % \begin{macro}{\mult@rightbox}
3335 % \begin{macro}{\mult@grightbox}
3336 % \begin{macro}{\mult@firstbox}
3337 % \begin{macro}{\mult@gfirstbox}
3338 %    Early releases of these macros used the first box registers
3339 %    0, 2, 4,\ldots\ for global boxes and 1, 3, 5,\ldots\ for the
3340 %    corresponding local boxes. (You might still find some traces
3341 %    of this setup in the documentation, sigh.) This produced a problem
3342 %    at the moment we had more than 5 columns because then officially
3343 %    allocated boxes were overwritten by the algorithm.
3344 %    The new release now uses private box registers
3345 %    \begin{macrocode}
3346 \newbox\mult@rightbox
3347 \newbox\mult@grightbox
3348 \newbox\mult@gfirstbox
3349 \newbox\mult@firstbox
3350 \newbox\@tempa\newbox\@tempa
3351 \newbox\@tempa\newbox\@tempa
3352 \newbox\@tempa\newbox\@tempa
3353 \newbox\@tempa\newbox\@tempa
3354 \newbox\@tempa\newbox\@tempa
3355 \newbox\@tempa\newbox\@tempa
3356 \newbox\@tempa\newbox\@tempa
3357 \newbox\@tempa\newbox\@tempa
3358 \newbox\@tempa
3359 \let\@tempa\relax
3360 %    \end{macrocode}
3361 % \end{macro}
3362 % \end{macro}
3363 % \end{macro}
3364 % \end{macro}
3367 % \end{multicols}
3370 % \begin{multicols}{2}[\section{New macros and hacks for version 1.2}]
3372 % \begin{macro}{\emergencystretch}
3373 % \begin{macro}{\setemergencystretch}
3374 %    If we don't use \TeX{} 3.0 |\emergencystretch| is undefined
3375 %    so in this case we simply add it as an unused \meta{dimen}
3376 %    register.
3377 % \changes{v1.4j}{1992/06/25}{Setting of \cs{emergencystretch} on top
3378 %                  removed.}
3379 %    \begin{macrocode}
3380 \@ifundefined{emergencystretch}
3381      {\newdimen\emergencystretch}{}
3382 %    \end{macrocode}
3383 % \changes{v1.2a}{1990/02/05}{Macro added.}
3384 %    My tests showed that the following formula worked pretty well.
3385 %    Nevertheless the |\setemergencystretch| macro also gets
3386 %    |\hsize| as second argument to enable the user to try
3387 %    different formulae.
3388 %    \begin{macrocode}
3389 \def\setemergencystretch#1#2{%
3390    \emergencystretch 4pt
3391    \multiply\emergencystretch#1}
3392 %    \end{macrocode}
3393 % \end{macro}
3394 % \end{macro}
3397 % \begin{macro}{\set@floatcmds}
3398 % \changes{v1.2a}{1990/02/05}{Macro added.}
3399 % \changes{v1.5g}{1994/06/07}{Updated since floats have changed}
3400 % \changes{v1.5j}{1994/06/07}{Updated since floats have changed again}
3401 % \changes{v1.5l}{1995/10/19}{Added \cs{@largefloatcheck}}
3402 % \changes{v1.6g}{2006/02/23}{Added \cs{@minipagefalse}}
3403 % \changes{v1.6h}{2008/12/05}{Use \cs{@endfloatbox} to better support
3404 %   the modifications done by the float package}
3405 %    Even if this should be used as a hook we use a |@| in the
3406 %    name since it is more for experts.
3407 %    \begin{macrocode}
3408 \def\set@floatcmds{%
3409  \let\@dblfloat\@dbflt
3410  \def\end@dblfloat{\@endfloatbox
3411    \@largefloatcheck
3412    \outer@nobreak
3413 %    \end{macrocode}
3414 %    This is cheap (deferring the floats until after the current page)
3415 %    but any other solution would go deep into \LaTeX's output
3416 %    routine and I don't like to work on it until I know which parts
3417 %    of the output routine have to be reimplemented anyway for
3418 %    \LaTeX3.
3419 %    \begin{macrocode}
3420    \ifnum\@floatpenalty<\z@
3421 %    \end{macrocode}
3422 %    We have to add the float to the |\@deferlist| because we assume
3423 %    that outside the \mc{} environment we are in one column mode.
3424 %    This is not entirely correct, I already used the \mc{}
3425 %    environment inside of \LaTeX{}s |\twocolumn| declaration but it
3426 %    will do for most applications.
3427 %    \begin{macrocode}
3428      \@cons\@deferlist\@currbox
3429    \fi
3430    \ifnum\@floatpenalty=-\@Mii
3431      \@Esphack
3432    \fi}}
3433 %    \end{macrocode}
3434 % \end{macro}
3436 % \end{multicols}
3438 % \begin{multicols}{2}[\subsection{Maintaining the mark registers}]
3439 % \label{sec:v14}
3441 % This section contains the routines that set the marks so that they
3442 % will be handled correctly. They have been introduced with version~1.4.
3444 %  \begin{macro}{\kept@topmark}
3445 % \changes{v1.4h}{1992/06/04}{Init to double brace pair}
3446 %  \begin{macro}{\kept@firstmark}
3447 %  \begin{macro}{\kept@botmark}
3448 %    First thing we do is to reserve three macro names to hold the
3449 %    replacement text for \TeX's primitives |\firstmark|, |\botmark| and
3450 %    |\topmark|. We initialize the first two to be empty and
3451 %    |\kept@topmark| to contain  two empty pair of braces. This is
3452 %    necessary since |\kept@topmark| is supposed to contain the last
3453 %    mark from a preceding page and in \LaTeX{} any ``real'' mark must
3454 %    contain two parts representing left and right mark information.
3455 %    \begin{macrocode}
3456 \def\kept@topmark{{}{}}
3457 \let\kept@firstmark\@empty
3458 \let\kept@botmark\@empty
3459 %    \end{macrocode}
3460 %  \end{macro}
3461 %  \end{macro}
3462 %  \end{macro}
3465 %  \begin{macro}{\return@nonemptymark}
3466 %    Sometimes we want to return the value of a ``kept'' mark into a
3467 %    |\mark| node on the main vertical list. This is done by the
3468 %    function |\return@nonemptymark|. As the name suggests it only acts
3469 %    if the replacement text of the kept mark is non-empty. This is done
3470 %    to avoid adding an empty mark when no mark was actually present. If
3471 %    we would nevertheless add such a mark it would be regarded as a
3472 %    valid |\firstmark| later on.
3473 %    \begin{macrocode}
3474 \def\return@nonemptymark#1#2{%
3475   \ifx#2\@empty
3476   \else
3477 %    \end{macrocode}
3478 %    For debugging purposes we take a look at the value of the kept mark
3479 %    that we are about to return. This code will get stripped out for
3480 %    production.
3481 %    \begin{macrocode}
3482 %<*marktrace>
3483     \mult@info\tw@
3484       {Returned #1 mark:\MessageBreak
3485        \meaning#2}%
3486 %      \nobreak
3487 %    \fi
3488 %</marktrace>
3489 %    \end{macrocode}
3490 %    Since the contents of the mark may be arbitrary \LaTeX{} code we
3491 %    better make sure that it doesn't get expanded any further. (Some
3492 %    expansion have been done already during the execution of
3493 %    |\markright| or |\markboth|.) We therefore use the usual mechanism
3494 %    of a toks register to prohibit expansion.\footnote{Due to the
3495 %    current definition of \cs{markright} etc.\ it wouldn't
3496 %    help to define the \cs{protect} command to prohibit
3497 %    expansion as any \cs{protect} has already vanished due to
3498 %    earlier expansions.}
3499 % \changes{v1.4n}{1992/09/10}{Make marks robust}
3500 % \changes{v1.5t}{1999/03/22}{re-add \cs{mark} command which was commented out
3501 %       by mistake at some point in 1998 (pr/2978)}
3502 %    \begin{macrocode}
3503     \toks@\expandafter{#2}%
3504     \mark{\the\toks@}%
3505 %    \end{macrocode}
3506 %    We don't want any breakpoint between such a returned mark and the
3507 %    following material (which is usually just the box where the mark
3508 %    came from).
3509 %    \begin{macrocode}
3510     \nobreak
3511   \fi}
3512 %    \end{macrocode}
3513 %  \end{macro}
3516 %  \begin{macro}{\get@keptmarks}
3517 %    If we have some material in a box register we may want to get the
3518 %    first and the last mark out of this box. This can be done with
3519 %    |\get@keptmarks| which takes one argument: the box register number
3520 %    or its nick name defined by |\newbox|.
3521 %    \begin{macrocode}
3522 \def\get@keptmarks#1{%
3523 %    \end{macrocode}
3524 %    For debugging purposes we take a look at the current dimensions
3525 %    of the box since in earlier versions of the code I made some
3526 %    mistakes in this area.
3527 %    \begin{macrocode}
3528 %<*debug>
3529       \typeout{Mark box #1 before:
3530                ht \the\ht#1, dp \the\dp#1}%
3531 %</debug>
3532 %    \end{macrocode}
3533 %    Now we open a new group an locally copy the box to itself. As a
3534 %    result any operation, i.e.\ |\vsplit|, will only have a local
3535 %    effect. Without this trick the box content would get lost up to
3536 %    the level where the last assignment to the box register was done.
3537 %    \begin{macrocode}
3538   \begingroup
3539    \vbadness\@M
3540    \setbox#1\copy#1%
3541 %    \end{macrocode}
3542 %    Now we split the box to the maximal possible dimension. This
3543 %    should split off the full contents of the box so that effectively
3544 %    everything is split off. As a result |\splitfirstmark| and
3545 %    |\splitbotmark| will contain the first and last mark in the box
3546 %    respectively.
3547 %    \begin{macrocode}
3548    \setbox#1\vsplit#1to\maxdimen
3549 %    \end{macrocode}
3550 %    Therefore we can now set the kept marks which is a global
3551 %    operation and afterwards close the group. This will restore the
3552 %    original box contents.
3553 %    \begin{macrocode}
3554    \set@keptmarks
3555  \endgroup
3556 %    \end{macrocode}
3557 %    For debugging we take again a look at the box dimension which
3558 %    shouldn't have changed.
3559 %    \begin{macrocode}
3560 %<*debug>
3561     \typeout{Mark box #1 \space after:
3562              ht \the\ht#1, dp \the\dp#1}%
3563 %</debug>
3565 %    \end{macrocode}
3566 %  \end{macro}
3569 %  \begin{macro}{\set@keptmarks}
3570 %    The macro |\set@keptmarks| is responsible for setting
3571 %    |\kept@firstmark| and |\kept@botmark|, by checking the current
3572 %    values for |\splitfirstmark| and |\splitbotmark|.
3573 %    \begin{macrocode}
3574 \def\set@keptmarks{%
3575 %    \end{macrocode}
3576 %    If |\kept@firstmark| is empty we assume that it isn't set. This
3577 %    is strictly speaking not correct as we loose the ability to have
3578 %    marks that are explicitly empty, but for standard \LaTeX{}
3579 %    application it is sufficient. If it is non-empty we don't change
3580 %    the value---within the output routines it will then be restored
3581 %    to |\@empty|.
3582 %    \begin{macrocode}
3583    \ifx\kept@firstmark\@empty
3584 %    \end{macrocode}
3585 %    We now put the contents of |\splitfirstmark| into
3586 %    |\kept@firstmark|. In the case that there wasn't any mark at all
3587 %    |\kept@firstmark| will not change by that operation.
3588 %    \begin{macrocode}
3589      \expandafter\gdef\expandafter
3590         \kept@firstmark
3591         \expandafter{\splitfirstmark}%
3592 %    \end{macrocode}
3593 %    When debugging we show the assignment but only when something
3594 %    actually happened.
3595 %    \begin{macrocode}
3596 %<*marktrace>
3597      \ifx\kept@firstmark\@empty\else
3598        \mult@info\tw@
3599          {Set kept first mark:\MessageBreak
3600           \meaning\kept@firstmark%
3601           \@gobbletwo}%
3602      \fi
3603 %</marktrace>
3604    \fi
3605 %    \end{macrocode}
3606 %    We always try to set the bottom mark to the |\splitbotmark| but
3607 %    of course only when there has been a |\splitbotmark| at all.
3608 %    Again, we assume that an empty |\splitbotmark| means that the
3609 %    split off box part didn't contain any marks at all.
3610 %    \begin{macrocode}
3611    \expandafter\def\expandafter\@tempa
3612       \expandafter{\splitbotmark}%
3613    \ifx\@tempa\@empty\else
3614       \global\let\kept@botmark\@tempa
3615 %<*marktrace>
3616       \mult@info\tw@
3617         {Set kept bot mark:\MessageBreak
3618          \meaning\kept@botmark%
3619          \@gobbletwo}%
3620 %</marktrace>
3621    \fi}%
3622 %    \end{macrocode}
3623 %  \end{macro}
3626 %  \begin{macro}{\prep@keptmarks}
3627 %    The |\prep@keptmarks| function is used to initialize the kept
3628 %    marks from the contents of  |\partial@page|, i.e.\ the box that
3629 %    holds everything from the top of the current page prior to
3630 %    starting the \mc{} environment. However, such a box is only
3631 %    available if we are not producing a boxed \mc{}.
3632 %    \begin{macrocode}
3633 \def\prep@keptmarks{%
3634    \if@boxedmulticols \else
3635      \get@keptmarks\partial@page
3636    \fi}
3637 %    \end{macrocode}
3638 %  \end{macro}
3641 %  \begin{macro}{\remove@discardable@items}
3642 %    There are situations when we may have some space at the end of a
3643 %    column and this macro here will attempt to get rid of it. The
3644 %    typical \LaTeX{} sequence is a series of selfcanceling glues so
3645 %    if we remove them recursively we are usually fine.
3647 %    Special care is needed with handling |\vspace*| as that
3648 %    corresponds to |\penalty10000|, |\vskip <skip>|, followed by
3649 %    |\vskip 0pt|. If we see this sequence going backwards in the the
3650 %    vertical list we assume that this is a ``desired'' space. We
3651 %    therefore stop the recursion and reinsert the spaces.
3653 %    As the multicol code sometimes add an explicit penalty at the end
3654 %    of a column we first attempt to remove it in case it is there.
3655 % \changes{v1.8m}{2015/03/31}{Another rewrite of
3656 %     \cs{remove@discardable@items} hopefully okay now}
3657 %    \begin{macrocode}
3658 \skip0=0pt
3659 \edef\the@zero@skip{\the\skip0}
3660 \def\remove@discardable@items{%
3661      \unpenalty
3662 %    \end{macrocode}
3663 %    Save a previous skip (if there) and then remove it, we can't
3664 %    really tell the difference between no skip an a skip of zero but
3665 %    that's life.
3666 %    \begin{macrocode}
3667      \edef\@tempa{\the\lastskip}%
3668 %\typeout{s1=\@tempa}%
3669      \unskip
3670 %    \end{macrocode}
3671 %    If it was a zero skip (or none) we save the next previous skip
3672 %    (if any).
3673 %    \begin{macrocode}
3674      \ifx\@tempa\the@zero@skip
3675        \edef\@tempb{\the\lastskip}%
3676 %\typeout{s2=\@tempb}%
3677 %    \end{macrocode}
3678 %    If this one again was zero (or more likely not there in the first
3679 %    place) we stop.
3680 %    \begin{macrocode}
3681        \ifx\@tempb\the@zero@skip
3682        \else
3683 %    \end{macrocode}
3684 %    Otherwise we remove this ``real'' skip. Then we look if it was
3685 %    preceeded by a penalty of 10000 (i.e., a |\nobreak|)
3686 %    \begin{macrocode}
3687          \unskip
3688 %\typeout{p=\lastpenalty}%
3689          \ifnum \lastpenalty=\@M
3690 %    \end{macrocode}
3691 %    If so this was a |\vspace*| or something equivalent to
3692 %    it. Therefore we reintroduce the skips and stop. Otherwise we
3693 %    recurse.
3694 %    \begin{macrocode}
3695            \vskip\@tempb\vskip\@tempa\relax
3696          \else 
3697            \remove@discardable@items
3698          \fi
3699        \fi
3700      \else
3701 %    \end{macrocode}
3702 %    If the first skip was a non-zero skip we recurse as well.
3703 %    \begin{macrocode}
3704        \remove@discardable@items
3705      \fi
3707 %    \end{macrocode}
3708 %  \end{macro}
3710 %    \begin{macrocode}
3711 %<*badness>
3712 \newif\iftoo@bad
3713 \def\too@badtrue{\global\let\iftoo@bad\iftrue}
3714 \def\too@badfalse{\global\let\iftoo@bad\iffalse}
3715 %    \end{macrocode}
3716 %    
3717 % \changes{v1.8k}{2015/03/21}{The new switch}
3718 %    \begin{macrocode}
3719 \newif\ifforcedbreak@leftover
3720 %    \end{macrocode}
3722 % \begin{macro}{\c@columnbadness}
3723 % \begin{macro}{\c@finalcolumnbadness}
3724 %    \begin{macrocode}
3725 \newcount\c@columnbadness
3726 \c@columnbadness=10000
3727 \newcount\c@finalcolumnbadness
3728 \c@finalcolumnbadness=9999
3730 \newdimen\last@try
3732 %    \end{macrocode}
3734 % \changes{v1.5z1}{2003/02/17}{Change wrong default for
3735 %    \cs{multicolovershoot} to zero (pr/3465).}
3736 %    \begin{macrocode}
3737 \newdimen\multicolovershoot
3738 \newdimen\multicolundershoot
3739 \multicolovershoot=0pt
3740 \multicolundershoot=2pt
3741 \newbox\mult@nat@firstbox
3742 %</badness>
3743 %    \end{macrocode}
3744 % \end{macro}
3745 % \end{macro}
3747 %  \begin{macro}{\mult@info}
3748 %    A helper for producing info messages
3749 %    \begin{macrocode}
3750 \def\mult@info#1#2{%
3751   \ifnum\c@tracingmulticols>#1%
3752    \GenericWarning
3753        {(multicol)\@spaces\@spaces}%
3754        {Package multicol: #2}%
3755   \fi
3757 %    \end{macrocode}
3758 %  \end{macro}
3760 % \end{multicols}
3763 % \begin{multicols}{2}[\section{Fixing the
3764 %                        \cs{columnwidth}}]
3766 %  \begin{macro}{\@footnotetext}
3767 % \changes{v1.5o}{1997/11/16}{Redefinition added pr/2664.}
3768 % \changes{v1.5r}{1998/08/17}{Use \cs{@footnotetext} but with
3769 %                             local change to \cs{columnwidth}.}
3770 %  \begin{macro}{\mult@footnotetext}
3771 % \changes{v1.5r}{1998/08/17}{Macro removed again.}
3772 %    If we store the current column width in |\columnwidth| we have
3773 %    to redefine the internal |\@footnotetext| macro to use |\textwidth|
3774 %    for the width of the footnotes rather than using the original
3775 %    definition.
3777 %    Starting with version v1.5r this is now done in a way that the original
3778 %    definition is still used, except that locally |\columnwidth| is set to
3779 %    |\textwidth|.
3781 %    This solves two problems: first redefinitions of |\@footnotetext|
3782 %    done by a class will correctly survive and second if multicols is
3783 %    used inside a minipage environment the special definition of
3784 %    |\@footnotetext| in that environment will be picked up and not the
3785 %    one for the main galley (the latter would result in all footnotes
3786 %    getting lost in that case).
3788 %    See the definition of the |\multicols| command further up for the exact
3789 %    code.
3790 %  \end{macro}
3791 %  \end{macro}
3792 % \end{multicols}
3795 % \begin{multicols*}{2}[\section{Further extensions}]
3797 % This section does contain code for extensions added to this package
3798 % over time. Not all of them may be active, some might sit dormant and
3799 % wait for being activated in some later release.
3801 % \subsection{Not balancing the columns}
3803 %  This is fairly trivial to implement. we just have to disable the
3804 %  balancing output routine and replace it by the one that ships out
3805 %  the other pages.
3807 %  \begin{macro}{\multicols*}
3808 % \changes{v1.5q}{1998/01/19}{Macro added}
3809 %  The code for this environment was suggested by Matthias Clasen.
3810 %    \begin{macrocode}
3811 %<*nobalance>
3812  \@namedef{multicols*}{%
3813 %    \end{macrocode}
3814 %    If we are not on the main galley, i.e., inside a box of some
3815 %    sort, that approach will not work since we don't have a vertical
3816 %    size for the box so we better warn that we balance anyway.
3817 %    \begin{macrocode}
3818    \ifinner
3819      \PackageWarning{multicol}%
3820        {multicols* inside a box does
3821         not make sense.\MessageBreak
3822         Going to balance anyway}%
3823    \else
3824      \let\balance@columns@out
3825          \multi@column@out
3826    \fi
3827    \begin{multicols}
3829 %    \end{macrocode}
3830 %  \end{macro}
3832 %  \begin{macro}{\endmulticols*}
3833 %    When ending the environment we simply end the inner
3834 %    \texttt{multicols} environment, except that we better also stick
3835 %    in some stretchable vertical glue so that the last column still
3836 %    containing text is not vertically stretched out. 
3838 %    We do this as follows: first we ensure that we are back in vertical mode
3839 %    and then we cancel out |\lastskip| if it was
3840 %    positive (in case of a negative glue we assume that it was
3841 %    deliberate, for a deliberate positive glue one needs to use
3842 %    |\vspace*|). We can't simply use |\remove@discardable@items| here
3843 %    as this only works inside boxes but we are here on the main
3844 %    vertical list.
3846 %    Then we back up by |\prevdepth| but not more than |\boxmaxdepth|
3847 %    so that a baseline of the last box is now at the bottom. This way
3848 %    the material will align properly in case something like |\vfill|
3849 %    spreads it out after all.
3850 %    Finally we append |\vfil| to put white space at the bottom of the
3851 %    column, but we only do this if we aren't anyway doing |\raggedcolumns|.
3852 % \changes{v1.5q}{1998/01/19}{Macro added}
3853 % \changes{v1.8h}{2014/09/12}{Use \cs{vfilmaxdepth}}
3854 % \changes{v1.8i}{2014/10/28}{Add \cs{null} to hide the final fill and only add
3855 %                             vertical space if not doing \cs{raggedcolumns}}
3856 % \changes{v1.8j}{2015/03/07}{Redesign the whole approach.}
3857 % \changes{v1.8k}{2015/03/21}{And a bit more redesign because of the
3858 %    change in \cs{remove@discardable@items}}
3859 % \changes{v1.8o}{2016/02/08}{Ensure we are back in vmode before using
3860 %    \cs{prevdepth} (pr/4448)}
3861 %    \begin{macrocode}
3862 \@namedef{endmulticols*}{%
3863    \par
3864    \ifdim\lastskip>\z@ \vskip-\lastskip \fi
3865    \ifdim \prevdepth>\z@
3866      \vskip-\ifdim\prevdepth>\boxmaxdepth 
3867                   \boxmaxdepth
3868             \else \prevdepth \fi
3869    \fi
3870    \ifshr@nking\else
3871      \vfil
3872    \fi
3873    \end{multicols}}
3874 %</nobalance>
3875 %    \end{macrocode}
3876 %  \end{macro}
3879 % \subsection{Manual column breaking} \label{sec:colbreak}
3881 % The problem with manual page breaks within \mc{} is the fact that
3882 % during collection of material for all columns a page-forcing penalty
3883 % (i.e. -10000 or higher) would stop the collecting pass which is not
3884 % quite what is desired. On the other hand, using a penalty like -9999
3885 % would mean that there would be occasions where the |\vsplit|ing
3886 % operations within \mc{} would ignore that penalty and still choose a
3887 % different break point.
3889 % For this reason the current implementation
3890 % uses a completely different approach. In a nutshell it extends the \LaTeX{}
3891 % output routine handling by introducing an additional penalty flag
3892 % (i.e., a penalty which is forcing but higher than -10000 so that the
3893 % output routine can look at this value and thus knows why it has been
3894 % called).
3896 % Inside the output routine we test for this value and if it appears
3897 % we do two things: save the galley up to this point in a special box
3898 % for later use and reduce the |\vsize| by the height of the material
3899 % seen. This way the forcing penalty is now hidden in that box and we
3900 % can restart the collection process for the remaining
3901 % columns. (This is done in |\speci@ls| above.)
3903 % In the output routines that do the |\vsplit|ting either for
3904 % balancing or for a full page we simply combine box~255 with the
3905 % saved box thus getting a single box for  splitting which now
3906 % contains forcing breaks in the right positions.
3909 %  \begin{macro}{\columnbreak}
3910 % \changes{v1.5u}{1999/05/25}{Macro added}
3911 %    |\columnbreak| is modelled after |\pagebreak| except that we
3912 %    generate a penalty -10005.
3913 %    \begin{macrocode}
3914 \mathchardef\@Mv=10005
3915 \def\columnbreak{%
3916 %    \end{macrocode}
3917 %    We have to ensure that it is only used within a \mc{}
3918 %    environment since if that penalty would be seen by the unmodified
3919 %    \LaTeX{} output routine strange things would happen.
3920 %    \begin{macrocode}
3921  \ifnum\col@number<\tw@
3922   \PackageError{multicol}%
3923    {\noexpand\columnbreak outside multicols}%
3924    {This command can only be used within
3925     a multicols or multicols* environment.}%
3926  \else
3927   \ifvmode
3928     \penalty -\@Mv\relax
3929   \else
3930     \@bsphack
3931     \vadjust{\penalty -\@Mv\relax}%
3932     \@esphack
3933   \fi
3934  \fi}
3935 %    \end{macrocode}
3936 %  \end{macro}
3939 %  \begin{macro}{\colbreak@box}
3940 % \changes{v1.5u}{1999/05/25}{Macro added}
3941 %    Need a box to collect the galley up to the column break.
3942 %    \begin{macrocode}
3943 \newbox\colbreak@box
3944 %</package>
3945 %    \end{macrocode}
3946 %  \end{macro}
3949 % \subsection{Supporting right-to-left languages} \label{sec:RL}
3952 % \changes{v1.7a}{2010/10/24}{RL language support added}
3953 % \changes{v1.7b}{2011/12/18}{RL language support fixed}
3955 %  \begin{macro}{\LR@column@boxes}
3956 %    |\LR@column@boxes| is called when we are assembling the columns for left
3957 %    to right typesetting. When we start we are inside an |\hbox| of
3958 %    full width.
3959 %    Left to right typesetting is fairly easy, we basically output
3960 %    each column box intermixed with vertical rules and proper
3961 %    spacing. As this happens inside a box of a defined width the
3962 %    rules and the columns automatically get into the right positions.
3963 %    \begin{macrocode}
3964 \def\LR@column@boxes{%
3965 %    \end{macrocode}
3966 %    We loop through the columns with |\process@cols|
3967 %    \begin{macrocode}
3968      \process@cols\mult@gfirstbox{%
3969 %    \end{macrocode}
3970 %    If the depth of the current box is larger than the maximum found
3971 %    so far in |\dimen2| we update that register for later use.
3972 % \changes{v1.6a}{2003/03/15}{Preparing for adjusting \cs{prevdepth}}
3973 %    \begin{macrocode}
3974        \ifdim\dp\count@>\dimen\tw@
3975          \global\dimen\tw@\dp\count@ \fi
3976 %    \end{macrocode}
3977 %    If the \texttt{colaction} option is given we write out status
3978 %    information about the current column, otherwise the next command
3979 %    does nothing.
3980 % \changes{v1.8e}{2014/04/23}{Support \cs{docolaction}}
3981 %    \begin{macrocode}
3982        \mc@col@status@write
3983 %    \end{macrocode}
3984 %    The typeset box followed by the column rule material
3985 %    \begin{macrocode}
3986        \box\count@
3987        \hss{\columnseprulecolor\vrule
3988               \@width\columnseprule}\hss}%
3989 %    \end{macrocode}
3990 %    As you will have noticed, we started with box register
3991 %    |\mult@gfirstbox|  (i.e.\
3992 %    the left column). So this time |\count@| looped through 2,
3993 %    4,\ldots\ (plus the appropriate offset).
3994 %    Finally we add box |\mult@rightbox| and we are done.
3995 % \changes{v1.5a}{1992/11/04}{New box mechanism}
3996 % \changes{v1.6a}{2003/03/15}{Preparing for adjusting \cs{prevdepth}}
3997 %    Again we may have to update |\dimen\tw@|.
3998 %    \begin{macrocode}
3999      \ifdim\dp\mult@rightbox>\dimen\tw@
4000        \global\dimen\tw@\dp\mult@rightbox \fi
4001 %    \end{macrocode}
4002 %    If the \texttt{colaction} option is given we write out status
4003 %    information about the last column, otherwise the next command
4004 %    does nothing.
4005 % \changes{v1.8e}{2014/04/23}{Support \cs{docolaction}}
4006 %    \begin{macrocode}
4007      \mc@lastcol@status@write
4008      \box\mult@rightbox
4010 %    \end{macrocode}
4011 %  \end{macro}
4013 %  \begin{macro}{\RL@column@boxes}
4014 %    Assembling the boxes for right to left typesetting is far more
4015 %    complicated. When I first tried to build a solution for this my
4016 %    thinking was that all that is necessary to do is to reverse the
4017 %    order of the columns. But such an approach produces a subtle bug:
4018 %    If we work this way then the first column put on the page will be
4019 %    the last column of the text to read. and this means that the
4020 %    order in which \TeX{} executes write statements or assembles mark
4021 %    material will not happen in the order of the textual flow. So if,
4022 %    for example each column contains a section command then these
4023 %    sections will appear in reverse order in the table of content.
4025 %    For this reason some amount of gymnastics is needed to add the
4026 %    columns in their natural flow.
4027 %    \begin{macrocode}
4028 \def\RL@column@boxes{%
4029 %    \end{macrocode}
4030 %    First step is to put all rules in the right place (without adding
4031 %    the comes which are instead represented by a space of |\hsize|.
4032 %    \begin{macrocode}
4033      \process@cols\mult@gfirstbox{%
4034        \hskip\hsize
4035        \hss{\columnseprulecolor\vrule
4036               \@width\columnseprule}\hss
4037      }%
4038      \hskip\hsize
4039 %    \end{macrocode}
4040 %    At this point in the code our typesetting reference point is at
4041 %    the right end of the rightmost column (or rather where that column
4042 %    should appear).
4044 %    We are now typesetting all columns by first backing up by their
4045 %    width (which is |\hsize|) then typesetting the box and then
4046 %    backing up again, but this time further, i.e., also across the
4047 %    column separation. That will then enable us to typeset the next
4048 %    column using the same approach until we are done with all but the
4049 %    final column.
4050 %    \begin{macrocode}
4051      \process@cols\mult@gfirstbox{%
4052        \ifdim\dp\count@>\dimen\tw@
4053          \global\dimen\tw@\dp\count@ \fi
4054        \hskip-\hsize
4055 %    \end{macrocode}
4057 % \changes{v1.8e}{2014/04/23}{Support \cs{docolaction}}
4058 %    \begin{macrocode}
4059        \mc@col@status@write
4060        \box\count@
4061        \hskip-\hsize
4062        \hskip-\columnsep
4063      }%
4064 %    \end{macrocode}
4065 %    The approach for the final column is similar only that we do not
4066 %    have to back up over any column gap.
4067 %    \begin{macrocode}
4068      \ifdim\dp\mult@rightbox>\dimen\tw@
4069        \global\dimen\tw@\dp\mult@rightbox \fi
4070      \hskip-\hsize
4071 %    \end{macrocode}
4073 % \changes{v1.8e}{2014/04/23}{Support \cs{docolaction}}
4074 %    \begin{macrocode}
4075      \mc@lastcol@status@write
4076      \box\mult@rightbox
4077      \hskip-\hsize
4078 %    \end{macrocode}
4079 %    However we do have to move the reference point to its right
4080 %    place: to make the rules appear at the expected places, we should
4081 %    get the typesetting position to the far right again. As we at the
4082 %    moment at the far left we skip to the far right like this:
4083 %    \begin{macrocode}
4084      \hskip\full@width
4086 %    \end{macrocode}
4087 %  \end{macro}
4089 %  \begin{macro}{\RLmulticolcolumns}
4090 %  \begin{macro}{\LRmulticolcolumns}
4091 %  \begin{macro}{\mc@align@columns}
4092 %    Macros to switch between left-right and right-left typesetting. In LR
4093 %    typesetting the |\LR@column@boxes| is used to combine
4094 %    the columns. When typesetting right to left the |\RL@column@boxes|
4095 %    is used instead.
4096 %    \begin{macrocode}
4097 \newcommand\RLmulticolcolumns
4098     {\let\mc@align@columns
4099          \RL@column@boxes}
4100 \newcommand\LRmulticolcolumns
4101     {\let\mc@align@columns
4102       \LR@column@boxes}
4103 %    \end{macrocode}
4104 %    The default is left-to-right:
4105 %    \begin{macrocode}
4106 \LRmulticolcolumns
4107 %    \end{macrocode}
4108 %  \end{macro}
4109 %  \end{macro}
4110 %  \end{macro}
4113 % \subsection{Supporting \texttt{\textbackslash docolaction}}
4115 % \changes{v1.8e}{2014/04/23}{Support \cs{docolaction}}
4117 %   Whenever we want to do something that depends on the current
4118 %   column we execute \verb=\docolaction=. This command takes one
4119 %   optional and three mandatory arguments. The mandatory ones denote
4120 %   what to do if this is a ``left'', ``middle'', or ``right'' column
4121 %   and the optional one is simply there to say what to do if we don't
4122 %   know (default is to use the ``left'' column action in that case).
4124 %  \begin{macro}{\mc@col@check@num}
4125 %   We use one counter \verb=\mc@col@check@num= to generate us unique
4126 %   label names. Each time we execute \verb=\docolaction= we increment
4127 %   this counter to get a new name.
4128 %    \begin{macrocode}
4129 \newcount\mc@col@check@num
4130 %    \end{macrocode}
4131 %  \end{macro}
4133 %   The generated ``labels'' are named
4134 %\begin{verbatim}
4135 %\mc@col-\the\mc@col@check@num
4136 %\end{verbatim}
4137 %   and they hold as values the
4138 %   numbers 1, 2, or 3 denoting the current column type.
4140 %  \begin{macro}{\docolaction}
4142 %    \begin{macrocode}
4143 \newcommand\docolaction[4][1]{%
4144  \ifx\mc@col@status@write\relax
4145      \PackageError{multicol}%
4146       {Option 'colaction' not selected}%
4147       {\string\docolaction\space
4148        requires the use of the 'colaction'
4149        option on the package}%
4150  \fi
4151  \global\advance\mc@col@check@num\@ne
4152  \edef\mc@col@type{\expandafter\ifx
4153    \csname mc@col-\the\mc@col@check@num
4154    \endcsname\relax
4155                    0\else
4156    \csname mc@col-\the\mc@col@check@num
4157    \endcsname
4158                     \fi}%
4159 %    \end{macrocode}
4160 %    We prefix with 0 so that an unknown label (that returns
4161 %   \verb=\relax=) will result in case 0
4162 %    \begin{macrocode}
4163  \ifcase \mc@col@type\relax
4164 %    \end{macrocode}
4165 %    If column is unknown we use the default action or the action
4166 %   denoted by the optional argument (so that arg can take the value
4167 %   1, 2, 3).
4168 %    \begin{macrocode}
4169      \ifcase #1\or #2\or#3\or#4\fi
4170   \or
4171 %    \end{macrocode}
4172 %    Otherwise we know (or think we know) that this is a first, middle,
4173 %   or last column:
4174 %    \begin{macrocode}
4175      #2%  % 1 First col
4176   \or
4177      #3%  % 2 any middle col
4178   \or
4179      #4%  % 3 last col
4180   \else
4181     \ERROR
4182   \fi
4183 %    \end{macrocode}
4184 %    But how does the column number get associated with our label? We
4185 %   do do this by writing another line into the aux file at this point:
4186 %    \begin{macrocode}
4187   \edef\next{\write\@auxout
4188      {\string\mc@set@col@status
4189       {mc@col-\the\mc@col@check@num}%
4190       {\mc@col@type}}}%
4191   \next
4193 %    \end{macrocode}
4194 %  \end{macro}
4196 %   Because of extra data writing to the aux file the aux file will
4197 %   now contain something like the following after the document is
4198 %   processed the first time:
4199 %\begin{verbatim}
4200 %\relax
4201 %\mc@col@status{1}
4202 %\mc@set@col@status{lcol-1}{0}
4203 %\mc@col@status{2}
4204 %\mc@set@col@status{lcol-2}{0}
4205 %\mc@col@status{3}
4206 %\mc@set@col@status{lcol-3}{0}
4207 %\mc@col@status{1}
4208 %\mc@col@status{2}
4209 %\mc@col@status{3}
4210 %\mc@set@col@status{lcol-4}{0}
4211 %\end{verbatim}
4212 %   The \verb=\mc@col@status= line denotes the column type and has been
4213 %   written out just before corresponding the column box was placed
4214 %   onto the page.
4215 %   The\verb=\mc@set@col@status= lines have been written out as part
4216 %   of shipping the column boxes out, e.g.,
4217 %   \verb=\mc@set@col@status{lcol-1}{0}= was therefore somewhere within
4218 %   the first column as it appears between \verb=\mc@col@status{1}=
4219 %   and  \verb=\mc@col@status{2}=
4220 %   The second argument in that line is the value used in the previous
4221 %   run (or zero if there was no previous run. We can use this to
4222 %   determine if a rerun is necessary.
4224 %   Thus with this knowledge we can set things up to get the labels
4225 %   working.
4228 %  \begin{macro}{\mc@col@status}
4230 %   When the aux file is read in \verb=\mc@col@status= is used to set
4231 %   \verb=\mc@curr@col@status=:
4232 %    \begin{macrocode}
4233 \def\mc@col@status#1{%
4234     \gdef\mc@curr@col@status{#1}}
4235 %    \end{macrocode}
4236 %  \end{macro}
4240 %  \begin{macro}{\mc@set@col@status}
4242 %   And when \verb=\mc@set@col@status= is executed we can simply set
4243 %   up the label by associating it with the \verb=\mc@curr@col@status=
4244 %   and ignore the second argument:
4245 %    \begin{macrocode}
4246 \def\mc@set@col@status#1#2{%
4247   \global\expandafter\let\csname #1\endcsname
4248                          \mc@curr@col@status}
4249 %    \end{macrocode}
4250 %   The above definition is being used when the \texttt{.aux} file is
4251 %   read in at the beginning. At the end we need a different
4252 %   definition to test if another typesetting run is needed. There we
4253 %   compare the value used in the current run (stored in the second
4254 %   argument) with the value used on the next run. If those two values
4255 %   differ we set \verb=@tempswa= to false which will trigger the
4256 %   ``Label(s) may have changed'' warning.
4257 %    \begin{macrocode}
4258 \AtEndDocument{\def\mc@set@col@status#1#2{%
4259      \ifnum #2=\mc@curr@col@status\else
4260        \@tempswatrue
4261      \fi}%
4263 %    \end{macrocode}
4264 %  \end{macro}
4267 %  \begin{macro}{mc@firstcol}
4268 %   Finally, as part of determining in which column we are, we used a
4269 %   switch inside |\mc@col@status@write| to determine if we are in the
4270 %   first column or not.
4271 %  \begin{macrocode}
4272 \newif\ifmc@firstcol
4273 \mc@firstcoltrue
4274 %    \end{macrocode}
4275 %  \end{macro}
4276 % \end{multicols*}
4278 % \Finale
4280 \endinput