summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/paracol/probs.dtx
blob: 4d6ee18c7cadcd9602c23c455a33be5ec90338e2 (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
% \section{Known and Unknown Problems}
% \label{sec:problem}
% \changes{v1.2-7}{2013/05/11}
% 	{Add the section ``Known and Unknown Problems'' to summarize a few
% 	 typesetting issues and warn users of the possiblity of bugs.}
% \changes{v1.3-1}{2013/09/17}
%	{Remove the problem description of the placement of page-crossing
%	 spanning texts because it has been solved.}
% \changes{v1.3-3}{2013/09/17}
%	{Remove the problem description of the lack of column-separating rule
%	 drawing because it has been implmented.}
% 
% Here a few problems you could face in the use of \textsf{paracol} are
% summarized.
% 
% \begin{itemize}
% \item
% If your (e.g.,) left column goes ahead too much farther than the right
% column, \LaTeX{} could stop with the following error message.
% 
% \begin{quote}
% |! Package paracol Error: Too many unprocessed columns/floats.|
% \end{quote}
% 
% This usually means that the internal space to keep materials in the left
% column is exhausted.  More specifically, suppose at some point in your
% |.tex| the left column is in the page $p$ while the right is in $q<p$.
% We need $(p-q)$ \emph{boxes} to keep the left column contents in the pages
% $q$, $q+1$, \ldots, $p-1$ because these pages cannot be \emph{printed} yet
% until the right column fills them.  In addition, we also need two boxes
% for the left column in $p$ and the right column in $q$ so that you make
% \cswitch{} between them keeping unprinted contents in them.  Therefore, at
% least we need to have $(p-q)+2$ boxes, while the number of them provided
% by \LaTeX{} is only 18\footnote{
% 
% Readers who are acquainted with \LaTeX{} implementation will understand
% that 18 is the cardinality of the set $\{\cs{bx@A},\ldots,\cs{bx@R}\}$ for
% floats acquired by \cs{newinsert}.  Those who are more familiar with that
% might know that most \LaTeX{}, based on e-\TeX{} or others having similar
% extensions, now have 52 \cs{insert}s
% $\{\cs{bx@A},\ldots,\cs{bx@Z},\cs{bx@AA},\ldots,\cs{bx@ZZ}\}$ for floats
% and materials of \Paracol, since 2015}.
% 
% Therefore, \textsf{paracol} cannot continue its work if $(p-q)$ reaches
% 17.  Furthermore, other stuff also consumes the boxes as follows.
% 
% \begin{itemize}
% \item
% If there are $n$ pages in $q$, $q+1$, \ldots, $p$ having \preenv{} or
% page-wise floats, $n$ boxes are consumed by them.  Similarly, if $m$ pages
% in them have \Scfnote{}s, $m$ boxes are given to them.
% 
% \item
% If the left (resp.\ right) column has \Mcfnote{}s in $p$ (resp.\ $q$), a box
% is used for them.
% 
% \item
% If the left (resp.\ right) column has $k$ floats to be placed in $p$
% (resp.\ $q$) or to be deferred to $p+1$ (resp.\ $q+1$) or a succeeding page,
% $k$ boxes are reserved for them.
% \end{itemize}
% 
% Therefore, it should be safe to keep $(p-q)$ from exceeding 10 or so
% placing \!\switchcolumn! in both columns fairly frequently.
% 
% \item
% As discussed in Section~\ref{sec:ref-switchcolumn}, setting a \sync{}ation
% point in a page brings the following side effects.
% 
% \begin{itemize}
% \item
% Stretch and shrink factors of all vertical skips in the page are
% nullified.  The nullification of stretch factors could make a sparse
% column in the page have a vertical space at its bottom as if
% \!\raggedbottom! setting is in effect even with \!\flushbottom! one,
% rather than distributing the amount of the space to the skips so that the
% bottom line is aligned at the page bottom.  As for the nullification of
% shrink factors, it makes the page have lines a little bit less than that
% it would have without \sync{}ation because lines above the (last)
% \sync{}ation point cannot be compressed.  The other effect is a little bit
% subtle because the shrink factors below the last \sync{}ation point are
% taken care of by \TeX{}'s page builder when it examine the appropriateness
% of each breakable point, but they are nullified when the page is printed.
% That is, if \TeX{} finds a good break point which needs that the stuff
% between the \sync{}ation and break points is compressed a little bit, the
% stuff is printed without compression making its bottom edge a little
% bit below the page bottom.
% 
% \item
% After a \sync{}ation point is set, columns in the page cannot have top
% floats any more even if a column has space above the \sync{}ation point
% and large enough to place the float.  Therefore, if you like to exploit
% the space, you have to place the \env{figure} or \env{table} environment
% in question prior to the \cswitch{} command or environment for the
% \sync{}ation.
% \end{itemize}
% 
% \item
% \changes{v1.3-6}{2013/09/17}
%	{Add comments about usage of \cs{paragraph} etc.\ in spanning texts.}
% \begingroup\parskip\z@
% As the author did for Section\Tie1 to \ref{sec:float}, sometimes you will
% make a section header spanning all columns by giving a sectioning command
% such as \!\section!, \!\subsection! and \!\subsubsection! to the optional
% argument of \!\switchcolumn!|*| or \!\begin! of a \sync{}ing \csenv.
% These three commands work well and you will have what you intend to have,
% but you have to be careful with lower-level commands \!\paragraph! and
% \!\subparagraph!.  Unlike higher-level relatives, these lower-level
% commands does \emph{not} put the header \emph{immediately} but keep it
% somewhere\footnote{
% 
% For people familiar to \TeX's \emph{dangerous bends}, the header is kept in
% \!\everypar!.}
% 
% so that when the paragraph following the command starts it is put as the
% leading part of the paragraph.  Therefore if the \mctext{} has (e.g.)
% \!\paragraph! only, the header is not put as a \mctext{} but at the head of
% the first paragraph of the column to which you switch, leaving an
% empty \mctext{} with some large space as follows.
% 
% \par\leavevmode\Hrule
% \columnsep\z@
% \begin{paracol}{2}
% This left-column paragraph precedes a \sync{}ed \cswitch.
% \switchcolumn
% This right-column paragraph precedes a \sync{}ed \cswitch.
% \switchcolumn*[\paragraph{A Spanning Text Given by \cs{paragraph}}]
% This left-column paragraph follows the \sync{}ation but is led by
% \!\paragraph! given to the optional argument of \!\switchcolumn!|*| for
% \mctext.
% \switchcolumn
% This right-column paragraph follows the \sync{}ation with an empty \mctext.
% \end{paracol}
% \par\leavevmode\Hrule\par
% 
% Therefore, unless this is what you intend to do, you have to give some
% paragraph together with \!\paragraph! to the optional argument for
% \mctext.  For example, \!\mbox!|{}| is a good candidate as the paragraph
% following \!\paragraph! because it produces (almost) nothing.  By using
% this technique the example above becomes the followings.
% 
% \par\leavevmode\Hrule
% \begin{paracol}{2}
% This left-column paragraph precedes a \sync{}ed \cswitch.
% \switchcolumn
% This right-column paragraph precedes a \sync{}ed \cswitch.
% \switchcolumn*[\paragraph{A Spanning Text Given by \cs{paragraph} Followed
% by \cs{mbox}\texttt{\char`\{\char`\}}}\mbox{}]
% This left-column paragraph follows the \mctext{} above.
% \switchcolumn
% This right-column paragraph follows the \mctext{} above.
% \end{paracol}
% \par\leavevmode\Hrule
% \endgroup
% 
% \item
% As shown in Section~\ref{sec:fnnp}, it is not easy to have good numbering
% and stacking order of \Scfnote{}s even with the supports from
% \!\footnote!|*| and its relatives.  In addition, a footnote in a
% \env{paracol} environment cannot be broken into two (or more) pages.
% 
% \item
% \changes{v1.3-2}{2013/09/17}
%	{Add comments about the limitaion of parallel-paging.}
% 
% As the author confessed in Section\Tie\ref{sec:ppts-paired}, right
% \parapag{}es cannot have \pwstuff{} but have blank spaces in the
% corresponding region for them.  The author will try to remove this
% limitation from a future version of \Paracol, in the version 1.4 hopefully.
%
% \item
% \changes{v1.3-3}{2013/09/17}
%	{Add comments about the imperfectnss of extention of backgrond
%	 painting regions.}
% \begin{Hfuzz}{1.5pt}
% As discussed in Section\Tie\ref{sec:bgpaint-me}, it is desirable that
% \bgpaint{} region definition in \!\backgroundcolor! has position dependent
% extensions.  The author is fairly optimistic about the incorporation of
% this advanced feature in the version 1.4.
% \end{Hfuzz}
% 
% \item
% \changes{v1.32-3}{2015/10/10}
%	{Add comments about the out-of-order appearance of page-wise floats
%	 even with \protect\LaTeX-2015/01/10 or later.}
% In the release dated 2015/01/10, \LaTeX{} changed its mechanism of the
% placement of double-column floats (or in our terminology, \pwise{}
% floats) to avoid {\em out-of-order\/} appearance of them.  That is, until
% the release on 2014/05/01 a double-column float (e.g., \env{figure*}) can
% be overtaken by a single-column float of the same category (e.g.,
% \env{figure}) when they cannot be put into the page in which texts around
% them are put.  In order to cope with the problem, the new version merged
% two lists to keep {\em deferred\/} double- and single-column floats into
% one so that the appearance order of them is determined by their order in
% the single list.  Though this change should have made people happy when
% they typeset {\em ordinary\/} two-column (or multiple-column) documents,
% the new feature might not be welcomed by \Paracol{} users because your
% parallel-columns have their own {\em streams\/} of floats to be put in the
% corresponding columns.  Therefore, and for the sake of simplicity of
% \Paracol's implementation, the author decided to nullify this new feature
% in \env{paracol} environments.  That is, even with new releases of
% \LaTeX{}, your \pwise{} floats given in a \env{paracol} environment can be
% overtaken by \cwise{} floats.
% \end{itemize}
% 
% In addition to the problems above known to the author, there may be (or
% should be, honestly speaking) other unknown problems in \textsf{paracol}
% because it cannot be perfect though the author has made his best effort
% for testing and debugging it.  Particularly, sometimes it is very tough,
% if not impossible, to make \textsf{paracol} compatible with other
% packages, especially with those having dark magic as \textsf{paracol} has
% in it\footnote{
% 
% For example, the author knows it is almost impossible to make
% \textsf{paracol} compatible with one of the author's own package available
% in CTAN.}.
% 
% Therefore, though reporting incompatibleness with a package you use is
% very welcome\footnote{
% 
% For example, \textsf{paracol} is now compatible with \textsf{color}
% package thanks to a report from a user.},
% 
% you should kindly understand the toughness of the compatibility issue.
% 
% Furthermore, even without such problematic packages, \textsf{paracol}
% might produce weird results due to its bug.  If your document has
% something to make unknown bugs visible, you might have one (or more) of
% the followings which the author encountered in his debugging work.
% 
% \begin{itemize}
% \item
% A page, a column, a footnote and/or a float disappears\footnote{
% 
% In fact, a bug fixed in version 1.2 caused page losing though it happens
% very very rarely but an unlucky user encountered it.}.
% 
% \item
% A page, a column, a footnote and/or a float is duplicated.
% 
% \item
% A message like ``{\tt Overfull |\vbox| (1.23456pt too high) has occurred
% while |\ouptut| is active}'' is shown.
% 
% \item
% A message ``{\tt Underfull |\vbox| (badness 10000) has occurred while
% |\ouptut| is active}'' is shown.  This message, however, does not always
% mean a bug but may just be a complaint that a column or a page is too
% sparse to meet your request to align the bottom of all columns and pages
% by \!\flushbottom! setting.  Therefore, if you have this message and you
% cannot be sure whether it means a bug or not, try \!\raggedbottom! setting
% to see if you still have the message, before sending a bug report to the
% author.
% \end{itemize}
% 
% If you encounter anything like them (or whatever you cannot solve by
% yourself), don't hesitate to report it to the author with minimum source
% file to produce the problem\footnote{
% 
% And with patience because your problem might not be solved quickly.}.
% 
% \endinput