summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/paracol/probs.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/paracol/probs.dtx')
-rw-r--r--macros/latex/contrib/paracol/probs.dtx262
1 files changed, 262 insertions, 0 deletions
diff --git a/macros/latex/contrib/paracol/probs.dtx b/macros/latex/contrib/paracol/probs.dtx
new file mode 100644
index 0000000000..4d6ee18c7c
--- /dev/null
+++ b/macros/latex/contrib/paracol/probs.dtx
@@ -0,0 +1,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