From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex/contrib/parrun/parrun.dtx | 490 +++++++++++++++++++++++++++++++++ 1 file changed, 490 insertions(+) create mode 100644 macros/latex/contrib/parrun/parrun.dtx (limited to 'macros/latex/contrib/parrun/parrun.dtx') diff --git a/macros/latex/contrib/parrun/parrun.dtx b/macros/latex/contrib/parrun/parrun.dtx new file mode 100644 index 0000000000..67823c3f3b --- /dev/null +++ b/macros/latex/contrib/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} +% +%\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.} +} +% +% \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|. -- cgit v1.2.3