summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/paracol/ref.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/paracol/ref.dtx')
-rw-r--r--Master/texmf-dist/source/latex/paracol/ref.dtx321
1 files changed, 321 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/paracol/ref.dtx b/Master/texmf-dist/source/latex/paracol/ref.dtx
new file mode 100644
index 00000000000..5383aa5e3fb
--- /dev/null
+++ b/Master/texmf-dist/source/latex/paracol/ref.dtx
@@ -0,0 +1,321 @@
+% \section{Reference Manual}
+% \subsection{Environment \texttt{paracol}}
+%
+% \begin{description}
+% \item[\ENV{paracol}{\marg{num}\oarg{text}}]\mbox{}\par
+% The environment \env{paracol} contains \meta{body} typeset in \meta{num}
+% columns in parallel. The optional \meta{text} is put spanning all columns
+% prior to the multi-columned \meta{body}.
+% 
+% \begin{itemize}
+% \item
+% 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}
+% 
+% \UsageIndex{multi-column text}
+% 
+% 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.
+%
+% \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
+% 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
+% commonly have the value at \beginparacol.
+%
+% \item
+% 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
+% \postenv{}, with a vertical skip of \!\textfloatsep! separating them if
+% bottom floats exist. All deferred single-column 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.
+%
+% \item
+% The values of all \lcounter{}s in the leftmost column are used as the
+% initial values of them in the \postenv.
+%
+% \item
+% The \env{paracol} environment cannot be nested, or you will have an error
+% message of illegal nesting.
+%
+% \item
+% The commands \!\switchcolumn!, \!\synccounter!, \!\syncallcounters! and
+% \!\flushpage!, and environments \env{column}(|*|), \env{nthcolumn}(|*|),
+% \env{leftcolumn}(|*|) and \env{rightcolumn}(|*|) are {\em local} to
+% \env{paracol} environment and thus undefined outside the
+% environment\footnote{
+% 
+% Unless you dare to define them.}.
+% 
+% 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}
+% \end{description}
+%
+%
+%
+% \subsection{Column-Switching Command and Environments}
+%
+% \begin{description}
+% \item[\Midx{\!\switchcolumn!}\oarg{col}]\mbox{}
+% \Item[\Midx{\!\switchcolumn!}\oarg{col}\texttt{*}\oarg{text}]\mbox{}\par
+% The command switches columns from $i$ to $j$ where $i$ and $j$ is the
+% zero-origin ordinals of the columns from/to which we are leaving\slash
+% visiting respectively. Without the optional \meta{col}, $j=i+1\bmod n$
+% 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
+% \meta{text} is put.
+% 
+% \Index{multi-column 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.
+%
+% \item
+% If $\meta{col}\notin\LBRP0n$, an error is reported and, if you dare to
+% continue, you will switch to the leftmost column 0.
+%
+% \item
+% The \sync{}ation point is set just below the last line of the \lcolumn{}
+% in a page $p$, partly taking deferred floats into account. That is, all
+% 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.
+%
+% \item
+% In a page having one or more \sync{}ation points, stretch and shrink
+% factors of all vertical spaces, such as those surrounding sectionning
+% commands, are ingonred. Therefore, even if you specify \!\flushbottom!,
+% 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
+% having the point any more and thus will be deferred to the next or
+% succeeding page.
+% \end{itemize}
+%
+%
+%
+% \item[\ENV{column}{}]\mbox{}
+% \Item[\ENV{column*}{\oarg{text}}]\mbox{}\par
+% 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.
+% 
+% \Index{multi-column text}
+% 
+% \begin{itemize}
+% \item
+% The environments are almost equivalent to;
+% \begin{quote}
+% |{|\!\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
+% (i.e., right column if two-columned) but stay in the leftmost column 0.
+% More precicesly, \!\begin!|{|\env{column}(|*|)|}| does not make \cswitch{}
+% if it is not preceded by \!\switchcolumn! nor other \csenv{}s.
+%
+% \item
+% The \meta{body} of the environments cannot have \!\switchcolumn! nor other
+% \csenv{}s including \env{column}(|*|) themselves, or you will have an
+% error message of illegal use of command\slash environment.
+%
+% \item
+% 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.
+% \end{itemize}
+%
+%
+%
+% \item[\ENV{nthcolumn}{\marg{col}}]\mbox{}
+% \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.
+% 
+% \Index{multi-column text}
+% 
+% \begin{itemize}
+% \item
+% The environments are equivalent to;
+% 
+% \begin{quote}
+% |{|\!\switchcolumn!\oarg{col}\quad\meta{body}\quad\CSIndex{par}|}|\\
+% |{|\!\switchcolumn!\oarg{col}|*|\oarg{text}\quad
+% \meta{body}\quad\CSIndex{par}|}|
+% \end{quote}
+%
+% \item
+% The \meta{body} of the environments cannot have \!\switchcolumn! nor other
+% \csenv{}s including \env{nthcolumn}(|*|) themselves, or you will have an
+% error message of illegal use of command\slash environment.
+%
+% \item
+% 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.
+% \end{itemize}
+%
+%
+%
+% \newpage
+% \item[\ENV{leftcolumn}{}]\mbox{}
+% \Item[\ENV{leftcolumn*}{\oarg{text}}]\mbox{}
+% \Item[\ENV{rightcolumn}{}]\mbox{}
+% \Item[\ENV{rightcolumn*}{\oarg{text}}]\mbox{}\par\nobreak
+% The environment \env{leftcolumn} contains \meta{body} for the leftmost
+% 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.
+% 
+% \Index{multi-column text}
+% 
+% \begin{itemize}
+% \item
+% The environments \env{leftcolumn}(|*|) are equivalent to;
+% 
+% \begin{quote}
+% \Env{nthcolumn}{\Arg{\texttt{0}}}\\
+% \Env{nthcolumn*}{\Arg{\texttt{0}}\oarg{text}}
+% \end{quote}
+% 
+% while \env{rightcolumn}(|*|) are equivalent to;
+% 
+% \begin{quote}
+% \Env{nthcolumn}{\Arg{\texttt{1}}}\\
+% \Env{nthcolumn*}{\Arg{\texttt{1}}\oarg{text}}
+% \end{quote}
+% 
+% \end{itemize}
+% \end{description}
+%
+%
+%
+% \subsection{Commands for Counters}
+%
+% \begin{description}
+% \item[\Midx{\!\globalcounter!}\marg{ctr}]\mbox{}\par
+% The command declares that the counter \meta{ctr} is global to all columns.
+% An update of a \Uidx\gcounter{} in a column is seen by any other columns.
+% 
+% \begin{itemize}
+% \item
+% All column-local values of a descendant \lcounter{} of a \gcounter{} are
+% zero-cleared when the \gcounter{} is explicitly stepped by \!\stepcounter!
+% or \!\refstepcounter!, or implicitly by a sectioning command and so on.
+%
+% \item
+% The counter \counter{page} is always global but an explicit update of it
+% by e.g., \!\setcounter! in a non-leftmost column is not seen by other
+% columns and is canceled even for the column itself after a \cswitch{} or a
+% page break in the column. Therefore, if you want to make a \emph{jump} of
+% \counter{page}, it must be done in the leftmost column 0. Note that a
+% jump from a page $p$ to $q$ can be seen in other columns even if they have
+% gone beyond $p$ \emph{before} the column 0 makes the jump, as far as
+% \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
+% might have in ordinary \LaTeX{} documents.}.
+% \end{itemize}
+%
+%
+%
+% \item[\Midx{\!\definethecounter!}\marg{ctr}\marg{col}\marg{rep}]\mbox{}\par
+% The command defines |\the|\meta{ctr} being \marg{rep} for the local use in
+% the column \meta{col}. That is, |\the|\meta{ctr} in the column \meta{col}
+% acts as if it is defined by
+% \!\renewcommand!\Arg{\cs{the}\meta{ctr}}\Arg{\meta{rep}}.
+%
+%
+%
+% \item[\Midx{\!\synccounter!}\marg{ctr}]\mbox{}\par
+% The command \emph{broadcasts} the value of the \lcounter{} \meta{ctr} in
+% the column in which the command appears to the values in all other columns.
+%
+% \item[\Midx{\!\syncallcounters!}]\mbox{}\par
+% The command broadcasts the values of all \lcounter{}s in the column in
+% which the command appears to the values in all other columns.
+% \end{description}
+%
+%
+%
+% \subsection{Control of Contents Output}
+%
+% \begin{description}
+% \item[\Midx{\!\addcontentsonly!}\marg{file}\marg{col}]\mbox{}\par
+% The command inhibits the output of contents information to
+% $\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
+% 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
+%
+% \item
+% It must be $\meta{file}\in\{|toc|,|lof|,|lot|\}$, or you will have an
+% error message of illegal type of contents file.
+% \end{itemize}
+% \end{description}
+%
+%
+%
+% \subsection{Page Flushing Commands}
+%
+% \begin{description}
+% \item[\Midx{\!\flushpage!}]\mbox{}\par
+% The command flushes pages up to the {\em\Uidx\tpage} in which the \lcolumn{}
+% resides. Deferred floats which can be put in the pages up to the \tpage{}
+% are also flushed.
+%
+% \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}
+% environment.
+% \end{description}
+\endinput