summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/parrun
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/parrun')
-rw-r--r--Master/texmf-dist/source/latex/parrun/parrun.dtx490
-rw-r--r--Master/texmf-dist/source/latex/parrun/parrun.ins8
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
generated by cgit v1.2.3 (git 2.39.1) at 2024-11-16 14:36:49 +0000