summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/tools/multicol.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/tools/multicol.dtx')
-rw-r--r--Master/texmf-dist/source/latex/tools/multicol.dtx928
1 files changed, 681 insertions, 247 deletions
diff --git a/Master/texmf-dist/source/latex/tools/multicol.dtx b/Master/texmf-dist/source/latex/tools/multicol.dtx
index fd69fab4efb..3d70d330f66 100644
--- a/Master/texmf-dist/source/latex/tools/multicol.dtx
+++ b/Master/texmf-dist/source/latex/tools/multicol.dtx
@@ -1,27 +1,27 @@
% \iffalse meta-comment
%
-%
+%
% This file is part of the Standard LaTeX `Tools Bundle'.
% -------------------------------------------------------
-%
+%
% It may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
% http://www.latex-project.org/lppl.txt
-% and version 1.3c or later is part of all distributions of LaTeX
+% and version 1.3c or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
-%
+%
% The list of all files belonging to the LaTeX `Tools Bundle' is
% given in the file `manifest.txt'.
-%
+%
% \fi
%
% \iffalse This is a METACOMMENT
%
%% Package `multicol' to use with LaTeX2e
-%% Copyright 1989-2011 Frank Mittelbach
-%%
+%% Copyright 1989-2013 Frank Mittelbach
+%%
%% In addition to the terms of LPPL any distributed version
%% (unchanged or modified) of multicol has to keep the statement
%% about the moral obligation for using multicol. In case of major
@@ -91,10 +91,10 @@
%<driver> \ProvidesFile{multicol.drv}
% \fi
% \ProvidesFile{multicol.dtx}
- [2011/06/27 v1.7a multicolumn formatting (FMi)]
+ [2014/04/23 v1.8e multicolumn formatting (FMi)]
%
%
-%% \CheckSum{1669}
+%% \CheckSum{1839}
%% \CharacterTable
%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
@@ -181,14 +181,58 @@
% one and multicolumn format on the same page. Footnotes are handled
% correctly (for the most part), but will be placed at the bottom of
% the page and not under each column. \LaTeX{}'s float mechanism,
-% however, is partly disabled in the current implementation. At the
+% however, is partly disabled in this implementation. At the
% moment only page-wide floats (i.e., star-forms) can be used within
% the scope of the environment.
% \end{abstract}
%
+% \begin{multicols}{3}[\section*{Preface to version 1.8}]
+% The 1.8 release improves on the balancing approach. If due to a
+% limited number of break points (e.g., due to large objects) the
+% balanced columns exceed the available vertical space, then
+% balancing is canceled and a normal page is produced first. Some
+% overflow is allowed (controlled by the parameter
+% |\maxbalancingoverflow| which defaults to 12pt). This ensures
+% that we only cut a normal page if we get enough material carried
+% over to next page.
+%
+% Also added was support for |\enlargethispage|. This means it is
+% now possible to request a page to be artifically enlarged or
+% shortened. Note that if you enlarge pages by more than one line
+% you may have to increase the {\sf collectmore} counter value to
+% ensure that enough material is being picked up.
+%
+% This command was used on the second page of this manual to shorten
+% it by one line, in order to get rid of a number of widow lines on
+% the following pages.
+%
+%
+% Finally, version 1.8 adds the command |\docolaction| to help with
+% more complicated actions that depend on the current column. This
+% command expects 3 arguments: code that is executed if we are in
+% the ``first'' column, code to execute if we end up in any
+% ``middle'' column (if there are more than two) and finally code to
+% execute if we are in the ``last'' column. Thus
+%\begin{verbatim}
+% \docolaction{first}
+% {middle}{last}
+%\end{verbatim}
+% would typeset a different word depending the type of column this
+% code is executed. Using it like this is probably pointless, but
+% you can imagine applications like writing something into the
+% nearest margin, etc.
+%
+% As this feature needs at least two \LaTeX{} runs to produce correct
+% results and as it adds to the processing complexity it is only
+% made available if one add the option \texttt{colaction} when
+% loading the package.
+%
+% \end{multicols}
+%
% \RLmulticolcolumns
%
-% \begin{multicols}{3}[\section*{Preface to version 1.7}]
+% \begin{multicols}{3}[\section*{Preface to version 1.7
+% (right to left support)}]
% The 1.7 release adds support for languages that are typeset
% right-to-left. For those languages the order of the columns on the page
% also need to be reversed---something that wasn't supported before. This
@@ -199,6 +243,23 @@
%
% \LRmulticolcolumns
%
+% \begin{multicols}{3}
+% Right-to-left typesetting will only reverse the column orders. Any
+% other support needed will have to be provided by other means,
+% e.g., using apprpriate fonts and reversing the writing directions
+% within the columns. As footnotes are typeset in full measure the
+% footnote rule needs to be redefined as if they are below a single
+% column, i.e., using |\textwidth| not |\columnwidth|. For example:
+%\begin{verbatim}
+%\renewcommand \footnoterule{%
+% \kern-3pt\hbox to\textwidth
+% {\hskip .6\textwidth
+% \hrulefill }%
+% \kern2.6pt}
+%\end{verbatim}
+% \end{multicols}
+%
+%
% \begin{multicols}{3}[\section*{Preface to version 1.5 + 1.6}]
% \hbadness=10000
% The 1.5 release contains two major changes: \mc{} will now
@@ -261,6 +322,8 @@
% lack of time. To implement floats one has to reimplement the
% whole \LaTeX{} output routine.}.
%
+% \enlargethispage{-1\baselineskip}
+%
% \DescribeMacro\premulticols
% As its first action, the {\sf multicols} environment measures the
% current page to determine whether there is enough room for some
@@ -305,7 +368,7 @@
%\end{verbatim}
%
%
-% \DescribeMacro\columnsep
+% \DescribeMacro\columnsep
% The space between columns is controlled by the length parameter
% |\columnsep|. The width for the individual columns is automatically
% calculated from this parameter and the current |\linewidth|. In this
@@ -333,6 +396,7 @@
%
% \subsection{Balancing columns}
%
+%
% Besides the previously mentioned parameters, some others are
% provided to influence the layout of the columns generated.
%
@@ -396,10 +460,9 @@
%
% In the second step (balancing columns) we have other bells and
% whistles. First of all you can say |\raggedcolumns| if you
-% don't want the bottom lines to be aligned.
-% The default is |\flushcolumns|, so \TeX{} will normally try to
-% make both
-% \columnbreak
+% don't want the bottom lines to be aligned.
+% The default is |\flushcolumns|, so \TeX{} will normally try to
+% make both
% the top and bottom baselines of all columns align.
%
% Additionally you can set another counter, the `{\sf unbalance}'
@@ -407,7 +470,7 @@
% right-most column \meta{number} of lines longer than they would
% normally have been. `Lines' in this context refer to normal text
% lines (i.e.\ one |\baselineskip| apart); thus, if your columns
-% contain displays,
+% contain displays,
% for example, you may need a higher \meta{number}
% to shift something from one column into another.
%
@@ -430,10 +493,10 @@
% solutions where at least one column has a badness being larger than
% the value of the counter {\sf columnbadness}. The default value for
% this counter is 10000, thus \TeX{} will accept all solutions except
-% those being overfull.
+% those being overfull.
% By setting the counter to a smaller value you can force the algorithm
% to search for solutions that do not have columns with a lot of white
-% space.
+% space.
%
% However, if the setting is too low, the algorithm may not find any
% acceptable solution at all and will then finally choose the extreme
@@ -453,13 +516,21 @@
% bad. In that case the final column is allowed to run short which gives
% a much better result.
%
-% And there are two more parameters of some experimental nature,
-% one called |\multicolovershoot| the other |\multicolundershoot|.
-% They control
-% the amount of space a column is allowed to be ``too full'' or ``too
-% short'' without affecting the column badness. They are set to 0pt
-% and 2pt, respectively.
-%
+% And there are two more parameters of some experimental nature, one
+% called |\multicolovershoot| the other |\multicolundershoot|. They
+% control the amount of space a column within the \mc{} environment is
+% allowed to be ``too full'' or ``too short'' without affecting the
+% column badness. They are set to 0pt and 2pt, respectively.
+%
+% Finally, when doing the balancing at the end, columns may become
+% higher than the remaining available space. In that case the
+% algorithm aborts and instead generates a normal page. However, if the
+% amount is not too large, e.g., a line or so, then it might be better to
+% keep everything on the same page instead of starting a new page with
+% just one line after balancing. So the parameter
+% |\maxbalancingoverflow| governs this process: only when the excess
+% gets larger than its value balancing is aborted.
+%
% \subsection{Not balancing the columns}
%
% Although this package was written to solve the problem of balancing
@@ -471,7 +542,7 @@
% works on top-level, e.g., inside a box one has to balance to
% determine a column height in absence of a fixed value.
%
-%
+%
% \subsection{Manually breaking columns}
%
% Another request often voiced was: ``How do I tell \LaTeX{} that it
@@ -514,7 +585,7 @@
% \subsection{Warnings}
%
% Under certain circumstances the use of the \mc{} environment may
-% result in some
+% result in some
% warnings from \TeX{} or \LaTeX{}. Here is a list
% of the important ones and the possible cause:
% \begin{description}
@@ -525,7 +596,7 @@
% As the columns are often very narrow \TeX{} wasn't able to find a
% good way to break the paragraph. Underfull denotes a loose line but
% as long as the badness value is below $10000$ the result is probably
-% acceptable.
+% acceptable.
%
% \item[]
% {\hspace*{-\labelsep}\tt Underfull \string\vbox\space ... while
@@ -571,7 +642,7 @@
%
% To understand the reasoning behind the decisions \TeX{} makes when
% processing a \mc{} environment, a tracing mechanism is provided.
-% If you set the counter `\texttt{tracingmulticols}'
+% If you set the counter `\texttt{tracingmulticols}'
% to a positive \meta{number} you then
% will get some tracing information on the terminal and in the
% transcript file:
@@ -648,9 +719,9 @@
%
% When it finishes it must return the individual columns in boxes
% suitable for further processing with |\page@sofar|. This means
-% that the left column should be stored in box register
+% that the left column should be stored in box register
% |\mult@gfirstbox|, the next
-% in register |\mult@firstbox|${}+2$, \ldots,
+% in register |\mult@firstbox|${}+2$, \ldots,
% only the last one as an exception in
% register |\mult@grightbox|. Furthermore it has to set up
% the two macros
@@ -759,7 +830,7 @@
% \StopEventually{\PrintIndex \PrintChanges
% \ifx\Finale\relax
% \typeout{**********************************}
-% \typeout{* Info: Typesetting this document with
+% \typeout{* Info: Typesetting this document with
% \protect\OnlyDescription\space will}
% \typeout{* Info: result in one unresolved
% reference to `sec:v14'.}
@@ -831,16 +902,16 @@
% \begin{macrocode}
\setcounter{IndexColumns}{4}
\let\DescribeMacro\SpecialUsageIndex
-\let\DescribeEnv\SpecialEnvIndex
-\renewcommand\PrintMacroName[1]{}
+\let\DescribeEnv\SpecialEnvIndex
+\renewcommand\PrintMacroName[1]{}
\CodelineIndex
%\DisableCrossrefs % Partial index
\RecordChanges % Change log
% \end{macrocode}
% Line numbers are very small for this article.
% \begin{macrocode}
-\renewcommand{\theCodelineNo}
- {\scriptsize\rm\arabic{CodelineNo}}
+\renewcommand{\theCodelineNo}
+ {\scriptsize\rm\arabic{CodelineNo}}
\settowidth\MacroIndent{\scriptsize\rm 00\ }
\begin{document}
@@ -856,7 +927,7 @@
%
% \end{multicols}
%
-% \begin{multicols}{2}[\subsection{Identification and
+% \begin{multicols}{2}[\subsection{Identification and
% option processing}]
%
%
@@ -866,7 +937,7 @@
% \begin{macrocode}
%<*package>
% \NeedsTeXFormat{LaTeX2e}
-% \ProvidesPackage{multicol}[..../../..
+% \ProvidesPackage{multicol}[..../../..
% v... multicolum formatting]
% \end{macrocode}
%
@@ -904,13 +975,34 @@
% \begin{macrocode}
\let\mc@gridwarn\maxdimen
\DeclareOption{grid}{\def\mc@gridwarn{\maxdepth}}
+% \end{macrocode}
+%
+% \changes{v1.8e}{2014/04/23}{Support \cs{docolaction}}
+% Next option enables the |\docolaction| command. As this changes
+% the \texttt{.aux} file content this is not automatically enabled.
+% \begin{macrocode}
+\DeclareOption{colaction}{%
+ \def\mc@col@status@write{%
+ \protected@write\@auxout{}%
+ {\string\mc@col@status
+ {\ifmc@firstcol 1\else 2\fi}}%
+ \mc@firstcolfalse}%
+ \def\mc@lastcol@status@write{%
+ \protected@write\@auxout{}%
+ {\string\mc@col@status{3}}}%
+}
+\let\mc@col@status@write\relax
+\let\mc@lastcol@status@write\relax
+% \end{macrocode}
+%
+% \begin{macrocode}
\ProcessOptions
% \end{macrocode}
%
%
% \end{multicols}
%
-% \begin{multicols}{2}[\subsection{Starting and
+% \begin{multicols}{2}[\subsection{Starting and
% Ending the \mc{} Environment}]
%
% \begin{macro}{\multicols}
@@ -985,7 +1077,7 @@
%
%
% \begin{macro}{\mult@footnotetext}
-%
+%
% \begin{macrocode}
\long\def\mult@footnotetext#1{\begingroup
\columnwidth\textwidth
@@ -1063,7 +1155,7 @@
% \end{macrocode}
% Now we output the first argument and produce vertical space
% above the columns. (Note that this argument corresponds to the
-% first optional argument of the {\sf multicols} environment.)
+% first optional argument of the {\sf multicols} environment.)
% For many releases this argument was typeset in a group to get
% a similar effect as |\twocolumn[..]| where the argument is
% also implicitly surrounded by braces. However, this conflicts
@@ -1089,7 +1181,7 @@
% \changes{v1.5z1}{2003/02/17}{Add a kern to cancel potential depth of
% previous line}
% \begin{macrocode}
- \ifdim \prevdepth = -\@m\p@
+ \ifdim \prevdepth = -\@m\p@
\else
% \end{macrocode}
% The actual generation of this corrective space is a little bit
@@ -1125,11 +1217,17 @@
\if@boxedmulticols
\setbox\mult@box\vbox\bgroup
% \end{macrocode}
+%
+% \changes{v1.8c}{2013/11/03}{Add \cs{color@setgroup} to prevent color leak}
+% \begin{macrocode}
+ \color@setgroup
+% \end{macrocode}
% \changes{v1.5?}{1994/?/?}{Penalty moved to later point}
% We may have to reset some parameters at this point,
% perhaps |\@parboxrestore|
% would be the right action but I leave it for the moment.
-% \changes{v1.4l}{1992/08/17}{\cs{@totalleftmargin} now in \cs{prepare@multicols}}
+% \changes{v1.4l}{1992/08/17}{\cs{@totalleftmargin} now in
+% \cs{prepare@multicols}}
% \begin{macrocode}
\fi
% \end{macrocode}
@@ -1158,7 +1256,7 @@
% correct since it doesn't take the `shrinking' (i.e.\
% |\pageshrink|) into account. The `recent contribution list'
% might be nonempty so we start with |\par| and an explicit
-% |\penalty|.\footnote{See the documentation of
+% |\penalty|.\footnote{See the documentation of
% \cs{endmulticols} for further details.}
% Actually, we use |\addpenalty| to ensure that a following
% |\addvspace| will `see' the vertical space that might be
@@ -1518,7 +1616,7 @@
% \end{macro}
%
% \begin{macro}{\set@mult@vsize}
-%
+%
% Since we have to set |\col@umber| columns on one page,
% each with a height of |\@colroom|, we have to assign
% $
@@ -1574,12 +1672,14 @@
% \end{macrocode}
% In boxed mode we have to close the box in which we have gathered
% all material for the columns.
+% \changes{v1.8c}{2013/11/03}{Add \cs{color@endgroup} to prevent color leak}
% \begin{macrocode}
- \egroup
+ \color@endgroup\egroup
% \end{macrocode}
% Now we call |\balance@columns| the routine that balances material
% stored in the box |\mult@box|.
-% \changes{v1.5?}{1994/?/?}{Splitting off zero box moved to \cs{balance@columns}}
+% \changes{v1.5?}{1994/?/?}{Splitting off zero box moved to
+% \cs{balance@columns}}
% \begin{macrocode}
\balance@columns
% \end{macrocode}
@@ -1631,7 +1731,7 @@
\fi
%</colbreak>
% \end{macrocode}
-%
+%
% If we are in an unrestricted \mc{} environment we end the current
% paragraph above with |\par| but this isn't sufficient since \TeX{}s
% {\it page\_builder} will not totally empty the contribution
@@ -1868,7 +1968,7 @@
% First we ensure that the columns have equal width. We use
% |\process@cols| for this purpose, starting with
% $|\count@|=|\mult@rightbox|$. Therefore |\count@| loops through
-% |\mult@rightbox|, $|\mult@rightbox| + 2$,\ldots
+% |\mult@rightbox|, $|\mult@rightbox| + 2$,\ldots
% (to |\doublecol@number|).
% \changes{v1.5a}{1992/11/04}{New box mechanism}
% \begin{macrocode}
@@ -1893,7 +1993,7 @@
% \begin{macrocode}
\count@\col@number \advance\count@\m@ne
\mult@info\z@
- {Column spec: \the\full@width\space = indent
+ {Column spec: \the\full@width\space = indent
+ columns + sep =\MessageBreak
\the\multicol@leftmargin\space
+ \the\col@number\space
@@ -1923,7 +2023,7 @@
% calculations are used. We therefore better cancel that process.
% \changes{v1.5z1}{2003/02/17}{Suppress interline glue at this point}
% \begin{macrocode}
- \nointerlineskip
+ \nointerlineskip
% \end{macrocode}
% As mentioned earlier we want to have the reference point of the
% box we put on the page being at the baseline of the last line of
@@ -1942,55 +2042,28 @@
% \changes{v1.6a}{2003/03/15}{Preparing for adjusting \cs{prevdepth}}
% \begin{macrocode}
\setbox\z@\hbox{p}\global\dimen\tw@\dp\z@
-% \end{macrocode}
-% If the document is written in a language that is typeset right-to-left
-% then, of course, the multicol columns should be also typeset
-% right-to-left. To support this we call |\maybe@reverse@columns| which
-% either does nothin (in the LR case) or re-sorts the columns so that they
-% come out in reverse order (for the RL case).
-% \changes{v1.7a}{2010/10/24}{}
-% \begin{macrocode}
- \maybe@reverse@columns
-% \end{macrocode}
-% After that we can output all columns regardless of typesetting direction
-% in the same way.
-% \begin{macrocode}
\moveright\multicol@leftmargin
\hbox to\full@width{%
- \process@cols\mult@gfirstbox{%
-% \end{macrocode}
-% If the depth of the current box is larger than the maximum found
-% so far in |\dimen2| we update that register.
-% \changes{v1.6a}{2003/03/15}{Preparing for adjusting \cs{prevdepth}}
-% \begin{macrocode}
- \ifdim\dp\count@>\dimen\tw@
- \global\dimen\tw@\dp\count@ \fi
- \box\count@
- \hss{\columnseprulecolor\vrule
- \@width\columnseprule}\hss}%
% \end{macrocode}
-% As you will have noticed, we started with box register
-% |\mult@gfirstbox| (i.e.\
-% the left column). So this time |\count@| looped through 2,
-% 4,\ldots\ (plus the appropriate offset).
-% Finally we add box 0 and close the |\hbox|.
-% \changes{v1.5a}{1992/11/04}{New box mechanism}
-% \changes{v1.6a}{2003/03/15}{Preparing for adjusting \cs{prevdepth}}
-% Again we may have to update |\dimen\tw@|.
+% If the document is written in a language that is typeset right-to-left
+% then, of course, the multicol columns should be also typeset
+% right-to-left. To support this we call |\mc@align@columns| which
+% with execute different code depending on the typesetting direction.
+% \changes{v1.7b}{2011/12/18}{RL language support fixed}
% \begin{macrocode}
- \ifdim\dp\mult@rightbox>\dimen\tw@
- \global\dimen\tw@\dp\mult@rightbox \fi
- \box\mult@rightbox
+ \mc@align@columns
% \end{macrocode}
% The depths of the columns depend on their last lines. To ensure
% that we will always get a similar look as far as the rules are
-% concerned we force the depth at least the depth of a letter~`p'.
+% concerned we force the depth to be at least the depth of a
+% letter~`p' (which is what we initialized |\dimen2| to aboved).
% \begin{macrocode}
- \rlap{\phantom p}%
+ \rlap{\phantom p}%
}%
% \end{macrocode}
% Now after typesetting the box we back up to its baseline by using
-% the value stored in |\dimen2|.
+% the value stored in |\dimen2| (which will hold the largest depth
+% found on any column).
% \changes{v1.6a}{2003/03/15}{Now adjusting \cs{prevdepth}}
% \begin{macrocode}
\kern-\dimen\tw@
@@ -2014,7 +2087,7 @@
%
% \begin{macro}{\columnseprulecolor}
% \changes{v1.6f}{2006/09/19}{Make the color of the rule a hook}
-% By default the vertical rule between columns will be in |\normalcolor|.
+% By default the vertical rule between columns will be in |\normalcolor|.
% \begin{macrocode}
\def\columnseprulecolor{\normalcolor}
% \end{macrocode}
@@ -2062,7 +2135,7 @@
% \end{macrocode}
% otherwise we construct the final page.
% \changes{v1.5u}{1999/05/25}{Support \cs{columnbreak}}
-% \changes{v1.5v}{1999/07/18}{Added debug statements for
+% \changes{v1.5v}{1999/07/18}{Added debug statements for
% column break support}
% For the next block of code see comments in section~\ref{sec:colbreak}.
% \begin{macrocode}
@@ -2103,6 +2176,28 @@
\leave@mult@footins
\fi
% \end{macrocode}
+% And there is one more adjustment that we have to make: if the
+% user has issue a |\enlargethispage| command then the height the
+% |\@kludgeins| box will be the negation of the size by which the
+% page should be enlarged. If the star form of this command has
+% been used then we also need to shrink the resulting column. As we
+% don't know whether or not shrinking is already generally
+% requested with save the current value of |\ifshr@king| and
+% restore it afterwards.
+% \changes{v1.8a}{2011/12/20}{Support for \cs{enlargethispage}}
+% \begin{macrocode}
+ \let\ifshr@kingsaved\ifshr@king
+ \ifvbox \@kludgeins
+ \advance \dimen@ -\ht\@kludgeins
+% \end{macrocode}
+% The star form of |\enlargethispage| makes the width of the box
+% greater than zero (sneaky isn't it?).
+% \begin{macrocode}
+ \ifdim \wd\@kludgeins>\z@
+ \shr@nkingtrue
+ \fi
+ \fi
+% \end{macrocode}
% Now we are able to |\vsplit| off all but the last column.
% Recall that these columns should be saved in the box registers 2,
% 4,\ldots\ (plus offset).
@@ -2118,32 +2213,54 @@
% \end{macrocode}
% If |\raggedcolumns| is in force we add a |vfill| at the bottom by
% unboxing the split box.
+% But we need to unbox anyway to ensure that at the end of the box
+% we do not have unwanted space. This can sneak in in certain
+% situations, for example, if two lists follow each other and we
+% break between them. While sich space is usually zero it still has
+% an effect because it hides depth of the last line in the column
+% and that will result in incorrect placement.
% \changes{v1.3c}{1990/03/03}{\cs{unbox}ing avoided.}
+% \changes{v1.8b}{2013/08/28}{And 20odd years later conclude that
+% this was wrong and unboxing is always needed.}
+% \changes{v1.8b}{2013/08/28}{Remove discardable items at the
+% end of split boxes}
% \begin{macrocode}
- \ifshr@nking
- \setbox\count@
+ \setbox\count@
\vbox to\dimen@
- {\unvbox\count@\vfill}%
- \fi
+ {\unvbox\count@
+ \remove@discardable@items
+ \ifshr@nking\vfill\fi}%
}%
% \end{macrocode}
% Then the last column follows.
% \changes{v1.5a}{1992/11/04}{New box mechanism}
+% \changes{v1.8b}{2013/08/28}{Remove discardable items at the
+% end of split boxes}
% \begin{macrocode}
\setbox\mult@rightbox
\vsplit\@cclv to\dimen@
\set@keptmarks
- \ifshr@nking
- \setbox\mult@rightbox\vbox to\dimen@
- {\unvbox\mult@rightbox\vfill}%
- \fi
+ \setbox\mult@rightbox\vbox to\dimen@
+ {\unvbox\mult@rightbox
+ \remove@discardable@items
+ \ifshr@nking\vfill\fi}%
+% \end{macrocode}
+% Now that we are done with the boxes, we restored the current
+% setting for shrinking in case it got changed:
+% \begin{macrocode}
+ \let\ifshr@king\ifshr@kingsaved
% \end{macrocode}
% Having done this we hope that box 255 is emptied. If not, we
% reinsert its contents.
+% \changes{v1.8a}{2011/12/20}{Only re-add output penalty if it was
+% explictly set}
% \begin{macrocode}
\ifvoid\@cclv \else
\unvbox\@cclv
- \penalty\outputpenalty
+ \ifnum\outputpenalty=\@M
+ \else
+ \penalty\outputpenalty
+ \fi
% \end{macrocode}
% In this case a footnote that happens to fall into the leftover
% bit will be typeset on the wrong page. Therefore we warn the user
@@ -2195,10 +2312,10 @@
\mult@info\tw@
{Use kept top mark:\MessageBreak
\meaning\kept@topmark
- \MessageBreak
+ \MessageBreak
Use kept first mark:\MessageBreak
\meaning\kept@firstmark
- \MessageBreak
+ \MessageBreak
Use kept bot mark:\MessageBreak
\meaning\kept@botmark
\MessageBreak
@@ -2256,8 +2373,12 @@
% \end{macrocode}
% Now we reset |\@colroom| to |\@colht| which is \LaTeX's
% saved value of |\textheight|.
+% We also ahve to reset the recorded position of the last
+% |\marginpar| as we are now on a new page.
+% \changes{v1.8d}{2014/04/23}{Reset \cs{@mparbottom} after page finishes}
% \begin{macrocode}
\global\@colroom\@colht
+ \global \@mparbottom \z@
% \end{macrocode}
% Then we process deferred floats waiting for their chance to be
% placed on the next page.
@@ -2296,7 +2417,7 @@
%
% \begin{macro}{\leave@mult@footins}
% This macro is used to subtract the amount of space
-% occupied by footnotes for the current space from the
+% occupied by footnotes for the current space from the
% space available for the current column. The space current column
% is stored in |\dimen@|. See above for the description of the default
% action.
@@ -2313,7 +2434,7 @@
%
% \begin{macro}{\speci@ls}
% We left out two macros: |\process@deferreds| and
-% |\speci@ls|.
+% |\speci@ls|.
% \changes{v1.5c}{1993/04/18}{Support \cs{clearpage}}
% \begin{macrocode}
\def\speci@ls{%
@@ -2322,21 +2443,21 @@
% If the document ends in the middle of a multicols environment, e.g.,
% if the user forgot the |\end{multicols}|, \TeX{} adds a very
% negative penalty to the end of the galley which is intended to signal
-% the output routine that it is time to prepare for shipping out
-% everything remaining. Since inside multicols the output routine of
-% \LaTeX{} is disabled sometimes we better check for this case: if we
+% the output routine that it is time to prepare for shipping out
+% everything remaining. Since inside multicols the output routine of
+% \LaTeX{} is disabled sometimes we better check for this case: if we
% find a very negative penalty we produce an error message and run
% the default output routine for this case.
% \changes{v1.5s}{1998/09/10}{check for \cs{stop} penalty pr/2873}
% \begin{macrocode}
- \ifnum \outputpenalty<-\@MM
+ \ifnum \outputpenalty<-\@MM
\PackageError{multicol}{Document end
inside multicols environment}\@ehd
\@specialoutput
\else
% \end{macrocode}
% \changes{v1.5u}{1999/05/25}{Support \cs{columnbreak}}
-% \changes{v1.5v}{1999/07/18}{Added debug statements for
+% \changes{v1.5v}{1999/07/18}{Added debug statements for
% column break support}
% For the next block of code see comments in section~\ref{sec:colbreak}.
% \begin{macrocode}
@@ -2349,7 +2470,7 @@
\vbox{\ifvoid\colbreak@box
\else
\unvbox\colbreak@box
- \penalty-\@Mv
+ \penalty-\@Mv
\fi
\unvbox\@cclv}
\reinsert@footnotes
@@ -2466,7 +2587,7 @@
%<-colbreak> \vbox{\unvbox\@cclv}%
% \end{macrocode}
% \changes{v1.5u}{1999/05/25}{Support \cs{columnbreak}}
-% \changes{v1.5v}{1999/07/18}{Added debug statements for
+% \changes{v1.5v}{1999/07/18}{Added debug statements for
% column break support}
% For the next block of code see comments in section~\ref{sec:colbreak}.
% \begin{macrocode}
@@ -2481,24 +2602,68 @@
%</colbreak>
\balance@columns
% \end{macrocode}
-% This will bring us into the position to apply |\page@sofar|.
-% But first we have to set |\vsize| to a value suitable for
-% one column output.
+% If during balancing the columns got too long the flag
+% |\iftoo@bad| is set to true.
+% \changes{v1.8a}{2011/12/20}{Balancing concept improved}
+% \begin{macrocode}
+ \iftoo@bad
+ \mult@info\@ne
+ {Balancing failed ...
+ cut a normal page}%
+% \end{macrocode}
+% In that case we put the material back in box 255. The curious set of
+% |\vskip|s we add is necessary to cancel out the |\splittopskip|
+% that got added for balancing.
+% \begin{macrocode}
+ \setbox\@cclv\vbox
+ {\vskip\topskip
+ \vskip-\splittopskip
+ \unvbox\mult@box}%
+% \end{macrocode}
+% We then call the standard multicol output routine which will
+% produce a normal page for us (remember we are still within the
+% OR).
+% This also means that if there was an |\enlargethispage| present
+% it will apply to this page as |\multi@column@out| will look at
+% the status of |\@kludgeins|.
+% \begin{macrocode}
+ \multi@column@out
+% \end{macrocode}
+% Because balancing made the columns too long we are sure that there
+% will be some material remaining which was put back onto the main
+% vertical list by |\multi@column@out|. We therefore add another
+% breakpoint so that this material will then be processed by the
+% balancing OR to finish off the multicol environment.
+% \begin{macrocode}
+ \break
+ \else
+% \end{macrocode}
+% If the balancing went ok, we are in the position
+% to apply |\page@sofar|. But first we have to set |\vsize| to a
+% value suitable for one column output.
% \begin{macrocode}
- \global\vsize\@colroom
- \global\advance\vsize\ht\partial@page
+ \global\vsize\@colroom
+ \global\advance\vsize\ht\partial@page
+% \end{macrocode}
+% We also have to look at |\@kludgeins| and generate a new
+% |\insert| in case there was one present due to an
+% |\enlargethispage| command.
+% \changes{v1.8a}{2011/12/20}{Support for \cs{enlargethispage}}
+% \begin{macrocode}
+ \ifvbox\@kludgeins\insert\@kludgeins
+ {\unvbox\@kludgeins}\fi
% \end{macrocode}
% Then we |\unvbox| the |\partial@page| (which may be void if we
-% are not prcessing the first page of this \mc{} environment.
+% are not processing the first page of this \mc{} environment.
% \begin{macrocode}
- \unvbox\partial@page
+ \unvbox\partial@page
% \end{macrocode}
% Then we return the first and bottom mark and the gathered
% material to the main vertical list.
% \begin{macrocode}
- \return@nonemptymark{first}\kept@firstmark
- \return@nonemptymark{bot}\kept@botmark
- \page@sofar
+ \return@nonemptymark{first}\kept@firstmark
+ \return@nonemptymark{bot}\kept@botmark
+ \page@sofar
% \end{macrocode}
% We need to add a penalty at this point which allows to break at
% this point since calling the output routine may have removed the
@@ -2507,7 +2672,8 @@
% for |\multicolsep| etc. this could produce funny results.
% \changes{v1.5c}{1993/04/18}{added penalty at output routine exit}
% \begin{macrocode}
- \penalty\z@
+ \penalty\z@
+ \fi
}
% \end{macrocode}
% As we already know, reinserting of footnotes will be done in the
@@ -2523,7 +2689,7 @@
% We start by setting the kept marks by updating them with any
% marks from this box. This has to be done \emph{before} we add a
% penalty of $-10000$ to the top of the box, otherwise only an
-% empty box will be considered.
+% empty box will be considered.
% \changes{v1.5h}{1994/08/26}{Get kept marks first}
% \begin{macrocode}
\get@keptmarks\mult@box
@@ -2638,12 +2804,12 @@
% it.
% \changes{v1.2a}{1990/02/05}{Group around main loop removed.}
% \begin{macrocode}
- \vbadness\@M
+ \vbadness\@M
% \end{macrocode}
% We also allow for overfull boxes while we trying to split the
% columns.
% \begin{macrocode}
- \vfuzz \col@number\baselineskip
+ \vfuzz \col@number\baselineskip
% \end{macrocode}
% The variable |\last@try| will hold the dimension used in the
% previous trial splitting. We initialize it with a negative value.
@@ -2679,7 +2845,7 @@
% \changes{v1.5b}{1992/11/05}{New badness mechanism}
% \begin{macrocode}
%<*badness>
- \global\too@badfalse
+ \too@badfalse
%</badness>
% \end{macrocode}
% Using |\vsplit| we extract the other columns from box register
@@ -2691,6 +2857,16 @@
\global\setbox\count@
\vsplit\mult@grightbox to\dimen@
% \end{macrocode}
+% After splitting we need to ensure that there isn't any space at
+% the bottom, so we rebox once more.
+% \changes{v1.8b}{2013/08/28}{Remove discardable items at the
+% end of split boxes}
+% \begin{macrocode}
+ \global\setbox\count@
+ \vbox to\dimen@
+ {\unvbox\count@
+ \remove@discardable@items}%
+% \end{macrocode}
% After every split we check the badness of the resulting column,
% normally the amount of extra white in the column.
% \begin{macrocode}
@@ -2699,8 +2875,8 @@
\@tempcnta\count@
\advance\@tempcnta-\mult@grightbox
\divide\@tempcnta \tw@
- \message{^^JColumn
- \number\@tempcnta\space
+ \message{^^JColumn
+ \number\@tempcnta\space
badness: \the\badness\space}%
\fi
% \end{macrocode}
@@ -2709,10 +2885,10 @@
% \begin{macrocode}
\ifnum\badness>\c@columnbadness
\ifnum\c@tracingmulticols>\@ne
- \message{too bad
+ \message{too bad
(>\the\c@columnbadness)}%
\fi
- \global\too@badtrue
+ \too@badtrue
\fi
%</badness>
}}%
@@ -2765,13 +2941,13 @@
% |\raggedcolumns| means allows for all columns to run slightly short.
% \changes{v1.5q}{1998/01/19}{Do not reset \cs{mult@firstbox} (pr2739)}
% \begin{macrocode}
-% \ifshr@nking
+% \ifshr@nking
% \global\setbox\mult@firstbox
% \copy\mult@nat@firstbox
% \fi
% \end{macrocode}
% Then we give information about the last column.\footnote{With
-% \TeX{} version 3.141 it is now possible to use \LaTeX's
+% \TeX{} version 3.141 it is now possible to use \LaTeX's
% \cs{newlinechar} in the \cs{message} command, but
% people with older \TeX{} versions will now get
% \texttt{\string^\string^J} instead of a new line on the screen.}
@@ -2807,9 +2983,9 @@
% \begin{macrocode}
\ifdim\ht\mult@grightbox >\dimen@
% \end{macrocode}
-% If the height of the last box is too large we mark this trial as
+% If the height of the last box is too large we mark this trial as
% unsuccessful.
-% \changes{v1.5v}{1999/07/18}{Added tracing statements for
+% \changes{v1.5v}{1999/07/18}{Added tracing statements for
% trial unsuccesful}
% \begin{macrocode}
%<*badness>
@@ -2837,8 +3013,8 @@
\ifvoid\@tempboxa
%</colbreak>
% \end{macrocode}
-% Thus if |\@tempboxa| is void we have a valid solution.
-% In this case we take a closer
+% Thus if |\@tempboxa| is void we have a valid solution.
+% In this case we take a closer
% look at the last column to decide if this column should be made
% as long as all other columns or if it should be allowed to be
% shorter.
@@ -2850,7 +3026,7 @@
\vbox to\dimen@
{\unvbox\mult@grightbox}%
\ifnum\c@tracingmulticols>\@ne
- \message{Final badness:
+ \message{Final badness:
\the\badness}%
\fi
% \end{macrocode}
@@ -2901,7 +3077,7 @@
\last@try\dimen@
\advance\dimen@-\p@
\fi
- \fi
+ \fi
% \end{macrocode}
% Finally the switch |too@bad| is tested. If it was made true
% either earlier on or due to a rightmost column being too large
@@ -2909,7 +3085,7 @@
% \begin{macrocode}
\iftoo@bad
%</badness>
- \advance\dimen@\p@
+ \advance\dimen@\p@
\repeat
% \end{macrocode}
% At that point |\dimen@| holds the height that was determined by
@@ -2949,6 +3125,11 @@
\process@cols\mult@rightbox
{\@tempcnta\count@
\advance\@tempcnta\@ne
+% \end{macrocode}
+% when putting the final column together we want overfull
+% information:
+% \begin{macrocode}
+ \vfuzz\z@
\setbox\count@\vbox to\dimen@
{%
% \end{macrocode}
@@ -2958,11 +3139,58 @@
\@plus-\multicolundershoot
\@minus-\multicolovershoot
\unvbox\@tempcnta
- \ifshr@nking\vfill\fi}}%
+ \ifshr@nking\vfill\fi
+ }%
+% \end{macrocode}
+% If the resulting box is overfull there was too much material to
+% fit into the available space. The question though is how much? If
+% it wasn't more than |\maxbalancingoverflow| we accept it still to
+% avoid getting very little material for the next page (which we
+% would then have difficulties to balance).
+% \changes{v1.8a}{2011/12/20}{Balancing concept improved}
+% \begin{macrocode}
+ \ifnum\badness>\@M
+ \vfuzz\maxdimen % no overfull warning
+ \setbox\@tempboxa \vbox to\dimen@
+ {\vskip-\maxbalancingoverflow
+ \unvcopy\count@}%
+ \ifnum\badness>\@M
+ \mult@info\@ne
+ {Balanced column more than
+ \the\maxbalancingoverflow\space
+ too large}%
+% \end{macrocode}
+% Fail the balancing attempt:
+% \begin{macrocode}
+ \too@badtrue
+ \else
+% \end{macrocode}
+% Otherwise report that there is a problem but within the accepted
+% boundary.
+% \begin{macrocode}
+ \mult@info\@ne
+ {Balanced column
+ too large, but less than
+ \the\maxbalancingoverflow}%
+ \fi
+ \fi
+ }%
}
% \end{macrocode}
% \end{macro}
%
+%
+% \begin{macro}{\maxbalancingoverflow}
+% Amount that balancing is allowed to overflow the available column
+% space. We default to 12pt which means about one line in most
+% layouts.
+% \changes{v1.8a}{2011/12/20}{\cs{maxbalancingoverflow} parameter added}
+% \begin{macrocode}
+\newdimen\maxbalancingoverflow
+\maxbalancingoverflow=12pt
+% \end{macrocode}
+% \end{macro}
+
% \end{multicols}
%
% \begin{multicols}{2}[\subsection{The box allocations}]
@@ -2998,7 +3226,7 @@
% \end{macro}
% \end{macro}
% \end{macro}
-%
+%
%
% \end{multicols}
%
@@ -3275,7 +3503,10 @@
%
%
% \begin{macro}{\remove@discardable@items}
-%
+% There are situations when we may have some space at the end of a
+% column and this macro here will attempt to get rid of it. This
+% will not remove an extremly long sequence of spaces and
+% penalties, but in nearly all cases this will be enough.
% \begin{macrocode}
\def\remove@discardable@items{%
%<*debug>
@@ -3313,6 +3544,8 @@
% \begin{macrocode}
%<*badness>
\newif\iftoo@bad
+\def\too@badtrue{\global\let\iftoo@bad\iftrue}
+\def\too@badfalse{\global\let\iftoo@bad\iffalse}
% \end{macrocode}
%
% \begin{macro}{\c@columnbadness}
@@ -3326,8 +3559,8 @@
\newdimen\last@try
% \end{macrocode}
-%
-% \changes{v1.5z1}{2003/02/17}{Change wrong default for
+%
+% \changes{v1.5z1}{2003/02/17}{Change wrong default for
% \cs{multicolovershoot} to zero (pr/3465).}
% \begin{macrocode}
\newdimen\multicolovershoot
@@ -3356,7 +3589,7 @@
% \end{multicols}
%
%
-% \begin{multicols}{2}[\section{Fixing the
+% \begin{multicols}{2}[\section{Fixing the
% \cs{columnwidth}}]
%
% \begin{macro}{\@footnotetext}
@@ -3367,11 +3600,11 @@
% \changes{v1.5r}{1998/08/17}{Macro removed again.}
% If we store the current column width in |\columnwidth| we have
% to redefine the internal |\@footnotetext| macro to use |\textwidth|
-% for the width of the footnotes rather than using the original
+% for the width of the footnotes rather than using the original
% definition.
%
% Starting with version v1.5r this is now done in a way that the original
-% definition is still used, execpt that locally |\columnwidth| is set to
+% definition is still used, execpt that locally |\columnwidth| is set to
% |\textwidth|.
%
% This solves two problems: first redefinitions of |\@footnotetext|
@@ -3398,7 +3631,7 @@
%
% This is fairly trivial to implement. we just have to disable the
% balancing output routine and replace it by the one that ships out
-% the other pages.
+% the other pages.
%
% \begin{macro}{\multicols*}
% \changes{v1.5q}{1998/01/19}{Macro added}
@@ -3413,7 +3646,7 @@
% \begin{macrocode}
\ifinner
\PackageWarning{multicol}%
- {multicols* inside a box does
+ {multicols* inside a box does
not make sense.\MessageBreak
Going to balance anyway}%
\else
@@ -3447,7 +3680,7 @@
% quite what is desired. On the other hand, using a penalty like -9999
% would mean that there would be occasions where the |\vsplit|ing
% operations within \mc{} would ignore that penalty and still choose a
-% different break point.
+% different break point.
%
% For this reason the current implementation
% uses a completely different approach. In a nutshell it extends the \LaTeX{}
@@ -3460,7 +3693,7 @@
% we do two things: save the galley up to this point in a special box
% for later use and reduce the |\vsize| by the height of the material
% seen. This way the forcing penalty is now hidden in that box and we
-% can restart the collection process for the remaining
+% can restart the collection process for the remaining
% columns. (This is done in |\speci@ls| above.)
%
% In the output routines that do the |\vsplit|ting either for
@@ -3472,7 +3705,7 @@
% \begin{macro}{\columnbreak}
% \changes{v1.5u}{1999/05/25}{Macro added}
% |\columnbreak| is modelled after |\pagebreak| except that we
-% generate a penalty -10005.
+% generate a penalty -10005.
% \begin{macrocode}
%<*colbreak>
\mathchardef\@Mv=10005
@@ -3513,22 +3746,158 @@
%
% \subsection{Supporting right-to-left languages} \label{sec:RL}
%
-%
+%
% \changes{v1.7a}{2010/10/24}{RL language support added}
+% \changes{v1.7b}{2011/12/18}{RL language support fixed}
+%
+% \begin{macro}{\LR@column@boxes}
+% |\LR@column@boxes| is called when we are assembling the columns for left
+% to right typesetting. When we start we are inside an |\hbox| of
+% full width.
+% Left to right typesetting is fairly easy, we basically output
+% each column box intermixed with vertical rules and proper
+% spacing. As this happens inside a box of a defined width the
+% rules and the columns automatically get into the right positions.
+% \begin{macrocode}
+\def\LR@column@boxes{%
+% \end{macrocode}
+% We loop through the columns with |\process@cols|
+% \begin{macrocode}
+ \process@cols\mult@gfirstbox{%
+% \end{macrocode}
+% If the depth of the current box is larger than the maximum found
+% so far in |\dimen2| we update that register for later use.
+% \changes{v1.6a}{2003/03/15}{Preparing for adjusting \cs{prevdepth}}
+% \begin{macrocode}
+ \ifdim\dp\count@>\dimen\tw@
+ \global\dimen\tw@\dp\count@ \fi
+% \end{macrocode}
+% If the \texttt{colaction} option is given we write out status
+% information about the current column, otherwise the next command
+% does nothing.
+% \changes{v1.8e}{2014/04/23}{Support \cs{docolaction}}
+% \begin{macrocode}
+ \mc@col@status@write
+% \end{macrocode}
+% The typeset box followed by the column rule material
+% \begin{macrocode}
+ \box\count@
+ \hss{\columnseprulecolor\vrule
+ \@width\columnseprule}\hss}%
+% \end{macrocode}
+% As you will have noticed, we started with box register
+% |\mult@gfirstbox| (i.e.\
+% the left column). So this time |\count@| looped through 2,
+% 4,\ldots\ (plus the appropriate offset).
+% Finally we add box |\mult@rightbox| and we are done.
+% \changes{v1.5a}{1992/11/04}{New box mechanism}
+% \changes{v1.6a}{2003/03/15}{Preparing for adjusting \cs{prevdepth}}
+% Again we may have to update |\dimen\tw@|.
+% \begin{macrocode}
+ \ifdim\dp\mult@rightbox>\dimen\tw@
+ \global\dimen\tw@\dp\mult@rightbox \fi
+% \end{macrocode}
+% If the \texttt{colaction} option is given we write out status
+% information about the last column, otherwise the next command
+% does nothing.
+% \changes{v1.8e}{2014/04/23}{Support \cs{docolaction}}
+% \begin{macrocode}
+ \mc@lastcol@status@write
+ \box\mult@rightbox
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\RL@column@boxes}
+% Assembling the boxes for right to left typesetting is far more
+% complicated. When I first tried to build a solution for this my
+% thinking was that all that is necessary to do is to reverse the
+% order of the columns. But such an approach produces a subtle bug:
+% If we work this way then the first column put on the page will be
+% the last column of the text to read. and this means that the
+% order in which \TeX{} executes write statements or assembles mark
+% material will not happen in the order of the textual flow. So if,
+% for example each column contains a section command then these
+% sections will appear in reverse order in the table of content.
+%
+% For this reason some amount of gymnastics is needed to add the
+% columns in their natural flow.
+% \begin{macrocode}
+\def\RL@column@boxes{%
+% \end{macrocode}
+% First step is to put all rules in the right place (without adding
+% the comes which are instead represented by a space of |\hsize|.
+% \begin{macrocode}
+ \process@cols\mult@gfirstbox{%
+ \hskip\hsize
+ \hss{\columnseprulecolor\vrule
+ \@width\columnseprule}\hss
+ }%
+ \hskip\hsize
+% \end{macrocode}
+% At this point in the code our typesetting reference point is at
+% the right end of the rightmost column (or rather where that column
+% should appear).
+%
+% We are now typesetting all columns by first backing up by their
+% width (which is |\hsize|) then typesetting the box and then
+% backing up again, but this time further, i.e., also across the
+% column separation. That will then enable us to typeset the next
+% column using the same approach until we are done with all but the
+% final column.
+% \begin{macrocode}
+ \process@cols\mult@gfirstbox{%
+ \ifdim\dp\count@>\dimen\tw@
+ \global\dimen\tw@\dp\count@ \fi
+ \hskip-\hsize
+% \end{macrocode}
+%
+% \changes{v1.8e}{2014/04/23}{Support \cs{docolaction}}
+% \begin{macrocode}
+ \mc@col@status@write
+ \box\count@
+ \hskip-\hsize
+ \hskip-\columnsep
+ }%
+% \end{macrocode}
+% The approach for the final column is similar only that we do not
+% have to back up over any column gap.
+% \begin{macrocode}
+ \ifdim\dp\mult@rightbox>\dimen\tw@
+ \global\dimen\tw@\dp\mult@rightbox \fi
+ \hskip-\hsize
+% \end{macrocode}
+%
+% \changes{v1.8e}{2014/04/23}{Support \cs{docolaction}}
+% \begin{macrocode}
+ \mc@lastcol@status@write
+ \box\mult@rightbox
+ \hskip-\hsize
+% \end{macrocode}
+% However we do have to move the reference point to its right
+% place: to make the rules appear at the expected places, we should
+% get the typesetting position to the far right again. As we at the
+% moment at the far left we skip to the far right like this:
+% \begin{macrocode}
+ \hskip\full@width
+ }
+% \end{macrocode}
+% \end{macro}
%
% \begin{macro}{\RLmulticolcolumns}
% \begin{macro}{\LRmulticolcolumns}
-% \begin{macro}{\maybe@reverse@columns}
-% Macros to switch between left-right and right-left typesetting. In RL
-% typesetting the |\reverse@column@boxes| is executed prior to typesetting
-% the columns. In LR typesetting this resorting is omitted as the boxes are
-% already in the right order.
+% \begin{macro}{\mc@align@columns}
+% Macros to switch between left-right and right-left typesetting. In LR
+% typesetting the |\LR@column@boxes| is used to combine
+% the columns. When typesetting right to left the |\RL@column@boxes|
+% is used instead.
% \begin{macrocode}
\newcommand\RLmulticolcolumns
- {\let\maybe@reverse@columns
- \reverse@column@boxes}
+ {\let\mc@align@columns
+ \RL@column@boxes}
\newcommand\LRmulticolcolumns
- {\let\maybe@reverse@columns\relax}
+ {\let\mc@align@columns
+ \LR@column@boxes}
% \end{macrocode}
% The default is left-to-right:
% \begin{macrocode}
@@ -3537,110 +3906,175 @@
% \end{macro}
% \end{macro}
% \end{macro}
-
-
-% \begin{macro}{\multicol@sort@counter}
-% We need a counter to resort the column boxes if we are typesetting
-% right-to-left.
+%
+%
+% \subsection{Supporting \texttt{\textbackslash docolaction}}
+%
+% \changes{v1.8e}{2014/04/23}{Support \cs{docolaction}}
+%
+% Whenever we want to do something that depends on the current
+% column we execute \verb=\docolaction=. This command takes one
+% optional and three mandatory arguments. The mandatory ones denote
+% what to do if this is a ``left'', ``middle'', or ``right'' column
+% and the optional one is simply there to say what to do if we don't
+% know (default is to use the ``left'' column action in that case).
+%
+% \begin{macro}{\mc@col@check@num}
+% We use one counter \verb=\mc@col@check@num= to generate us unique
+% label names. Each time we execute \verb=\docolaction= we increment
+% this counter to get a new name.
% \begin{macrocode}
-\newcount\multicol@sort@counter
+\newcount\mc@col@check@num
% \end{macrocode}
% \end{macro}
+%
+% The generated ``labels'' are named
+%\begin{verbatim}
+%\mc@col-\the\mc@col@check@num
+%\end{verbatim}
+% and they hold as values the
+% numbers 1, 2, or 3 denoting the current column type.
-
-% \begin{macro}{\reverse@column@boxes}
-% This macro is called to re-sort the assembled column boxes when we are
-% typesetting right-to-left. The first step is to reverse the columns.
+% \begin{macro}{\docolaction}
+%
% \begin{macrocode}
-\def\reverse@column@boxes {%
- \ifnum\c@tracingmulticols>\thr@@
- \typeout{reversing columns ...}
+\newcommand\docolaction[4][1]{%
+ \ifx\mc@col@status@write\relax
+ \PackageError{multicol}%
+ {Option 'colaction' not selected}%
+ {\string\docolaction\space
+ requires the use of the 'colaction'
+ option on the package}%
+ \fi
+ \global\advance\mc@col@check@num\@ne
+ \edef\mc@col@type{\expandafter\ifx
+ \csname mc@col-\the\mc@col@check@num
+ \endcsname\relax
+ 0\else
+ \csname mc@col-\the\mc@col@check@num
+ \endcsname
+ \fi}%
+% \end{macrocode}
+% We prefix with 0 so that an unknown label (that returns
+% \verb=\relax=) will result in case 0
+% \begin{macrocode}
+ \ifcase \mc@col@type\relax
+% \end{macrocode}
+% If column is unknown we use the default action or the action
+% denoted by the optional argument (so that arg can take the value
+% 1, 2, 3).
+% \begin{macrocode}
+ \ifcase #1\or #2\or#3\or#4\fi
+ \or
+% \end{macrocode}
+% Otherwise we know (or think we know) that this is a first, middle,
+% or last column:
+% \begin{macrocode}
+ #2% % 1 First col
+ \or
+ #3% % 2 any middle col
+ \or
+ #4% % 3 last col
+ \else
+ \ERROR
\fi
% \end{macrocode}
-% The columns are at this point in the boxes with register numbers
-% |\mult@gfirstbox|, $|\mult@gfirstbox|+2$, \ldots{} but the last column
-% is in |\mult@rightbox| which is equal to $|\mult@gfirstbox|-2$.
-%
-% So to re-sort we use |\process@cols| with |\count@| starting at
-% |\mult@gfirstbox| and incrementing by 2 and |\multicol@sort@counter|
-% starting at the high end of the now unused intermediate boxes and
-% decrementing by 2.
-% \begin{macrocode}
- \multicol@sort@counter\doublecol@number
- \advance\multicol@sort@counter\m@ne
- \process@cols\mult@gfirstbox{%
- \setbox\multicol@sort@counter
- \box\count@
- \ifnum\c@tracingmulticols>\thr@@
- \typeout{Setting
- \the\multicol@sort@counter\space
- <- \the\count@}%
- \fi
- \advance \multicol@sort@counter -\tw@
- }%
-% \end{macrocode}
-% For example with 4 columns we would see something like
-% this:
-% What remains to do is to move the last box out of the way:
+% But how does the column number get associated with our label? We
+% do do this by writing another line into the aux file at this point:
% \begin{macrocode}
+ \edef\next{\write\@auxout
+ {\string\mc@set@col@status
+ {mc@col-\the\mc@col@check@num}%
+ {\mc@col@type}}}%
+ \next
+}
+% \end{macrocode}
+% \end{macro}
%
- \ifnum\c@tracingmulticols>\thr@@
- \typeout{Setting last:
- \the\mult@grightbox\space
- <- \the\mult@rightbox}%
- \fi
- \setbox \mult@grightbox \box\mult@rightbox
+% Because of extra data writing to the aux file the aux file will
+% now contain something like the following after the document is
+% processed the first time:
+%\begin{verbatim}
+%\relax
+%\mc@col@status{1}
+%\mc@set@col@status{lcol-1}{0}
+%\mc@col@status{2}
+%\mc@set@col@status{lcol-2}{0}
+%\mc@col@status{3}
+%\mc@set@col@status{lcol-3}{0}
+%\mc@col@status{1}
+%\mc@col@status{2}
+%\mc@col@status{3}
+%\mc@set@col@status{lcol-4}{0}
+%\end{verbatim}
+% The \verb=\mc@col@status= line denotes the column type and has been
+% writting out just before corresponding the column box was placed
+% onto the page.
+% The\verb=\mc@set@col@status= lines have been written out as part
+% of shipping the column boxes out, e.g.,
+% \verb=\mc@set@col@status{lcol-1}{0}= was therefore somewhere within
+% the first column as it appears between \verb=\mc@col@status{1}=
+% and \verb=\mc@col@status{2}=
+% The second argument in that line is the value used in the previous
+% run (or zero if there was no previous run. We can use this to
+% determine if a rerun is necessary.
+%
+% Thus with this knowledge we can set things up to get the labels
+% working.
+%
+%
+% \begin{macro}{\mc@col@status}
+%
+% When the aux file is read in \verb=\mc@col@status= is used to set
+% \verb=\mc@curr@col@status=:
+% \begin{macrocode}
+\def\mc@col@status#1{%
+ \gdef\mc@curr@col@status{#1}}
% \end{macrocode}
-% Now the boxes are more or less resorted but the register numbers are off
-% by one, so we shift the boxes again using |\process@cols|. This time
-% |\multicol@sort@counter| trails one behind |\count@|.
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\mc@set@col@status}
+%
+% And when \verb=\mc@set@col@status= is executed we can simply set
+% up the label by associating it with the \verb=\mc@curr@col@status=
+% and ignore the second argument:
% \begin{macrocode}
- \ifnum\c@tracingmulticols>\thr@@
- \typeout{shifting ...}
- \fi
- \multicol@sort@counter\mult@gfirstbox
- \advance\multicol@sort@counter \m@ne
- \process@cols\mult@gfirstbox{%
- \global\setbox\count@
- \box\multicol@sort@counter
- \ifnum\c@tracingmulticols>\thr@@
- \typeout{Setting \the\count@\space
- <- \the\multicol@sort@counter}%
- \fi
- \advance \multicol@sort@counter \tw@
- }%
-% \end{macrocode}
-% With 4 columns this would do the following register moves:
-% \begin{verbatim}
-% Setting 31 <- 30
-% Setting 33 <- 32
-% Setting 35 <- 34
-% \end{verbatim}
-% Now all columns except the last one are in the right place. That one is
-% now in highest register we used which corresponds to
-% $|\doublecol@number|-1$ if you look back to the first loop. And it has to
-% move to |\mult@rightbox| which happens in the following code.
-% \begin{macrocode}
- \multicol@sort@counter\doublecol@number
- \advance\multicol@sort@counter\m@ne
- \ifnum\c@tracingmulticols>\thr@@
- \typeout{Setting last:
- \the\mult@rightbox\space
- <- \the\multicol@sort@counter}%
- \fi
- \global\setbox \mult@rightbox
- \box\multicol@sort@counter
+\def\mc@set@col@status#1#2{%
+ \global\expandafter\let\csname #1\endcsname
+ \mc@curr@col@status}
% \end{macrocode}
-% After that the columns are in the same boxes as before but sorted the
-% other way around and thus can be processed without further adjustments by
-% the normal multicol code.
+% The above definition is being used when the \texttt{.aux} file is
+% read in at the beginning. At the end we need a different
+% definition to test if another typesetting run is needed. There we
+% compare the value used in the current run (stored in the second
+% argument) with the value used on the next run. If those two values
+% differ we set \verb=@tempswa= to false which will trigger the
+% ``Label(s) may have changed'' warning.
% \begin{macrocode}
+\AtEndDocument{\def\mc@set@col@status#1#2{%
+ \ifnum #2=\mc@curr@col@status\else
+ \@tempswatrue
+ \fi}%
}
% \end{macrocode}
% \end{macro}
%
+%
+% \begin{macro}{mc@firstcol}
+% Finally, as part of determining in which column we are, we used a
+% switch inside |\mc@col@status@write| to determine if we are in the
+% first column or not.
+% \begin{macrocode}
+\newif\ifmc@firstcol
+\mc@firstcoltrue
+% \end{macrocode}
+% \end{macro}
% \end{multicols*}
%
% \Finale
%
\endinput
+
+