%\iffalse
%% parrun.dtx
%% Copyright (C) 2003 Massimiliano Dominici
%
% This program is free software; you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation; either version 2 of the License, or
% (at your option) any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program; if not, write to the Free Software
% Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
%
% This program consists of the files parrun.dtx and parrun.ins
%
%<*driver>
\documentclass[a4paper]{ltxdoc}
\usepackage{parrun}
\GetFileInfo{parrun.sty}
\makeatletter
\c@IndexColumns=2
\def\DescribeOpt{\leavevmode\@bsphack\begingroup\MakePrivateLetters
\Describe@Opt}
\def\Describe@Opt#1{\endgroup
\marginpar{\raggedleft\PrintDescribeOpt{#1}}%
\SpecialOptIndex{#1}\@esphack\ignorespaces}
\def\SpecialOptIndex#1{\@bsphack
\index{#1\actualchar{\protect\ttfamily#1}
(option)\encapchar usage}%
\index{options:\levelchar{\protect\ttfamily#1}\encapchar
usage}\@esphack}
\newcommand{\PrintDescribeOpt}{\PrintDescribeEnv}
\makeatother
\EnableCrossrefs
\RecordChanges
\begin{document}
\DocInput{parrun.dtx}
\end{document}
%</driver>
%\fi
% \CheckSum{426}
%% \CharacterTable%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%% Digits \0\1\2\3\4\5\6\7\8\9
%% Exclamation \! Double quote \" Hash (number) \#
%% Dollar \$ Percent \% Ampersand \&
%% Acute accent \' Left paren \( Right paren \)
%% Asterisk \* Plus \+ Comma \,
%% Minus \- Point \. Solidus \/
%% Colon \: Semicolon \; Less than \<
%% Equals \= Greater than \> Question mark \?
%% Commercial at \@ Left bracket \[ Backslash \\
%% Right bracket \] Circumflex \^ Underscore \_
%% Grave accent \` Left brace \{ Vertical bar \|
%% Right brace \} Tilde \~}
%%
%
%\changes{v1.0}{2003/06/19}{First public release.}
%\changes{v1.1}{2003/11/18}{Added autocomputation, some macro names changed.}
%\changes{v1.1a}{2004/02/06}{Bug fixed.}
%
%\DoNotIndex{\advance,\AND,\baselineskip,\bgroup,\cr}
%\DoNotIndex{\DeclareOption,\divide,\else,\egroup,\fi}
%\DoNotIndex{\global,\hbox,\hfil,\hfilneg,\hrule,\ht}
%\DoNotIndex{\ifdim,\ifnum,\ifthenelse,\newbox}
%\DoNotIndex{\newcommand,\newcounter,\newdimen,\newif}
%\DoNotIndex{\noalign,\newenvironment,\PackageError}
%\DoNotIndex{\ProvidesPackage,\ProcessOptions,\RequirePackage}
%\DoNotIndex{\setbox,\smallskip,\string,\valign,\vbox}
%\DoNotIndex{\vbadness,\vfil,\vfill,\vsize,\whiledo}
%\DoNotIndex{\@ifstar,\AtEndDocument,\dimen,\immediate}
%\DoNotIndex{\NeedsTeXFormat,\m@ne,\newcount,\newlength}
%\DoNotIndex{\ratio,\smallskipamount,\write,\the}
%\StopEventually{
%\begin{thebibliography}{10}
% \bibitem{knuth} Donald Knuth.
% \newblock \emph{The \TeX book}
% \newblock Addison--Wesley, Reading, MA, 1996.
%\end{thebibliography}
%\PrintChanges
%\PrintIndex
%}
%
%\title{\texttt{parrun}\\User Guide\thanks
% {This file has version number \fileversion{} dated \filedate{}.}}
%\author{Massimiliano Dominici}
%\date{\filedate}
%\maketitle
%\abstract{The package |parrun| provides a set of macros useful for
%typesetting several (two) streams of text running parallel on the
%same physical page in a vertical layout.}
%
%\tableofcontents
%
%\section{Introduction}
%
%It may occur, especially in anthologies and collections, that a
%translation and the original parallel text must not be disposed on
%two different pages or columns, but one \emph{above} the other.
%The package |parrun|\marginpar{\raggedleft |parrun|} has been
%designed to handle this situation. The user interface is simple
%and provides two environments in order to define the respective
%streams of text and a command for placing them on the page, saving
%for each of them an exact fraction of the bodytext.
%
%Finally, as |parrun| showed himself, during tests, incompatible
%with package |multicol|\marginpar{\raggedleft |multicol|}, I had
%to introduce an explicit option for typesetting in two or more
%columns the second stream of text.
%
%\section{User interface}
%
%\subsection{Environments}
%
%\DescribeEnv{fframe}\DescribeEnv{sframe} The way to use the two
%environments is easy and there are no additional arguments. The
%environments do just what their names say, \emph{i.e.} they place
%in a |\box| the text enclosed between the initial and the final
%declaration, following the usual formulation
%|\begin{|\meta{env}|}| \meta{general text} |\end{|\meta{env}|}|.
%
%\subsection{The command \cs{Place}}
%
%The actual arrangement on the page of the content of the two
%|boxes|, following the user instructions, is the task of the
%command |\Place|. There are two ways to use it:
%
%\begin{itemize}
%\item \DescribeMacro{\Place*}the starred version (|\Place*|),
%without arguments, tries to automatically compute the optimal
%fraction of |\texteight| to be reserved for each |box|, so you
%need not to bore yourself with the whole matter.
%
%\item \DescribeMacro{\Place}the unstarred version is provided for
%the case the algorithm of autocomputation fails, and takes two
%arguments, \emph{i.e.}: the space to be reserved on the page for
%the two |boxes|, expressed in fractions of |\textheight|. So,
%typing |\Place{423}{57}|, you mean that the page will be divided
%in two regions, whose height is |0.423\textheight| and
%|0.57\textheight| respectively.
%\end{itemize}
%|\Place| checks wether the text is ill-balanced, with a stream
%keeping on running while the other is already finished, and, in
%the case of the unstarred version looks also after the total
%fraction of the text actually placed on the page checking it
%doesn't exceed the bodytext. In both cases compilation is halted
%and a warning appears giving possibility to get more help. Then
%compilation goes on till end and a table of the most important
%quantities used by the package is typed at the end of the log
%file, providing a useful hint for values to be used with the
%unstarred version in the case the autocomputation algorithm gives
%a bad result.
%
%\subsection{The option \texttt{multicol}}
%
%\DescribeOpt{multicol} As already mentioned, the package provides
%internally an option |multicol| for typesetting the content of the
%second stream of text on two columns. The user needs only to load the
%option together with the package
%(|\usepackage[multicol]{parrun}|). Changing the value of counter
%\DescribeMacro{\cnum}|\cnum|, the user can, as a consequence, vary
%the number of columns.
%
%\subsection{Limitations}
%
%Involving boxes containing large portions of text, the package
%deals with large dimensions. \TeX{} has very loose limitations in
%the use of large dimensions, yet these limitations exist and to
%find himself involved in such problems is easier than one can
%think. Obviously the use of a multicolumn layout increases the
%possibility to overrun the limits, so this solution should be used
%with care. The only apology I can make is that the package has
%been designed for such tasks that request no large amounts of text
%stuffed in a box. Maybe a different approach should be taken into
%consideration. Besides, large font dimensions and small heights of
%the bodytext can have as result an oscillating behaviour of the
%output which remains unbalanced.
%
%\section{The code}
% \begin{macrocode}
%<*parrun>
% \end{macrocode}
%\iffalse
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% %
%% ******************** %
%% * PARALLEL RUNNING * %
%% ******************** %
%% This is package ``parrun.sty'', providing %
%% a set of macro for typesetting two streams %
%% of text running parallel on the same phy- %
%% sical page, in a vertical layout. %
%% %
%% Author: Massimiliano Dominici %
%% Date: 18/11/2003 %
%% Version: 1.1 %
%% %
%% Released under the GNU General Public License. %
%% Please report any bugs to mlgdominici@interfree.it %
%% %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\fi
%\subsection{Package identification}
% \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}[2001/06/01]
\ProvidesPackage{parrun}[2004/02/06 v1.1a Package for parallel text]
\RequirePackage{ifthen} \RequirePackage{calc}
% \end{macrocode}
%\subsection{Conditionals and the option declaration}
% \begin{macrocode}
\newif\ifmultic@l
\DeclareOption{multicol}{\multic@ltrue}
\ProcessOptions
% \end{macrocode}
%\subsection{The beginning}
%We declare the |\box|es \dots
% \begin{macrocode}
\newbox\ffram
\newbox\sfram
% \end{macrocode}
%\dots\ the counters (|\cnum|, defining the number of columns in
%the option |multicol| is by default set equal to two)\dots
% \begin{macrocode}
\newcount\k
\newcount\cnum
\cnum=2
% \end{macrocode}
%\dots\ and some useful lengths.
% \begin{macrocode}
\newlength\flength
\newlength\slength
\newlength\ffrac
\newlength\sfrac
\newlength\nop
\newlength\total
\newlength\actualheight
\newlength\initskip
\setlength{\initskip}{0pt}
\newdimen\colframsep
\newdimen\h
\newdimen\test
\newdimen\temp
\colframsep=8pt
% \end{macrocode}
%\subsection{Environments}
%The two environments \DescribeMacro{fframe}|fframe| and
%\DescribeMacro{sframe}|sframe| place respectively in the two
%|\box|es |ffram| and |sfram| the \meta{general text} enclosed
%between the initial and the final declaration.
% \begin{macrocode}
\newenvironment{fframe}{\global\setbox\ffram=\vbox\bgroup}{\vfill\egroup}
% \end{macrocode}
%\begin{macro}{sframe}
%For what concerns |sframe| it has to distinguish if the option
%|multicol| is in force or not. In the first case he has to
%redefine |\hsize| so that the text can be distributed on the
%specified number of columns.
% \begin{macrocode}
\newenvironment{sframe}{%
\ifmultic@l \k=\cnum \advance\k by -1
\dimen0=\textwidth \divide\dimen0 by
\cnum \advance\dimen0 by -\k\colframsep
\hsize=\dimen0
\fi
\global\setbox\sfram=\vbox\bgroup}
{\vfill\egroup}
% \end{macrocode}
%\end{macro}
%\subsection{Commands for placing \texttt{boxes}}
%They are the commands directly charged to place the text on the
%page. They call, directly or indirectly, the primitive
%\DescribeMacro{\vsplit}|\vsplit| (for further details on its
%functioning see \TeX book \cite{knuth}).
%
%There are five macros: two for the option |multicol|, two for the
%package without options, and the last one shared (obviously it's
%\DescribeMacro{\v@idb@xtwo}|\v@idb@xtwo|, typesetting a void
%|\box| at the bottom of the page, when |\sfram| is void). Arguments
%are passed by |\Place|, consisting in fractions of |\textheight|,
%but, as can be easily seen, in the two macros used by |multicol|
%(\DescribeMacro{\b@xbalance}|\b@xbalance| and
%\DescribeMacro{\v@idb@xbalance}|\v@idb@xbalance|) only two
%arguments are visible. The third has been swallowed by
%\DescribeMacro{\rigidbalance}|\rigidbalance|, a macro to be
%examined in the following.
% \begin{macrocode}
\newcommand{\b@xbalance}{%
\vbox to\initskip{}
\vsplit\ffram to \flength
\smallskip \hrule \smallskip
\rigidbalance}
% \end{macrocode}
% \begin{macrocode}
\newcommand{\v@idb@xbalance}{%
\vbox to\initskip{}
\vbox to \flength{}
\smallskip \hrule \smallskip
\rigidbalance}
% \end{macrocode}
% \begin{macrocode}
\newcommand{\v@idb@xone}{%
\vbox to\initskip{}
\vbox to \flength{}
\smallskip \hrule \smallskip
\vsplit\sfram to \slength}
% \end{macrocode}
% \begin{macrocode}
\newcommand{\v@idb@xtwo}{%
\vbox to\initskip{}
\vsplit\ffram to \flength
\smallskip \hrule \smallskip
\vbox to \slength{}}
% \end{macrocode}
% \begin{macrocode}
\newcommand{\splitb@x}{%
\vbox to\initskip{}
\vsplit\ffram to \flength
\smallskip \hrule \smallskip
\vsplit\sfram to \slength}
% \end{macrocode}
%\begin{macro}{\rigidbalance}
%This macro has been taken, with remarkable adjustments, from the
%Appendix ``Dirty Tricks'' of the \TeX book (\cite{knuth}) and is
%needed to make sure that also on the last page the columns have
%all the same height. Namely, it checks the height of the content
%of the |box| and on the base of the outcome it calls the macro
%\DescribeMacro{\dosplits}|\dosplits| which splits the text in
%columns of normal height, or the macro
%\DescribeMacro{\dobalance}|\dobalance| which sets the height of
%the columns to the height of the remaining content of |\sfram|
%divided the number of columns and then splits the text.
% \begin{macrocode}
\newcommand{\rigidbalance}{\hsize=\textwidth \k=\cnum
\ifdim\ht\sfram>\cnum\slength
\myline{\splittopskip=\h \vbadness=10000 \hfilneg
\valign{##\vfil\cr\dosplits}}
\else
\myline{\temp=\ht\sfram \advance\temp by \baselineskip
\divide\temp by \cnum \splittopskip=\h \vbadness=10000
\hfilneg \valign{##\vfil\cr\dobalance}}
\fi}
\newcommand{\dosplits}{\ifnum\k>0 \noalign{\hfil}
\splitoff\global\advance\k-1\cr\dosplits\fi}
\newcommand{\splitoff}{
\vsplit\sfram to \slength}
\newcommand{\dobalance}{\ifnum\k>0 \noalign{\hfil}
\finalbalance\global\advance\k-1\cr\dobalance\fi}
\newcommand{\finalbalance}{
\vsplit\sfram to \temp}
% \end{macrocode}
%I had also to define a new command
%\DescribeMacro{\myline}|\myline| restoring the original meaning of
%|\line|, because it has been modified in the \LaTeX\ format.
% \begin{macrocode}
\newcommand{\myline}{\hbox to\hsize}
% \end{macrocode}
%\end{macro}
%\begin{macro}{\m@kelayout}
%The macro |\m@kelayout| executes tests on the content of |\ffram|
%and |\sfram| and on the base of their outcome calls a particular
%subroutine for placing |boxes| and let appear on the terminal any
%needed warning. All this regarding the presence or the absence of
%the option |multicol|.
% \begin{macrocode}
\newcommand{\m@kelayout}{%
\ifmultic@l
\whiledo{\ht\ffram>0 \AND \ht\sfram>0}{\b@xbalance}
\ifthenelse{\ht\ffram>0 \AND \ht\sfram=0}{\whiledo{\ht\ffram>0
\AND \ht\sfram=0}{\v@idb@xtwo}
\sec@nderror}
\ifthenelse{\ht\ffram=0 \AND \ht\sfram>0}{\whiledo{\ht\ffram=0
\AND \ht\sfram>0}{\v@idb@xbalance}
\sec@nderror}
\else
\whiledo{\ht\ffram>0 \AND \ht\sfram>0}{\splitb@x}
\ifthenelse{\ht\ffram>0 \AND \ht\sfram=0}{\whiledo{\ht\ffram>0
\AND \ht\sfram=0}{\v@idb@xtwo}
\sec@nderror}
\ifthenelse{\ht\ffram=0 \AND \ht\sfram>0}{\whiledo{\ht\ffram=0
\AND \ht\sfram>0}{\v@idb@xone}
\sec@nderror}
\fi
\UsefulLengthsTable}
% \end{macrocode}
%\end{macro}
%\begin{macro}{\UserDefWidths}
%\changes{v1.1}{2003/11/18}{name changed from \cs{Frame} to \cs{UserDefWidths};
% some adjustments made.}
%The macro |\UserDefWidths| translates the arguments given by the
%user in the relative dimensions, executes the check on the
%resulting amount of the single fractions and, in case they exceed
%the dimension of |\textheight| calls the consequent warning; then
%it calls |\m@kelayout|.
% \begin{macrocode}
\newcommand{\UserDefWidths}[2]{
\setlength{\actualheight}{%
\textheight-2\smallskipamount-\topskip-\baselineskip}
\flength=.#1\actualheight \slength=.#2\actualheight
\test=\flength \advance\test by \slength
\ifdim\test>\actualheight
\firsterror
\fi
\m@kelayout
}
% \end{macrocode}
%\end{macro}
%\begin{macro}{\AutoCompute}
%\changes{v1.1}{2003/11/18}{new macro \cs{AutoCompute} added.}
%The macro |\AutoCompute|, just as the name says, tries to
%automatically compute the optimal division of the page in the two
%regions where the boxes will be placed, so that the text will be
%well balanced. Actually the macro does not take in consideration
%the whole |\textheight| during computation, but a newly defined
%dimension, |\actualheight|, standing for the \emph{actual} height
%of the bodytext (in its definition is also involved the length
%|\initskip|, which can be used to insert an additional space
%between the header and the first box). During computation, scaling
%is needed to avoid exceeding |\maxdimen|, especially when the
%multicolumn option is active.
% \begin{macrocode}
\newcommand{\AutoCompute}{%
\setlength{\actualheight}{%
\textheight-2\smallskipamount-\topskip-\baselineskip-\initskip}
\ifmultic@l
\setlength{\total}{\cnum\ht\ffram+\ht\sfram}
\divide\total by 10 \divide\actualheight by 10%
\setlength{\nop}{1pt*\ratio{\total}{\cnum\actualheight}}
\setlength{\flength}{1pt*\ratio{\ht\ffram}{\nop}}
\setlength{\slength}{1pt*\ratio{\ht\sfram}{\cnum\nop}}
\else
\setlength{\total}{\ht\ffram+\ht\sfram}
\divide\total by 10 \divide\actualheight by 10%
\setlength{\nop}{1pt*\ratio{\total}{\actualheight}}
\setlength{\flength}{1pt*\ratio{\ht\ffram}{\nop}}
\setlength{\slength}{1pt*\ratio{\ht\sfram}{\nop}}
\fi
\setlength{\ffrac}{1pt*\ratio{\flength}{10\actualheight}}
\setlength{\sfrac}{1pt*\ratio{\slength}{10\actualheight}}
\m@kelayout
}
% \end{macrocode}
%\end{macro}
%\begin{macro}{\Place}
%\changes{v1.1}{2003/11/18}{new macro \cs{Place} added.}
%The macro |\Place| is merely a switcher between |\AutoCompute| and
%|\UserDefWidths|.
% \begin{macrocode}
\newcommand{\Place}{%
\@ifstar{\AutoCompute}{\UserDefWidths}}
% \end{macrocode}
%\end{macro}
%\subsection{Warnings}
% \begin{macrocode}
\newcommand{\UsefulLengthsTable}{%
\AtEndDocument{\immediate\write\m@ne{******************************************^^J%
ffrac=\the\ffrac, sfrac=\the\sfrac^^J%
flength=\the\flength, slength=\the\slength^^J%
******************************************}}
}
\newcommand{\firsterror}{\PackageError{parrun}{%
Warning: Text fractions exceeding \string\textheight}
{The total dimension of
the single fractions of text exceeds \string\textheight.^^J%
You probably should reconsider the parameters in \string\Place.^^J%
However, if you are sure of what you have done, you can go on.^^J%
Luck!}}
\newcommand{\sec@nderror}{\PackageError{parrun}{%
Warning: the box still contains some text}
{Your text is not well balanced. Probably you'll get a bad ^^J%
output. You should reconsider your document's layout.^^J%
You will find at the end of the log file some useful^^J%
length for dealing with.}
}
%</parrun>
% \end{macrocode}
%\Finale
\endinput
To achieve his task, the command |\Place| calls two internal
macros: \DescribeMacro{\AutoCompute}|\AutoCompute| for the starred
version and |\UserDefWidths| for the unstarred version. In the
second occurrence a bug has been detected: a message of |undefined
control sequence| appears on the terminal for the command |\AND|,
and at the end of the document is typeset the following sequence
of characters: |�0|.