summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/paracol/ref.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-11-08 23:43:59 +0000
committerKarl Berry <karl@freefriends.org>2013-11-08 23:43:59 +0000
commit92f13c38adca9511a17969f8efde0f4d0e6e5f3a (patch)
treeb6a58333142feae9cdcaae185fd2ef7cfb439578 /Master/texmf-dist/source/latex/paracol/ref.dtx
parent77d66d8f7bc360ae2b37c1ea1c2cb53f7a201e57 (diff)
paracol (8nov13)
git-svn-id: svn://tug.org/texlive/trunk@32099 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.dtx1069
1 files changed, 898 insertions, 171 deletions
diff --git a/Master/texmf-dist/source/latex/paracol/ref.dtx b/Master/texmf-dist/source/latex/paracol/ref.dtx
index bf26658fb3f..98bd32a2abf 100644
--- a/Master/texmf-dist/source/latex/paracol/ref.dtx
+++ b/Master/texmf-dist/source/latex/paracol/ref.dtx
@@ -1,4 +1,4 @@
-% \mergedfootnotes
+% \footnotelayout{m}
% \columnratio{}
% \section{Reference Manual}
% \label{sec:ref}
@@ -14,7 +14,7 @@
% \begin{itemize}
% \item
% \changes{v1.2-2}{2013/05/11}
-% {Add a footnote mentioning single-columned footnotes merged with
+% {Add a footnote mentioning page-wise footnotes merged with
% pre-environment staff.}
% 
% The environment may start from \emph{any} vertical position in a page,
@@ -23,12 +23,12 @@
% 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
+% With \Mgfnote{} layout 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
+% or bottom floats. If these kinds of bottom stuff exist, they are
% put above the multi-columned \meta{body}, or the spanning \meta{text}
% 
% \UsageIndex{spanning text}
@@ -93,16 +93,16 @@
%
% \item
% All \Uidx\lcounter{}s in all columns are initialized to have the values at
-% \beginparacol{} on its first occurence. On the second and succeeding
-% occurences of \beginparacol, the \lcounter{}s in each column have the
+% \beginparacol{} on its first occurrence. On the second and succeeding
+% occurrences of \beginparacol, the \lcounter{}s in each column have the
% value at the last \Endparacol, unless they are modified after the
% \Endparacol. If a counter is modified (or declared by \!\newcounter!)
-% after the \Endparacol, the local versions of the counter in all column
+% after the \Endparacol, the local versions of the counter in all columns
% commonly have the value at \beginparacol.
%
% \item
% \changes{v1.2-2}{2013/05/11}
-% {Add a footnote mentioning single-columned footnotes merged with
+% {Add a footnote mentioning page-wise footnotes merged with
% post-environment staff.}
% 
% The environment may end at \emph{any} vertical position in a page, i.e.,
@@ -112,7 +112,7 @@
% 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
+% With \Mgfnote{} layout 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.}
@@ -146,6 +146,56 @@
% The command \!\clearpage! is of course usable outside and inside the
% environment but its function inside is a little bit different from outside.
% \end{itemize}
+%
+%
+%
+% \item[\ENV{paracol}{\oarg{numleft}\marg{num}\oarg{text}}]\mbox{}
+% \Item[\ENV{paracol}{\oarg{numleft}\texttt{*}\marg{num}\oarg{text}}]
+% \mbox{}\par
+% \changes{v1.3-2}{2013/09/17}
+% {Add description of parallel-paging.}
+% 
+% If a \beginparacol{} has the optional \meta{numleft} argument to specify
+% the number of leading columns $n_l$ together with the total $n$ given by
+% \meta{num}, columns in the environment are laid out across two adjacent
+% pages. In this {\em\Uidx\parapag{}e} typesetting, the first $n_l$ columns
+% are placed in the {\em left} page while remaining $n_r=n-n_l$ columns go to
+% the next {\em right} page. The pair of left and right pages is
+% considered as comprising a virtual {\em\Uidx\paired} page and thus shares
+% a common page number, unless {\em\Uidx\npaired} typesetting is specified
+% by the optional `|*|' following the optional \meta{numleft} argument. In
+% the \npaired{} \parapag{}ing, when the leading $n_l$ columns are put in a
+% page $p$, the trailing $n_r$ columns are in the page $p+1$.
+% 
+% \begin{itemize}
+% \item
+% All {\em\Uidx\pwstuff}, i.e., \Preenv{} and \postenv, page-wise floats,
+% \mctext{} and (\mgfnote{} or non-merged) \Scfnote{}s, are placed only in
+% left \parapag{}es leaving corresponding regions in right \parapag{}es
+% blank\footnote{
+% 
+% Someday the author could devise an advanced mechanism to exploit the space
+% in right \parapag{}es.}.
+%
+% \item
+% A \npaired{} left \parapag{}e is not necessary to be even-numbered, though
+% the printing tradition requires so if you naturally want to have a
+% \parapag{}e pair in a double spread. The page number given to the first
+% left \parapag{}e is simply the number of the page $p_1$ in which
+% \beginparacol{} reside, and that for the $k$-th left \parapag{}e is
+% $p_1+2(k-1)$\footnote{
+% 
+% Unless you make some change to \counter{page} counter.}.
+% 
+% Therefore, to make it sure $p_1$ is even, you might need to have an
+% ordinary page of blank, a title, etc., or to let \counter{page} counter have
+% an even number by \!\setcounter!, etc., before starting a \env{paracol}
+% environment.
+%
+% \item
+% Section~\ref{sec:ppts} shows examples of \parapag{}ing together with
+% related issues on two-sided typesetting.
+% \end{itemize}
% \end{description}
%
%
@@ -216,9 +266,9 @@
% |{|\!\switchcolumn!\quad\meta{body}\quad\CSIndex{par}|}|\\
% |{|\!\switchcolumn!|*|\oarg{text}\quad\meta{body}\quad\CSIndex{par}|}|
% \end{quote}
-% except for their first occurences which don't switch to the column 1
+% except for their first occurrences which don't switch to the column 1
% (i.e., right column if two-columned) but stay in the leftmost column 0.
-% More precicesly, \!\begin!|{|\env{column}(|*|)|}| does not make \cswitch{}
+% More precisely, \!\begin!|{|\env{column}(|*|)|}| does not make \cswitch{}
% if it is not preceded by \!\switchcolumn! nor other \csenv{}s.
%
% \item
@@ -230,7 +280,7 @@
% Column-switching\index{column-switching} does not take place at
% \!\end!|{|\env{column}(|*|)|}|. Therefore, texts following the
% environments are put in the column in which \meta{body} resides until a
-% \cswitch{} commnad\slash environment is given.
+% \cswitch{} command\slash environment is given.
% \end{itemize}
%
%
@@ -262,11 +312,12 @@
% Column-switching\index{column-switching} does not take place at
% \!\end!|{|\env{nthcolumn}(|*|)|}|. Therefore, texts following the
% environments are put in the column in which \meta{body} resides until a
-% \cswitch{} commnad\slash environment is given.
+% \cswitch{} command\slash environment is given.
% \end{itemize}
%
%
%
+% \KeepSpace{4}
% \item[\ENV{leftcolumn}{}]\mbox{}
% \Item[\ENV{leftcolumn*}{\oarg{text}}]\mbox{}
% \Item[\ENV{rightcolumn}{}]\mbox{}
@@ -296,17 +347,125 @@
% \end{quote}
% 
% \end{itemize}
+%
+%
+%
+% \item[\Midx{\!\thecolumn!}]\mbox{}\par
+% \changes{v1.3-5}{2013/09/17}
+% {Add description of \cs{thecolumn}.}
+% The command gives you the zero-origin ordinal of the column in which this
+% command appears. Therefore, the following code snip;
+% 
+% \begin{itemize}\item[]
+% |\begin{paracol}{3}|\\
+% |Column-\thecolumn.\switchcolumn|
+% |Column-\thecolumn.\switchcolumn|
+% |Column-\thecolumn.|\\
+% |\end{paracol}|
+% \end{itemize}
+% 
+% gives us the followings.
+% 
+% \par\medskip
+% \begin{paracol}{3}
+% Column-\thecolumn.\switchcolumn
+% Column-\thecolumn.\switchcolumn
+% Column-\thecolumn.
+% \end{paracol}
+% 
+% \begin{itemize}
+% \item
+% The command is {\em neither} a \LaTeX's counter nor \!\count! register of
+% native \TeX{}, and thus the value it keeps cannot be modified. However,
+% it can be used wherever an integer number is required or appropriate.
+% Therefore for example, \!\setcounter!|{mycounter}{|\!\thecolumn!|}| works
+% well to give the column ordinal to the counter |mycounter|.
+% \end{itemize}
+%
+%
+%
+% \item[\Midx{\!\ensurevspace!}\marg{len}]\mbox{}\par
+% \changes{v1.3-5}{2013/09/17}
+% {Add description of \cs{ensurevspace}.}
+% 
+% The command tells the first \sync{}ing \cswitch{} command (i.e.,
+% \!\switchcolumn!\oarg{col}|*|) or environment (i.e., \env{column*}, etc.\@)
+% following this command that the page must be broken before \sync{}ation
+% unless the \sync{}ation point has the space of \meta{len} or more below it
+% in the page. If a \sync{}ation does not have the command after the
+% previous \sync{}ation, it is assumed that
+% \!\ensurevspace!|{|\!\baselineskip!|}| is given.
+% 
+% \begin{itemize}
+% \item
+% This command is to be used when a \sync{}ation point would be placed near
+% the bottom of a page $p$ and the space below it is not sufficient for a column
+% $c$ to put anything in the page, while another column $c'$ can have a few
+% lines in the page. If this happens, the first line after the \sync{}ation
+% should start at the top of the page $p+1$ in the column $c$, while that of
+% $c'$ is still in the page $p$, giving you an impression that the
+% \sync{}ation fails to align the top of all columns below it. The fact is,
+% however, the \sync{}ation point is properly established near at the bottom
+% of the page but the first line of $c$ needs some large space due to, for
+% example, the followings.
+% 
+% \begin{itemize}
+% \item
+% The line has unusually tall stuff including larger font letters.
+%
+% \item
+% The line has a footnote reference which is hardly apart from the
+% footnote, and thus the line and the footnote go to the next page together.
+%
+% \item
+% The parameter \!\clubpenalty! is too large (e.g., 10000) to break the
+% first and second lines into separate pages.
+%
+% \item
+% The first line follows a vertical space.
+% \end{itemize}
+%
+% \item
+% This manual itself has some instances of \!\ensurevspace! command in the
+% page \pageref{page:bfreude} and \pageref{page:efreude} in which each German
+% stanza is enclosed in \env{verse} and then \env{leftcolumn*} environments
+% and has \!\ensurevspace!|{2|\!\baselineskip!|}| before the \!\begin!ing of
+% the outer \env{leftcolumn*} because the first line of the stanza is
+% preceded by a vertical space inserted by \!\begin!|{|\env{verse}|}|. In
+% fact without \!\ensurevspace!, the first two lines of the sixth English
+% stanza would be in the page \pageref{page:bfreude}, while corresponding
+% German stanza go to the next page \pageref{page:efreude} as a whole, due
+% to the difference of the height of footnotes in each column, i.e., German
+% ones are taller than English ones to narrow the space for the German
+% column.
+%
+% \item
+% As the author does in the ``An die Freude/To Joy'' example, it is a good
+% tactics to have an \!\ensurevspace! with some vertical space larger than the
+% default \!\baselineskip! if it is sure that a column has a feature shown
+% above regardless of the position of the \sync{}ation point in question,
+% because the point goes up or down with revisions of your document and
+% using an \!\ensurevspace! for a \sync{}ation far above the page bottom is
+% perfectly harmless. Similarly, if you find a problem in a \sync{}ation
+% and add an \!\ensurevspace! to solve it, keeping the command attached is
+% recommended even when the \sync{}ation point moves up or down to make the
+% command unnecessary.
+% \end{itemize}
% \end{description}
%
%
%
-% \subsection{Commands for Column Width, Position and Color}
-% \label{sec:ref-columnratio}
+% \subsection{Commands for Column and Gap Width}
+% \label{sec:ref-colwidth}
%
% \begin{description}
-% \item[\Midx{\!\columnratio!}\Arg{$r_0,r_1,\cdots,r_k$}]\mbox{}\par
+% \item[\Midx{\!\columnratio!}\Arg{$r_0,r_1,\cdots,r_k$}
+% {|[|$r'_0,r'_1,\cdots,r'_{k'}$|]|}]\mbox{}\par
% \changes{v1.1}{2012/05/11}
% {Add description of \cs{columnratio}.}
+% \changes{v1.3-2}{2013/09/17}
+% {Add descriptino of the optional argument of \cs{columnratio} for
+% parallel-paging.}
% 
% 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
@@ -322,12 +481,19 @@
% \displaystyle{(1-\sum_{j=0}^k r_j)W'\over n-(k+1)}&$i>k$}
% \end{eqnarray*}
% 
+% For a \env{paracol} environment with \parapag{}ing, $n$ is replaced with
+% $n_l$ for the columns in left \parapag{}es, while $n$ and $w_i$ are
+% replaced with $n_r$ and $w_{n_r+i}$ for those in right \parapag{}es.
+% Moreover, if the optional argument having $r'_0,r'_1,\cdots,r'_{k'}$ is
+% provided, $w_{n_r+i}$ for a column in right \parapag{}es is determined
+% by $r'_i$ and $k'$ instead of $r_i$ and $k$.
+% 
% \begin{itemize}
% \item
% The equations above imply that $k<n-1$, $r_i>0$ and $\sum_{j=0}^k
% r_j<1$. If $k\geq n-1$, $k$ is assumed to be $n-2$ and all $r_i$ such
% that $i\geq n-1$ are ignored. If $r_i$ or its sum does not satisfy the
-% conditions, you will have an ugly result with ``Overful'' messages.
+% conditions, you will have an ugly result with ``Overfull'' messages.
%
% \item
% The argument $r_0,r_1,\cdots,r_k$ can be empty to mean $k=-1$ to let all
@@ -362,142 +528,301 @@
% \!\linewidth! had at \beginparacol{}, i.e., the \!\linewidth! for the
% \env{list}-like environment surrounding \env{paracol} if any, or
% \!\textwidth! otherwise.
+%
+% \item
+% You can specify width of each column and that of each {\em gap} between
+% two columns more detailedly by \!\setcolumnwidth! shown below. If your
+% document has both of \!\columnratio! and \!\setcolumnwidth! prior to a
+% \env{paracol} environment, the command given later is effective for the
+% environment.
% \end{itemize}
%
%
%
-% \item[\Midx{\!\swapcolumninevenpages!}]\mbox{}
-% \Item[\Midx{\!\noswapcolumninevenpages!}]\mbox{}\par
-% \changes{v1.2-4}{2013/05/11}
-% {Add description of \cs{[no]swapcolumninevenpages}.}
+% \item[\Midx{\!\setcolumnwidth!}\Arg{$s_0,s_1,\cdots,s_k$}
+% {|[|$s'_0,s'_1,\cdots,s'_{k'}$|]|}]\mbox{}\par
+% \changes{v1.3-2}{2013/09/17}
+% {Add descriptino of \cs{setcolumnwidth}.}
+% 
+% The command defines the width of each column and that of each {\em gap}
+% between two columns by the column/gap specification $s_i$ for the $i$-th
+% column and the gap between it and the $(i{+}1)$-th column. More
+% specifically, $s_i$ has the form of $\hat w_i$ or $\hat w_i\,|/|\,\hat g_i$
+% where each of $\hat w_i$ and $\hat g_i$ is a proper glue including a
+% proper dimension, or an empty string to mean $\hat w_i=\!\fill!$ and $\hat
+% g_i=\!\columnsep!$, to determine the width of $i$-th column $\w_i$ and that
+% of $i$-th gap $\Midx{\gap}_i$ as follows, where $\mathit{nat}(x)$ is the
+% natural width of the glue $x$, $\mathit{str}(x)$ is the infinite stretch
+% factor of $x$, $W$ is \!\textwidth!, and $n$ is the number of columns
+% given to \beginparacol.
+% 
+% \begin{eqnarray*}
+% W'&=&\sum_{i=0}^{n-2}\big(\mathit{nat}(\hat w_i)+\mathit{nat}(\hat g_i)\big)+
+% \mathit{nat}(\hat w_{n-1})\\
+% F&=&\sum_{i=0}^{n-2}\big(\mathit{str}(\hat g_i)+\mathit{str}(\hat g_i)\big)+
+% \mathit{str}(\hat w_{n-1})\\
+% x_i&=&\cases{(W/W')\mathit{nat}(\hat x_i)&$W'\geq W\;\lor\;F\leq0$\cr
+% \mathit{nat}(\hat x_i)+(\mathit{str}(\hat x_i)/F)(W-W')&
+% $W'< W\;\land\;F>0$}
+% \qquad(x\in\{w,g\})
+% \end{eqnarray*}
+% That is, if the total of natural widths $W'$ is larger than \!\textwidth!
+% $W$ or there are no infinite stretch factors in the specification, given
+% widths are scaled down or up so that the scaled total is equal to $W$.
+% Otherwise, each width with an infinite stretch factor is extended
+% according to its ratio in the total stretch so that the stretched total is
+% equal to $W$.
+%
+% For a \env{paracol} environment with \parapag{}ing, $n$ is replaced with
+% $n_l$ for the columns in left \parapag{}es, while $n$, $w_i$ and $g_i$ are
+% replaced with $n_r$, $w_{n_r+i}$ and $g_{n_r+i}$ for those in right
+% \parapag{}es. Moreover, if the optional argument having
+% $s'_0,s'_1,\cdots,s'_{k'}$ is provided, $w_{n_r+i}$ and $g_{n_r+i}$ for a
+% column in right \parapag{}es are determined by $s'_i$ instead of $s_i$.
+% 
+% \begin{itemize}
+% \item
+% In \env{paracol} environments having $n$ columns, $s_i$ s.t.\ $i\geq n$
+% and $\hat g_{n-1}$ are ignored. On the other hand if $k<n-1$, it is
+% assumed $s_i$ is an empty string for all $i>k$.
+%
+% \item
+% Finite stretch factors and finite or infinite shrink factors in $\hat w_i$
+% and $\hat g_i$ are ignored.
+%
+% \item
+% Unlike \TeX's genuine glue addition, all infinite unit |fil|, |fill| and
+% |filll| are not distinguished in the summation for $F$. Also unlike
+% \TeX's genuine scaling of a glue primitive,
+% $f\!\fill!$ means $0\,|pt|\ |plus|\ f\,|fill|$ for convenience\footnote{
+% 
+% In \TeX's grammar, $f\!\fill!$ means a dimension rather than a glue and is
+% $0\,|pt|$ because the natural component of \!\fill! is 0.}.
+%
+% \item
+% The division $W/W'$ and $\mathit{str}(\hat x_i)/F$ can have some
+% arithmetic errors and thus the total of $w_i$ and $g_i$ may not be equal to
+% $W$ exactly but can be a little bit less than $W$. This small error is,
+% however, equally distributed to $g_i$ in typesetting of a page to make the
+% total width of columns and gaps is exactly $W$\footnote{
% 
-% 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.
+% If we may ignore the arithmetic error inherent in \TeX.}.
+%
+% \item
+% All the specifications shown in the table below give us same results for a
+% \env{paracol} environment having three columns, providing
+% $\!\textwidth!=360\,|pt|$ and $\!\columnsep!=S=20\,|pt|$.
+% 
+% \par\hbox to\textwidth\bgroup\hfil
+% \nosv \def\|{\verb|}\small\arraycolsep0pt\def\arraystretch{1.1}
+% $\begin{array}[b]{l|ccccc}
+% s_0,s_1,s_2&w_0&g_0&w_1&g_1&w_2\rlap{ (in \texttt{pt})}\\\hline
+% \|50pt/20pt,100pt/40pt,150pt|&50&20&100&40&150\\
+% \|50pt,100pt/2\columnsep,150pt|&50&S&
+% 100&2S&150\\
+% \|50pt/\fill,100pt/2\fill,150pt|&50&(1/3)\cdot60&100&(2/3)\cdot60&150\\
+% \|,2\fill/2\columnsep,3\fill|&\ (1/6)\cdot300&S&
+% (2/6)\cdot300&2S&
+% (3/6)\cdot300\\
+% \|50pt/20,50pt plus 1fil/40pt,50pt plus 2fil |&
+% 50&20&50+(1/3)\cdot150&40&
+% 50+(2/3)\cdot150\\
+% \|5pt/2pt,10pt/4pt,15pt|&10\cdot5&10\cdot2&10\cdot10&10\cdot4&
+% 10\cdot15\\
+% \|100pt/40pt,200pt/80pt,300pt|&0.5\cdot100&0.5\cdot40&
+% 0.5\cdot200&0.5\cdot80&
+% 0.5\cdot300
+% \end{array}$\hfil\egroup
+%
+% \item
+% If your document has both of \!\columnratio! and \!\setcolumnwidth! prior
+% to a \env{paracol} environment, the command given later is effective for
+% the environment.
+% \end{itemize}
+% \end{description}
+%
+%
+%
+% \subsection{Commands for Two-Sided Typesetting and Marginal Note Placement}
+% \label{sec:ref-twoside}
+% \changes{v1.3-3}{2013/09/17}
+% {Add the sub-section ``Commands for Two-Sided Typesetting and Marginal
+% Note Placement''.}
+% \changes{v1.3-4}{2013/09/17}
+% {Add the sub-section ``Commands for Two-Sided Typesetting and Marginal
+% Note Placement''.}
+% \changes{v1.3-5}{2013/09/17}
+% {Add the sub-section ``Commands for Two-Sided Typesetting and Marginal
+% Note Placement''.}
+%
+% \begin{description}
+% \item[\Midx{\!\twosided!}{$|[|t_1t_2\cdots t_k|]|$}]\mbox{}\par
+% \changes{v1.3-3}{2013/09/17}
+% {Add description of \cs{twosided}.}
+% \changes{v1.3-4}{2013/09/17}
+% {Add description of \cs{twosided}.}
+% \changes{v1.3-5}{2013/09/17}
+% {Add description of \cs{twosided}.}
+% 
+% The command enables a set of two-sided typesetting features
+% $\Set{t_i}{t_i\in\{|p|,|c|,|m|,|b|\},\ 1\leq i\leq k}$ explicitly by the
+% optional argument, or all of the following four features as a whole
+% without the argument, in even-numbered pages.
+% 
+% \begin{description}
+% \item[|p|\rm(\textit{age})]
+% for ordinary two-sided paging, letting the left side margin be
+% \!\evensidemargin!, page headers be different from those in odd-numbered
+% pages with |headings| or |myheadings| page style, and \!\cleardoublepage!
+% leave an even-numbered page blank if it is used in an odd-numbered page.
+%
+% \item[|c|\rm(\textit{olumn})]
+% for {\em\Uidx\cswap} to \emph{print} columns in even-numbered pages in
+% reverse order. This feature is sometimes preferable in typesetting
+% especially with unbalanced parallel columns to make, for example, a wider
+% columns are always \emph{inside} while narrower ones are \emph{outside}.
+%
+% \item[|m|\rm(\textit{arginal text})]
+% to place marginal notes in the side margin opposite to that specified by
+% the command \!\marginparthreshold! discussed shortly.
+%
+% \item[|b|\rm(\textit{ackground painting})]
+% to make \bgpaint, shown in Section~\ref{sec:ref-bgpaint},
+% \emph{\mirror{}ed} so that, for example, a color specified for the left
+% margin is used to paint the right margin instead.
+% \end{description}
% 
% \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
+% The feature |p| is also enabled by the |twoside| option of
+% \!\documentclass! with almost all classes including |article|, |book|,
+% |report|, etc. Though it is strongly recommended to make both settings by
+% \!\documentclass! and this command consistent, they can be inconsistent
+% resulting in lack of some expected functions. For example, enabling |p|
+% feature by \!\twosided! without |twoside| option in \!\documentclass!
+% makes the format of headers and footers in all pages same even with
+% \!\pagestyle!|{headings}|.
+%
+% \item
+% The \cswap{} enabled by the feature |c| is ineffective in \npaired{}
+% \parapag{}ing because it is meaningless\footnote{
+% 
+% Unless somebody tells the author it is meaningful.},
+% 
+% and thus silently ignored.
+%
+% \item
+% In ordinary single-column typesetting, marginal note swapping in
+% even-numbered pages is enabled by the |twoside| option, while it never takes
+% place in ordinary two-column typesetting. For marginal notes given in
+% \env{paracol} environments, however, swapping of them in
+% even-numbered pages is enabled by giving the feature |m| to \!\twosided!.
+%
+% \item\label{page:cswap}
+% The command has to be outside of \env{paracol} environments to decide the
+% action in the environments following them. If it appears in a
+% \env{paracol} environment, you will have a warning message saying it is
% ignored.
%
-% \swapcolumninevenpages\columnratio{0.6}\columnsep0pt
+% \twosided[c]\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.
+% \pageref{page:cswap} is odd, this wider column-0 with roman font is placed
+% in left side and thus inside at the begining, but now we are in an even
+% page in which this column is in right 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.
+% This narrower, outside and italicized column-1 is at first in right
+% side but the page break has changed the position to the left.
% \end{paracol}
+%
+% \item
+% \changes{v1.2-4}{2013/05/11}
+% {Add description of \cs{[no]swapcolumninevenpages}.}
+% \changes{v1.3-5}{2013/09/17}
+% {Remove description of \cs{[no]swapcolumninevenpages} but mention
+% they are still available.}
+% 
+% In old versions of \Paracol, namely 1.2 and its minor revisions 1.2x,
+% \cswap{} was controlled by lengthy commmands
+% \Midx{\!\swapcolumninevenpages!} and \Midx{\!\noswapcolumninevenpages!}.
+% Though they are still available and will be so forever for backward
+% compatibility, it is recommended to use \!\twosided! with or without the
+% feature |c|. The old versions also have a problem that \spanning{}
+% crossing a page boundary is placed incorrectly after the page break in it,
+% but this problem is solved by a fix incorporated in version 1.3.
+%
+% \item
+% It must be $t_i\in\{|p|,|c|,|m|,|b|\}$, or you will have an error message
+% of illegal two-siding feature.
+%
+% \item
+% Section~\ref{sec:ppts} shows examples of two-sided typesetting together
+% with related issues on \parapag{}ing.
% \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}.}
+% \item[\Midx{\!\marginparthreshold!}$\Arg{k}{|[|k'|]|}$]\mbox{}\par
+% \changes{v1.3-4}{2013/09/17}
+% {Add description of \cs{marginparthreshold}.}
% 
-% 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.
+% The command specifies the minimum ordinal $k$ of columns whose marginal
+% notes are placed in right margin. That is, marginal notes given in a
+% column-$i$ go to left margin if $i<k$, while they go to right if $i\geq
+% k$. The optional argument $k'$, if given, is for columns in right
+% \parapag{}es to decide the margin where their marginal notes are placed.
+% In default, $k=1$ is assumed to let marginal notes from the leftmost
+% column-0 go to left margin while those from other columns go to right.
% 
% \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.
+% You may specify $k=0$ to let all marginal notes go to right margin, or may
+% give the command a large number, say 100, to place all of them in left
+% margin.
%
% \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.
+% The setting $k=0$ or $k=100$ above makes a side margin \emph{shared} by
+% marginal notes from different columns, and sharing is inevitable when a
+% (parallel-) page has three or more columns. When a margin is shared by
+% marginal notes from two or more columns, it can happen that two marginal
+% notes from different columns conflict over the space to be occupied by each
+% of them. This conflict is solved by \Paracol{} to push down the note
+% given later in your source |.tex| until an available space for it is
+% found. Note that the marginal note to be pushed down is determined by the
+% position in the source rather than that in the printed result. Also note
+% that \Paracol{} exploits space between two marginal notes having been
+% already placed in the placement of other note coming later to place it at
+% the natural position if possible or to minimize the amount of pushing down
+% otherwise.
%
% \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.
+% In the decision of the real margin in which a marginal note is placed,
+% other two factors are involved; |m| feature of \!\twosided! command and
+% the parity of the page; and \LaTeX's genuine command \!\reversemarginpar!.
+% More specifically, after the first preliminary decision is made according
+% to the threshold given to \!\marginparthreshold!, we have the following
+% two steps to modify the decision; if |m| feature has been specified in
+% \!\twosided! command and the marginal note belongs to an even-numbered
+% page, the decision is reversed to have the second preliminary result; and
+% then if \!\reversemarginpar! has been specified, the second result is
+% reversed (again) to have the final result.
%
% \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
-% specification 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}
+% In old versions of \Paracol, namely older than 1.3, marginal note
+% placement was not only uncontrollable but also gave ugly results when your
+% document has three or more columns because the marginal notes from a column
+% not being leftmost or rightmost were placed in the gap following the
+% column rather than a margin. This miserable {\em gap note} placement does
+% not happen any more, or in other words this is no more available because
+% the author believes nobody loves it.
%
-% \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 colored black as \cs{normalcolor} specifies.}.
+% \item
+% Section~\ref{sec:ppts} shows examples of marginal note placement together
+% with related issues on \parapag{}ing and two-sided typesetting.
% \end{itemize}
% \end{description}
%
@@ -528,7 +853,7 @@
% \counter{page} having $q$ (or its successor) is referred to by \!\pageref!
% or through \emph{contents} files such as |.toc|\footnote{
% 
-% Direct reference to \counter{page} may give an inconsisent result, as you
+% Direct reference to \counter{page} may give an inconsistent result, as you
% might have in ordinary \LaTeX{} documents.}.
%
% \item
@@ -570,32 +895,37 @@
%
%
%
-% \subsection{Single-Columned Footnotes}
+% \subsection{Page-Wise 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.}
+% introducerd commands for page-wise footnotes.}
+% \changes{v1.3-5}{2013/09/17}
+% {Rename the sub-section title from ``Single-Columned Footnotes'' to
+% ``Page-Wise Footnotes'' following new naming.}
%
% \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.
+% \item[\Midx{\!\footnotelayout!}\marg{layout}]\mbox{}\par
+% The command specifies the \meta{layout}${}\in\{|c|,|p|,|m|\}$ of footnotes
+% in \env{paracol} environments as follows.
+% 
+% \begin{description}
+% \item[|c|\rm(\textit{olumn})] makes footnotes {\em\Uidx\mcfnote} (aka
+% multi-columned) being default to place footnotes in each column at the
+% bottom of the column and separating them from \Preenv{} and \Postenv{}
+% footnotes.
+%
+% \item[|p|\rm(\textit{age})] makes footnotes {\em\Uidx\scfnote} (aka
+% single-columned) so that footnotes in all columns are gathered, typeset
+% spanning all columns, and placed at the bottom of the page in which they
+% appear or at the end of the \env{paracol} environment they belong to, so
+% that they are separated from \Preenv{} and \Postenv{} footnotes.
+%
+% \item[|m|\rm(\textit{erge})] makes \Scfnote{}s {\em\Uidx\mgfnote} with
+% footnotes in outside of the environment but in the same page, i.e., those
+% in \Preenv{} and \postenv.
+% \end{description}
+%
% 
% \begin{itemize}
% \item
@@ -605,28 +935,56 @@
% 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
+% \mcfnote{} 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).
+% In any layouts, 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
+% Choosing the layout |p|age-wise or |m|erged makes \counter{footnote}
+% counter global and \!\fncounteradjustment! shown below performed inside
+% \!\footnotelayout!. Choosing |c|olumn-wise let the command do the
+% operations 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
+% for each footnote layout but you can override them by explicitly using
% commands like \!\localcounter!|{footnote}|.
+%
+% \item
+% The command has to be outside of \env{paracol} environments to decide the
+% action in the environments following them. If it appears in a
+% \env{paracol} environment, you will have a warning message saying it is
+% ignored.
+%
+% \item
+% \changes{v1.3-5}{2013/09/17}
+% {Remove description of \cs{multicolumnfootnotes},
+% \cs{singlecolumnfootnotes}, \cs{mergedfootnotes} but mention they
+% are still available.}
+% 
+% In old versions of \Paracol, namely 1.2 and its minor revisions 1.2x,
+% footnote layout was controlled by a set of lengthy commands
+% \Midx{\!\multicolumnfootnotes!} for |c|, \Midx{\!\singlecolumnfootnotes!}
+% for |p|, and \Midx{\!\mergedfootnotes!} for |m|.
+% Though they are still available and will be so forever for backward
+% compatibility, it is recommended to use \!\footnotelayout!\footnote{
+% 
+% Not only for type saving but also for being familiar with this command
+% which could have some advanced feature, for example to put gathered
+% footnotes into a specific column, someday.}.
+%
+% % \item
+% It must be $\meta{layout}\in\{|c|,|p|,|m|\}$, or you will have an error
+% message of illegal layout specifier.
% \end{itemize}
%
%
%
+% \KeepSpace{5}
% \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
@@ -638,6 +996,7 @@
%
%
%
+% \KeepSpace{3}
% \item[\Midx{\!\fncounteradjustment!}]\mbox{}
% \Item[\Midx{\!\nofncounteradjustment!}]\mbox{}\par
% The maintenance of \counter{footnote} with the starred footnote commands
@@ -651,11 +1010,10 @@
%
% \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.
+% Though \!\footnotelayout! with |p|(age-wise) or |m|(erged) argument does
+% \!\fncounteradjustment! while that with |c|(olumn) does
+% \!\nofncounteradjustment! inside of it, you can override these settings by
+% explicitly putting a counter adjustment command after \!\footnotelayout!.
%
% \item
% The effect of \!\fncounteradjustment! is shown in Section~\ref{sec:fnnp}.
@@ -664,6 +1022,369 @@
%
%
%
+% \KeepSpace{6}
+% \subsection{Commands for Coloring Texts and Column-Separating Rules}
+% \label{sec:ref-tcolor}
+% \changes{v1.3-3}{2013/09/17}
+% {Rename the sub-sectoin title from ``Commands for Text Coloring'' to
+% ``Commands for Coloring Texts and Column-Separating Rules'' to
+% add description of the rule coloring together with the rule
+% drawing itself.}
+%
+% \begin{description}
+% \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
+% specification 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.
+%
+% \twosided[]\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 colored black as \cs{normalcolor} specifies.}.
+% \end{itemize}
+%
+%
+%
+% \KeepSpace{4}
+% \item[\Midx{\!\coloredwordhyphenated!}]\mbox{}
+% \Item[\Midx{\!\nocoloredwordhyphenated!}]\mbox{}\par
+% \changes{v1.3-3}{2013/09/17}
+% {Add description of \cs{coloredwordhyphenated} and
+% \cs{nocoloredwordhyphenated}.}
+% 
+% The command \!\coloredwordhyphenated! allows the first word following a
+% coloring command such as \!\color! to be hyphenated, but at the same time
+% make it possible that a line is broken before the word. The command
+% \!\nocoloredwordhyphenated! acts oppositely and thus line breaking before
+% the first word and hyphenating it are inhibited. By default,
+% \!\coloredwordhyphenated! is effective.
+% 
+% \begin{itemize}
+% \item
+% The implementation of \textsf{color} package and its relatives makes it
+% impossible that \meta{word} is hyphenated when it appears like
+% |{|\!\color!|{red}|\meta{word} \ldots|}| or
+% \!\textcolor!|{|\meta{word} \ldots|}|. This inhibition of the hyphenation
+% is sometimes annoying especially when the document is multi-columned and
+% thus a line is narrow and a column is written in a language having long
+% words such as German. Therefore in \Paracol{} package, a trick is used to
+% allow the \meta{word} is hyphenated. However this trick being insertion
+% of a null horizontal space has a side effect that the word can have a line
+% break before it. Though this line break is usually unharmful, in a
+% special occasion the break is undesirable and
+% in\textcolor{red}{appropriate} by making it possible that the
+% \emph{half-colored} word `inappropriate' is broken between `in' and
+% `appropriate' without hyphenation. Therefore, if you find such a
+% inappropriate break, use \!\nocoloredwordhyphenated! as follows, for example.
+% \begin{quote}
+% |{\nocoloredwordhyphenated in\textcolor{red}{appropriate}}|
+% \end{quote}
+% \end{itemize}
+%
+%
+% \KeepSpace{4}
+% \item[\Midx{\!\colseprulecolor!}\oarg{mode}\marg{color}\oarg{col}]\mbox{}
+% \Item[\Midx{\!\normalcolseprulecolor!}\oarg{col}]\mbox{}\par
+% \changes{v1.3-3}{2013/09/17}
+% {Add description of \cs{colseprulecolor} and
+% \cs{normalcolseprulecolor}.}
+% 
+% The command \!\colseprulecolor! declares the color for
+% {\em\Uidx\cseprule{}s}, being the vertical rules drawn at the center of
+% gaps between columns, is \meta{color} or what it specifies by the
+% combination with the optional \meta{mode}. The command
+% \!\normalcolseprulecolor! declares the color of rules is what
+% \!\normalcolor! specifies, i.e., black usually. If the optional argument
+% \meta{col} is given, these commands specifies the color of the rule in the
+% gap following the column whose ordinal is \meta{col}, rather than all rules.
+% 
+% \begin{itemize}
+% \item
+% The rules are drawn if \LaTeX's typesetting parameter \!\columnseprule!
+% for the rule width has non-zero value, e.g., 0.4\,|pt| to obey the
+% standard rule thickness. The rules are \emph{not} drawn on \pwstuff{},
+% i.e., \Preenv{} and \postenv, page-wise floats or (\mgfnote{} or
+% non-merged) \Scfnote{}s of course but also \mctext{}s. Therefore, if a
+% page has \mctext{}s, the rules are {\em broken} by them as shown in the
+% red rule example below.
+% \global\unitlength\@totalleftmargin
+% \end{itemize}
+% \end{description}
+%
+% \columnseprule0.4pt\colseprulecolor{red}[1]\colseprulecolor{white}[0]
+% \setcolumnwidth{\unitlength/0pt}
+% \begin{paracol}{3}\switchcolumn\noindent
+% This is a left column paragraph preceding a \mctext. Of cource the rule
+% separating this and the next column starts from the top of this paragraph.
+% \switchcolumn\noindent
+% This is a right column paragraph preceding a \mctext{} given by the
+% \!\switchcolumn!|*| at its end.
+% \switchcolumn[1]*[\subsubsection*{\hbox to\unitlength{}
+% An Example of Spanning Text Given by \cs{subsubsection}|*| Command}]
+% Since we have a \mctext{} above, the red rule separating this and the next
+% column is broken by the text.
+% \switchcolumn
+% It is also natural that the rule separating this and the previous column is
+% terminated at the end of this \env{paracol} environment.
+% \end{paracol}
+% \columnseprule0pt\columnratio{}
+% 
+% \begin{description}
+% \Item[]\mbox{}
+% \begin{itemize}
+% \Item
+% To give a color to rules 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
+% Once you give a color to rules in a specific gap with the optional
+% \meta{col}, another \!\colseprulecolor! or \!\normalcolseprulecolor!
+% without \meta{col} does \emph{not} change the color of the rule in the
+% gap.
+% \end{itemize}
+% \end{description}
+%
+%
+%
+% \KeepSpace{7}
+% \subsection{Commands for Background Painting}
+% \label{sec:ref-bgpaint}
+% \changes{v1.3-3}{2013/09/17}
+% {Add the sub-section ``Commands for Background Painting.}
+%
+% \begin{description}
+% \item[\Midx{\!\backgroundcolor!}\marg{region}\oarg{mode}\marg{color}]
+% \mbox{}\par
+% \Item[\Midx{\!\backgroundcolor!}
+% \Arg{\meta{region}$|(|x_0|,|y_0|)|$}\oarg{mode}\marg{color}]
+% \mbox{}\par
+% \Item[\Midx{\!\backgroundcolor!}
+% \Arg{\meta{region}$|(|x_0|,|y_0|)||(|x_1|,|y_1|)|$}
+% \oarg{mode}\marg{color}]
+% \mbox{}\par
+% \changes{v1.3-3}{2013/09/17}
+% {Add description of \cs{backgroundcolor}.}
+% 
+% The command declares that {\em\Uidx\bgpaint} of \meta{region} is performed
+% with \meta{color} or what it specifies by the combination of the optional
+% \meta{mode}. The \meta{region} whose \bground{} is painted is one of the
+% following.
+% 
+% \begin{description}
+% \item[|c|\rm(\textit{olumn})] for all columns, or particular one if
+% \meta{region} is |c|\oarg{col} to specify its ordinal \meta{col}.
+%
+% \item[|g|\rm(\textit{ap})] for all gaps between columns, or particular one
+% if \meta{region} is |g|\oarg{col} to specify the ordinal \meta{col} of the
+% column preceding the gap.
+%
+% \item[|s|\rm(\textit{panning})] for \mctext{}s.
+%
+% \item[|f|\rm(\textit{loat})] for page-wise floats.
+%
+% \item[|n|\rm(\textit{ote})] for (\mgfnote{} or non-merged) \Scfnote{}s.
+%
+% \item[|p|\rm(\textit{re/post})] for \Preenv{} and \postenv.
+%
+% \item[|t|\rm(\textit{op})] for top margin.
+%
+% \item[|b|\rm(\textit{ottom})] for bottom margin.
+%
+% \item[|l|\rm(\textit{eft})] for left margin.
+%
+% \item[|r|\rm(\textit{ight})] for right margin.
+% \end{description}
+% 
+% In addition, capitals of the keys above, i.e., |C|, |G|, \ldots, |L|, are
+% also legitimate for {\em under painting}. For example, you may specify to
+% paint the \bground{} of a region, say top margin, by two
+% \!\backgroundcolor! with |t| and |T| and with different color arranging the
+% size of the region of either |t| or |T| (or both of them) by the
+% \emph{\bgext} option shown below.
+%
+% The optional $|(|x_0|,|y_0|)|$ is to enlarge the region to be painted
+% shifting its left-top and right-bottom corner outside by
+% the dimension $x_0$ horizontally and $y_0$ vertically, or to shrink it
+% with negative dimensions. This {\em\Uidx\bgext} can be asymmetric giving
+% another optional $|(|x_1|,|y_1|)|$ so that it acts on the right-bottom
+% corner while let $|(|x_0|,|y_0|)|$ shift only the left-top corner.
+% Moreover, you may make each \bgext{} {\em infinite} by giving 10000\,|pt|
+% (about 3.5\,m) to $x_0$, $y_0$, $x_1$ and/or $y_1$ so that the
+% corresponding region edge is shifted to the paper edge. Furthermore, this
+% {\em\Uidx\bginfext{}} can be terminated at the point $\alpha$ inside the
+% corresponding paper edge by giving $10000\,|pt|-\alpha$
+% ($\alpha\leq1000\,|pt|$) to an extension parameter $x_0$, etc.
+% 
+% \begin{itemize}
+% \item
+% A region whose color is not specified is not painted and thus left blank
+% (or kept as painted by \!\pagecolor! if you specify it).
+%
+% \item
+% Under-painting of columns and gaps by |C| and |G| is made for regions
+% different from those over-painting |c| and |g|. That is, under-painting
+% is done ignoring all \pwstuff{} and thus the height of the regions is
+% always $\!\textheight!+\!\maxdepth!$. On the other hand, over-painting is
+% only for chunks shrunk or separated by \pwstuff.
+%
+% \item
+% You may exploit the following painting order, where $x_i$
+% is the $i$-th \mctext{} ($x\in\{|s|,|S|\}$) or $i$-th chunk followed by
+% the $i$-th \mctext, $m$ and $n$ is the number of \mctext{}s and columns in
+% a page respectively, to overlay a preceding region with a succeeding
+% region, if your \emph{printer} allows overlaid color painting.
+% 
+% \begin{eqnarray*}
+% |T|&\to&|B|\to|L|\to|R|
+% \to|G[|0|]|\to\cdots\to|G[|n{-}1|]|\to|C[|0|]|\to\cdots\to|C[|n{-}1|]|\\
+% &\to&|t|\to|b|\to|l|\to|r|\to|N|\to|n|\to\{|F|,|P|\}\to\{|f|,|p|\}
+% \to|S|_1\to\cdots\to|S|_m\\
+% &\to&|g|_1|[|0|]|\to\cdots|g|_1|[|n{-}2|]|\to
+% |c|_1|[|0|]|\to\cdots|c|_1|[|n{-}1|]|\to|s|_1\\
+% &\to&\cdots\\
+% &\to&|g|_m|[|0|]|\to\cdots|g|_m|[|n{-}2|]|\to
+% |c|_m|[|0|]|\to\cdots|c|_m|[|n{-}1|]|\to|s|_m\\
+% &\to&|g|_{m+1}|[|0|]|\to\cdots|g|_{m+1}|[|n{-}2|]|\to
+% |c|_{m+1}|[|0|]|\to\cdots|c|_m|[|n{-}1|]|
+% \end{eqnarray*}
+%
+% \item
+% If you specify |b| feature by \!\twosided!, \bgpaint{} is
+% {\em\Uidx\mirror{}ed} in even-numbered pages so that |l| and |L| mean
+% right margin, |r| and |R| mean left margin, and asymmetric extensions are
+% applied to right-top and left-bottom corners.
+%
+% \item
+% To give a color for \bgpaint{} 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
+% To paint margins and regions having infinite extension correctly, the
+% parameters \!\paperwidth! and \!\paperheight! should be set properly by,
+% for example, a paper selection option of \!\documentclass!.
+%
+% \item
+% Section~\ref{sec:bgpaint} shows examples of \bgpaint{} to give you more
+% intutive explanations of \!\backgroundcolor! and its region specifications.
+% \end{itemize}
+%
+%
+%
+% \item[\Midx{\!\nobackgroundcolor!}\marg{region}]\mbox{}
+% \Item[\Midx{\!\resetbackgroundcolor!}]\mbox{}\par
+% \changes{v1.3-3}{2013/09/17}
+% {Add description of \cs{nobackgroundcolor} and
+% \cs{resetbackgroundcolor}.}
+% 
+% The command \!\nobackgroundcolor! declares that the \bground{} of
+% \meta{region} is not painted, where \meta{region} is one of legitimate
+% region specifiers of \!\backgroundcolor!. The command
+% \!\resetbackgroundcolor! declares no regions are painted and thus gives
+% you the default state.
+% 
+% \begin{itemize}
+% \item
+% If you specified the \bgpaint{} of |c|\oarg{col} or |g|\oarg{col} by
+% \!\backgroundcolor!, the painting is \emph{not} canceled by
+% \!\nobackgroundcolor! with |c| or |g| but without \oarg{col}. Similarly,
+% once you made declarations of \bgpaint{} of both |c| and |c|\oarg{col}
+% (resp.\ |g| and |g|\oarg{col}), \!\nobackgroundcolor! with |c|\oarg{col}
+% (resp.\ |g|\oarg{col}) cancels the painting of |c|\oarg{col} (resp.\
+% |g|\oarg{col}) but the region will still be painted by the color you gave
+% to |c| (resp.\ |g|).
+% \end{itemize}
+%
+%
+%
+% \item[\Midx{\!\pagerim!}]\mbox{}\par
+% \changes{v1.3-3}{2013/09/17}
+% {Add description of \cs{pagerim}.}
+% 
+% This is a (kind of) \emph{length command}\footnote{
+% 
+% In reality, it is a \cs{dimen} register rather than a \cs{skip} register.}
+% 
+% to have the width of the \emph{rim} area placed at each paper edge to
+% inhibit \bgpaint{} in the area. That is, the inner edges of the area are
+% considered as virtual paper edges to block painting of all margins and
+% regions having \bginfext{} to the edges, for example in order to
+% avoid printing troubles caused by painting the rim area too close to the
+% real paper edges. The default value of \!\pagerim! is 0 to allow paint
+% anywhere in a paper.
+% \end{description}
+%
+%
+%
% \subsection{Control of Contents Output}
% \label{sec:ref-contents}
%
@@ -673,21 +1394,11 @@
% $\meta{file}\in\{|toc|,|lof|,|lot|\}$ from columns other than \meta{col}.
% 
% \begin{itemize}
-% \ifx\ONLYDESCRIPTION\undefined
% \item
% For example, this manual has \!\addcontentsonly!|{toc}{0}| to
-inhibit the % contents information output from \!\subsection! commands
-in the right column % in % Section~\ref{sec:env} and~\ref{sec:float},
-or the table should have % duplicated entries of sub-sections.
-%
-% \else
-% \item
-% For example, if this manual had the table of contents,
-% \!\addcontentsonly!|{toc}{0}| should be specified to inhibit the contents
-% information output from \!\subsection! commands in Section~\ref{sec:env}
-% and~\ref{sec:float}, or the table should have duplicated entries of
-% sub-sections.
-% \fi
+% inhibit the contents information output from \!\subsection! commands
+% in the right column in Section~\ref{sec:env} and~\ref{sec:float},
+% or the table should have duplicated entries of sub-sections.
%
% \item
% It must be $\meta{file}\in\{|toc|,|lof|,|lot|\}$, or you will have an
@@ -713,5 +1424,21 @@ or the table should have % duplicated entries of sub-sections.
% then for page-wise ones creating {\em\Uidx\fpage{}s} only with
% page-wise floats, as \LaTeX's \!\clearpage! does outside \env{paracol}
% environment.
+%
+% \item[\Midx{\!\cleardoublepage!}]\mbox{}\par
+% \changes{v1.3-5}{2013/09/17}
+% {Add description of \cs{cleardoublepage}.}
+% The command does what \LaTeX's \!\cleardoublepage! does outside
+% \env{paracol}. That is, it does \!\clearpage! always and then leaves a
+% blank page if it is even-numbered and two-sided |p|(age) feature is
+% enabled by |twoside| option of \!\documentclass! or \Paracol's own
+% \!\twosided! command shown in Section~\ref{sec:ref-twoside}.
+% 
+% \begin{itemize}
+% \item
+% This command is equivalent to \!\clearpage! in \env{paracol} environments
+% for \npaired{} \parapag{}ing because \!\clearpage! flushes \emph{both}
+% left and right \parapag{}es.
+% \end{itemize}
% \end{description}
\endinput