diff options
Diffstat (limited to 'Master/texmf-dist/source/plain/pdcmac/pdcoput5.dtx')
-rw-r--r-- | Master/texmf-dist/source/plain/pdcmac/pdcoput5.dtx | 986 |
1 files changed, 986 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/plain/pdcmac/pdcoput5.dtx b/Master/texmf-dist/source/plain/pdcmac/pdcoput5.dtx new file mode 100644 index 00000000000..59930102a17 --- /dev/null +++ b/Master/texmf-dist/source/plain/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: |