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'.
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
87 \ProvidesFile{multicol.dtx}
89 %<package>\NeedsTeXFormat{LaTeX2e}[1997/12/01]
90 %<package>\ProvidesPackage{multicol}
91 %<driver> \ProvidesFile{multicol.drv}
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
108 % \changes{v1.0f}{1989/07/11}{Changed \cs{z@} to 0pt in redefinition of
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}
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}
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.
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
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
202 % \docolaction{first}
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.
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|.
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:
240 %\renewcommand \footnoterule{%
241 % \kern-3pt\hbox to\textwidth
242 % {\hskip .6\textwidth
250 % \begin{multicols}{3}[\section*{Preface to version 1.5 + 1.6}]
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
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.
267 % \setcounter{collectmore}{2}
268 % \begin{multicols}{3}[\section{Introduction}]
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
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.
297 % \setcounter{collectmore}{0}
298 % \begin{multicols}{3}[\section{The User Interface}]
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
339 % \begin{multicols}{3}
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
350 % \begin{multicols}{3}
352 % This index contains ...]
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.}
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.
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
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}.
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
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
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
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
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
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
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
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
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
597 % \item[] {\hspace*{-\labelsep}\tt LaTeX Warning: I moved some lines
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.
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
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.
663 % \begin{multicols}{3}[\section{Prefaces to older versions}
664 % \subsection{Preface to version 1.4}]
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
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!
698 % \begin{multicols}{2}
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
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.
726 % \caption{Interface description for \cs{balance@columns}}
727 % \label{tab:balance}
731 % \begin{multicols}{3}[\subsection{Preface to version 1.2}]
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
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.
775 % \setlength{\multicolsep}{0pt}
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
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.
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}
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.
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
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{**********************************}
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}
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
843 % Since this is the first code in this file one can produce the
845 % simply by running \LaTeX{} on the \texttt{.dtx} file.
848 \documentclass{ltxdoc}
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.
855 \usepackage{multicol}[1999/05/25]
858 % First we set up the page layout suitable for
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}
871 % We want a rule between columns.
873 \setlength\columnseprule{.4pt}
875 % We also want to ensure that a new \mc{} environment finds enough
876 % space at the bottom of the page.
878 \setlength\premulticols{6\baselineskip}
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.
884 \setcounter{columnbadness}{7000}
885 \setcounter{finalcolumnbadness}{7000}
887 % The index is supposed to come out in four columns.
888 % And we don't show macro names in the margin.
890 \setcounter{IndexColumns}{4}
891 \let\DescribeMacro\SpecialUsageIndex
892 \let\DescribeEnv\SpecialEnvIndex
893 \renewcommand\PrintMacroName[1]{}
895 %\DisableCrossrefs % Partial index
896 \RecordChanges % Change log
898 % Line numbers are very small for this article.
900 \renewcommand{\theCodelineNo}
901 {\scriptsize\rm\arabic{CodelineNo}}
902 \settowidth\MacroIndent{\scriptsize\rm 00\ }
906 {****************************************
907 ^^J* Expect some Under- and overfull boxes.
908 ^^J****************************************}
909 \DocInput{multicol.dtx}
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.)
926 % \NeedsTeXFormat{LaTeX2e}
927 % \ProvidesPackage{multicol}[..../../..
928 % v... multicolumn formatting]
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.
938 \DeclareOption{twocolumn}
939 {\PackageWarning{multicol}{May not work
940 with the twocolumn option}}
942 % Tracing is done using a counter. However
943 % it is also possible to invoke the tracing
944 % using the options declared below.
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}
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}
963 \let\mc@gridwarn\maxdimen
964 \DeclareOption{grid}{\def\mc@gridwarn{\maxdepth}}
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.
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}}%
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
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|
1001 \def\multicols#1{\col@number#1\relax
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}
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}%
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}
1022 \ifnum\col@number>10
1023 \PackageError{multicol}%
1025 {Current implementation doesn't
1026 support more than 10 columns.%
1028 I therefore use 10 columns instead}%
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)}.
1053 \ifx\@footnotetext\mult@footnotetext\else
1054 \let\orig@footnotetext\@footnotetext
1055 \let\@footnotetext\mult@footnotetext
1058 % Now we can safely look for the optional arguments.
1060 \@ifnextchar[\mult@cols{\mult@cols[]}}
1066 % \begin{macro}{\mult@footnotetext}
1069 \long\def\mult@footnotetext#1{\begingroup
1070 \columnwidth\textwidth
1071 \orig@footnotetext{#1}\endgroup}
1075 % \begin{macro}{\mult@cols}
1076 % The |\mult@cols| macro grabs the first optional argument
1077 % (if any) and looks for the second one.
1079 \def\mult@cols[#1]{\@ifnextchar[%
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
1087 {\mult@@cols{#1}[\premulticols]}}
1092 % \begin{macro}{\mult@@cols}
1093 % After removing all arguments from the input we are able
1094 % to start with |\mult@@cols|.
1096 \def\mult@@cols#1[#2]{%
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}
1109 \ifinner \@boxedmulticolstrue
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
1118 \ifnum \doublecol@number>\z@
1119 \@boxedmulticolstrue
1123 % Then we look to see if statistics are requested:
1126 {Starting environment with
1127 \the\col@number\space columns%
1129 % In boxed mode we add some more info.
1130 % \changes{v1.4f}{1992/04/28}{\cs{on@line} added to tracing info}
1132 \if@boxedmulticols\MessageBreak
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}
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
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}
1157 #1\par\addvspace\multicolsep
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
1171 \ifdim \prevdepth = -\@m\p@
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}
1183 \@tempcnta\prevdepth
1184 \@tempcntb\baselineskip
1185 \divide\@tempcnta\@tempcntb
1186 \advance\@tempcnta\@ne
1188 \advance\dimen@ -\@tempcnta\baselineskip
1189 \advance\dimen@ \topskip
1193 % We start a new grouping level to hide all subsequent changes
1194 % (done in |\prepare@multicols| for example).
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
1205 \setbox\mult@box\vbox\bgroup
1208 % \changes{v1.8c}{2013/11/03}{Add \cs{color@setgroup} to prevent color leak}
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}}
1221 % We finish by suppressing initial spaces.
1227 % \begin{macro}{\if@boxedmulticols}
1228 % Here is the switch and the box for ``boxed'' multicols code.
1230 \newif\if@boxedmulticols
1231 \@boxedmulticolsfalse
1236 % \begin{macro}{\enough@room}
1237 % \changes{v1.0c}{1989/05/12}{Penalty 0 added to empty the contribution
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
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}}
1260 \def\enough@room#1{%
1262 % Measuring makes only sense when we are not in ``boxed mode'' so
1263 % the routine does nothing if the switch is true.
1265 \if@boxedmulticols\else
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
1279 \bgroup\@nobreakfalse\addpenalty\z@\egroup
1280 \page@free \pagegoal
1281 \advance \page@free -\pagetotal
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
1292 % Now we test whether tracing information is required:
1295 {Current page:\MessageBreak
1297 \the\pagegoal: used \the\pagetotal
1298 \space -> free=\the\page@free
1300 needed \the\@tempskipa
1303 % Our last action is to force a page break if there isn't enough
1306 \ifdim \page@free <#1\newpage \fi
1311 % \begin{macro}{\prepare@multicols}
1312 % When preparing for multicolumn output several things must
1315 \def\prepare@multicols{%
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}}
1326 \multicol@leftmargin\@totalleftmargin
1327 \@totalleftmargin\z@
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
1334 % \changes{v1.5a}{1992/11/04}{Add offset to \cs{doublecolnumber}}
1336 \doublecol@number\col@number
1337 \multiply\doublecol@number\tw@
1338 \advance\doublecol@number\mult@rightbox
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
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
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.}
1364 \nointerlineskip {\topskip\z@\null}%
1366 \global\setbox\partial@page\vbox
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.}
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
1405 \global\setbox\last@line\lastbox
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}
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.}
1429 \global\let\kept@topmark\firstmark
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
1439 \advance\@colroom-\ht\partial@page
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}}
1451 \set@mult@vsize\relax
1453 % Now we switch to a new |\output| routine which will be used
1454 % to put the gathered column material together.
1456 \output{\multi@column@out}%
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
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}}
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.
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
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.}
1495 \vbadness\@Mi \hbadness5000
1496 \tolerance\multicoltolerance
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
1503 % \changes{v1.2a}{1990/02/05}{\cs{pretolerance} -1 because it nearly never
1505 % \changes{v1.4e}{1992/03/20}{Using}
1507 \pretolerance\multicolpretolerance
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.}
1517 \setemergencystretch\col@number\hsize
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.}
1528 % Additionally, we advance |\baselineskip| by
1529 % |\multicolbaselineskip| to allow corrections for narrow
1532 \advance\baselineskip\multicolbaselineskip
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:
1539 % { |\linewidth| - (|\col@number|-1)
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:
1551 \hsize\linewidth \advance\hsize\columnsep
1552 \advance\hsize-\col@number\columnsep
1553 \divide\hsize\col@number
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
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
1586 \full@width\linewidth
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.
1598 \def\init@mult@footins{%
1599 \multiply\count\footins\col@number
1600 \multiply\skip \footins\col@number
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
1610 % |\vsize| = |\col@number| \times |\@colroom|
1612 % in order to collect enough material before entering the
1613 % |\output| routine again. In fact we have to add another
1615 % (|\col@number|-1) \times (|\baselineskip|-|\topskip|)
1617 % if you think about it.
1618 % \changes{v1.4p}{1992/11/26}{Macro added.}
1620 \def\set@mult@vsize#1{%
1622 \@tempdima\baselineskip
1623 \advance\@tempdima-\topskip
1624 \advance\vsize\@tempdima
1625 \vsize\col@number\vsize
1626 \advance\vsize-\@tempdima
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}
1636 \advance\vsize\col@number\baselineskip
1638 \c@collectmore\baselineskip}
1643 % \begin{macro}{\multicol@leftmargin}
1644 % Here is the dimen register we need for saving away the outer
1645 % value of |\@totalleftmargin|.
1647 \newdimen\multicol@leftmargin
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.
1657 \def\endmulticols{\par
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
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}}
1669 \remove@discardable@items\color@endgroup\egroup
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}}
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|.
1682 \return@nonemptymark{first}%
1684 \return@nonemptymark{bot}%
1690 \global\let\kept@firstmark
1692 \global\let\kept@botmark
1696 {Restore kept marks to\MessageBreak
1697 first: \meaning\kept@firstmark
1698 \MessageBreak bot\space\space:
1699 \meaning\kept@botmark }%
1702 % This finishes the code for the ``boxed'' case.
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
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
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.
1749 % Now it's safe to change the output routine in order to balance
1752 \output{\balance@columns@out}%
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}
1763 \ifvbox\partial@page
1764 \unvbox\partial@page\fi
1766 % After the output routine has acted we restore
1767 % the kept marks to their initial value.
1769 \global\let\kept@firstmark\@empty
1770 \global\let\kept@botmark\@empty
1773 {Make kept marks empty}%
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.}
1792 \@checkend{multicols}%
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
1801 \global\c@unbalance\z@
1803 % Now it's time to return any footnotes if we are in unrestricted
1806 \if@boxedmulticols\else
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
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}
1823 \ifdim \pagegoal=\maxdimen
1824 \global\vsize\@colroom
1826 \enough@room\postmulticols
1829 \addvspace\multicolsep
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}
1844 % If statistics are required we finally report that we have
1845 % finished everything.
1850 \space(boxed mode)\fi
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
1872 \newcount\c@unbalance
1873 \newcount\c@collectmore
1875 % In the new \LaTeX{} release |\col@number| is already allocated by
1876 % the kernel, so we don't allocate it again.
1878 %\newcount\col@number
1879 \newcount\doublecol@number
1880 \newcount\multicoltolerance
1881 \newcount\multicolpretolerance
1882 \newdimen\full@width
1884 \newdimen\premulticols
1885 \newdimen\postmulticols
1886 \newskip\multicolsep
1887 \newskip\multicolbaselineskip
1888 \newbox\partial@page
1891 % And here are their default values:
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)}
1905 \multicoltolerance = 9999
1906 \multicolpretolerance = -1
1907 \premulticols = 50pt
1908 \postmulticols= 20pt
1909 \multicolsep = 12pt plus 4pt minus 3pt
1910 \multicolbaselineskip=0pt
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.
1935 \def\process@cols#1#2{\count@#1\relax
1938 \typeout{Looking at box \the\count@}
1942 \ifnum\count@<\doublecol@number
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|.
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}
1971 \process@cols\mult@rightbox
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.}
1980 \setbox\count@\hbox to\hsize{}%
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}
1990 \count@\col@number \advance\count@\m@ne
1992 {Column spec: \the\full@width\space = indent
1993 + columns + sep =\MessageBreak
1994 \the\multicol@leftmargin\space
1995 + \the\col@number\space
2001 % At this point we should always be in vertical mode.
2003 \ifvmode\else\errmessage{Multicol Error}\fi
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
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
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}
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
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}}
2040 \setbox\z@\hbox{p}\global\dimen\tw@\dp\z@
2041 \moveright\multicol@leftmargin
2042 \hbox to\full@width{%
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}
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).
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
2070 % \changes{v1.8g}{2014/08/24}{Resetting \cs{prevdepth} in the right place}
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}}
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}
2090 \ifdim\dimen\tw@ > \mc@gridwarn
2091 \PackageWarning{multicol}%
2092 {Very deep columns!\MessageBreak
2093 Grid alignment might be broken}%
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|.
2103 \def\columnseprulecolor{\normalcolor}
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.}
2121 \def\reinsert@footnotes{\ifvoid\footins\else
2122 \insert\footins{}\fi}
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}
2140 \def\vfilmaxdepth{\vskip \z@ \@plus .0001fil
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
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}}
2158 \def\multi@column@out{%
2159 \ifnum\outputpenalty <-\@M
2161 % If this was a |\clearpage|, a float or a marginpar we call
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}.
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
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|.
2186 \splittopskip\topskip
2187 \splitmaxdepth\maxdepth
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}}
2193 \boxmaxdepth\maxdepth
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
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}}
2209 \divide\skip\footins\col@number
2210 \ifvoid\footins \else
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}}
2224 \let\ifshr@kingsaved\ifshr@king
2226 \advance \dimen@ -\ht\@kludgeins
2228 % The star form of |\enlargethispage| makes the width of the box
2229 % greater than zero (sneaky isn't it?).
2231 \ifdim \wd\@kludgeins>\z@
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}
2241 \process@cols\mult@gfirstbox{%
2243 \vsplit\@cclv to\dimen@
2245 % After splitting we update the kept marks.
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}
2268 \ifshr@nking\vfilmaxdepth\fi}%
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}
2278 \setbox\mult@rightbox
2279 \vsplit\@cclv to\dimen@
2281 \setbox\mult@rightbox\vbox to\dimen@
2282 {\unvbox\mult@rightbox
2283 \ifshr@nking\vfilmaxdepth\fi}%
2285 % Now that we are done with the boxes, we restored the current
2286 % setting for shrinking in case it got changed:
2288 \let\ifshr@king\ifshr@kingsaved
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
2297 \ifnum\outputpenalty=\@M
2299 \penalty\outputpenalty
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.}
2310 \ifvoid\footins\else
2311 \PackageWarning{multicol}%
2312 {I moved some lines to
2313 the next page.\MessageBreak
2315 \thepage\space might be wrong}%
2318 % If the `{\sf tracingmulticols}' counter is 4 or higher we also
2321 \ifnum \c@tracingmulticols>\thr@@
2322 \hrule\allowbreak \fi
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}}
2335 \ifx\@empty\kept@firstmark
2336 \let\firstmark\kept@topmark
2337 \let\botmark\kept@topmark
2339 \let\firstmark\kept@firstmark
2340 \let\botmark\kept@botmark
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}}
2347 \let\topmark\kept@topmark
2350 {Use kept top mark:\MessageBreak
2351 \meaning\kept@topmark
2353 Use kept first mark:\MessageBreak
2354 \meaning\kept@firstmark
2356 Use kept bot mark:\MessageBreak
2357 \meaning\kept@botmark
2359 Produce first mark:\MessageBreak
2362 Produce bot mark:\MessageBreak
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
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}}
2386 \boxmaxdepth\maxdimen
2387 \setbox\@cclv\vbox{\unvbox\partial@page
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.
2395 \@makecol\@outputpage
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}}
2405 \global\let\kept@topmark\botmark
2406 \global\let\kept@firstmark\@empty
2407 \global\let\kept@botmark\@empty
2410 {(Re)Init top mark:\MessageBreak
2411 \meaning\kept@topmark
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}
2423 \global\@colroom\@colht
2424 \global \@mparbottom \z@
2425 \global \@textfloatsheight \z@
2427 % Then we process deferred floats waiting for their chance to be
2428 % placed on the next page.
2431 \@whilesw\if@fcolmade\fi{\@outputpage
2432 \global\@colroom\@colht
2433 \process@deferreds}%
2435 % If the user is interested in statistics we inform him about the
2436 % amount of space reserved for floats.
2439 {Colroom:\MessageBreak
2441 after float space removed
2442 = \the\@colroom \@gobble}%
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}
2450 \set@mult@vsize \global
2452 % The |\footins| skip register will be adjusted when the output
2454 % \changes{v1.3c}{1991/03/03}{Unnecessary code removed}
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
2468 % \changes{v1.5?}{1994/?/?}{Macro added}
2470 \def\leave@mult@footins{%
2471 \advance\dimen@-\skip\footins
2472 \advance\dimen@-\ht\footins
2479 % \begin{macro}{\speci@ls}
2480 % We left out two macros: |\process@deferreds| and
2482 % \changes{v1.5c}{1993/04/18}{Support \cs{clearpage}}
2485 \ifnum\outputpenalty <-\@Mi
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}
2497 \ifnum \outputpenalty<-\@MM
2498 \PackageError{multicol}{Document end
2499 inside multicols environment}\@ehd
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}.
2508 \ifnum\outputpenalty = -\@Mv
2509 \mult@info\@ne{Forced column
2511 \global\advance\vsize-\pagetotal
2512 \global\setbox\colbreak@box
2514 \ifvoid\colbreak@box
2516 \unvbox\colbreak@box
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
2536 \boxmaxdepth\maxdepth
2537 \setbox\@cclv\vbox{%
2539 \remove@discardable@items}%
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.
2551 \PackageWarningNoLine{multicol}%
2552 {Floats and marginpars not
2553 allowed inside `multicols'
2555 \unvbox\@cclv\reinsert@footnotes
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.}
2564 \xdef\@freelist{\@freelist\@currlist}%
2569 % If the penalty is $-10001$ it will come from a |\clearpage| and
2570 % we will execute |\@doclearpage| to get rid of any deferred
2573 \else \@doclearpage \fi
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|.
2585 \def\process@deferreds{%
2587 \@tryfcolumn\@deferlist
2590 \let\@tempb\@deferlist
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.
2601 % Now we call |\@tempb| which has the form
2603 % |\@elt|\meta{box register}|\@elt|^^A
2604 % \meta{box register}\ldots{}
2606 % So |\@elt| (i.e.\ |\@scolelt|) will distribute the
2607 % boxes to the three lists.
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...|
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|.
2631 \def\raggedcolumns{%
2632 \@bsphack\shr@nkingtrue\@esphack}
2634 \@bsphack\shr@nkingfalse\@esphack}
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.
2647 \def\balance@columns@out{%
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}
2661 \setbox\mult@box\vbox{%
2662 \ifvoid\colbreak@box\else
2663 \unvbox\colbreak@box
2665 \mult@info\@ne{Re-adding
2666 forced break(s) in balancing}%
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.}
2675 \remove@discardable@items
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}
2685 {Balancing failed ...
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.
2695 \vskip-\splittopskip
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|.
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}
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.
2723 \global\vsize\@colroom
2724 \global\advance\vsize\ht\partial@page
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}}
2731 \ifvbox\@kludgeins\insert\@kludgeins
2732 {\unvbox\@kludgeins}\fi
2734 % Then we |\unvbox| the |\partial@page| (which may be void if we
2735 % are not processing the first page of this \mc{} environment.
2737 \unvbox\partial@page
2739 % Then we return the first and bottom mark and the gathered
2740 % material to the main vertical list.
2742 \return@nonemptymark{first}\kept@firstmark
2743 \return@nonemptymark{bot}\kept@botmark
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}
2757 % As we already know, reinserting of footnotes will be done in the
2758 % macro |\endmulticols|.
2762 % \begin{macro}{\balance@columns}
2763 % This macro now does the actual balancing.
2765 \def\balance@columns{%
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}
2773 \get@keptmarks\mult@box
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}
2782 \setbox\mult@box\vbox{%
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}
2794 \splittopskip\@tempdima
2795 \@plus\multicolundershoot
2796 \@minus\multicolovershoot
2797 \splitmaxdepth\maxdepth
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)}
2807 \boxmaxdepth\maxdepth
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
2822 % \changes{v1.5?}{1994/?/?}{Do splitting to zero here}
2824 \setbox\@tempboxa\vsplit\mult@box to\z@
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}
2835 \@tempdima\ht\mult@box
2836 \advance\@tempdima\dp\mult@box
2837 \divide\@tempdima\col@number
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|.
2848 \divide\count@\baselineskip
2849 \dimen@\count@\baselineskip
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|.
2856 \advance\dimen@\topskip
2857 \ifdim \dimen@ >\@tempdima
2858 \advance\dimen@-\baselineskip
2861 % At the user's request we start with a higher value (or lower, but
2862 % this usually only increases the number of tries).
2864 \advance\dimen@\c@unbalance\baselineskip
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}
2870 {Balance columns\on@line:
2871 \ifnum\c@unbalance=\z@\else
2872 (off balance=\number\c@unbalance)\fi
2875 % But we don't allow nonsense values for a start.
2877 \ifnum\dimen@<\topskip
2880 \the\dimen@ \space ->
2881 \the\topskip \space (corrected)}%
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
2893 % \changes{v1.2a}{1990/02/05}{Group around main loop removed.}
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}
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}}
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}
2920 {\process@cols\mult@grightbox
2921 {\global\setbox\count@
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.)
2928 \global\setbox\mult@grightbox
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}}
2941 \forcedbreak@leftoverfalse
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
2949 {\process@cols\mult@firstbox{%
2950 \global\setbox\count@
2951 \vsplit\mult@grightbox to\dimen@
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}
2960 \global\setbox\count@
2964 % After every split we check the badness of the resulting column,
2965 % normally the amount of extra white in the column.
2968 \ifnum\c@tracingmulticols>\@ne
2970 \advance\@tempcnta-\mult@grightbox
2971 \divide\@tempcnta \tw@
2973 \number\@tempcnta\space
2974 badness: \the\badness\space}%
2977 % If this badness is larger than the allowed column badness
2978 % we reject this solution by setting |too@bad| to \texttt{true}.
2980 \ifnum\badness>\c@columnbadness
2981 \ifnum\c@tracingmulticols>\@ne
2983 (>\the\c@columnbadness)}%
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|
2997 % make the result of the testing incorrect. So we change the value
2998 % by unboxing the box into itself.
3000 \global\setbox\mult@grightbox
3001 \vbox{\unvbox\mult@grightbox}%
3003 % We also save a copy |\mult@firstbox| at its ``natural'' size
3006 \setbox\mult@nat@firstbox
3007 \vbox{\unvcopy\mult@firstbox}%
3009 % After |\process@cols| has done its job we have the following
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
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}
3025 \ifnum\c@tracingmulticols>\@ne
3026 \message{^^JFirst column
3028 (\the\ht\mult@nat@firstbox)}\fi
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)}
3039 % \global\setbox\mult@firstbox
3040 % \copy\mult@nat@firstbox
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}}
3050 \ifnum\c@tracingmulticols>\@ne
3051 \message{<> last column =
3052 \the\ht\mult@grightbox^^J}%
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}
3060 \ifnum\c@tracingmulticols>4
3063 \process@cols\mult@grightbox
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
3076 % \changes{v1.3c}{1991/03/03}{\cs{global}\cs{advance} left over from older code}
3078 \ifdim\ht\mult@grightbox >\dimen@
3080 % If the height of the last box is too large we mark this trial as
3082 % \changes{v1.5v}{1999/07/18}{Added tracing statements for
3083 % trial unsuccessful}
3087 \ifnum\c@tracingmulticols>\@ne
3088 \typeout{Rejected: last
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.
3104 \copy\mult@grightbox
3105 \setbox\z@\vsplit\@tempboxa to\maxdimen
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
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.
3117 \global\setbox\mult@grightbox
3119 {\unvbox\mult@grightbox}%
3120 \ifnum\c@tracingmulticols>\@ne
3121 \message{Final badness:
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}
3131 \ifnum\badness>\c@finalcolumnbadness
3132 \global\setbox\mult@grightbox
3134 {\unvbox\mult@grightbox\vfil}%
3135 \ifnum\c@tracingmulticols>\@ne
3136 \message{ setting natural
3137 (> \the\c@finalcolumnbadness)}%
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}
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}
3162 \advance\@tempdima \maxbalancingoverflow
3163 \ifdim \dimen@ < \@tempdima
3165 \ifnum\c@tracingmulticols>\@ne
3166 \typeout{Rejected: unprocessed
3167 forced break(s) in last column!}%
3170 \forcedbreak@leftovertrue
3171 \ifnum\c@tracingmulticols>\@ne
3172 \typeout{Failed: columns too large
3173 with unprocessed forced break(s)!}%
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.
3186 \ifdim\ht\mult@nat@firstbox<\dimen@
3187 \ifdim\ht\mult@nat@firstbox>\last@try
3189 \ifnum\c@tracingmulticols>\@ne
3190 \typeout{Retry: using natural
3191 height of first column!}%
3193 \dimen@\ht\mult@nat@firstbox
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@|.
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
3215 % \changes{v1.8k}{2015/03/21}{}
3217 \ifforcedbreak@leftover
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
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
3240 \if@boxedmulticols\else
3241 \ifdim\dimen@>\@colroom
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}.}
3255 \process@cols\mult@rightbox
3257 \advance\@tempcnta\@ne
3259 % when putting the final column together we want overfull
3263 \setbox\count@\vbox to\dimen@
3267 % \changes{v1.8h}{2014/09/12}{Use \cs{vfilmaxdepth}}
3270 \@plus-\multicolundershoot
3271 \@minus-\multicolovershoot
3273 \ifshr@nking\vfilmaxdepth\fi
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}
3284 \vfuzz\maxdimen % no overfull warning
3285 \setbox\@tempboxa \vbox to\dimen@
3286 {\vskip-\maxbalancingoverflow
3290 {Balanced column more than
3291 \the\maxbalancingoverflow\space
3294 % Fail the balancing attempt:
3299 % Otherwise report that there is a problem but within the accepted
3304 too large, but less than
3305 \the\maxbalancingoverflow}%
3310 % Finally end the |\ifforcedbreak@leftover| conditional.
3311 % \changes{v1.8k}{2015/03/21}{Finish the new conditional}
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
3323 % \changes{v1.8a}{2011/12/20}{\cs{maxbalancingoverflow} parameter added}
3325 \newdimen\maxbalancingoverflow
3326 \maxbalancingoverflow=12pt
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
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
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}
3377 % \changes{v1.4j}{1992/06/25}{Setting of \cs{emergencystretch} on top
3380 \@ifundefined{emergencystretch}
3381 {\newdimen\emergencystretch}{}
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.
3389 \def\setemergencystretch#1#2{%
3390 \emergencystretch 4pt
3391 \multiply\emergencystretch#1}
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.
3408 \def\set@floatcmds{%
3409 \let\@dblfloat\@dbflt
3410 \def\end@dblfloat{\@endfloatbox
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
3420 \ifnum\@floatpenalty<\z@
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.
3428 \@cons\@deferlist\@currbox
3430 \ifnum\@floatpenalty=-\@Mii
3438 % \begin{multicols}{2}[\subsection{Maintaining the mark registers}]
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.
3456 \def\kept@topmark{{}{}}
3457 \let\kept@firstmark\@empty
3458 \let\kept@botmark\@empty
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.
3474 \def\return@nonemptymark#1#2{%
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
3484 {Returned #1 mark:\MessageBreak
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)}
3503 \toks@\expandafter{#2}%
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
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|.
3522 \def\get@keptmarks#1{%
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.
3529 \typeout{Mark box #1 before:
3530 ht \the\ht#1, dp \the\dp#1}%
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.
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
3548 \setbox#1\vsplit#1to\maxdimen
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.
3557 % For debugging we take again a look at the box dimension which
3558 % shouldn't have changed.
3561 \typeout{Mark box #1 \space after:
3562 ht \the\ht#1, dp \the\dp#1}%
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|.
3574 \def\set@keptmarks{%
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
3583 \ifx\kept@firstmark\@empty
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.
3589 \expandafter\gdef\expandafter
3591 \expandafter{\splitfirstmark}%
3593 % When debugging we show the assignment but only when something
3594 % actually happened.
3597 \ifx\kept@firstmark\@empty\else
3599 {Set kept first mark:\MessageBreak
3600 \meaning\kept@firstmark%
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.
3611 \expandafter\def\expandafter\@tempa
3612 \expandafter{\splitbotmark}%
3613 \ifx\@tempa\@empty\else
3614 \global\let\kept@botmark\@tempa
3617 {Set kept bot mark:\MessageBreak
3618 \meaning\kept@botmark%
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{}.
3633 \def\prep@keptmarks{%
3634 \if@boxedmulticols \else
3635 \get@keptmarks\partial@page
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}
3659 \edef\the@zero@skip{\the\skip0}
3660 \def\remove@discardable@items{%
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
3667 \edef\@tempa{\the\lastskip}%
3668 %\typeout{s1=\@tempa}%
3671 % If it was a zero skip (or none) we save the next previous skip
3674 \ifx\@tempa\the@zero@skip
3675 \edef\@tempb{\the\lastskip}%
3676 %\typeout{s2=\@tempb}%
3678 % If this one again was zero (or more likely not there in the first
3681 \ifx\@tempb\the@zero@skip
3684 % Otherwise we remove this ``real'' skip. Then we look if it was
3685 % preceeded by a penalty of 10000 (i.e., a |\nobreak|)
3688 %\typeout{p=\lastpenalty}%
3689 \ifnum \lastpenalty=\@M
3691 % If so this was a |\vspace*| or something equivalent to
3692 % it. Therefore we reintroduce the skips and stop. Otherwise we
3695 \vskip\@tempb\vskip\@tempa\relax
3697 \remove@discardable@items
3702 % If the first skip was a non-zero skip we recurse as well.
3704 \remove@discardable@items
3713 \def\too@badtrue{\global\let\iftoo@bad\iftrue}
3714 \def\too@badfalse{\global\let\iftoo@bad\iffalse}
3717 % \changes{v1.8k}{2015/03/21}{The new switch}
3719 \newif\ifforcedbreak@leftover
3722 % \begin{macro}{\c@columnbadness}
3723 % \begin{macro}{\c@finalcolumnbadness}
3725 \newcount\c@columnbadness
3726 \c@columnbadness=10000
3727 \newcount\c@finalcolumnbadness
3728 \c@finalcolumnbadness=9999
3734 % \changes{v1.5z1}{2003/02/17}{Change wrong default for
3735 % \cs{multicolovershoot} to zero (pr/3465).}
3737 \newdimen\multicolovershoot
3738 \newdimen\multicolundershoot
3739 \multicolovershoot=0pt
3740 \multicolundershoot=2pt
3741 \newbox\mult@nat@firstbox
3747 % \begin{macro}{\mult@info}
3748 % A helper for producing info messages
3750 \def\mult@info#1#2{%
3751 \ifnum\c@tracingmulticols>#1%
3753 {(multicol)\@spaces\@spaces}%
3754 {Package multicol: #2}%
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
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
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
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
3807 % \begin{macro}{\multicols*}
3808 % \changes{v1.5q}{1998/01/19}{Macro added}
3809 % The code for this environment was suggested by Matthias Clasen.
3812 \@namedef{multicols*}{%
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.
3819 \PackageWarning{multicol}%
3820 {multicols* inside a box does
3821 not make sense.\MessageBreak
3822 Going to balance anyway}%
3824 \let\balance@columns@out
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
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)}
3862 \@namedef{endmulticols*}{%
3864 \ifdim\lastskip>\z@ \vskip-\lastskip \fi
3865 \ifdim \prevdepth>\z@
3866 \vskip-\ifdim\prevdepth>\boxmaxdepth
3868 \else \prevdepth \fi
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
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.
3914 \mathchardef\@Mv=10005
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.
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.}%
3928 \penalty -\@Mv\relax
3931 \vadjust{\penalty -\@Mv\relax}%
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.
3943 \newbox\colbreak@box
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
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.
3964 \def\LR@column@boxes{%
3966 % We loop through the columns with |\process@cols|
3968 \process@cols\mult@gfirstbox{%
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}}
3974 \ifdim\dp\count@>\dimen\tw@
3975 \global\dimen\tw@\dp\count@ \fi
3977 % If the \texttt{colaction} option is given we write out status
3978 % information about the current column, otherwise the next command
3980 % \changes{v1.8e}{2014/04/23}{Support \cs{docolaction}}
3982 \mc@col@status@write
3984 % The typeset box followed by the column rule material
3987 \hss{\columnseprulecolor\vrule
3988 \@width\columnseprule}\hss}%
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@|.
3999 \ifdim\dp\mult@rightbox>\dimen\tw@
4000 \global\dimen\tw@\dp\mult@rightbox \fi
4002 % If the \texttt{colaction} option is given we write out status
4003 % information about the last column, otherwise the next command
4005 % \changes{v1.8e}{2014/04/23}{Support \cs{docolaction}}
4007 \mc@lastcol@status@write
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.
4028 \def\RL@column@boxes{%
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|.
4033 \process@cols\mult@gfirstbox{%
4035 \hss{\columnseprulecolor\vrule
4036 \@width\columnseprule}\hss
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
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
4051 \process@cols\mult@gfirstbox{%
4052 \ifdim\dp\count@>\dimen\tw@
4053 \global\dimen\tw@\dp\count@ \fi
4057 % \changes{v1.8e}{2014/04/23}{Support \cs{docolaction}}
4059 \mc@col@status@write
4065 % The approach for the final column is similar only that we do not
4066 % have to back up over any column gap.
4068 \ifdim\dp\mult@rightbox>\dimen\tw@
4069 \global\dimen\tw@\dp\mult@rightbox \fi
4073 % \changes{v1.8e}{2014/04/23}{Support \cs{docolaction}}
4075 \mc@lastcol@status@write
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:
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|
4097 \newcommand\RLmulticolcolumns
4098 {\let\mc@align@columns
4100 \newcommand\LRmulticolcolumns
4101 {\let\mc@align@columns
4104 % The default is left-to-right:
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.
4129 \newcount\mc@col@check@num
4133 % The generated ``labels'' are named
4135 %\mc@col-\the\mc@col@check@num
4137 % and they hold as values the
4138 % numbers 1, 2, or 3 denoting the current column type.
4140 % \begin{macro}{\docolaction}
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}%
4151 \global\advance\mc@col@check@num\@ne
4152 \edef\mc@col@type{\expandafter\ifx
4153 \csname mc@col-\the\mc@col@check@num
4156 \csname mc@col-\the\mc@col@check@num
4160 % We prefix with 0 so that an unknown label (that returns
4161 % \verb=\relax=) will result in case 0
4163 \ifcase \mc@col@type\relax
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
4169 \ifcase #1\or #2\or#3\or#4\fi
4172 % Otherwise we know (or think we know) that this is a first, middle,
4177 #3% % 2 any middle col
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:
4187 \edef\next{\write\@auxout
4188 {\string\mc@set@col@status
4189 {mc@col-\the\mc@col@check@num}%
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:
4202 %\mc@set@col@status{lcol-1}{0}
4204 %\mc@set@col@status{lcol-2}{0}
4206 %\mc@set@col@status{lcol-3}{0}
4210 %\mc@set@col@status{lcol-4}{0}
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
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
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=:
4233 \def\mc@col@status#1{%
4234 \gdef\mc@curr@col@status{#1}}
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:
4246 \def\mc@set@col@status#1#2{%
4247 \global\expandafter\let\csname #1\endcsname
4248 \mc@curr@col@status}
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.
4258 \AtEndDocument{\def\mc@set@col@status#1#2{%
4259 \ifnum #2=\mc@curr@col@status\else
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.
4272 \newif\ifmc@firstcol