Initial commit

1 files changed, 986 insertions, 0 deletions

diff --git a/macros/plain/contrib/pdcmac/pdcoput5.dtx b/macros/plain/contrib/pdcmac/pdcoput5.dtx
new file mode 100644
index 0000000000..106b45feca
--- /dev/null
+++ b/macros/plain/contrib/pdcmac/pdcoput5.dtx
@@ -0,0 +1,986 @@
+% pdcoput5.dtx -- documentation & source for outpout routine -*-tex-*-

+        

+%%%@TeX-document-file {

+%%% title 	= "PDCOPUT5 -- An output routine for zines",

+%%% filename 	= "$texmf/doc/plain/pdcmac/pdcoput5.dtx",

+%%% version 	= "$Revision: 5.3 $",

+%%% package 	= "pdcmac 1.0",

+%%% date 	= "$Date: 1995/04/06 11:51:03 $",

+%%% author	= "P. Damian Cugley",

+%%% email	= "damian.cugley@comlab.ox.ac.uk",

+%%% address	= "Oxford University Computing Laboratory,"

+%%%                Parks Road, Oxford  OX1 3QD, UK",

+%%% abstract	= "This document describes and is the source code for 

+%%%                the TeX definitions file pdcoput5.tex.

+%%%                Running plain TeX on this file produces both the

+%%%                definitions file and the printed documentation.",

+%%% copyright	= "Copyright (c) 1991-1995 P. Damian Cugley",

+%%% copying	= "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.",

+%%% notice	= "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.",

+%%% notice	= "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.",

+%%% codetable	= "USASCII",

+%%% dependencies = "pdccode.tex"

+%%%}

+

