path: root/macros/latex/contrib/paracol/probs.dtx

% \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