diff options
author | Norbert Preining <preining@logic.at> | 2013-05-27 01:43:45 +0000 |
---|---|---|
committer | Norbert Preining <preining@logic.at> | 2013-05-27 01:43:45 +0000 |
commit | b651954f7ba70b34a0a9e73c374da6ed725fe796 (patch) | |
tree | 61627d91f36d156ca38f64fa20b3ac55352cd985 /Master/texmf-dist/source/latex/paracol/ref.dtx | |
parent | b2941aa318c54c9d2acb00a560f456d35d90f888 (diff) |
paracol update 5/27
git-svn-id: svn://tug.org/texlive/trunk@30705 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/paracol/ref.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/paracol/ref.dtx | 423 |
1 files changed, 379 insertions, 44 deletions
diff --git a/Master/texmf-dist/source/latex/paracol/ref.dtx b/Master/texmf-dist/source/latex/paracol/ref.dtx index 29cbda9a706..d5e29741d5a 100644 --- a/Master/texmf-dist/source/latex/paracol/ref.dtx +++ b/Master/texmf-dist/source/latex/paracol/ref.dtx @@ -1,3 +1,5 @@ +% \mergedfootnotes +% \columnratio{} % \section{Reference Manual} % \label{sec:ref} % \subsection{Environment \texttt{paracol}} @@ -11,18 +13,83 @@ % % \begin{itemize} % \item +% \changes{v1.2-2}{2013/05/11} +% {Add a footnote mentioning single-columned footnotes merged with +% pre-environment staff.} +% % The environment may start from \emph{any} vertical position in a page, -% i.e., not necessary at the top of a page. The single-column contents of -% the {\em\Uidx\spage} in which \beginparacol{} lies are naturally connected -% to the beginning part of \meta{body} in each column, unless the page has -% footnotes or bottom floats. If these kind of bottom stuff exist, they are -% put above the multi-columned \meta{body}, or the multi-column \meta{text} +% i.e., not necessary at the top of a page. The single-column +% {\em\Uidx\preenv} of the {\em\Uidx\spage} in which \beginparacol{} lies +% are naturally connected to the beginning part of \meta{body} in each +% column, unless the page has footnotes\footnote{ +% +% With merged footnotes setting shown in Section~\ref{sec:ref-scfnote}, the +% footnotes in the single-column contents are merged with those in +% \env{paracol} environment and are put at the bottom of the \spage{} +% together as shown in this page.} +% +% or bottom floats. If these kind of bottom stuff exist, they are +% put above the multi-columned \meta{body}, or the spanning \meta{text} +% +% \UsageIndex{spanning text} +% +% if provided, with a vertical skip of \!\textfloatsep! separating them if +% bottom floats exist. The \emph{deferred} floats which have not yet +% appeared in the starting page and thus will appear in the next or +% succeeding pages are considered as page-wise floats given in the +% environment. +% +% \item +% \changes{v1.2-5}{2013/05/11} +% {Add an item to show that \string\texttt{paracol} can be enclosed in +% a \string\texttt{list}-like environment.} +% +% The environment can be enclosed in a \env{list}{\em-like environment} such +% as \env{enumerate}, \env{itemize} and \env{description}. If so, \!\item!s +% in each column are typeset using the parameters of the surrounding +% environment such as \!\leftmargin! and \!\rightmargin!. For example, the +% following short \env{paracol} environment is included in an \env{itemize} +% for this and other \!\item!s in this page. +% +% \begin{paracol}{2} +% \item +% This is the first \!\item! in the left column. +% +% \item +% This is the second \!\item! in the left column followed by a +% \!\switchcolumn!\footnote{. % -% \UsageIndex{multi-column text} +% This footnote is to show the footnotes in this page are merged.}. +% \switchcolumn +% +% \item +% This is the first \!\item! in the right column. +% +% \item +% This is the second \!\item! in the right column. +% +% \item +% This is the third and last \!\item! in the right column. +% \end{paracol} +% You are now seeing the switching to/from multi-columned and \env{itemize}d +% texts are naturally connected with the last and this single-columned +% sentences. You may feel the space between two columns above is too large +% but it simply results from the large total \!\leftmargin!s of the outer +% \env{description} and this \env{itemize}, which make the right column +% shifted right. A simple remedy for this large space is to make +% \!\columnsep! narrower, for example 0\,pt as shown below. % -% if provided. The \emph{deferred} floats which have not yet appeared in -% the starting page and thus will appear in the next or succeeding pages are -% considered as multi-column floats given in the environment. +% \columnsep0pt +% \begin{paracol}{2} +% \item +% This \!\item! is wider than the last \!\item! above because +% \!\columnsep! is 0\,pt. +% \switchcolumn +% +% \item +% Therefore, this \!\item! is shifted left a little bit to make +% inter-column spece narrower. +% \end{paracol} % % \item % All \Uidx\lcounter{}s in all columns are initialized to have the values at @@ -34,19 +101,30 @@ % commonly have the value at \beginparacol. % % \item +% \changes{v1.2-2}{2013/05/11} +% {Add a footnote mentioning single-columned footnotes merged with +% post-environment staff.} +% % The environment may end at \emph{any} vertical position in a page, i.e., % the {\em\Uidx\postenv} being the single-column texts and others -% following \Endparacol{} may not start from the top of a page. If any -% columns don't have deferred single-column floats and the most advanced -% {\em\Uidx\lcolumn} at \Endparacol{} has neither of footnotes nor bottom -% floats, its bottom is naturally connected to the \postenv{}. If the -% \lcolumn{} has these kinds of bottom stuff, they are put above the +% following \Endparacol{} in the {\em\Uidx\lpage} of the environment may not +% start from the top of a page. If any columns don't have deferred +% column-wise floats and the most advanced {\em\Uidx\lcolumn} at +% \Endparacol{} has neither of footnotes\footnote{ +% +% With merged-footnote setting shown in Section~\ref{sec:ref-scfnote}, the +% footnotes in the closing \env{paracol} environment are merged with those +% in \postenv{} and are put at the bottom of the page{} together as shown in +% this page.} +% +% nor bottom floats, its bottom is naturally connected to the \postenv{}. +% If the \lcolumn{} has these kinds of bottom stuff, they are put above the % \postenv{}, with a vertical skip of \!\textfloatsep! separating them if -% bottom floats exist. All deferred single-column floats given in the +% bottom floats exist. All deferred column-wise floats given in the % environment are flushed before the \postenv{} appears, possibly creating % {\em\Uidx\fcolumn{}s} only with floats. On the other hand, deferred -% multi-column floats given in the environment are considered as deferred -% single-column floats given just after \Endparacol. +% page-wise floats given in the environment are considered as deferred +% (single-) column-wise floats given just after \Endparacol. % % \item % The values of all \lcounter{}s in the leftmost column are used as the @@ -84,17 +162,16 @@ % where $n$ is the number of columns given to \beginparacol, while % $j=\meta{col}$ with the optional argument. If the command (or % \oarg{col} if specified) is followed by a |*|, the \cswitch{} takes -% place after \sync{}ation and, if specified, the optional multi-column +% place after \sync{}ation and, if specified, the optional spanning % \meta{text} is put. % -% \Index{multi-column text} +% \Index{spanning text} % % \begin{itemize} % \item -% Using \!\switchcolumn! in a \env{list} and other relative environments -% such as \env{itemize} causes an ugly result without any error\slash -% warning messages. This caution is effectual for all \csenv{}s -% too. +% Using \!\switchcolumn! in a \env{list}-like environment \emph{included} in +% a \env{paracol} environment causes an ugly result without any error\slash +% warning messages. This caution is effectual for all \csenv{}s too. % % \item % If $\meta{col}\notin\LBRP0n$, an error is reported and, if you dare to @@ -106,7 +183,9 @@ % deferred floats are put in the pages up to $p-1$ and at the top of $p$ if % possible. Then, if a non-\lcolumn{} has footnotes and/or bottom floats % and they cannot be pushed down below the \sync{}ation point, the point is -% moved to the next page top. +% moved to the next page top\footnote{ +% +% Or below top floats deferred to the page.}. % % \item % In a page having one or more \sync{}ation points, stretch and shrink @@ -115,9 +194,9 @@ % the page is typeset as if \!\raggedbottom! were specified. % % \item -% After a sync{}ation point is set, top floats will not be put in the page +% After a \sync{}ation point is set, top floats will not be put in the page % having the point any more and thus will be deferred to the next or -% succeeding page. +% a succeeding page. % \end{itemize} % % @@ -127,9 +206,9 @@ % The environment \env{column} contains \meta{body} for the column next to % what we are in just before \!\begin!|{|\env{column}|}|. The starred % version \env{column*} does the same after \sync{}ation and, if specified, -% the optional multi-column \meta{text} is put. +% the optional spanning \meta{text} is put. % -% \Index{multi-column text} +% \Index{spanning text} % % \begin{itemize} % \item @@ -144,7 +223,7 @@ % if it is not preceded by \!\switchcolumn! nor other \csenv{}s. % % \item -% The \meta{body} of the environments cannot have \!\switchcolumn! nor other +% The \meta{body} of the environments cannot have \!\switchcolumn! nor % \csenv{}s including \env{column}(|*|) themselves, or you will have an % error message of illegal use of command\slash environment. % @@ -161,10 +240,9 @@ % \Item[\ENV{nthcolumn*}{\marg{col}\oarg{text}}]\mbox{}\par % The environment \env{nthcolumn} contains \meta{body} for the column % \meta{col}. The starred version \env{nthcolumn*} does the same after -% \sync{}ation and, if specified, the optional multi-column \meta{text} is -% put. +% \sync{}ation and, if specified, the optional spanning \meta{text} is put. % -% \Index{multi-column text} +% \Index{spanning text} % % \begin{itemize} % \item @@ -177,7 +255,7 @@ % \end{quote} % % \item -% The \meta{body} of the environments cannot have \!\switchcolumn! nor other +% The \meta{body} of the environments cannot have \!\switchcolumn! nor % \csenv{}s including \env{nthcolumn}(|*|) themselves, or you will have an % error message of illegal use of command\slash environment. % @@ -190,7 +268,6 @@ % % % -% \newpage % \item[\ENV{leftcolumn}{}]\mbox{} % \Item[\ENV{leftcolumn*}{\oarg{text}}]\mbox{} % \Item[\ENV{rightcolumn}{}]\mbox{} @@ -199,9 +276,9 @@ % column 0, while \env{rightcolumn} for the column 1 being the right column % in two-column typesetting. The starred versions \env{leftcolumn*} and % \env{rightcolumn*} do the same after \sync{}ation and, if specified, the -% optional multi-column \meta{text} is put. +% optional spanning \meta{text} is put. % -% \Index{multi-column text} +% \Index{spanning text} % % \begin{itemize} % \item @@ -223,18 +300,20 @@ % \end{description} % % -% \subsection{Command to Control Column Width} +% +% \subsection{Commands for Column Width, Position and Color} % \label{sec:ref-columnratio} -% \changes{v1.1}{2012/05/11} -% {Add description of \cs{columnratio}.} % % \begin{description} % \item[\Midx{\!\columnratio!}\Arg{$r_0,r_1,\cdots,r_k$}]\mbox{}\par +% \changes{v1.1}{2012/05/11} +% {Add description of \cs{columnratio}.} +% % The command defines the width of each column by the fraction $r_i$ to % specify the portion which $i$-th ($i=0$ for the leftmost) column % occupies. More specifically, the width $\Midx{\w}_i$ of the $i$-th column % is defined as follows, where $W$ is \!\textwidth!, $S$ is \!\columnsep!, -% and $n$ is the numnber of columns given to \beginparacol. +% and $n$ is the number of columns given to \beginparacol. % % \begin{eqnarray*} % W'&=&W-(n-1)S\\ @@ -273,8 +352,153 @@ % shown in Section~\ref{sec:man-close}. % % \item +% \changes{v1.2-5}{2013/05/11} +% {Modify the description about \cs{linewidth} reflecting the fact +% that \string\texttt{paracol} may be included in a +% \string\texttt{list}-like environment.} +% % In the $i$-th column, \!\columnwidth! has $w_i$ and, for outermost -% paragraphs in the column, \!\linewidth! and \!\hsize! have $w_i$ as well. +% paragraphs in the column, \!\hsize! has $w_i$ as well. As for +% \!\linewidth!, it has $w_i-(\!\textwidth!-l)$ where $l$ is what +% \!\linewidth! had at \beginparacol{}, i.e., the \!\linewidth! for the +% \env{list}-like environment surrounding \env{paracol} if any, or +% \!\textwidth! otherwise. +% \end{itemize} +% +% +% +% \item[\Midx{\!\swapcolumninevenpages!}]\mbox{} +% \Item[\Midx{\!\noswapcolumninevenpages!}]\mbox{}\par +% \changes{v1.2-4}{2013/05/11} +% {Add description of \cs{[no]swapcolumninevenpages}.} +% +% In a book with unbalanced parallel columns, sometimes it is preferable +% that, for example, wider columns are always \emph{inside} while narrower +% ones are \emph{outside}. This {\em\Uidx\cswap} to \emph{print} columns in +% even pages in reverse order is enabled by \!\swapcolumninevenpages!. The +% other command \!\noswapcolumninevenpages! disables this function to give +% the default setting. +% +% \begin{itemize} +% \item +% The \cswap{} affects not only columns but also marginal notes and, more +% subtlely, the column to which \mctext{}s is put. That is, with the natural +% ordering of column printing, column-0 accommodate \mctext{}s and its marginal +% notes go to left margin while those of other columns are placed at their +% right, but with reverse ordering the role of column-0 is delegated to +% column-$(n-1)$ in $n$-parallel-column typesetting. Since the printing +% position of each column is decided \emph{after} the page number for columns +% are fixed, columns are placed always correctly. As for marginal notes and +% \mctext{}s, however, we have to decide which column is the leftmost +% \emph{before} the page in which they reside is fixed. Therefore, the +% \textsf{paracol} can misunderstand the page parity to misplace +% these items. In particular, it is almost impossible to produce a good +% result when a \mctext{} crosses a page boundary to lie in two pages whose +% parities of course disagree. Therefore, you are requested to insert +% \!\newpage! before the such stuff if you have weird results. +% +% \item\label{pag:cswap} +% The commands have to be outside of \env{paracol} environments to decide +% the action in the environments following them. If they appear in a +% \env{paracol} environment, you will have a warning message saying they are +% ignored. +% +% \swapcolumninevenpages\columnratio{0.6}\columnsep0pt +% \begin{paracol}{2} +% \hfuzz2pt +% \item +% Here is an example of column swapping. Since this page +% \pageref{pag:cswap} is even, this wider column-0 with roman font is placed +% in right side and thus inside at the begining, but now we are in a odd +% page in which this column is in left side. +% +% \switchcolumn +% \item\it +% This narrower, outside and italicized column-1 is at first in left +% side but the page break has changed the position to the right. +% \end{paracol} +% \end{itemize} +% +% +% +% \item[\Midx{\!\columncolor!}\oarg{mode}\marg{color}\oarg{col}]\mbox{} +% \Item[\Midx{\!\normalcolumncolor!}\oarg{col}]\mbox{}\par +% \changes{v1.2-1}{2013/05/11} +% {Add description of \cs{columncolor} and \cs{normlcolumncolor}.} +% +% The command \!\columncolor! declares that the \emph{default color} of a +% column is +% \meta{color} or what it specifies by the combination with the optional +% \meta{mode}. The command \!\normalcolumncolor! declares the default color +% is what \!\normalcolor! specifies, i.e., black usually. The target column +% of these commands is that in which the commands reside, or \meta{col} if +% it specified. +% +% \begin{itemize} +% \item +% The command may be outside of \env{paracol} environment. If so and +% \meta{col} is not provided, the target column is the leftmost 0. +% +% \item +% The default color declaration is \emph{global}. Therefore, even if the +% command appears in a \env{paracol} environment (and even in some grouping +% structure in it), the declaration will be kept effective after +% \Endparacol{} to determine the default color of the specified column in +% succeeding \env{paracol} environments. +% +% \item +% To give a color to texts (and maybe other stuff) in a column correctly, +% you need to load \textsf{color} package or its relative (e.g., +% \textsf{xcolor}) which the implementation of coloring in \textsf{paracol} +% relies on. +% +% \item +% Coloring with \!\color!\oarg{mode}\marg{color} and other coloring commands +% in \env{paracol} environments is of course allowed. One caution is that +% the \!\color! decides the color for following texts until other +% specificatoin is given or the group surrounding the command is closed. +% Therefore, \!\switchcolumn! does not affect the coloring but a color given +% to the texts in a column is also applied to the texts in the column to be +% switched to. This irrelativeness of coloring and \cswitch{} is shown in +% the example below. +% +% \noswapcolumninevenpages\columnratio{0.5}\columnsep0pt +% \tolerance5000\hbadness5000 +% \begin{paracol}{2} +% \columncolor{blue} +% This column is colored blue because\\ +% \mbox{}\qquad \!\columncolor!|{blue}|\\ +% is specfied. Here we have a \!\switchcolumn!. +% \switchcolumn +% \columncolor{red} +% This column is colored red because\\ +% \mbox{}\qquad\!\columncolor!|{red}|\\ +% is specified. +% +% \begin{color}{green} +% Now the color of the right column is changed to green because\\ +% \mbox{}\qquad\!\begin!|{color}{green}|\\ +% is given prior to this paragraph. Now we have another \!\switchcolumn! to +% go back to the left. +% \switchcolumn +% The color of this paragraph is green because we are still in the +% environment of green coloring, which we are now closing.\par +% \end{color}% +% +% Since the coloring environment has been closed, the color of this +% paragraph is the default blue. Now we have yet another and the last +% \!\switchcolumn! to the right. +% \switchcolumn +% Since this paragraph is outside of the coloring environment, its color is +% the default red. +% \end{paracol} +% +% \normalcolumncolor[0]\normalcolumncolor[1] +% The default coloring of columns does not affect anything outside of +% \env{paracol} environment of course, and thus this sentence is not +% colored\footnote{ +% +% Or colred black as \cs{normalcolor} specifies.}. % \end{itemize} % \end{description} % @@ -307,6 +531,23 @@ % % Direct reference to \counter{page} may give an inconsisent result, as you % might have in ordinary \LaTeX{} documents.}. +% +% \item +% Globalizing a \meta{ctr} being already global is just ignored without any +% complaints. +% \end{itemize} +% +% +% +% \item[\Midx{\!\localcounter!}\marg{ctr}]\mbox{}\par +% The command declares that the counter \meta{ctr} is local for each column. +% +% \begin{itemize} +% \item +% Though this command is intended for localizing a \meta{ctr} which is once +% globalized, localizing a local counter does not causes any error but is +% just ignored. Localizing the permanently global \counter{page} is also +% just ignored without any complaints. % \end{itemize} % % @@ -330,6 +571,100 @@ % % % +% \subsection{Single-Columned Footnotes} +% \label{sec:ref-scfnote} +% \changes{v1.2-2}{2013/05/11} +% {Add the sub-section ``Single-Columned Footnotes'' to describe newly +% introducerd commands for single-columned footnotes.} +% +% \begin{description} +% \item[\Midx{\!\singlecolumnfootnotes!}]\mbox{} +% \Item[\Midx{\!\mergedfootnotes!}]\mbox{} +% \Item[\Midx{\!\multicolumnfootnotes!}]\mbox{}\par +% The command \!\singlecolumnfootnotes! makes footnotes in \env{paracol} +% environments {\em\Uidx\scfnote} so that footnotes in all columns are +% gathered to be typeset spanning all columns, i.e., single-columned, and are +% put at the bottom of the page in which they appear. The command +% \!\mergedfootnotes! also makes footnotes \scfnote{} and \emph{merges} +% +% \Uidx{\Index{merged footnote}} +% +% them with footnotes in outside of the environment but in the same page, +% i.e., those in \Preenv{} and \postenv{}, while with +% \!\singlecolumnfootnotes! \Preenv{} footnotes are put above multi-columns +% and those in the \lpage{} of the environment is put below multi-columns +% to separate single- and multi-column stuff. The command +% \!\multicolumnfootnotes! is to choose the default {\em\Uidx\mcfnote} +% footnote typesetting, i.e., footnotes in each column are put below the +% column itself and are separated from \Preenv{} and \Postenv{} footnotes. +% +% \begin{itemize} +% \item +% An example of \Mgfnote{} is found in p.~\pageref{sec:ref-paracol} while +% you will see many of them in Section~\ref{sec:fnnp}\footnote{ +% +% The left-column footnote \ref{fn:flush} in p.~\pageref{fn:flush} looks like +% a merged footnote because it is at the bottom of the page and the marked +% text is above the single-column text. However, it is an ordinary +% multi-columned one produced by a trick with \cs{footnotemark} and +% \cs{footnotetext} in different \env{paracol} environments.}. +% +% \item +% In any styles of footnote typesetting, a footnote cannot have page breaks +% in it, i.e., a footnote is always put in a page as a whole. This makes it +% impossible to have a footnote taller than \!\textheight! and thus you will +% see a warning message if you give a very long footnote which will be +% printed intruding into the area for page footer (or out of the paper bound). +% +% \item +% The commands \!\singlecolumnfootnotes! and \!\mergedfootnotes! make +% \counter{footnote} counter global and perform \!\fncounteradjustment! +% shown below inside them. The command \!\multicolumnfoot~notes! does +% the opperations oppositely, i.e., localizes \counter{footnote} and does +% \!\nofncounteradjustment!. Though these settings are usually appropriate +% for each footnote typesetting but you can override them by explictly using +% commands like \!\localcounter!|{footnote}|. +% \end{itemize} +% +% +% +% \item[\Midx{\!\footnote!}\texttt{*}\oarg{num}\marg{text}]\mbox{} +% \Item[\Midx{\!\footnotemark!}\texttt{*}\oarg{num}]\mbox{} +% \Item[\Midx{\!\footnotetext!}\texttt{*}\oarg{num}\marg{text}]\mbox{}\par +% The starred version of \!\footnote!, \!\footnotemark! and \!\footnotetext! +% are for the adjustment of the footnote numbering, the order of footnote +% marks in main texts, and the stacking order of footnotes at page +% bottom. Their usages with various examples are given in +% Section~\ref{sec:fnnp}. +% +% +% +% \item[\Midx{\!\fncounteradjustment!}]\mbox{} +% \Item[\Midx{\!\nofncounteradjustment!}]\mbox{}\par +% The maintenance of \counter{footnote} with the starred footnote commands +% such as \!\footnote!|*| shown above causes out-of-order progress of the +% counter to make it hard to have a consistent counter value at +% \Endparacol. The command \!\fncounteradjustment! is to let \Endparacol{} +% adjust the value of the counter based on its value at +% \beginparacol{} and the number of footnote commands in the environment. +% The command \!\nofncounteradjustment! is to tell \Endparacol{} to do +% nothing as in default. +% +% \begin{itemize} +% \item +% Though \!\singlecolumnfootnotes! and \!\mergedfootnotes! do +% \!\fncounteradjustment! and \!\multi~columnfootnotes! does +% \!\nofncounteradjustment! inside of them, you can override these settings +% by explicitly putting a counter adjustment command after a footnote +% typesetting command. +% +% \item +% The effect of \!\fncounteradjustment! is shown in Section~\ref{sec:fnnp}. +% \end{itemize} +% \end{description} +% +% +% % \subsection{Control of Contents Output} % \label{sec:ref-contents} % @@ -375,9 +710,9 @@ or the table should have % duplicated entries of sub-sections. % \item[\Midx{\!\clearpage!}]\mbox{}\par % The command does what \!\flushpage! does and then flushes all floats still % deferred if any. The deferred float flushing beyond the \tpage{} takes -% place at first for single-column ones creating \fcolumn{}s for them, and -% then for multi-column ones creating {\em\Uidx\fpage{}s} only with -% multi-column floats, as \LaTeX's \!\clearpage! does outside \env{paracol} +% place at first for column-wise ones creating \fcolumn{}s for them, and +% then for page-wise ones creating {\em\Uidx\fpage{}s} only with +% page-wise floats, as \LaTeX's \!\clearpage! does outside \env{paracol} % environment. % \end{description} \endinput |