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