diff options
author | Karl Berry <karl@freefriends.org> | 2013-11-08 23:43:59 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2013-11-08 23:43:59 +0000 |
commit | 92f13c38adca9511a17969f8efde0f4d0e6e5f3a (patch) | |
tree | b6a58333142feae9cdcaae185fd2ef7cfb439578 /Master/texmf-dist/source/latex/paracol/probs.dtx | |
parent | 77d66d8f7bc360ae2b37c1ea1c2cb53f7a201e57 (diff) |
paracol (8nov13)
git-svn-id: svn://tug.org/texlive/trunk@32099 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/paracol/probs.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/paracol/probs.dtx | 234 |
1 files changed, 234 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/paracol/probs.dtx b/Master/texmf-dist/source/latex/paracol/probs.dtx new file mode 100644 index 00000000000..e8c69fd556d --- /dev/null +++ b/Master/texmf-dist/source/latex/paracol/probs.dtx @@ -0,0 +1,234 @@ +% \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.} +% \changes{v1.3-6}{2013/09/17} +% {Add comments about usage of \cs{paragraph} etc.\ in spanning texts.} +% \changes{v1.3-2}{2013/09/17} +% {Add comments about the limitaion of parallel-paging.} +% \changes{v1.3-3}{2013/09/17} +% {Add comments about the imperfectnss of extention of backgrond +% painting regions.} +% +% 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}.}. +% +% 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 +% \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 +% 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 +% \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} +% \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 |