trunk/Master/texmf-dist/source/latex/parrun

git-svn-id: svn://tug.org/texlive/trunk@436 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 498 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex/parrun/parrun.dtx b/Master/texmf-dist/source/latex/parrun/parrun.dtx
new file mode 100644
index 00000000000..67823c3f3bb
--- /dev/null
+++ b/Master/texmf-dist/source/latex/parrun/parrun.dtx
@@ -0,0 +1,490 @@
+%\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|.
diff --git a/Master/texmf-dist/source/latex/parrun/parrun.ins b/Master/texmf-dist/source/latex/parrun/parrun.ins
new file mode 100644
index 00000000000..02034dcded0
--- /dev/null
+++ b/Master/texmf-dist/source/latex/parrun/parrun.ins
@@ -0,0 +1,8 @@
+\input docstrip.tex
+
+\usedir{tex/latex/parrun}
+
+\generate{\file{parrun.sty}{\from{parrun.dtx}{parrun}}
+         }
+
+\endbatchfile