path: root/macros/latex/contrib/parrun/parrun.dtx

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