summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/parrun/parrun.dtx
blob: 67823c3f3bb27b3d9c58c5b6a213b65b5fd5c1d1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
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|.