summaryrefslogtreecommitdiff
path: root/macros/plain/contrib/pdcmac/pdcoput5.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/plain/contrib/pdcmac/pdcoput5.dtx')
-rw-r--r--macros/plain/contrib/pdcmac/pdcoput5.dtx986
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: