summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/paracol/ref.dtx
blob: 29cbda9a70616750ef3166a52786311200e1d900 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
% \section{Reference Manual}
% \label{sec:ref}
% \subsection{Environment \texttt{paracol}}
% \label{sec:ref-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}
% \label{sec:ref-switchcolumn}
% 
% \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{Command to Control Column Width} 
% \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
% 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.
% 
% \begin{eqnarray*}
% W'&=&W-(n-1)S\\
% w_i&=&\cases{
%   r_iW'
%     \vrule height1.5\ht\strutbox depth1.5\dp\strutbox width0pt&$i\leq k$\cr
%   \displaystyle{(1-\sum_{j=0}^k r_j)W'\over n-(k+1)}&$i>k$}
% \end{eqnarray*}
% 
% \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.
% 
% \item
% The argument $r_0,r_1,\cdots,r_k$ can be empty to mean $k=-1$ to let all
% column widths be $W'/n$ as default.
% 
% \item
% The setting of column width by the command takes effect in the |paracol|
% environments following the command\footnote{
% 
% If the command is in a \texttt{paracol} environment, the command does not
% affect the column widths of the environment but does the next ones, though
% such usage is very unusual.}.
% 
% Therefore, though placing the command in the preamble is the most natural
% way\footnote{
% 
% Or second most to not using it at all, of course.},
% 
% you may place this command between two |paracol| environments to change
% the column layout for the second one even when they appear in a page as
% shown in Section~\ref{sec:man-close}.
% 
% \item
% In the $i$-th column, \!\columnwidth! has $w_i$ and, for outermost
% paragraphs in the column, \!\linewidth! and \!\hsize! have $w_i$ as well.
% \end{itemize}
% \end{description}
% 
% 
% 
% \subsection{Commands for Counters}
% \label{sec:ref-counter}
% 
% \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}
% \label{sec:ref-contents}
% 
% \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 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
% 
% \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}
% \label{sec:ref-flush}
% 
% \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