diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/tools/multicol.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/tools/multicol.dtx | 928 |
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 + + |