Debian Codegraph @

texmf-dist/source/latex/sauerj/parcolumns.dtx

raw
1 % \iffalse meta-comment
2 % Line endings: UNIX
3 % Tab size: 4
4 %
5 % Copyright 2004 Jonathan Sauer
6 %
7 % This work may be distributed and/or modified under the
8 % conditions of the LaTeX Project Public License, either version 1.3
9 % of this license or (at your option) any later version.
10 % The latest version of this license is in
11 %
12 % http://www.latex-project.org/lppl.txt
13 %
14 % and version 1.3 or later is part of all distributions of LaTeX
15 % version 2003/12/01 or later.
16 %
17 % This work has the LPPL maintenance status "maintained".
18 %
19 % The Current Maintainer of this work is Jonathan Sauer
20 % (<[email protected]>).
21 %
22 % This work consists of the files parcolumns.dtx and parcolumns.ins
23 % and the derived file parcolumns.sty.
24 %
25 % \fi
26 %
27 % \iffalse
28 %
29 %<*driver>
30 \documentclass{ltxdoc}
31 \usepackage{parcolumns}
32 \EnableCrossrefs
33 \CodelineIndex
34 \RecordChanges
35 % Modification of verbatim for tabs in listings
36 \makeatletter
37 {\catcode`\ =\active%
38 \catcode`\^^I=\active%
39 \gdef\@vobeyspaces{%
40 \catcode`\ \active\let \@xobeysp%
41 \catcode`\^^I\active\def^^I{~~}%
42 }}%
43 \makeatother
44 \begin{document}
45 \DocInput{\jobname.dtx}
46 \end{document}
47 %</driver>
48 %
49 %<package>\NeedsTeXFormat{LaTeX2e}
50 %<package>\ProvidesPackage{parcolumns}
51 %<package> [2004/11/25 v1.2 Typeset multiple parallel columns]
52 %<package>\RequirePackage{processkv}[2004/08/05]
53 %
54 % \fi
55 %
56 % \CheckSum{368}
57 % \CharacterTable
58 % {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
59 % 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
60 % Digits \0\1\2\3\4\5\6\7\8\9
61 % Exclamation \! Double quote \" Hash (number) \#
62 % Dollar \$ Percent \% Ampersand \&
63 % Acute accent \' Left paren \( Right paren \)
64 % Asterisk \* Plus \+ Comma \,
65 % Minus \- Point \. Solidus \/
66 % Colon \: Semicolon \; Less than \<
67 % Equals \= Greater than \> Question mark \?
68 % Commercial at \@ Left bracket \[ Backslash \\
69 % Right bracket \] Circumflex \^ Underscore \_
70 % Grave accent \` Left brace \{ Vertical bar \|
71 % Right brace \} Tilde \~}
72 %
73 % \DoNotIndex{\@clubpenalty,\@doendpe,\@ehc,\@ifundefined,\@M,\@ne}
74 % \DoNotIndex{\@one,\@nobreakfalse,\@plus,\@tempa,\@tempb,\@tempboxa}
75 % \DoNotIndex{\@tempcnta,\@tempdima,\@tempdimb,\@tempdimc}
76 % \DoNotIndex{\@tempswafalse,\@testopt,\advance,\afterassignment}
77 % \DoNotIndex{\box,\brokenpenalty,\clubpenalty,\count@,\csname}
78 % \DoNotIndex{\def,\define@key,\displaywidowpenalty,\divide,\dp,\edef}
79 % \DoNotIndex{\else,\endcsname,\endgraf,\everypar,\expandafter}
80 % \DoNotIndex{\fi,\global,\hbadness,\hb@xt@,\hfill,\hsize,\hskip}
81 % \DoNotIndex{\if@tempswa,\ifnum,\ifvoid,\ifx,\interlinepenalty}
82 % \DoNotIndex{\lastbox,\leavevmode,\let,\linewidth,\long,\loop}
83 % \DoNotIndex{\m@ne,\multiply,\newbox,\newcommand,\newcount}
84 % \DoNotIndex{\newdimen,\newenvironment,\newif,\newtoks}
85 % \DoNotIndex{\number,\PackageError,\PackageInfo,\processkeyvalues}
86 % \DoNotIndex{\relax,\repeat,\setbox,\setkeys,\space,\spaceskip}
87 % \DoNotIndex{\splittopsep,\splittopskip,\strut,\strutbox,\the}
88 % \DoNotIndex{\toks@,\tolerance,\unvbox,\vbadness,\vbox,\vfuzz}
89 % \DoNotIndex{\vrule,\vsplit,\widowpenalty,\z@,\z@skip,\\}
90 %
91 % \GetFileInfo{\jobname.sty}
92 %
93 % \title{The \textsf{parcolumns} package\thanks{This document
94 % corresponds to \textsf{\filename}~\fileversion, dated \filedate.}}
95 %
96 % \author{Jonathan Sauer \\ \texttt{[email protected]}}
97 %
98 % \date{\filedate}
99 %
100 % \maketitle
101 %
102 % \begin{abstract}
103 % This file describes the \textsf{parcolumns} package that provides an
104 % environment for typesetting text in two or more columns columns in
105 % parallel.
106 %
107 % \end{abstract}
108 %
109 % \tableofcontents
110 %
111 % \section{Introduction}
112 %
113 % Sometimes it is necessary to typeset text in two or more columns in
114 % parallel, i.e. when typesetting a text in its original language and
115 % in its translation(s). This package provides the \verb|parcolumns|
116 % environment for typesetting text in several columns, where the text
117 % of all columns is aligned vertically.
118 %
119 % Text in the |parcolums| environment is typeset in chunks, where the
120 % chunks of one row are aligned vertically. A chunk consists of one or
121 % more paragraphs of text, including \TeX\ macros.
122 %
123 %
124 % \section{Usage}\label{sec:Usage}
125 %
126 % \DescribeEnv{parcolumns} Usage: |parcolumns| \oarg{options}
127 % \marg{number of colums}.
128 %
129 % Inside the |parcolumns| environment text can be typeset in two or
130 % more columns in parallel via the |\parchunk| macro. Normal text can
131 % also be included.
132 %
133 % The \verb|parcolumns| environment takes an optional parameter that
134 % specifies the options for the environment using the \textsf{keyval}
135 % and \textsf{processkv} packages. The following options exist:
136 %
137 % \begin{description}
138 % \item[\emph{colwidths}] Sets the widths of the columns. The
139 % widths are specified as key-values,
140 % \meta{columnnumber}=\meta{width}.
141 % Columns start at `1'. Note that in
142 % order to be ignored by the
143 % \textsf{keyval} package, the complete
144 % value has to be surrounded by braces,
145 % i.e. `|colwidths={1=2cm,3=5cm,4=2cm}|'
146 % to set the first column to a width of
147 % 2~cm, the third to 5~cm and the fourth
148 % to 2~cm. (the second column is
149 % calculated)
150 %
151 % Columns not set this way will be
152 % distributed evenly across the remaining
153 % horizontal space of the page.
154 %
155 % \item[distance] Sets the distance between two columns.
156 % If omitted set to \verb|2em|.
157 %
158 % \item[rulebetween] (Flag)\footnote{Meaning that if you
159 % just say \texttt{rulebetween}, you set the
160 % flag, as well as when you say
161 % \texttt{rulebetween=true}. Saying
162 % \texttt{rulebetween=false} clears the flag,
163 % even though this does not make much sense,
164 % as it is the default.}
165 % Typeset a vertical bar between two
166 % columns.
167 %
168 % |false| if omitted.
169 %
170 % \item[nofirstindent] (Flag) Suppress the indentation of the first
171 % paragraph in the environment.
172 %
173 % |false| if omitted.
174 %
175 % \item[sloppy] (Flag) Typeset text in the columns in a
176 % more sloppy way, preventing overfull
177 % hboxes at the cost of larger
178 % interword spacing.
179 %
180 % |false| if omitted.
181 %
182 % \item[sloppyspaces] (Flag) Makes spaces in the columns
183 % stretchable, preventing overfull
184 % hboxes at the cost of even larger
185 % interword spacing that |sloppy|.
186 %
187 % |false| if omitted.
188 %
189 % \end{description}
190 %
191 %
192 % \DescribeMacro{\colchunk} Usage: |\colchunk| \oarg{column}
193 % \marg{chunk}.
194 %
195 % The macro |\colchunk| sets a chunk of text for the next column. You
196 % don't have to set chunks for all columns; the colums not set remain
197 % empty. However, the columns are filled from left to right, so if a
198 % column inbetween should remain empty, you must say |\colchunk{}| or
199 % specify the column to set using the optional parameter (columns
200 % start at 1): |\colchunk[2]{|\ldots|}| sets the text of the second
201 % column. Following calls to |\colchunk| without optional parameter
202 % fill the third, fourth et cetera column.
203 %
204 % After a call to |\colplacechunks|, the column number is reset to
205 % one.
206 %
207 %
208 %
209 % \DescribeMacro{\colplacechunks} Usage: |\colplacechunks|.
210 %
211 % The macro |\colplacechunks| places the chunks added with |\colchunk|
212 % on the page. If there are no chunks to place, it does nothing.
213 %
214 %
215 %
216 % \section{Examples}
217 %
218 % Two columns, option |rulebetween=true| (which is the same as
219 % just saying |rulebetween|):
220 %
221 % \addvspace{\baselineskip}
222 % \begin{parcolumns}[rulebetween=true]{2}
223 % \colchunk{Erwarten Sie von mir, dass ich rede? -- Nein, Mister
224 % Bond, ich erwarte von Ihnen, dass Sie sterben!}
225 %
226 % \colchunk{Do you expect me to talk? -- No, Mister Bond, I expect you
227 % to die!}
228 %
229 % \colplacechunks
230 %
231 % \colchunk{Erwarten Sie von mir, dass ich rede? -- Nein, Mister
232 % Bond, ich erwarte von Ihnen, dass Sie sterben!}
233 %
234 % \colchunk{Do you expect me to talk? -- No, Mister Bond, I expect you
235 % to die!}
236 %
237 % \colplacechunks
238 %
239 % \end{parcolumns}
240 % \addvspace{\baselineskip}
241 % As the german text is slightly longer, let's make the left column
242 % alittle bit larger using |colwidths={1=.55\linewidth}|:
243 %
244 % \addvspace{\baselineskip}
245 % \begin{parcolumns}[rulebetween=true,colwidths={1=.55\linewidth}]{2}
246 % \colchunk{Erwarten Sie von mir, dass ich rede? -- Nein, Mister
247 % Bond, ich erwarte von Ihnen, dass Sie sterben!}
248 %
249 % \colchunk{Do you expect me to talk? -- No, Mister Bond, I expect you
250 % to die!}
251 %
252 % \colplacechunks
253 %
254 % \colchunk{Erwarten Sie von mir, dass ich rede? -- Nein, Mister
255 % Bond, ich erwarte von Ihnen, dass Sie sterben!}
256 %
257 % \colchunk{Do you expect me to talk? -- No, Mister Bond, I expect you
258 % to die!}
259 %
260 % \colplacechunks
261 %
262 % \end{parcolumns}
263 % \addvspace{\baselineskip}
264 % Three columns, option |nofirstindent=true|:
265 %
266 % \addvspace{\baselineskip}
267 % \begin{parcolumns}[nofirstindent]{3}
268 % \colchunk{This is just a short english text, just long enough to fill
269 % a few lines.}
270 %
271 % \colchunk{Dies ist nur ein kurzer deutscher Text, gerade lang genug,
272 % um ein paar Zeilen zu fuellen.}
273 %
274 % \colchunk{This is another short english text, as my french is not
275 % that good anymore.}
276 %
277 % \colplacechunks
278 %
279 % \end{parcolumns}
280 % \addvspace{\baselineskip}
281 % There was an overfull |\hbox| in the previous text. Let's
282 % try that again with the option |sloppy|:
283 %
284 % \addvspace{\baselineskip}
285 % \begin{parcolumns}[nofirstindent,sloppy]{3}
286 % \colchunk{This is just a short english text, just long enough to fill
287 % a few lines.}
288 %
289 % \colchunk{Dies ist nur ein kurzer deutscher Text, gerade lang genug,
290 % um ein paar Zeilen zu fuellen.}
291 %
292 % \colchunk{This is another short english text, as my french is not
293 % that good anymore.}
294 %
295 % \colplacechunks
296 %
297 % \end{parcolumns}
298 % \addvspace{\baselineskip}
299 % No overfull hbox this time, but the spacing in the first column
300 % is not optimal. You just have to pick what's better. Or you could
301 % try the interword spacing provided by the \textsf{soul} package.
302 %
303 % \addvspace{\baselineskip}\noindent Maybe we do not want to fill the
304 % first column, but do not want to type |\colchunk{}| either. Then we
305 % can say |\colchunk[2]| to directly start with the second column
306 % (note that we are using the option |sloppy|, too):
307 %
308 % \addvspace{\baselineskip}
309 % \begin{parcolumns}[nofirstindent,sloppy]{3}
310 % \colchunk[2]{This is just a short english text, just long enough to fill
311 % a few lines.}
312 %
313 % \colchunk{Dies ist nur ein kurzer deutscher Text, gerade lang genug,
314 % um ein paar Zeilen zu fuellen.}
315 %
316 % \colplacechunks
317 %
318 % \end{parcolumns}
319 % \addvspace{\baselineskip}
320 % Note that \texttt{parcolumns} does not insert vertical space
321 % before or after the environment! In these examples, the space has
322 % manually been added with |\addvspace|.
323 %
324 %
325 %
326 % \section{Notes}\label{sec:Notes}
327 %
328 % \begin{itemize}
329 % \item The columns will always fill the complete width of the
330 % page by stretching or shrinking the space between the columns.
331 % That means that if the total width of all columns is set
332 % to about half the page width, the space between the columns
333 % will take up the rest, ignoring whatever was set with the
334 % key |distance|.\footnote{The key \texttt{distance} is only
335 % used for calculating the width of the columns and is ignored
336 % afterwards.}
337 %
338 % \item Footnotes are not set in columns.
339 %
340 % \item \textsf{parcolumns} does not work very well with displayed
341 % formula. The best way to typeset a |displaymath| et.al.
342 % environment is to include it in separate |\colchunk|
343 % commands, i.e. (assuming two columns and the same formula
344 % in both):
345 %
346 % \begin{verbatim}
347 % ... some text placed using \colchunk ...
348 % \colchunk{ % Left column
349 % \begin{displaymath}
350 % x^2 + y^2 = z^2
351 % \end{displaymath}
352 % }
353 % \colchunk{ % Right column
354 % \begin{displaymath}
355 % x^2 + y^2 = z^2
356 % \end{displaymath}
357 % }
358 % \colplacechunks
359 % ... some more text placed using \colchunk ...
360 % \end{verbatim}
361 %
362 % \end{itemize}
363 %
364 %
365 %
366 % \StopEventually{}
367 %
368 % \section{Implementation}
369 %
370 % \subsection{Allocation}
371 %
372 % The current column (starting with one):
373 %
374 % \begin{macrocode}
375 \newcount\pc@columnctr
376 % \end{macrocode}
377 %
378 % The total number of columns in the current |parcolums| environment.
379 %
380 % \begin{macrocode}
381 \newcount\pc@columncount
382 % \end{macrocode}
383 %
384 % Place a vertical rule between two columns?
385 %
386 % \begin{macrocode}
387 \newif\ifpc@rulebetween
388 % \end{macrocode}
389 %
390 % Stores |\everypar| for use in |\parparagraphs|.
391 %
392 % \begin{macrocode}
393 \newtoks\pc@everypar
394 % \end{macrocode}
395 %
396 % Note that additional allocations are performed later on-demand in
397 % |\pc@alloccolumns|.
398 %
399 %
400 %
401 % \subsection{\textsf{keyvalue} keys}
402 %
403 % \begin{macro}{\pc@boolkey}
404 %
405 % Sets an \verb|if|-condition in \marg{\#1} to the value passed as
406 % \marg{\#2}. If \verb|#2| is \verb|false|, set \verb|if#1| to
407 % \verb|false|, else (any other value) to \verb|true|.
408 %
409 % Usage: |\pc@boolkey| \marg{ifcondition} \marg{value}
410 %
411 % \begin{macrocode}
412 \def\pc@boolkey#1#2{%
413 \edef\@tempa{#2}%
414 \edef\@tempb{false}%
415 \ifx\@tempa\@tempb%
416 \csname #1false\endcsname%
417 \else%
418 \csname #1true\endcsname%
419 \fi%
420 }
421 % \end{macrocode}
422 % \end{macro}
423 %
424 %
425 % Define the keys for the options of |parcolumns|.
426 %
427 % \begin{macrocode}
428 \define@key{parcolumns}{distance}{%
429 \@tempdimc#1\relax%
430 }
431 \define@key{parcolumns}{rulebetween}[true]{%
432 \pc@boolkey{pc@rulebetween}{#1}%
433 }
434 \define@key{parcolumns}{nofirstindent}[true]{%
435 \pc@boolkey{@tempswa}{#1}%
436 % \end{macrocode}
437 %
438 % If the indentation of the first line of the first paragraph should
439 % be suppressed, change |\pc@everypar| accordingly. The token register
440 % is reset after the placing of the first row of chunks in
441 % |\colplacechunks|.
442 %
443 % What exactly are we doing? First we assign box 0 the contents of
444 % |\lastbox|. At the beginning of a paragraph |\lastbox| contains
445 % the glue inserted for the indentation of the first line. By
446 % assigning this box to box 0, we remove the indentation. We do
447 % this in a group as not to change the contents of box 0.
448 %
449 % Afterwards we set |\everypar| to nothing. This is necessary because
450 % we only want to suppress the indentation for the first paragraph of
451 % the |parcolumns| environment, not every paragraph. We set
452 % |\everypar| and not |\pc@everypar| to nothing, because
453 % |\pc@everypar| is only a temporary storage that will be assigned to
454 % |\everypar| when used.
455 %
456 % \begin{macrocode}
457 \if@tempswa\pc@everypar{{\setbox\z@\lastbox}\everypar{}}\fi%
458 }
459 \define@key{parcolumns}{sloppy}[true]{%
460 \pc@boolkey{@tempswa}{#1}%
461 % \end{macrocode}
462 %
463 % If sloppy typesetting is asked for, we set |\hbadness| and
464 % |\tolerance| to 10000, so that \TeX\ breaks lines whenever possible,
465 % even if this means high interword spacing.
466 %
467 % \begin{macrocode}
468 \if@tempswa%
469 \hbadness\@M%
470 \tolerance\@M%
471 \fi%
472 }
473 \define@key{parcolumns}{sloppyspaces}[true]{%
474 \pc@boolkey{@tempswa}{#1}%
475 % \end{macrocode}
476 %
477 % If sloppy spaces are asked for, we make the space stretchable:
478 %
479 % \begin{macrocode}
480 \if@tempswa%
481 \spaceskip.3333em\@plus1em %
482 \fi%
483 }
484 % \end{macrocode}
485 %
486 %
487 % We save the key-value-list containing widths of the columns in
488 % |\toks@| for later use in |\pc@setcolumnwidths|.
489 %
490 % \begin{macrocode}
491 \define@key{parcolumns}{colwidths}{%
492 \toks@{#1}%
493 }
494 % \end{macrocode}
495 %
496 %
497 % \subsection{Main environments and macros}
498 %
499 % \begin{environment}{parcolumns}
500 %
501 % Environment for a number of columns of text set in parallel (see
502 % section \ref{sec:Usage} on page \pageref{sec:Usage} for the possible
503 % options)
504 %
505 % Usage: |\begin{parcolumns}| \oarg{options} \marg{number of columns}
506 % \ldots\ |\end{parcolums}|
507 %
508 % \begin{macrocode}
509 \newenvironment{parcolumns}[2][]{%
510 \pc@rulebetweenfalse%
511 % \end{macrocode}
512 %
513 % |\if@tempswa| is |true|, if the indentation of the first line
514 % should be suppressed, otherwise |false|. Default is |false|:
515 %
516 % \begin{macrocode}
517 \@tempswafalse%
518 % \end{macrocode}
519 %
520 % |\@tempdimc| contains the space between two columns. Default
521 % is |2em|:
522 %
523 % \begin{macrocode}
524 \@tempdimc2em\relax%
525 % \end{macrocode}
526 %
527 % We set the options:
528 %
529 % \begin{macrocode}
530 \toks@{}%
531 \setkeys{parcolumns}{#1}%
532 % \end{macrocode}
533 %
534 % We store the total number of columns and reset the counter for
535 % the current column:
536 %
537 % \begin{macrocode}
538 \pc@columncount#2 %
539 \pc@columnctr\z@%
540 % \end{macrocode}
541 %
542 % We allocate the columns and set their widths:
543 %
544 % \begin{macrocode}
545 \pc@alloccolumns%
546 \pc@setcolumnwidths%
547 % \end{macrocode}
548 %
549 % We switch to vertical mode:
550 %
551 % \begin{macrocode}
552 \endgraf%
553 % \end{macrocode}
554 %
555 % As we are changing |\everypar|, we need to make sure that the most
556 % important flag is reset, which normally happens in the |\everypar|
557 % of a |\section|-command: |\if@nobreak|. (otherwise the next section
558 % is typeset directly after the text of the previous section instead
559 % of leaving some space)\footnote{I discovered this the hard way,
560 % spending one or two hours wondering why the spacing between two
561 % sections was much too small.}
562 %
563 % \begin{macrocode}
564 \@nobreakfalse%
565 % \end{macrocode}
566 %
567 % We reset |\everypar|, as it is of no use for us and can only screw
568 % up things badly:
569 %
570 % \begin{macrocode}
571 \global\everypar{}%
572 }{%
573 % \end{macrocode}
574 %
575 % At the end of the |parcolumns|-environment \ldots\ just in case, we
576 % place the last chunks, if not already done so:
577 %
578 % \begin{macrocode}
579 \colplacechunks%
580 \endgraf%
581 % \end{macrocode}
582 %
583 % We reset |\clubpenalty| globally to its normal value (the |\global|
584 % makes sure that if |\everypar| should have reset |\clubpenalty|, it
585 % is reset now).
586 %
587 % \begin{macrocode}
588 \global\clubpenalty\@clubpenalty%
589 % \end{macrocode}
590 %
591 % We suppress the indentation of the next paragraph immediately
592 % following the environment:
593 %
594 % \begin{macrocode}
595 \@doendpe%
596 }
597 % \end{macrocode}
598 % \end{environment}
599 %
600 %
601 % \begin{macro}{\colchunk}
602 %
603 % Sets the text for the next chunk of the next column.
604 %
605 % Usage: |\colchunk| \oarg{column} \marg{chunk}. (note that the |{|
606 % and |}| are \emph{not} optional, even if the chunk consists of only
607 % one token!)
608 %
609 % We need two macros for handling the optional parameter
610 % \meta{column}, |\colchunk| and |\colchunk@|. First we define
611 % |\colchunk|:
612 %
613 % \changes{1.1}{2004/08/22}{Optional parameter added.}
614 %
615 % \begin{macrocode}
616 \newcommand{\colchunk}{\@testopt\colchunk@{}}%
617 % \end{macrocode}
618 % \end{macro}
619 %
620 %
621 % \begin{macro}{\colchunk@}
622 %
623 % What are we doing now? By suffixing the last (optional) parameter by
624 % |#|, we tell \TeX\ that the last parameter of |\colchunk| is to be
625 % delimited by a right brace |{|, or \TeX\ will complain with a more
626 % comprehensible message that without the |#|: `Use of |\colchunk|
627 % doesn't match its definition.' instead of `Missing |{| inserted.'
628 %
629 % \changes{1.0.1}{2004/08/10}{Parameter added.}
630 % \changes{1.1}{2004/08/22}{Optional parameter added.}
631 %
632 % \begin{macrocode}
633 \long\def\colchunk@[#1]#{%
634 % \end{macrocode}
635 %
636 % We check if the optional parameter is not empty. Then we use it as
637 % the column number, otherwise we simply pick the next column:
638 %
639 % \begin{macrocode}
640 \ifx\\#1\\%
641 \advance\pc@columnctr\@ne%
642 \else%
643 \pc@columnctr#1\relax%
644 \fi%
645 % \end{macrocode}
646 %
647 % If we try to add a column past the last one, we display an error
648 % message:
649 %
650 % \begin{macrocode}
651 \ifnum\pc@columnctr>\pc@columncount%
652 \PackageError{parcolumns}{The column \number\pc@columnctr\space%
653 is too large}{Only \number\pc@columncount\space columns are%
654 \space allowed.}
655 % \end{macrocode}
656 %
657 % As we cannot simply skip the chunk (we could gobble what follows
658 % after the macro, but this would require a lot of jumping, and just
659 % for handling a small mistake \ldots), we simply set the last column:
660 %
661 % \changes{1.0.1}{2004/08/10}{Error handling somewhat improved.}
662 %
663 % \begin{macrocode}
664 \pc@columnctr\pc@columncount%
665 \fi%
666 % \end{macrocode}
667 %
668 % We zero the |\clubpenalty| that could have been changed, i.e. by
669 % |\everypar| of a |\section|-command: |\section| changes the
670 % clubpenalty to prevent a break between the first two lines of the
671 % paragraph following immediately after the section; as we split off
672 % line after line when typesetting the two columns, this would make
673 % splitting of a single line impossible (|\vsplit| uses the same logic
674 % as page-breaking), thus resulting in a lot of overfull vboxes and
675 % weird spacing inbetween, as \emph{two} lines would be split off.
676 %
677 % We do this every time we add chunks just in case some macro in the
678 % chunks has changed |\clubpenalty|. Note that we cannot prevent a
679 % macro in the text of the chunk to change the
680 % |\clubpenalty|.\footnote{Well we could, by redefining the
681 % clubpenalty to be a macro that simply throws its parameter away, and
682 % using some tricks to make this macro behave like a register,
683 % therefore completely ignoring any change of the clubpenalty.} But if
684 % it is changed, at least it will not stay changed (though the typeset
685 % columns will still look bad).
686 %
687 % \changes{1.0.1}{2004/08/09}{clubpenalty is always reset before
688 % adding chunks}
689 %
690 % \begin{macrocode}
691 \clubpenalty\z@%
692 % \end{macrocode}
693 %
694 % The same goes for the other penalties \TeX\ will insert between two
695 % lines, as we absolutely, positively \emph{must} be able to break
696 % between any two lines:\footnote{C.f. chapter 14 of the \TeX book}
697 %
698 % \changes{1.2}{2004/11/25}{other penalties added}
699 %
700 % \begin{macrocode}
701 \interlinepenalty\z@%
702 \displaywidowpenalty\z@%
703 \widowpenalty\z@%
704 \brokenpenalty\z@%
705 % \end{macrocode}
706 %
707 % We set |\everypar| to our self-defined |\pc@everypar| to suppress
708 % the indentation of the first paragraph if so desired:
709 %
710 % \begin{macrocode}
711 \everypar\expandafter{\the\pc@everypar}%
712 % \end{macrocode}
713 %
714 % After the next assignment, insert the width of the column:
715 %
716 % \begin{macrocode}
717 \afterassignment\pc@setcolumnwidth%
718 % \end{macrocode}
719 %
720 % We typeset the chunk's text into the box |\pc@column@|\meta{column
721 % counter}. The text of the chunk follows the macro, meaning that the
722 % last line looks like this: |\vbox{|\meta{chunk text}|}|.
723 %
724 % But what about the width of the box? |\hsize| must be set in the
725 % vbox in order to make it the correct width! We achieve this using
726 % the |\afterassignment| above: After the assignment of the chunk's
727 % text to the box, we are inside the box, therefore the contents of
728 % |\pc@setcolumnwidth| is inserted at the very beginning of the vbox,
729 % setting the correct width.
730 %
731 % Why don't we simply make |\colchunk| take one parameter that
732 % contains the text of the chunk? Because in that case, macros that
733 % change catcodes like |\verb| would be prohibited, which would
734 % restrict this package somewhat. Also it would be slower and would
735 % use more memory.
736 %
737 % \begin{macrocode}
738 \expandafter\setbox\csname pc@column@\number\pc@columnctr\endcsname%
739 \vbox%
740 }
741 % \end{macrocode}
742 % \end{macro}
743 %
744 %
745 % \begin{macro}{\colplacechunks}
746 %
747 % Places all chunks set with |\colchunk|.
748 %
749 % \begin{macrocode}
750 \newcommand{\colplacechunks}{%
751 % \end{macrocode}
752 %
753 % If there are any chunks to place:
754 %
755 % \begin{macrocode}
756 \ifnum\pc@columnctr>\z@%
757 % \end{macrocode}
758 %
759 % We place them:
760 %
761 % \begin{macrocode}
762 \pc@placeboxes%
763 % \end{macrocode}
764 %
765 % We reset the column counter:
766 %
767 % \begin{macrocode}
768 \pc@columnctr\z@%
769 % \end{macrocode}
770 %
771 % We clear |\pc@everypar|, because we only want to suppress the
772 % indentation of the first paragraph of each column at the very top of
773 % the |parcolumns| environment, not of the first paragraph of every
774 % call to |\colchunk|.
775 %
776 % \begin{macrocode}
777 \pc@everypar{}%
778 \fi%
779 }
780 % \end{macrocode}
781 % \end{macro}
782 %
783 %
784 %
785 %
786 % \subsection{Internal environments and macros}
787 %
788 % \begin{macro}{\pc@placeboxes}
789 %
790 % Places the prepared boxes (containing the chunks) on the page.
791 %
792 % \begin{macrocode}
793 \def\pc@placeboxes{%
794 % \end{macrocode}
795 %
796 % We assume we don't have to perform another line (|\@tempa| contains
797 % what we have to to after we are finished with this macro). The
798 % assignment is global because later on when changing |\@tempa| we are
799 % in a group:
800 %
801 % \begin{macrocode}
802 \global\let\@tempa\relax%
803 \count@\z@%
804 % \end{macrocode}
805 %
806 % We create a hbox. Inside a hbox, vboxes are put horizontally
807 % next to each other and are aligned on their baseline:
808 %
809 % \begin{macrocode}
810 \hb@xt@\linewidth{%
811 % \end{macrocode}
812 %
813 % Before doing any work, we change a few parameters:
814 %
815 % \changes{1.2}{2004/11/22}{moved parameter changes from begin of
816 % environment}
817 %
818 % We prevent warnings of overfull and underfull vboxes as they can
819 % happen, but we do not really care (happens when we |\vsplit| the top
820 % off the chunks, this is okay):
821 %
822 % \changes{1.2}{2004/11/22}{vfuzz increased to prevent warnings with
823 % math}
824 %
825 % \changes{1.2}{2004/11/22}{vbadness set}
826 %
827 % \begin{macrocode}
828 \vfuzz30ex %
829 \vbadness\@M%
830 % \end{macrocode}
831 %
832 % We prevent vertical glue to be insert when |vsplit|ting a vbox
833 % (otherwise it screws up the spacing).
834 %
835 % \begin{macrocode}
836 \splittopskip\z@skip%
837 % \end{macrocode}
838 %
839 % Now we loop over all the prepared boxes. We can use |\loop| here as
840 % we are in a group (begun by |\hbox|). Otherwise we would have to
841 % open a group manually or loop manually, as to not screw up a |\loop|
842 % outside the macro:
843 %
844 % \begin{macrocode}
845 \loop\ifnum\count@<\pc@columncount%
846 \advance\count@\@ne%
847 % \end{macrocode}
848 %
849 % If the box |\pc@column@|\meta{counter} is empty, we simply insert a
850 % hskip the width of the box (saved in
851 % |\pc@column@width@|\meta{counter}):
852 %
853 % \begin{macrocode}
854 \expandafter\ifvoid\csname pc@column@\number\count@%
855 \endcsname%
856 \hskip\csname pc@column@width@\number\count@\endcsname%
857 \else%
858 % \end{macrocode}
859 %
860 % Otherwise we |\vsplit| the first line of the box (at the same time
861 % removing it from |\pc@column@|\meta{counter}) and save it in
862 % |\@tempboxa|. Then, we strip this resulting box of its enclosing
863 % vbox and put it into another vbox, which we put into the hbox begun
864 % a few lines ago.
865 %
866 % Why is this so complicated? To ensure that proper vertical glue is
867 % inserted (otherwise the spacing between the lines would be wrong).
868 %
869 % \begin{macrocode}
870 \expandafter\setbox\expandafter\@tempboxa\expandafter%
871 \vsplit\csname pc@column@\number\count@\endcsname%
872 to \dp\strutbox%
873 \vbox{\unvbox\@tempboxa}%
874 \fi%
875 % \end{macrocode}
876 %
877 % If the remaining box is not empty, we have to perform at least
878 % another line:
879 %
880 % \begin{macrocode}
881 \expandafter\ifvoid\csname pc@column@\number\count@%
882 \endcsname\else%
883 \global\let\@tempa\pc@placeboxes%
884 \fi%
885 % \end{macrocode}
886 %
887 % If this is not the last column, we put a strut into the hbox to
888 % ensure propery vertical spacing:
889 %
890 % \begin{macrocode}
891 \ifnum\count@<\pc@columncount%
892 \strut%
893 % \end{macrocode}
894 %
895 % If a vertical line should be placed between two columns, we insert
896 % it now, centering it between two |\hfill|s. Otherwise, we simply
897 % insert a |\hfill| that stretches as much as possible, pushing the
898 % right column to the right margin. (see also section \ref{sec:Notes}
899 % on page \pageref{sec:Notes})
900 %
901 % \begin{macrocode}
902 \hfill%
903 \ifpc@rulebetween%
904 \vrule%
905 \hfill%
906 \fi%
907 \fi%
908 \repeat%
909 }%
910 % \end{macrocode}
911 %
912 % If necessary, we perform another line:
913 %
914 % \begin{macrocode}
915 \@tempa%
916 }
917 % \end{macrocode}
918 % \end{macro}
919 %
920 %
921 % \begin{macro}{\pc@alloccolumns}
922 %
923 % Allocates a number of |\box|es, named |\pc@column@1|, |\pc@column@2|
924 % et cetera, if not already allocated.
925 %
926 % Also allocates a number of |\dimen|s, named |\pc@column@width@1| et
927 % cetera.
928 %
929 % If the |\box|es and |\dimen|s are already allocated, they are
930 % cleared (|\box|es) or set to zero (|\dimen|s).
931 %
932 % \begin{macrocode}
933 \def\pc@alloccolumns{%
934 \count@\z@%
935 \loop\ifnum\count@<\pc@columncount%
936 \advance\count@\@ne%
937 \@ifundefined{pc@column@\number\count@}{%
938 \expandafter\newbox\csname pc@column@\number\count@%
939 \endcsname%
940 \expandafter\newdimen\csname pc@column@width@\number%
941 \count@\endcsname%
942 }{%
943 \setbox0\box\csname pc@column@\number\count@\endcsname%
944 \csname pc@column@width@\number\count@\endcsname\z@%
945 }%
946 \repeat%
947 }
948 % \end{macrocode}
949 % \end{macro}
950 %
951 %
952 % \begin{macro}{\pc@setcolumnwidths}
953 %
954 % Sets the widths of all columns. The defined widths have been
955 % temporarily stored in |\toks@|. |\@tempdimc| contains the space
956 % between two columns.
957 %
958 % \begin{macrocode}
959 \def\pc@setcolumnwidths{%
960 \expandafter\processkeyvalues\expandafter{\the\toks@}%
961 \pc@setsinglecolwidth%
962 % \end{macrocode}
963 %
964 % |\@tempdima| will contain the total width of all columns that have a
965 % known width (read: have had their width set via the parameter
966 % |colwidths|)
967 %
968 % \begin{macrocode}
969 \@tempdima\z@%
970 % \end{macrocode}
971 %
972 % |\@tempcnta| will contain the count of columns that an unknown width
973 % (read: have had their width \emph{not} set via the parameter
974 % |colwidths|, thus now having a width of zero points, as the widths
975 % of all columns have been reset in |\pc@alloccolumns|):
976 %
977 % \begin{macrocode}
978 \@tempcnta\z@%
979 % \end{macrocode}
980 %
981 % We calculate the total width of all columns known. We count how many
982 % columns have an unknown width:
983 %
984 % \begin{macrocode}
985 \count@\z@%
986 \loop\ifnum\count@<\pc@columncount%
987 \advance\count@\@ne%
988 \@tempdimb\csname pc@column@width@\number\count@\endcsname%
989 \advance\@tempdima\@tempdimb%
990 \ifnum\@tempdimb=\z@%
991 \advance\@tempcnta\@ne%
992 \else%
993 \PackageInfo{parcolumns}{Width of column \number\count@%
994 \space set to \the\@tempdimb}
995 \fi%
996 \repeat%
997 % \end{macrocode}
998 %
999 % If at least one column has an unknown width:
1000 %
1001 % \begin{macrocode}
1002 \ifnum\@tempcnta>\z@%
1003 % \end{macrocode}
1004 %
1005 % |\@tempdimc| contains the distance between columns. We calculate the
1006 % space left for the columns with an unknown width.
1007 %
1008 % |\@tempdimb| will contain the sum of the space between all the
1009 % columns \ldots
1010 %
1011 % \begin{macrocode}
1012 \@tempdimb\@tempdimc%
1013 \multiply\@tempdimb\pc@columncount%
1014 \advance\@tempdimb-\@tempdimc%
1015 % \end{macrocode}
1016 %
1017 % \ldots\ plus the sum of the width of all columns with a known width:
1018 %
1019 % \begin{macrocode}
1020 \advance\@tempdimb\@tempdima%
1021 % \end{macrocode}
1022 %
1023 % |\@tempdima| will contain the space for each column with an unknown
1024 % width:
1025 %
1026 % \begin{macrocode}
1027 \@tempdima\linewidth%
1028 \advance\@tempdima-\@tempdimb%
1029 \divide\@tempdima\@tempcnta%
1030 % \end{macrocode}
1031 %
1032 % We set the widths of the colums with an unknown width:
1033 %
1034 % \begin{macrocode}
1035 \count@\z@%
1036 \loop\ifnum\count@<\pc@columncount%
1037 \advance\count@\@ne%
1038 \ifnum\csname pc@column@width@\number\count@\endcsname=\z@%
1039 \csname pc@column@width@\number\count@\endcsname\@tempdima%
1040 \PackageInfo{parcolumns}{Width of column \number\count@%
1041 \space calculated as \the\@tempdima}
1042 \fi%
1043 \repeat%
1044 \fi%
1045 }
1046 % \end{macrocode}
1047 % \end{macro}
1048 %
1049 %
1050 % \begin{macro}{\pc@setsinglecolwidth}
1051 %
1052 % Usage: |\pc@setsinglecolwidth| \marg{column} \marg{width}.
1053 %
1054 % Sets the width of the column \meta{column} to the width
1055 % \meta{width}. Displays an error message if the column is not valid.
1056 %
1057 % \begin{macrocode}
1058 \def\pc@setsinglecolwidth#1#2{%
1059 \@ifundefined{pc@column@width@\number#1}{
1060 \PackageError{parcolumns}{`#1' is not a valid column number!}%
1061 {\@ehc}%
1062 }{%
1063 \csname pc@column@width@\number#1\endcsname=#2\relax%
1064 }%
1065 }
1066 % \end{macrocode}
1067 % \end{macro}
1068 %
1069 %
1070 % \begin{macro}{\pc@setcolumnwidth}
1071 %
1072 % Sets |\hsize| to the width of a column (stored in
1073 % |\pc@column@width@|\meta{pc@columnctr}) and enters horizonal mode.
1074 %
1075 % \changes{1.2}{2004/11/22}{linewidth set, too}
1076 %
1077 % \begin{macrocode}
1078 \def\pc@setcolumnwidth{%
1079 \hsize\csname pc@column@width@\number\pc@columnctr\endcsname%
1080 \linewidth\hsize%
1081 \leavevmode%
1082 }
1083 % \end{macrocode}
1084 % \end{macro}
1085 %
1086 %
1087 % \Finale
1088 % \PrintChanges
1089 % \PrintIndex
1090 \endinput