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.dtx231
1 files changed, 194 insertions, 37 deletions
diff --git a/Master/texmf-dist/source/latex/tools/multicol.dtx b/Master/texmf-dist/source/latex/tools/multicol.dtx
index e0e293bb4f2..fd69fab4efb 100644
--- a/Master/texmf-dist/source/latex/tools/multicol.dtx
+++ b/Master/texmf-dist/source/latex/tools/multicol.dtx
@@ -1,9 +1,5 @@
% \iffalse meta-comment
%
-% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005
-% 2006 2008 2009
-% The LaTeX3 Project and any individual authors listed elsewhere
-% in this file.
%
% This file is part of the Standard LaTeX `Tools Bundle'.
% -------------------------------------------------------
@@ -24,7 +20,7 @@
% \iffalse This is a METACOMMENT
%
%% Package `multicol' to use with LaTeX2e
-%% Copyright 1989-2007 Frank Mittelbach
+%% Copyright 1989-2011 Frank Mittelbach
%%
%% In addition to the terms of LPPL any distributed version
%% (unchanged or modified) of multicol has to keep the statement
@@ -95,10 +91,10 @@
%<driver> \ProvidesFile{multicol.drv}
% \fi
% \ProvidesFile{multicol.dtx}
- [2008/12/05 v1.6h multicolumn formatting (FMi)]
+ [2011/06/27 v1.7a multicolumn formatting (FMi)]
%
%
-%% \CheckSum{1560}
+%% \CheckSum{1669}
%% \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
@@ -190,6 +186,18 @@
% the scope of the environment.
% \end{abstract}
%
+% \RLmulticolcolumns
+%
+% \begin{multicols}{3}[\section*{Preface to version 1.7}]
+% 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
+% paragraph demonstrates the result (as it is typeset as if we are writing
+% in a left-to-right language---so restart reading the rightmost column
+% first if you started with this column).
+% \end{multicols}
+%
+% \LRmulticolcolumns
%
% \begin{multicols}{3}[\section*{Preface to version 1.5 + 1.6}]
% \hbadness=10000
@@ -211,9 +219,9 @@
% \setcounter{collectmore}{2}
% \begin{multicols}{3}[\section{Introduction}]
% \hbadness=10000
-% Switching between two column and one column layout is possible in
+% Switching between two-column and one-column layout is possible in
% \LaTeX{}, but every use of |\twocolumn| or |\onecolumn|
-% starts a new page. Moreover, the last page of two column output
+% starts a new page. Moreover, the last page of two-column output
% isn't balanced and this often results in an empty, or nearly
% empty, right column. When I started to write macros for {\sf
% doc.sty} (see ``The {\tt doc}--Option'', \TUB\
@@ -224,11 +232,11 @@
% course that it is also possible to start the next article on the
% same page. Rewriting the index environment was comparatively easy,
% but the next goal, designing an environment which takes care of
-% footnotes, floats etc., was a harder task. It took me a whole
+% footnotes, floats, etc., was a harder task. It took me a whole
% weekend\footnote{I started with the algorithm given in the \TeX
% book on page 417. Without this help a weekend would not have been
% enough. (This remark was made in the documentation of the initial
-% release, since then several hundreds more hours went into it
+% release, since then several hundreds more hours went into
% improving the original code.)} to get together the few lines of
% code below and there is
% still a good chance that I missed something after all.
@@ -358,7 +366,7 @@
% step, balancing will be done when the end of the \mc{} environment
% is reached.
% In the first step \TeX{} might consider more material whilst
-% finding the final columns than it actually use when shipping out the
+% finding the final column content than it actually uses when shipping out the
% page. This might cause a problem if a footnote is encountered in
% the part of the input considered, but not used, on the current page.
% In this case the footnote might show up on the current page, while the
@@ -431,7 +439,7 @@
% acceptable solution at all and will then finally choose the extreme
% solution of placing all text into the first column.
%
-% Often, when colunms are balanced, it is impossible to find a solution
+% Often, when columns are balanced, it is impossible to find a solution
% that distributes the text evenly over all columns. If that is the case
% the last column usually has less text than the others. In the earlier
% releases this text was stretched to produce a column with the same
@@ -461,12 +469,12 @@
% \texttt{multicols*} instead of the usual environment the columns on
% the last page are not balanced. Of course, this environment only
% works on top-level, e.g., inside a box one has to balance to
-% determine a column height in absense of a fixed value.
+% determine a column height in absence of a fixed value.
%
%
% \subsection{Manually breaking columns}
%
-% Another request often voiced was: ``How to I tell \LaTeX{} that it
+% Another request often voiced was: ``How do I tell \LaTeX{} that it
% should break the first column after this particular line?''. The
% |\pagebreak| command (which works with the two-column option of
% \LaTeX{}) is of no use here since it would end the collection phase
@@ -474,7 +482,7 @@
% the |\columnbreak| command was added. If used within a paragraph it
% marks the end of the current line as the desired breakpoint. You can
% observe its effect on
-% the previous page where three lines of text have been artifically
+% the previous page where three lines of text have been artificially
% forced into the second column (resulting in some white
% space between paragraphs in the first column).
%
@@ -494,6 +502,15 @@
% |\topfraction|, etc.\ rather than by |\dbl...|.
%
%
+% \subsection{Support for right-to-left typesetting}
+%
+% In right-to-left typesetting the order of the columns on the page
+% also need to be reversed, i.e., the first column has to appear on the far
+% right and the last column on the left. This is supported through the
+% commands |\RLmulticolcolumns| (switching to right-to-left typesetting)
+% and |\LRmulticolcolumns| (switching to left-to-right typesetting) the
+% latter being the default.
+%
% \subsection{Warnings}
%
% Under certain circumstances the use of the \mc{} environment may
@@ -507,14 +524,14 @@
%
% 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 the badness values is below $10000$ the result is probably
+% as long as the badness value is below $10000$ the result is probably
% acceptable.
%
% \item[]
% {\hspace*{-\labelsep}\tt Underfull \string\vbox\space ... while
% \string\output\space is active}
%
-% If a column contains an character with an unusual depth, for
+% If a column contains a character with an unusual depth, for
% example a `(', in the bottom line then this message may show up. It
% usually has no significance as long as the value is not more than a
% few points.
@@ -524,9 +541,9 @@
%
% As mentioned above, \mc{} sometimes screws up the footnote
% numbering. As a precaution, whenever there is a footnote on a
-% page that where \mc{} had to leave a remainder for the following
+% page where \mc{} had to leave a remainder for the following
% page this warning appears. Check the footnote numbering on this
-% page. If it turns out that it is wrong you have to manually break
+% page. If it turns out that it is wrong, you have to manually break
% the page using |\newpage| or |\pagebreak[..]|.
%
% \item[] {\hspace*{-\labelsep}\tt Floats and marginpars not allowed
@@ -609,7 +626,7 @@
% revision.
%
% A note to people who like to improve the balancing algorithm of
-% \mc{}: The balancing routine in now placed into a single macro
+% \mc{}: The balancing routine is now placed into a single macro
% which is called |\balance@columns|. This means that one can easily
% try different balancing routines by rewriting this macro. The
% interface for it is explained in table \ref{tab:balance}. There are
@@ -636,7 +653,7 @@
% in register |\mult@firstbox|${}+2$, \ldots,
% only the last one as an exception in
% register |\mult@grightbox|. Furthermore it has to set up
-% two the macros
+% the two macros
% |\kept@firstmark| and |\kept@botmark| to hold the values for the
% first and bottom mark as found in the individual columns. There
% are some helper functions defined in section \ref{sec:v14} which
@@ -683,7 +700,7 @@
% running both in the old and the new \TeX{} (actually it will
% simply ignore the new feature if it is not available). The
% calculation of |\emergencystretch| is probably incorrect. I
-% made a few tests but of course one has have much more experience
+% made a few tests but of course one has to have much more experience
% with the new possibilities to achieve the maximum quality.
%
% Version 1.1a had a nice `feature': the penalty for using the
@@ -855,7 +872,7 @@
%
%^^A \subsection{Option processing}
%
-% Next we declare options supported by \mc{}. Twocolumn mode
+% Next we declare options supported by \mc{}. Two-column mode
% and \mc{} do not work together so we warn about possible
% problems. However, since you can revert to |\onecolumn|
% in which case \mc{} does work, we don't make this an error.
@@ -1893,6 +1910,11 @@
% |\full@width| (shifting it by |\multicol@leftmargin| to the right
% so that it will be placed correctly if we are within a list
% environment)
+% and separating the columns with a rule if desired.
+% \changes{v1.5a}{1992/11/04}{New box mechanism}
+% \changes{v1.5z}{2000/07/10}{Ensure that column rule has always
+% \cs{normalcolor}}
+% \changes{v1.6f}{2006/09/19}{Make the color of the rule a hook}
% \changes{v1.4l}{1992/08/17}{use \cs{multicol@leftmargin} instead of
% \cs{@totalleftmargin}}
%
@@ -1920,15 +1942,21 @@
% \changes{v1.6a}{2003/03/15}{Preparing for adjusting \cs{prevdepth}}
% \begin{macrocode}
\setbox\z@\hbox{p}\global\dimen\tw@\dp\z@
- \moveright\multicol@leftmargin
- \hbox to\full@width{%
% \end{macrocode}
-% and separating the columns with a rule if desired.
-% \changes{v1.5a}{1992/11/04}{New box mechanism}
-% \changes{v1.5z}{2000/07/10}{Ensure that column rule has always
-% \cs{normalcolor}}
-% \changes{v1.6f}{2006/09/19}{Make the color of the rule a hook}
+% 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
@@ -1967,9 +1995,9 @@
% \begin{macrocode}
\kern-\dimen\tw@
% \end{macrocode}
-% However, in case of of the columns was unusually deep \TeX{} may
+% However, in case one of the columns was unusually deep \TeX{} may
% have tried some corrective actions in which case backing up by
-% the ahve value will not bring us back to the baseline. A good
+% the saved value will not bring us back to the baseline. A good
% indication for this is a depth of |\maxdepth| though it is not an
% absolute proof. If the option \texttt{grid} is used
% |\mc@gridwarn| will expand to this, otherwise to |\maxdimen| in
@@ -2015,8 +2043,8 @@
% \begin{macro}{\multi@column@out}
% Now we can't postpone the difficulties any longer. The
% |\multi@column@out| routine will be called in two situations.
-% Either the page is full (i.e.\ we have collected enough material
-% to generate all the required columns) or a float or marginpar (or
+% Either the page is full (i.e., we have collected enough material
+% to generate all the required columns) or a float or marginpar or
% a |\clearpage| is
% sensed. In the latter case the |\outputpenalty| is less
% than $-10000$, otherwise the penalty which triggered the output
@@ -2140,13 +2168,13 @@
\hrule\allowbreak \fi
\fi
% \end{macrocode}
-% To get a correct marks for the current page we have to (locally
+% To get a correct marks for the current page we have to (locally)
% redefine |\firstmark| and |\botmark|.
% If |\kept@firstmark| is non-empty then |\kept@botmark| must be
% non-empty too so we can use their values. Otherwise we use the
% value of |\kept@topmark| which was first initialized when we
% gathered the |\partical@page| and later on was updated to the
-% |\botmark| for the preceding page
+% |\botmark| for the preceding page.
%
% \changes{v1.4a}{1992/02/14}{\cs{botmark} set to \cs{splitbotmark}}
% \begin{macrocode}
@@ -3482,6 +3510,135 @@
% \end{macrocode}
% \end{macro}
%
+%
+% \subsection{Supporting right-to-left languages} \label{sec:RL}
+%
+%
+% \changes{v1.7a}{2010/10/24}{RL language support added}
+%
+% \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{macrocode}
+\newcommand\RLmulticolcolumns
+ {\let\maybe@reverse@columns
+ \reverse@column@boxes}
+\newcommand\LRmulticolcolumns
+ {\let\maybe@reverse@columns\relax}
+% \end{macrocode}
+% The default is left-to-right:
+% \begin{macrocode}
+\LRmulticolcolumns
+% \end{macrocode}
+% \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.
+% \begin{macrocode}
+\newcount\multicol@sort@counter
+% \end{macrocode}
+% \end{macro}
+
+
+% \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{macrocode}
+\def\reverse@column@boxes {%
+ \ifnum\c@tracingmulticols>\thr@@
+ \typeout{reversing columns ...}
+ \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:
+% \begin{macrocode}
+%
+ \ifnum\c@tracingmulticols>\thr@@
+ \typeout{Setting last:
+ \the\mult@grightbox\space
+ <- \the\mult@rightbox}%
+ \fi
+ \setbox \mult@grightbox \box\mult@rightbox
+% \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@|.
+% \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
+% \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.
+% \begin{macrocode}
+}
+% \end{macrocode}
+% \end{macro}
+%
% \end{multicols*}
%
% \Finale