+%{{{ pdcoput5.tex

+%{{{  preamble

+

+\relax

+\input pdccode

+\input epsf

+

+\document

+\rcs$Id: pdcoput5.dtx,v 5.3 1995/04/06 11:51:03 pdc Exp $\endrcs

+

+\codefile{pdcoput5.tex}

+

+\countdef\counta=255 \newcount\countb

+\counta=`a \countb="7461

+\loop \ifnum\counta<"7B

+    \mathcode\counta\countb

+    \advance\counta1 \advance\countb1

+\repeat

+\counta=`A \countb="7441

+\loop \ifnum\counta<"5B

+    \mathcode\counta\countb

+    \advance\counta1 \advance\countb1

+\repeat

+

+%}}}  preamble

+%{{{  introduction

+

+\title{PDCOPUT5---an output routine for zines}

+

+\section{Introduction}

+

+	This document describes |pdcoput5.tex|, a \TeX\ definition file

+	that defines an output routine for \TeX\ documents.  The

+	complete text of the macros is reproduced, with brief

+	descriptions of how to exploit them.

+

+	In fact, running plain \TeX\ on the file |pdcoput5.dtx|

+	generates a copy of the macros in a file called |pdcoput5.tex|

+	in the current directory, as well as the printed

+	documentation.\footnote*{The \LaTeX~2e distribution uses files

+	with the suffix |dtx| for similar purposes.}  This should help

+	ensure that the printed documentation matches the file it

+	describes.

+

+	The name ends with `-|5|' to distinguish this file from its

+	predecessor (version 4.1.7), so that documents based on the old

+	macros can still be printed.

+

+%{{{   output routines

+\subsec{Output routines}

+

+	In a \TeX\ document, there is a special sequence of \TeX\

+	commands called the {\it output routine} which controls the

+	assembly of pages for output to the |dvi| file.  

+	Plain \TeX\ comes with an output routine that handles simple

+	documents (with footnotes and topinserts); \LaTeX\ has a more

+	complex output routine that has many extra features (margin

+	paragraphs, \LaTeX's floats).

+%}}}   output routines

+%{{{   backgorund

+	

+\subsec{Background to this output routine}

+

+	I have been using \TeX\ to typeset fanzines\footnote\dag{The

+	word {\it fanzine} comes from science fiction fans' jargon: {\it

+	fan} for amateur (in the sense of unpaid, not necessarily

+	amateurish) + {\it magazine}.  (They call professional magazines

+	{\it prozines}.)  Thus a fanzine (or zine for short) is a small

+	magazine, often produced by photocopying or cheap printing by

+	its editor.  The word {\it zine} rhymes with {\it scene} not

+	{\it sign}, and isn't spelled with an apostrophe (unless you are

+	the sort of person who spells {\it phone}, {\it cello} and {\it

+	bus} with an apostrophe).}  for some years.  Unfortunately, for

+	magazine layouts, the `floating' insertions provided by plain

+	\TeX\ and \LaTeX\ do exactly the wrong thing---in a magazine,

+	the designer wants to lay out the components of the page

+	(illustrations, text, headings) exactly where he or she wants

+	them, whereas the standard \TeX\ formats are designed to let the

+	formatter place components according to its own complex rules.

+	

+	Originally I~tried browbeating \LaTeX\ into doing the zine

+	layouts I~wanted.  I realized eventually that by the time I~had

+	redefined enough of \LaTeX's kernel to get the effects I~wanted

+	I~would more or less have written everything from scratch.  The

+	sort of typesetting I~wanted is so unlike what \LaTeX\ is

+	designed for that \LaTeX\ was getting in the way.

+	

+	Thus I~developed a set of \TeX\ definition files,\footnote\ddag{We

+	can ignore the intermediate stage, which involved writing a

+	`user-friendly' format in the style of \LaTeX\ and Texinfo, with

+	structures very different from plain \TeX's syntax.  In the end

+	I realized that a format that requires disguising or renaming

+	plain \TeX\ constructs makes using and modifying the macros

+	harder, not easier, because the user has to understand the new

+	conventions in addition to plain \TeX\ syntax.} with an output

+	routine that allowed a page to be peppered with inserts with the

+	text flowing in between them (with a more restricted class of

+	inserts than, say, a DTP program, but still flexible enough to

+	be useful).  The output routine also does multi-column text---in

+	this respect it is very similar to the |multicol| package in

+	\LaTeX~2e.  The routine presented here has been rewritten from

+	scratch a few times, each time shedding some cruft as I~have a

+	better understanding of \TeX.

+%}}}   backgorund

+%{{{   layout model

+	

+\subsec{The layout model}

+

+\topinsert

+    \line{\vbox{\advance\hsize-1pc \hsize=0.333\hsize

+		\noindent{\bf Figure 1}\quad Page layout.  This shows a

+		page without the optional extra boxes.  In this example,

+		text columns each span two grid cells.  The left-hand

+		column has an illo (space for an illustration) with caption.

+	}%

+	\epsfxsize=\hsize \advance\epsfxsize-1pc

+	\epsfxsize=0.667\epsfxsize \epsffile{oput01.eps}\hfil

+}

+\medskip\hrule\medskip

+\endinsert

+

+\topinsert

+    \line{\epsfxsize=\hsize \advance\epsfxsize-1pc

+	\epsfxsize=0.667\epsfxsize \epsffile{oput02.eps}\hfil

+	\vbox{\advance\hsize-1pc \hsize=0.333\hsize

+		\noindent{\bf Figure 2}\quad Page layout parameters.  

+		This page has with

+		all the optional boxes (shown with dashed lines).  One text

+		column has a space left for artwork.  Text columns are the same

+		width as grid cells.

+	}}

+\medskip\hrule\medskip

+\endinsert

+

+	The main part of the page (everything except the headline and

+	footline) is called the {\it body}.  The body is divided into a

+	grid of cells.  The cells are conceptually the framework on

+	which page components like text columns and illustrations are

+	hung.  For example, text columns may span two cells.  Figure~1

+	shows a simple layout.  Fitting on the grid usually means the

+	width of the object is $N\times gridwd + (N-1)\times colsep$ and

+	its left edge is $K\times(gridwd + colsep)$ from the left edge

+	of the page body.  

+

+	The aim of using a grid layout is to combine flexibility with

+	enough structure that the result is not a chaotic mess.  The

+	example grid is 5~cells wide, so that text columns can probably

+	be 2 or 3 cells wide without being too narrow or too wide.

+	Illustrations may be anything from 1 to 5 cells wide, or may

+	bleed off the page.

+

+	

+

+	

+%}}}   layout model

+%}}}  introduction

+%{{{  identification

+\section{File identification}

+

+	Macro files nowadays tend to start with a whole slew of header

+	comments designed to be useful to people comign across the file

+	in some archive and unaware of what it is for.

+

+\code

+	\|\% \filename~\fileversion~\filedate~-- output routine for zines

+	|

+	|%%%@TeX-definition-file {

+	|%%% filename       = "$texmf/tex/plain/pdcmac/pdcoput5.tex",

+	\|\%\%\% version~~~~~~~~= "\fileversion",

+	\|\%\%\% date~~~~~~~~~~~= "\filedate",

+	|%%% package        = "pdcmac 1.0",

+	|%%% author         = "P. Damian Cugley",

+	|%%% email          = "damian.cugley@comlab.ox.ac.uk",

+	|%%% address        = "Oxford University Computing Laboratory,

+	|%%%                   Parks Road, Oxford  OX1 3QD, UK",

+	|%%% codetable      = "USASCII",

+	|%%% keywords       = "TeX, plain TeX, macros",

+	|%%% supported      = "Maybe",

+	|%%% abstract       = "TeX output routine for magazine-style layout.

+	|%%%                   This file was generated by running

+	\|\%\%\%~~~~~~~~~~~~~~~~~~~plain TeX on \jobname.dtx",

+	|%%% copyright      = "Copyright (c) 1991-1995 P. Damian Cugley",

+	|%%% copying        = "DO NOT DISTRIBUTE THIS FILE.

+	\|\%\%\%~~~~~~~~~~~~~~~~~~~Distribute \jobname.dtx only as part of the

+	|%%%                   package it came in.",

+	|%%% dependencies   = "",

+	|%%% }

+	|

+	\|\\message\{\fileversion~<pdc \filedate>\}

+	|

+\endcode

+%}}}  identification

+%{{{  internals

+\section{Miscellaneous internal definitions}

+\subsec{Scratch registers}

+	

+	These are one-token names for some handy non-global temporary

+	registers (in plain \TeX\ these are given names with |@| in

+	them; these definitions give them names I can use).

+\code

+	|\countdef\counta=255

+	|\dimendef\dimena=0 \dimendef\dimenb=2

+	|\toksdef\toksa=0 \toksdef\toksb=2

+\endcode

+	I~don't use |\dimen1| and |\toks1| because they are supposed to

+	be used only globally (as discussed in {\it\TeX book}

+	Appendix~B).

+

+\subsec{Queues}

+

+	These macros manipulate queues of instructions for the ouytput

+	routine, represented as list macros of a form similar to those

+	described in {\it\TeX book} Appendix~D Section~2 (the parameters

+	in different order).

+

+\notepar

+	All of these work by making assignments and so will not work in

+	\TeX's mouth.

+\endnotepar

+

+	We can describe these briefly using letters like $x$ to stand

+	for elements (enclosed in braces) and $xs$ to stand for a list

+	macro of $x$s.  Each macr has a duplicate starting with `|g|-'

+	which does the same operation globally.

+

+%	|\prepend| $xs$ $x$ --- $xs:=\langle x\rangle + xs$

+%\code

+%	|\long\def\prepend#1#2{%

+%	|    \toksa={\\{#2}}\toksb=\expandafter{#1}%

+%	|    \edef#1{\the\toksa\the\toksb}%

+%	|}

+%\smallbreak

+%	|\long\def\gprepend#1#2{%

+%	|    \toksa={\\{#2}}\toksb=\expandafter{#1}%

+%	|    \xdef#1{\the\toksa\the\toksb}%

+%	|}

+%\endcode

+	|\qappend| $xs$ $x$ --- $xs:= xs + \langle x\rangle $

+\code

+	|\long\def\qappend#1#2{%

+	|    \toksa={\\{#2}}\toksb=\expandafter{#1}%

+	|    \xdef#1{\the\toksb\the\toksa}%

+	|}

+\endcode

+%	|\catenate| $xs$ $ys$ $zs$ --- $xs:=ys + zs$

+%\code

+%	|\def\catenate#1#2#3{%

+%	|    \toksa=\expandafter{#2}\toksb=\expandafter{#3}%

+%	|    \edef#1{\the\toksa\the\toksb}%

+%	|}

+%\smallbreak

+%	|\def\gcatenate#1#2#3{%

+%	|    \toksa=\expandafter{#2}\toksb=\expandafter{#3}%

+%	|    \xdef#1{\the\toksa\the\toksb}%

+%	|}

+%\endcode

+	|\qremove| $x$ $xs$ --- $x, xs := hd(xs), tl(xs)$

+	(where $xs = \langle hd(xs)\rangle + tl(xs)$)

+\code

+	|\def\qremove#1#2{%

+	|    \expandafter\glopoff#2\glopoff#1#2%

+	|}

+	|\long\def\glopoff\\#1#2\glopoff#3#4{%

+	|    \gdef#3{#1}\gdef#4{#2}%

+	|}

+\endcode

+

+%}}}  internals

+%{{{  parameters

+\section{Parameters}

+

+	We collect here definitions for parameters that customizate the

+	layout.  In documents, many of these are set in using

+	higher-level macros.

+

+	The abbreviations |mg| (margin), |wd| (width) and |ht| (height)

+	are used a lot in dimen names.

+

+\subsec{Heights and depths}

+	The physical size of the paper is $paperwd\times paperwd$.  The

+	area which will be filled with text columns is $bodywd\times

+	bodyht$.  This area is divided in to a grid of cells each

+	$gridwd\times gridht$, with cells separated by $colsep$

+	horizontally but butting vertically (there are $n$ cells, so

+	$n\times gridwd + (n-1)\times colsep = bodywd$).  Finally,

+	$colwd$ is the width of text columns ($colwd = k\times gridwd +

+	(k-1)\times colsep$) and $colht$ is the height of text columns

+	on the current page (it is equal to $bodyht$ iff therte is no

+	topbox or botbox).

+\code

+	|\newdimen\paperwd \newdimen\paperht

+	|\newdimen\bodywd \newdimen\bodyht

+	|\newdimen\gridwd \newdimen\gridht

+	|\newdimen\colwd \newdimen\colht

+\endcode

+

+

+\subsec{Margins and separators}

+	These margins measure from the edge of the paper as defined by

+	|\paperwd| and |\paperht|.  The inner margin (|\innermg|) is on

+	the left on odd pages and on the right for even pages.

+

+	The bottom margin will be increased slightly later on to make

+	$$vsize=N\times baselineskip + topskip\quad.$$

+	

+\code

+	|\newdimen\topmg    \topmg=20mm

+	|\newdimen\outermg  \outermg=20mm

+	|\newdimen\innermg  \innermg=20mm

+	|\newdimen\botmg    \botmg=27mm

+\endcode

+

+	Parameters for the distance between the baselines of the

+	headline and the first line of text the corresponding distance

+	for footlines.

+\code

+	|\newskip\headlineskip  \headlineskip=10mm 

+	|\newskip\footlineskip  \footlineskip=10mm

+\endcode

+

+

+	The parameters |\caprule| and |\capsep| specify the separation

+	between captions and the adjacent text column.  The vertical

+	displacement is $capsep$, with a horizontal rule of thickness

+	$caprule$ is drawn in the middle (set this to $0\pt$ to have no

+	rule).

+

+\code

+	|\newdimen\caprule  \caprule=0.4pt

+	|\newskip\capsep    \capsep=5mm

+\endcode

+

+	The corresponding parameters for column separators---this time

+	it is a vertical rule.

+\code

+	|\newdimen\colrule  \colrule=0.4pt

+	|\newdimen\colsep   \colsep=5mm

+\endcode

+

+	The number of text columns on a page.  

+\code

+	|\newcount\ncols \ncols=1

+\endcode

+

+\subsec{Boxes}

+	To switch the number of columns in mid page, the first text is

+	run through the output routine and the resultant partial page is

+	stored in |\partialpage| to be placed at the top of the next

+	output.

+

+\code

+	|\newbox\partialpage  

+\endcode

+

+	The special boxes |\topbox| and |\botbox|, if non-void, are

+	placed at the top and bottom of the page, going inside the

+	headline and footline but outside the body text area (which is

+	reduced correspondingly).  These are often useful in

+	multi-column text to put titles that span the page.

+\code

+	|\newbox\topbox \newbox\botbox

+\endcode

+

+	These boxes, if not void, go at the left and right of the body

+	text.  The amount of space for columns of text is reduced by the

+	width of the boxes.

+\code

+	|\newbox\leftbox \newbox\rightbox

+\endcode

+

+	The output routine is passed the current page contents in

+	box~255.

+\code

+	|\chardef\pagebox=255

+\endcode

+

+\subsec{Hooks}

+

+	These two list macros are used to override the output routine

+	with customized layouts.

+

+	One item is removed from |\pagelist| to generate each page body

+	(the page body is everything except the headline, footline,

+	topbox, botbox amd partial page).  If the list is empty, then

+	the default action is `|\makebody\pagebox|'.  The commands

+	should make a box with width |\bodywd|m and heght |\colht|.

+\code

+	|\let\pagelist\empty

+\endcode

+	An item is removed from |\collist| each time a column is to be

+	created by |\makebody|.  Each item should be \TeX\ commands that

+	generate a box with width |\colwd| and height |\colht|.

+\code

+	|\let\collist\empty

+\endcode

+

+	Finally, token registers that may be used to customize pages and

+	captions.  For example, |\everypage| is used in |pdccmdoc.tex|

+	to create an empty |\leftbox| on each page.

+\code

+	|\newtoks\everypage

+	|\newtoks\everycaption

+\endcode

+%}}}  parameters

+%{{{  make a column (vbox)

+\section{How to make one column}

+

+	This is the default way to generate a column of text---this will

+	normally be invoked $k$ times if there are $k$ columns.

+

+	A column is a vbox of height $colht$ and width $colwd$.  It

+	contains, in order from top to bottom, an illustration (vertical

+	mode material, normally white space for artwork to be pasted

+	into), caption separator, text (from the page), caption

+	separator, and bottom illustration.  The illustrations are

+	usually omitted.  When there is no illustration, the caption

+	separators are omitted too.

+ 	The macro takes the following parameters:

+$$\halign{\indent\tt\##\hfil&\quad#\hfil&\quad#\hfil\cr

+	1&  vertical mode material& illustration at top of column\cr

+	2&  \<8-bit number>&	box to make middle out of\cr

+	3&  vertical mode material& illustration for bottom of column\cr

+}$$ 

+ 	To make baselines line up, $capsep=baselineskip$ and the height

+	of a top illustration must be $N\times baselineskip + topskip$

+	and of a bottom illustration must be $N\times baselineskip$

+	(|\prevdepth| is set to $0\pt$ at the start of the bottom

+	illustration, so if it starts with a box, baselineskip glue will

+	be inserted to make the baseline of the box align correctly.)

+\code

+	|\newdimen\toptotal \newdimen\bottotal

+\smallbreak

+	|\def\xxxmakecolumn#1#2#3#4#5{\xmakecolumn

+	|    {\ifdim#1=0pt\else \kern#1 \fi

+	|     \def\tmp{#2}\ifx\tmp\empty\else #2 \fi}

+	|    {#3}

+	|    {\def\tmp{#2}\ifx\tmp\empty\else #2 \fi

+	|     \ifdim#1=0pt\else \kern#1 \fi}%

+	|}

+\smallbreak

+	|\def\xmakecolumn#1#2#3{%

+	|    \vbox to \colht{

+\endcode

+	Calculate in |\dimena| how much of the text box will be needed

+	once we have allowed for any illustrations, footnotes or

+	topinserts:

+\code

+	|        \dimena\colht 

+	|        \setbox0=\vbox{#1}\advance\dimena-\ht0

+	|        \ifdim\ht0>0pt 

+	|            \advance\dimena-\capsep 

+	|            \advance\dimena\topskip \advance\dimena-\baselineskip

+	|        \fi

+	|        \setbox4=\vbox{\prevdepth=0pt #3}%

+	|        \advance\dimena-\ht4

+	|        \ifdim\ht4>0pt \advance\dimena-\capsep \fi

+	|        \ifvoid\footins\else

+	|            \advance\dimena-\ht\footins

+	|            \advance\dimena-\skip\footins

+	|        \fi

+	|        \ifvoid\topins\else

+	|            \advance\dimena-\ht\topins

+	|            \advance\dimena-\skip\topins

+	|        \fi

+\endcode

+	Split that much text off the top of the box:

+\code

+	|        \splittopskip\topskip \splitmaxdepth\maxdepth

+	|        \setbox2=\vsplit#2to\dimena

+\endcode

+	Now to sandwich it all together.  

+\code

+	|        \dimena=\ht0 \dimenb=\dp0 \unvbox0

+	|        \ifdim\dimena>0pt  

+	|            \prevdepth=\dimenb

+	|            \capseparator 

+	|            \dimena\baselineskip \advance\dimena-\topskip

+	|            \kern\dimena

+	|            \nointerlineskip

+	|        \fi

+	|        \ifvoid\topins\else \unvbox\topins \vskip\skip\topins \fi

+	|        \dimena\dp2	

+	|        \ifvoid2 \vfil \else \unvbox2 \fi

+	|        \ifvoid\footins \else

+	|            \vskip\skip\footins \footnoterule

+	|            \dimena=\dp\footins \unvbox\footins

+	|        \fi

+	|        \ifdim\ht4>0pt 

+	|            \prevdepth=\dimena

+	|            \capseparator \kern-\prevdepth \prevdepth0pt

+	|        \fi

+	|        \unvbox4

+	|    }%

+	|}

+\endcode

+	The caption separator is in an hbox so that 

+	baselineskip glue will be added appropriately.

+\code

+	|\def\capseparator{%

+	|    \hbox to \colwd{%

+	|        \dimena=0.5ex \advance\dimena-0.5\caprule

+	|        \dimenb=\dimena \advance\dimenb\caprule

+	|        \vrule height \dimenb depth-\dimena width\colwd

+	|    }%

+	|}

+\endcode

+

+	Here's a macro for making an illustration (blank space) with

+	caption, suitable for top of page.  |#1| is the cation, |#2| is

+	vertical mode material commands to make the illustration (often

+	this will be something like `|\kern|$n$|\baselineskip|' to leave

+	$n$ lines of blank space).  The whitespace between illustration

+	and caption is adjusted to make the whole shebang line up.

+\code

+	|\def\topillustration#1#2{%

+	|    \setbox0=\vbox{#2}%

+	|    \dimena\ht0 \dimenb\dp0 \unvbox0

+	|    \counta\dimena \divide\counta\baselineskip

+	|    \advance\dimena-\counta\baselineskip \advance\dimena-\topskip

+	|    \kern-\dimena \prevdepth\dimenb

+	|    \hsize=\colwd \vskip-\parskip \noindent#1\par

+	|}

+\endcode

+

+	Similar for bottom of column.

+\code

+	|\def\botillustration#1#2{%

+	|    \setbox0\vbox{\hsize=\colwd \vskip-\parskip \prevdepth=0pt #1}

+	|    \setbox2=\vbox{\prevdepth=\dp0 #2}%

+	|    \dimena=\ht0 \advance\dimena\dp0 \advance\dimena\ht2

+	|    \unvbox0

+	|    \counta\dimena \divide\counta\baselineskip 

+	|    \advance\dimena-\counta\baselineskip 

+	|    \advance\dimena-\baselineskip

+	|    \kern-\dimena

+	|    \unvbox2

+	|}

+\endcode

+

+%}}}  make a column

+%{{{  make body part of page (hbox)

+\section{Making the page body hbox}

+

+	The page body is everything except the footline, headline,

+	topbox and botbox.  It should be a box of height |\bodywd|

+	(which is normally fixed) and height |\colht| (which is

+	|\bodyht| minus the top and bot boxes).

+

+	The default macro for making the body is |\makebody| which takes

+	as its parameter the box number (usually |\pagebox|).  (This may

+	be replaced by adding items to the list macro |\pagelist|.)

+\code

+	|\def\makebody#1{%

+	|    \hbox to \bodywd{%

+	|        \ifvoid\leftbox\else 

+	|            \box\leftbox 

+	|            \colseparator

+	|        \fi

+	|        \makecolumnfromcollist{#1}%

+	|        \counta\ncols

+	|        \loop \ifnum\counta>1

+	|            \colseparator

+	|            \makecolumnfromcollist{#1}%

+	|            \advance\counta -1

+	|        \repeat

+	|        \ifvoid\rightbox\else 

+	|            \colseparator

+	|            \box\rightbox 

+	|        \fi

+	|    }%

+	|}

+\smallbreak

+	|\def\colseparator{%

+	|    \hfil \vrule width\colrule depth0pt \hfil 

+	|}

+\endcode

+

+	The macro |\makecolumnfromcollist| is used to generate columns

+	(which must be boxes of height |\colht| and width |\colwd|).  It

+	uses the next item on |\collist| if there is one, otherwise it

+	just uses |\xmakecolumn|.

+\code

+	|\def\makecolumnfromcollist#1{%

+	|    \ifx\collist\empty

+	|        \xmakecolumn{}{#1}{}%

+	|    \else

+	|        \qremove\temp\collist

+	|        \temp

+	|    \fi

+	|}

+	|

+\endcode

+%}}}  make insides of page (hbox)

+%{{{  make a page (vbox)

+\section{Making a page vbox}

+

+	The macro generates a new page---a vbox to be `shipped out'.

+	The first page includes a |papersize| special; this is because

+	if the macros used to change the paper size also generated the

+	|\special| then there might be conflicting |\special|s which

+	would confuse the printer driver.  This way the paper size may

+	be changed a few times before the first page.

+

+	The |\colht| register is set to the height of text columns on

+	this page (which is $bodyht$ minus the height of any partial

+	page, top or bottom boxes).

+\code

+	|\def\makepage{%

+	|    \vbox{

+	|        \papersizespecial

+	|        \colht\bodyht \advance\colht-\ht\partialpage

+	|        \advance\colht-\ht\topbox \advance\colht-\ht\botbox

+	|        \advance\colht-\dp\partialpage

+	|        \advance\colht-\dp\topbox

+	|        \the\everypage

+	|        \makeheadline \nointerlineskip

+	|        \box\partialpage \nointerlineskip

+	|        \box\topbox \nointerlineskip

+	|        \ifx\pagelist\empty

+	|            \makebody\pagebox

+	|        \else

+	|            \qremove\temp\pagelist 

+	|            \temp

+	|        \fi

+	|        \unvbox\botbox

+	|        \makefootline

+	|    }%

+	|}

+\endcode

+

+	The |\makeheadline| macro generates the headline in the form of

+	vertical mode material with zero height.  It is expanded after

+	|\everypage| has been expanded, at the very top of the page's

+	vbox.

+\code

+	|\def\makeheadline{

+	|    \vbox to 0pt {

+	|        \skip0=\topskip \advance\skip0-2\ht\strutbox 

+	|        \advance\skip0-\headlineskip

+	|        \vskip\skip0

+	|        \hbox to \bodywd{\the\headline}

+	|        \vss

+	|    }

+	|}

+\endcode

+

+	The footline is, naturally, generated with |\makefootline|.

+	This time there is no requirement for it to be zero height.  It

+	is the last thing in the box being shipped out.

+\code

+	|\def\makefootline{{

+	|    \baselineskip=\footlineskip

+	|    \hbox to \bodywd{\the\footline}

+	|}}

+\endcode

+

+	The |papersize| special is specified in the manual for DVIPS.

+	It specifies the physical size of the medium---and so must be

+	multiplied by the current magnification.

+\code

+	|\def\papersizespecial{{%

+	|    \dimena=0.001\paperwd \multiply\dimena\mag

+	|    \dimenb=0.001\paperht \multiply\dimenb\mag

+	|    \special{papersize=\the\dimena,\the\dimenb}%

+	|    \global\let\papersizespecial=\relax

+	|}}

+	|

+\endcode

+%}}}  make a page (vbox)

+%{{{  output

+\section{The output routine}

+

+	The output routine sets |\hoffset| appropiately (subtracting

+	$1{\scriptstyle''}$ to allow for \TeX's peculiar origin point

+	one inch from the top left of the page.

+\code

+	|\def\pdcoutput{%

+	|    \ifodd\pageno \hoffset=\innermg \else \hoffset=\outermg \fi

+	|    \advance\hoffset-1 true in

+	|    \voffset=\topmg

+	|    \advance\voffset-1truein

+	|    \shipout\makepage \advancepageno 

+	|    \ifnum\outputpenalty>-20000 \else \dosupereject \fi

+	|    \unvbox\pagebox

+	|}

+\smallbreak

+	|\output={\pdcoutput}

+\endcode

+%}}}  output

+%{{{  automated column setting

+\section{Specifying a grid}

+

+	These macros for setting the paper size ought to be invoked

+	after the base font and baseline skip have been set but before

+	the numebr of columns is chosen.

+

+\subsec{Specifiying the paper size}

+

+	This is a macro that might be used in documents.  It takes two

+	parameters, \<dimen>s for the width and height of the paper.

+\code

+	|\def\setpaper#1#2{%

+	|    \paperwd=#1\relax

+	|    \paperht=#2\relax

+	|    \OPUTcalcbodywdht

+	|    \OPUTcalctopskip

+	|}

+\endcode

+	Calculate the page body width |\bodywd| from the paper size and

+	the size of the margins:

+\code

+	|\def\OPUTcalcbodywdht{

+	|    \bodywd=\paperwd \advance\bodywd-\outermg \advance\bodywd-\innermg

+	|    \bodyht=\paperht \advance\bodyht-\topmg \advance\bodyht-\botmg

+	|    \OPUTcalctopskip

+	|}

+\endcode

+

+	To avoid having to write `Aiv' or `afour' for specifying

+	international standard A4 paper, I~use an

+	|\ifcase|.\footnote*{Note for Americans: A4 corresponds to

+	American Letter size, and A3 to Ledger size.}  This macro

+	handles A0 to A5.

+\code

+	|\def\setpaperA#1{

+	|    \ifcase#1

+	|        \setpaper{841mm}{1189mm}\or

+	|        \setpaper{594mm}{841mm}\or	

+	|        \setpaper{420mm}{594mm}\or	

+	|        \setpaper{297mm}{420mm}\or	

+	|        \setpaper{210mm}{297mm}\or	

+	|        \setpaper{148mm}{210mm}	

+	|    \else

+	|        \errmessage{Dunno how big DIN A#1 paper is, sorry.}

+	|    \fi

+	|}

+\endcode

+

+\subsec{Adjusting the body height and top skip}

+

+	Plain \TeX\ sets |\topskip| to $10\pt$, which means there is a

+	gap between the top of the letters of the top line of text and

+	the top of the pages's vbox (i.e., $vsize$ is measured from the

+	baseline of the last line to a line $topskip$ above the baseline

+	of the first line).  For magazine-style setting, it is more

+	usual to have $topskip$ set to the cap-height of the font

+	(assuming there are no strange tall characters in use).  

+

+	To have an exactly $N$ lines to a page,

+    $$

+	bodyht = (N-1)\times baselineskip + topskip	\quad.

+    $$  

+ 	This macro increases the bottom margin in order to set $bodyht$

+	to such a value.

+\code

+	|\def\OPUTcalctopskip{

+	|    \setbox0=\hbox{AXbl()!gyJQ,}

+	|    \topskip=\ht0 \maxdepth=\dp0

+	|    \advance\bodyht-\topskip \divide\bodyht\baselineskip

+	|    \multiply\bodyht\baselineskip \advance\bodyht\topskip

+	|}

+\endcode

+

+	Give this value for $bodyht$, we can set $hsize$ and $vsize$

+	according to the number of columns to a page.  For $N$ lines to

+	a column, we need $N\times ncols$ lines to make a whole page, so

+    $$

+	\eqalign{vsize 

+		&= (ncols \times N - 1) \times baselineskip + topskip\cr

+		&= (bodyht + \delta) \times ncols - \delta\cr

+	}

+    $$

+ 	where $\delta=baselineskip-topskip$.

+\code

+	|\def\OPUTcalchsizevsize{

+	|    \hsize=\colwd

+	|    \vsize=\bodyht 

+	|    \advance\vsize-\topskip \advance\vsize\baselineskip 

+	|    \multiply\vsize\ncols 

+	|    \advance\vsize-\baselineskip \advance\vsize\topskip

+	|}

+\endcode

+

+

+\subsec{Setting the number of columns}

+

+	Now some macros used in documents for setting the number of

+	coumns.  In the general case we have a grid of $n$ cells with

+	text columnns spanning $k$ cells.  This macro takes two number

+	parameters, $n$ and $k$.  It sets |\ncols| to as many columns

+	fit on the page.

+    $$

+	\eqalign{colwd &= k \times gridwd + (k - 1) \times colsep\cr

+	ncols &= \lfloor n \mathbin/ k \rfloor\cr}

+    $$ 

+ 	Often $n$ is not a multiple of $k$, which leaves some grid cells

+	`spare' for illustrations or extra margins and so on.

+\code

+	|\def\setnkgrid#1#2{%

+	|    \gridwd=\bodywd 

+	|    \advance\gridwd-#1\colsep \advance\gridwd\colsep \divide\gridwd#1

+	|    \colwd#2\gridwd \advance\colwd#2\colsep \advance\colwd-\colsep

+	|    \ncols#1 \divide\ncols#2

+	|    \gridht=\baselineskip

+	|    \capsep=\gridht

+	|    \OPUTcalchsizevsize

+	|}

+\endcode

+

+	For simpler layouts, we just set the number of columns and set

+	the grid and column widths to be the same.

+\code

+	|\def\setncolumns#1{%

+	|    \colwd=\bodywd

+	|    \advance\colwd-#1\colsep \advance\colwd\colsep \divide\colwd #1

+	|    \gridwd=\colwd

+	|    \ncols=#1

+	|    \OPUTcalchsizevsize

+	|}

+\endcode

+

+\subsec{Setting default values}

+

+	We give all the parameters default values by assuming A4 paper

+	and a single-column layout in \TeX's default fonts.

+\code

+	|\setpaperA4

+	|\setncolumns1

+\endcode

+

+%}}}  automated column setting

+%{{{  balancing columns

+\section{Routines for balanced columns}

+

+\subsec{Balanced columns from a rigid vbox}

+

+	This is the routine discussed in {\it\TeX book}, Appendix~D,

+	Section~7 (pp.\thinspace396--397).  It takes a rigid, regular

+	vbox (rigid meaning there is no stretchable glue between lines,

+	and regular meaning that baselines are all the same distance

+	apart).  Its parameters are

+    $$\centerline{\vbox{\halign{\tt\char`\##\hfil&&\quad#\hfil\cr

+	1&\<8-bit number>&	box to chop\cr

+	2&\<number>&		how many columns to make (${}>0$)\cr

+	3&\<dimen>&		the value of \cs{topskip} for the box\cr

+	4&tokens&		what to put between columns\cr

+    }}}$$

+ 	the last parameter will usually be |\hfil| or |\colseparator|.

+	Usually this command will be used like

+$$\hbox{|\hbox to \bodywd{\rigidbalance...}|}$$

+	

+

+\code

+	|\newcount\RGDncols

+\smallbreak

+	|\def\rigidbalance#1#2#3#4{%

+	|    \setbox0=\box#1\relax \RGDncols=#2\relax \toksa={#4}%

+	|    \begingroup\splittopskip#3\relax \vbadness=10000 

+	|        \valign{##\vfil\cr \RGDdosplits}%

+	|    \endgroup

+	|}

+\endcode

+	The helper function that produces the insides of the valign is

+	recursive.

+\code

+	|\def\RGDdosplits{

+	|    \dimena\ht0 \divide\dimena\RGDncols 

+	|    \advance\dimena\splittopskip

+	|    \setbox1=\vsplit0 to\dimena

+	|    \unvbox1

+	|    \global\advance\RGDncols-1

+	|    \cr

+	|    \ifnum\RGDncols>0 

+	|        \noalign{\the\toksa}

+	|        \RGDdosplits

+	|    \fi

+	|}

+\endcode

+

+\subsec{Balance partial page}

+

+	Occasionally it is useful to switch between different grids or

+	numbers of columns within one page.  This macro does this,

+	creating a shorter-than-usual page body (including topbox and

+	botbox) and then putting the result in |\partialpage| Its

+	parameters are |#1| the \TeX\ code used to generate the text

+	columns and |#2| what to put between the partial page and the

+	rest of the page.

+

+\code

+	|\def\makepartialpage#1#2{

+	|    \maybepagebreak

+	|    \begingroup

+	|        \output{%

+	|            \message{[partial}

+	|            \setbox0=\vbox{\unvbox\pagebox}%

+	|            \global\setbox\partialpage\vbox{

+	|                \box\partialpage \nointerlineskip

+	|                \the\everypage

+	|                \box\topbox \nointerlineskip

+	|                \hbox to \bodywd{%

+	|                    \ifvoid\leftbox\else 

+	|                        \box\leftbox \colseparator 

+	|                    \fi

+	|                    #1%

+	|                    \ifvoid\rightbox\else 

+	|                        \colseparator \box\rightbox 

+	|                    \fi

+	|                }% \nointerlineskip

+	|                \box\botbox

+	|                #2

+	|                \dimena\baselineskip \advance\dimena-\topskip

+	|                \kern\dimena

+	|            }%

+	|            \message{page]}

+	|        }

+	|        \eject

+	|    \endgroup

+	|}

+\smallbreak

+	|\def\rigidbalancepartialpage{

+	|    \makepartialpage{\rigidbalance0\ncols\topskip\colseparator}

+	|}

+\endcode

+	Occasionally \TeX\ might have just over a pageful of text when

+	this command is used (since the page break calculations do not

+	take into account the space subtracted by

+	illustrations\footnote*{This is probably a bug.}). In this case

+	we have to force out a complete page.

+\code

+	|\def\maybepagebreak{%

+	|    \vskip0pt plus\baselineskip \penalty-100

+	|    \loop 

+	|        \dimena\vsize \advance\dimena-\ncols\ht\partialpage

+	|        \advance\dimena-\ncols\ht\topbox

+	|        \advance\dimena-\ncols\ht\botbox

+	|    \ifdim\pagetotal>\dimena

+	|        \eject\null

+	|    \repeat

+	|}

+\endcode

+%}}}  balancing columns

+\endcodefile 

+\enddocument 

+\bye

+%}}} pdcoput5.tex

+

+%Local variables:

+%fold-folded-p: t

+%fill-prefix: "	"

+%End: