% FILE DOCHC % % *** Source for hardcopy of Documentation for HP TeX Macros *** % Copyright 1984 Hewlett-Packard Co. % \catcode`@=11 \def\itemlist#1{\medskip\resetsubitems\itemset@\@ne\@ne{#1}} \def\itempar{\smallskip\itemset@\@ne\@ne\empty} \catcode`@=12 \def\spacechar{\hskip1pt\lower3pt\vbox{ \hbox to 5pt {\vrule height4pt width.009in \hfill \vrule height4pt width.009in} \hrule depth.009in height0pt}\hskip2pt} \def\langle{$\mathchar"4268$} \def\rangle{$\mathchar"5269$} \def\evenheading{\vbox{\hbox to \hsize{\eightrm Page \folio\hfil\HPTEX} \nointerlineskip\vskip2pt \hbox{\vrule width \hsize height .4pt}}} \def\oddheading{\vbox{\hbox to \hsize{\eightrm Documentation\hfil Page \folio} \nointerlineskip\vskip2pt \hbox{\vrule width \hsize height .4pt}}} \def\noheading{\hfil} \headline{\ifnum\pageno=1\noheading \else\ifodd\pageno\oddheading\else\evenheading\fi\fi} \def\NOTE#1:{\itemlist{\hbox to .7in{NOTE\hfil#1}:}} \def\\{$\backslash$} \parindent.825in \parskip5pt \nopagenumbers \inset=.825in \def\section#1{\relax} \null \vskip.75in \centerline{\twelvebf DOCUMENTATION FOR \HPTEX\ MACROS}\footnote{}{\hskip-.76in \eightrm\copyright 1984 Hewlett-Packard Co.} \smallskip \centerline{version A.00.00, Feb. 14, 1984.} \vskip1in \NOTE 1: PLAIN is read in as a separate file. \NOTE 2: ``@'' temporarily becomes a letter so that \HPTEX\ can use the internal control sequences of PLAIN, and to avoid conflict between the internal control sequences of \HPTEX\ and user names. \NOTE 3: This defines leaders used in the table of contents macros. \section{FONTS} \NOTE 4: \HPTEX\ has fonts available in sizes from 5 points to 24 points. The fonts loaded in Plain are listed as comments to make it easier to verify the fonts available. \NOTE 5: In case a font is used in a write or message. \NOTE 6: \\fontdef\#1\#2 defines the control sequence for the font, but the font is not loaded until the first time the control sequence is actually used. The first parameter is the control sequence to be defined; the second is the external font name. \section{MACROS TO SET FSTYLE} \NOTE 7: These macros set the family and the background style. Then, using \\setfont, they set the current font. \section{MACROS TO SET FSIZE} \NOTE 8: These macros set the background font size, and then use \\setfont to set the current font. \\baselineskip and \\strutbox are set to values appropriate to the font size. The fonts in families 0, 1, and 2 are changed to appropriate sizes. The fonts that are not already loaded, are not loaded unless they are needed by an entry into either math mode or display mode. \section{MACROS TO SET CURRENT FONT USING FSTYLE AND FSIZE} \NOTE 9: \\tryfont\#1 sets \\nofont@ to true if the control sequence determine by the current background font size and style (\#1) has not yet been defined. If the control sequence does exist, \\nofont@ is set to false, and the control sequence is invoked. \NOTE 10: \\setfont uses \\tryfont to set the current font based on the background font size and style. If there is no control sequence defined for that font, then \\tryfont is used again to check for a font with the background size and in roman style. If there is still no control sequence defined for that font, the size ten and style roman is tried. This will always succeed in \HPTEX. \itempar\\{f}fam will be a third factor in determining the current font when other font families become available. \section{DEFAULTS} \NOTE 11: The default values in \HPTEX\ are family0 and font \\tenrm, with a background style of roman, a background size of ten points, and a superscript/subscript size of seven points. \section{LINE MACROS} \NOTE 12: These line setting macros take \\leftskip and \\rightskip into account. \section{MORE MACROS} \NOTE 13: This replaces Knuth's definition of \\narrower. \\narrow@ is used in the note and warning macros. \NOTE 14: \\need is followed by a dimension x. It uses \\need@ to determine if x space remains on the page, and if not, causes an eject to the next page. \itempar\\need@ depends on \\okbreak which merely encourages a page break at that point. Its effect is dependent on its nearness to the bottom of the page, and whether the text following the \\need fits completely on the page or not. \NOTE 15: \\for provides a for-loop. Parameter \#1 (\\fcount@) contains the variable name; \#2 is the initial value of the variable; \#3 (\\fexit@) is the terminating value; \#4 (\\floop@) contains the instructions to be done in the loop. The loop will not execute unless the initial value (\#2) is less than or equal to the terminating value (\#3). \\next@ is set to \\fnext@. \NOTE 16: \\fnext@ provides the looping capability for \\for. It executes \\floop@ and then checks to see if \\fcount@ has reached the terminating value. If it hasn't, then \\fcount@ is incremented. If the terminating value has been reached, \\next@ is set to \\relax. \\next@ is then entered and depending on its current meaning, either the loop is repeated via \\fnext@, or \\relax ends the looping. \NOTE 17: \\uline\#1 makes a \\vbox containing \#1 with a horizontal rule .23em under its baseline, and then creates an \\hbox containing the vbox lowered by the amount necessary to place the baseline of \#1 in line with the baseline of the current line of text. \section{START AND FINISH GROUP STRUCTURE} \NOTE 18: \\start\#1 and \\finish\#1 define local nestable blocks. In the event of any error, the error message is delayed until corrections are complete. \NOTE 19: \\start\#1 uses \\{if}invalid@ to determine if \#1 is a valid blockname. If it is, a block (group) is begun and \\blockname@ stores \#1 as the name of the current block. The control sequence \\BEGIN\#1 is invoked and \\Error is called to print out any error messages. \NOTE 20: \\finish\#1 calls \\{if}invalid@ to determine if \#1 is a valid blockname. If it is valid, \\matchup@ is called to close block \#1. \\Error is called to print out any error messages. \NOTE 21: \\{if}invalid@\#1 tests to see if the control sequence \\BEGIN\#1 has been defined. If it has not been defined, it is ignored and \\errset is called to store an error message. \NOTE 22: \\matchup@\#1 closes blocks as follows: if a \\finish is used when no block currently exists, it is ignored. if a finish does not match the current blockname, blocks are closed until either a match is found or all blocks are closed. The parameter is the parameter to \\finish. \NOTE 23: \\done closes the current block. \section{GENERAL ERROR HANDLING} \NOTE 24: These macros are used for general purpose error handling. \\errfalse clears the error status. \\errset assumes an argument of an error message; any use of \\errset sets the error status and produces an error message when \\Error is encountered. \section{DATE AND TIME MACROS} \NOTE 25: \\mon sets the current month with the current font. \NOTE 26: \\date sets the current date: \langle month\rangle \langle day\rangle, \langle year\rangle. \NOTE 27: \\hour sets the current time of day in 12 hour format: \langle hour\rangle:\langle minutes\rangle \langle AM or PM\rangle. \section{INDENTSTYLE} \NOTE 28: The switch \\{if}indent acts as a flag to indicate when \\indentstyle is being used. This is used in \\indentstyle, \\noindentstyle, and \\indentspace. \NOTE 29: \\indentstyle sets \\parindent to \\indentsize. If \\indentstyle is already in effect, \\parskip is not changed. If \\indentstyle is not already in effect, \\parskip is decreased by 5 points. \NOTE 30: \\noindentstyle sets \\parindent to zero points. If \\indentstyle is in effect, \\parskip is increased by 5 points, otherwise it is not changed. \NOTE 31: \\indentspace will update \\parindent only if \\indentstyle is in effect. \section{RAGGED MARGIN} \NOTE 32: \\fixmargin@ preserves the original \\rightskip. \NOTE 33: \\justify undoes the effects of \\raggedright by returning to the original \\rightskip, and resetting the interword and intersentence space to the default values. \NOTE 34: \\raggedright saves the original \\rightskip with \\fixmargin@, adds some stretch to \\rightskip, and if \\tt is not in effect, fixes the interword and intersentence spaces. \NOTE 35: \\tt@ is used in \\raggedright in the \\ifx comparison. It is necessary if the comparison is to succeed. \section{ITEM AND SUBITEM} \NOTE 36: \\itemset@ takes three parameters: \#1 specifies the left indentation (in multiples of \\inset), \#2 should be the sum of the left and right indentation (in multiples of \\inset), and \#3 is the tag to be hung to the left of the item. The line size is in \\dimen@. \\parshape is used to build the paragraph. The tag (\#3) is hung to the left of the paragraph. \NOTE 37: \\itemlist\#1 is syntactically the same as \\item, however \\itemlist preserves \\leftskip and \\right\-skip, and both the left and right margins are indented by the value of \\inset. The parameter contains the tag for the item. Each time \\itemlist is used, the subitem tag is reset, and the item tag is incremented if appropriate. \NOTE 38: \\subitem\#1 is syntactically the same as \\itemitem, however left an rightskip are preserved, and both the left and right margins are indented by twice the value of \\inset. The parameter contains the tag for the subitem. Each time \\subitem is used, the subitem tag is incremented, if appropriate. \NOTE 39: \\itempar creates a paragraph identical to that created by \\itemlist except it will have an empty tag. It can be used for the second paragraph of an item. \NOTE 40: \\subitempar creates a paragraph like that created by \\subitem, but with an empty tag. \section{ITEM TAG AND SUBITEM TAG MACROS} \NOTE 41: The definition of a tag must do three things: \inset1in\itempar (1) define a control sequence \\reset[sub]items which will be used to restart tag allocation between lists; \itempar (2) restart tag allocation; \itempar (3) define a control sequence \\[sub]itemtag to produce a tag. \inset.825in \itempar\\icount@ (\\scount@) holds the value used to determine the current item (subitem) tag for numbered and lettered tags. \itempar\\idigit@ (\\sdigit@) is used with lettered tags to keep track of how many times the item [subitem] tags have gone through the alphabet without being reset. \NOTE 42: \\itemn@\#1 is used in the allocation of numbered tags. The parameter is either \\icount@ or \\scount@. \NOTE 43: \\itemr@\#1 is used in the allocation of lower case Roman tags. The parameter is either \\icount@ or \\scount@. \NOTE 44: \\itemR@\#1 is used in the allocation of upper case Roman tags. The parameter is either \\icount@ or \\scount@. \NOTE 45: \\iteml@\#1\#2 is used in the allocation of lettered tags. If the end of the alphabet is reached, it begins again with ``aa'' or ``AA''. The first parameter is either \\icount@ or \\scount@. The second parameter is either \\idigit@ or \\sdigit@. \NOTE 46: \\item@\#1,\#2,\#3 takes three parameters: \#1 is the initial value o \\icount@ (item counter), \#2 is the value of \\idigit@ which is used to print out the appropriate number of letters when using letters as tags, and \#3 is the definition of the \\itemtag. It defines \\resetitems to be the initialization of \\icount@ and \\idigit@. \NOTE 47: \\itm does not take a parameter. It uses the current \\itemtag as the parameter to \\itemlist. If the \\itemtag is numbers or letters, a period is appended to the tag. \NOTE 48: \\subitem@ is similar to \\item@. \NOTE 49: \\sitm is the subitem macro equivalent to \\itm for item. \NOTE 50: The defaults are \\numbereditems and \\letteredsubitems. The execution of these macros defines \\itemtag, \\subitemtag, \\resetitems, and \\resetsubitems. \section{NOTE AND WARNING MACROS} \NOTE 51: \\BEGINnote defines the blockname ``note'' and sets the indentation at twice the left and right skip amounts. \NOTE 52: \\BEGINwarning defines the blockname ``warning,'' sets the indentatio to twice the left and rightskip amounts, and places a horizontal rule above the text. \\ENDwarning places a horizontal rule below the text. \NOTE 53: \\marginrule\#1 defines an \\hrule limited by \\leftskip and \\rightskip. Its only parameter specifies the height of the rule. \section{VERBATIM MODE} \NOTE 54: In verbatim mode, all characters except (\\), ($\{$) and ($\}$) are treated verbatim. Characters that cannot be extracted from the current font are taken from the math font and given a fixed space equal to the space of the current font. \section{LUMPLINE AND LUMPSPACE MACROS} \NOTE 55: These macros make the verbatim mode use less memory. Multiple lines and spaces are lumped together to make one large glob of glue rather than many small globs. \itempar The carriage return is made into an active character, and given the meaning of \\lumpline@. \\lumpline@ accumulates sequential carriage returns into one lump of vertical glue in \\skip@. \itempar ``\\{\spacechar}'' is made into an active character, and given the meaning of \\lumpspace@. \\lumpspace@ accumulates sequential spaces into one lump of horizontal glue in \\skip@. \goodbreak \section{PAGE CONTROL MACROS} \NOTE 56: \\newpage first balances multi-column format which transfers the contents of \\box 255 to \\contrb@, so it always looks like the page is empty immediately afterwards. The box \\contrb@ is checked to see if the page is really empty. \itempar If \\newpage occurs at the bottom of a full page, the \\null\\vfill remains in recent contributions and causes an extra page to be ejected. The workaround is to insert an \\eject in the document just before the \\newpage (or the macro containing the \\newpage). \itempar The same problem occurs with \\evenpage and \\oddpage, and the same workaround is effective. \section{HEADING AND FOOTING MACROS} \NOTE 57: Headlines and footlines are constructed as follows: \inset1in \itempar (1) under normal conditions the centered heading or footing is centered, but in the event that one (or more) of the headings or footings are too wide, space is distributed if possible so there is no overlap. The macro triplehead@ does this. \itempar (2) inside and outside headings and footings have priority over left and right headings and footings. \\buildline takes care of this. \inset.825in \itempar Notice that if the tokens in an \\hbox have width 0pt, it is assumed they are empty. \itempar The macros and token registers associated with headings and footings should be used near forced page breaks or at the begining of the document. TeX scans ahead when building a page, so the use of these macros could affect the previous page. \NOTE 58: \\buildline decides which tokens will be on the left and right of the headline or footline that is being constructed. \\lft and \\rght hold the numbers of the boxes containing the tokens to be placed on the left and right sides of the line. They are initialized to the boxes for \\leftheading and \\rightheading. If the box containing the \\insideheading (\\box3) is not empty, then for an odd page \\lft is set to 3, and for an even page \\rght is set to 3. \itempar If the box containing the \\outsideheading (\\box4) is not empty, then for an odd page \\rght is set to 4, and for an even page \\lft is set to 4. \itempar \\triplehead is called to actually construct the line. \NOTE 59: \\triplehead\#1\#2\#3 requires three parameters. \#1 is the number of the box that is to go to the left, \#2 is the box number for the center, and \#3 is the box number for the right. \\skip@ is the glue to go between the left and center boxes, and \\skip@ii is the glue to go between the center and right boxes. \itempar If the width of the left box is greater than the width of the right box, \\skip@ii is increased by the difference, otherwise, \\skip@ is increased by the difference. \itempar The line is then built by stringing together the boxes and glue. \NOTE 60: \\loadbox\#1\#2 takes two parameters: \#1 is the box number, \#2 is t token list to be put in the box. \NOTE 61: \\headline checks to see if headings are turned on or off. If on, it loads the appropriate boxes with the various heading token lists and calls \\buildline. If off, it adds horizontal glue, and if \\suspendheading is in effect, updates the \\headcount. \NOTE 62: \\footline is similar to \\headline. \section{BOX MACROS} \NOTE 63: \\boxit\#1 takes as its parameter the text to be placed in the box, and can be used when a real box is wanted, e.g., \\setbox0\\boxit$\{${$\ldots$}$\}$. \\boxit uses \\halign to center the lines of text, separated by \\cr, within the box. \itempar The value of \\boxline determines the thickness of the rule around the box. The value of \\boxspace determines the amount of space between the rule and the text. \NOTE 64: \\centerbox\#1 takes as its parameter the text to be boxed, and then uses \\centerline to center the box resulting from \\boxit\#1. The box is separated from surrounding text by \\abovedisplayskip and \\belowdisplayskip. \NOTE 65: \\textbox\#1 takes as its parameter the text to be boxed. It places the boxed text in the current line (or begins a new paragraph if encountered in vertical mode) with the baseline of the enclosed text lined up with the baseline of the line. \section{HP2680A and HP2688A COPY CONTROL MACROS} \NOTE 66: These commands control the number of copies per page. Owing to the synchronization problems associated with TeX, these should only be used near forced page ejects or at the begining of a document. \itempar \\globalspecial writes the parameter to the postamble of the PIF file. \itempar \\copycnt contains the number of the register that the PIF server will look in to find the number of copies desired. \itempar \\oldcopy contains the number of copies desired. The default is two, so if \\copieson is invoked before the user has used \\copies\langle n\rangle, two copies will be generated. \section{HP2680A and HP2688A LOGICAL PAGE CONTROL (LPC) MACROS} \NOTE 67: \\lpcount@ holds the number of the register to be interpreted by the PIF driver for explicit logical page control. \itempar\\nextlp@ holds the page control number to be put into \\count\\lpcount@. \itempar These macros avoid the synchronization problems of TeX by interjecting a page eject at an appropriate time. At the beginning of the document and after each \\shipout, the ``empty@'' flag is set to true. \itempar If an LPC macro occurs when the ``empty@'' flag is true, \\ne is updated, its value is put into \\count\\lpcount@, and the flag is set to false. \itempar If an LPC macro occurs when the ``empty@'' flag is false, \\n is updated, but the value in the register \\count\\lpcount@ is not changed. After the next shipout, \\count\\lpcount@ is updated by the output routine. \itempar The codes for \\lpreset and \\lpexit will, if left alone, onl for one page. \section{TABLE MACROS} \NOTE 68: The table macros are complex. It is recommended that anyone wanting to understand how they work examine the LOG file of a table made with \\tracingmacros=1 and \\tracingcommands=2. \itempar The table macros use unallocated dimension and token registers to store the column specifications. New dimensions or tokens should not be allocated between the \\tableformat and the last \\tablerow or \\tablebar in a table. If any are allocated the result will be a very strange looking table and a TeX error. If too many columns, dimensions, tokens or inserts are allocated, an error message is given and the registers are used anyway. \itempar A row is processed in sections. \\parseline@ takes sections of the parameter to \\tableformat or \\tablerow. Each section is delimited by a ``\~{}''. \\parsecol@ takes sub-sections of the section where each sub-section is delimited by a ``$|$''. After a sub-section is processed, the next sub-section is fetched until the end of a section is reached. The next section is then fetched and processed until the end of the original parameter to \\tableformat or \\tablerow is reached. \itempar \\span is temporarily redefined during the execution of either a \\tablerow or \\tablebar macro to allow spanning of multiple columns. \itempar The standard table specifications are \\leftline, \\rightline, \\centerline and (for internal columns) \\paragraph. You can also make your own. There are only two rules: \inset1in \itempar(1) your macro will have one parameter (the text) \itempar(2) your macro will yield a box of width \\hsize. \inset.825in \NOTE 69: \\uptoks@ increments \\cntA@, used as a pointer to a token register to hold column alignment specifications, and \\cntB@, used as a pointer to a dimension register used to hold column width specifi\-% cations. If too many token registers are used, an error message is printed, and processing continues. \NOTE 70: \\bump@ increments \\cntC@, which contains the number of columns processed in the current \\tablerow or \\tablebar. If the total number of columns specified in the \\tableformat has not yet been processed, then \\cntC@ is incremented, and \\uptoks@ is called to increment the pointers to the registers that hold the column specifications. \NOTE 71: \\tableformat\#1 has as its parameter the description of the table format. The alignment for the entire table is given first, followed by the formats for each column. A column format consists of its alignment followed by its width. A ``$|$'' separates the table format from the column formats, and each column format from the next. \itempar \\tableformat first calls \\tablelet with the three parameters \\just@, \\just@, and \\relax. \itempar Next, \\parse@ (which has been assigned the meaning of \\parseline@) is called and sent one parameter, which is delimited by ``\lower4pt\hbox{\~{}}''. This effectively sends the contents of the parameter of \\tableformat up to the first \lower4pt\hbox{\~{}} to \\parse@ (\\parseline@). The \\done@ is an undefined control sequence used to mark the end of the specifications in the \\tableformat. \NOTE 72: \\tablerow\#1 is similar to \\tableformat. Its parameter is a list of the contents for each column of the row. Each column must start and terminate with either a ``$|$'' for a visible bar, or a ``\lower4pt\hbox{\~{}}'' for an invisible bar. \itempar The parameters sent to \\tablelet are: \\bbar@, \\wbar@, and \\endrow@. \NOTE 73: \\tablebar\#1 sets horizontal rules across the table. It resets \\topstrut, \\botstrut, and \\table\-space, and then passes its parameter to \\tablerow. Its parameter is a list of column contents, with each column indicated as for \\tablerow. A column can be empty, contain a \\vrule, or contain \\tbar. \NOTE 74: \\tablelet requires three parameters. The first is assigned to the control sequence \\b@, the second to \\w@, and the third to \\f@. \\CntA@, \\CntB@, and \\CntC@ are initialized. \\parse@ is assigned the meaning of \\parseline@. If currently in horizontal mode, vertical mode is entered; if in vertical mode, interline glue is inhibited. \NOTE 75: \\just@\#1 is never invoked directly. The control sequences \\b@ and \\w@ are \\let to be \\just@ in \\tablelet when \\tablelet is called from \\tableformat. \\just@ is invoked by \\parsecol@ the first time \\parsecol@ is entered. The parameter to \\just@ is the alignment specification for the table. \itempar \\just@ assigns the control sequences \\b@ and \\w@ the meaning of \\tform@, and initializes \\maxcol@ to 0. The control sequence \\tablejust@ is assigned the table alignment specification (\#1). \NOTE 76: \\tform@\#1 passes its parameter, which is the set of specifications for a column, on to \\tform@@ with a \lower 4pt\hbox{\~{}} deliminating the parameter. \NOTE 77: \\tform@@\#1\#2\lower 4pt\hbox{\~{}} updates the pointers to the registers to be used for storing column specifications, puts the column alignment (\#1) into the current token register, and the column width (\#2) into the current dimension register. Then \\maxcol@ is incremented to count the column just completed. \NOTE 78: \\bbar@\#1 begins a row that starts with a visible vrule. The parameter is empty. \NOTE 79: \\wbar@\#1 begins a row that starts with an invisible vrule. The parameter is empty. \NOTE 80: \\beginrow@\#1 reassigns \\b@ and \\w@ the meanings of \\vbar@ and \\ibar@ respectively. The parameter is empty. \itempar Box 0, an \\hbox that will contain the row, is begun with a \\bgroup, and the assignments that should hold within the box are made. \NOTE 81: \\endrow@ finishes Box 0 and aligns the resulting box according to \\tablejust@. \NOTE 82: \\vbar@\#1 adds a column entry that terminates with a visible \\vrule The parameter contains the column entry. \NOTE 83: \\ibar@\#1 adds a column entry that terminates with an invisible rule. The parameter contains the column entry. \NOTE 84: \\cs@\#1 determines if a column entry (\#1) spans multiple columns, and invokes \\span@ with the appropriate parameters. \NOTE 85: \\parseline@\#1\lower 4pt\hbox{\~{}} is called by \\tableformat and \\tablerow (and indirectly by \\tablebar). Its parameter is the part (section) of the parameter to the calling macro terminated by the first occurrence of ``\lower 4pt\hbox{\~{}}'' . If the parameter is \\done@, then processing is complete, and \\parse@ is assigned the current meaning of \\f@, which is \\relax if \\parseline@ was called from \\tableformat, or \\endrow@ if \\parseline@ was called from \\tablerow. \itempar If processing is not done, \\p@ss is assigned the meaning of \\parsecol@, and then \\p@ss is invoked and its parameter is that part (sub-section) of the parameter to \\parseline@ up to the first occurrence of ``$|$''. \\done@ is an end of processing indicator. \\parse@ is invoked and, depending on its current assigned meaning, either terminates processing of this \\tableformat or \\tablerow parameter, or takes the next section of the parameter of the \\tableformat or \\tablerow terminated by \lower 4pt\hbox{\~{}} as its parameter. \NOTE 86: \\parsecol@\#1 is called by \\parseline@ and has as its parameter tha part (sub-section) of the parameter to \\parseline@ up to the next occurrence of $|$. It defines the macro \\parsemode@: if we are on the last column, then the currently assigned value of \\w@ (\\tform@ or \\ibar@, depending on whether a \\tableformat or a \\tablerow is being processed) is invoked, and \\p@ss becomes \\lastp@ss; if we are not on the last column, then \\b@ (which is either \\tform@ or \\vbar@) is invoked; in either case, \\p@ss is called again and will either terminate processing or get the next section to be processed. \NOTE 87: \\span@\#1\#2 sets a box spanning the required number of columns and containing the text in the parameter. \\hsize and \\z@ are set to the width and alignment specifications respectively of the first column spanned. The pointers are then incremented once for each column spanned, and the width of each column plus the width of a vertical bar is added to the \\hsize for each column spanned. The first parameter is the integer following \\span, and the second is the remainder of the column contents. \section{SECTION AND HEADING MACROS} \NOTE 88: These macros are used for head or section level control. \itempar\\basehead is the zero pointer value for the four pointers to the head counters. The head counters count the number of current headings at each heading level. \itempar\\headlevel keeps track of the level of the current heading. \itempar To add a fifth level, do the following: \inset1in \itempar(1) Change the ``\\advance\\count10 by~4'' command to ``\\advance\\count10 by~5''. This allocates the counters for the level number. \itempar(2) Change ``\\ifnum\\hdlevel$<$4 '' to ``\\ifnum\\hdlevel$<$5'' in the \\sethead@ macro. \itempar(3) Allocate a new token register, \\fifthlevelhead, and define a corresponding \\headE@:\hfil\break \\def\\headE@$\{$\\head5\\the\\fifthlevelhead$\}$. \itempar(4) Modify the \\level macro so that it includes \\headE@. \itempar(5) Load \\fifthlevelhead with some appropriate tokens. \inset.825in \NOTE 89: \\setlevelno\#1 has one parameter: the levelnumber to be established. This can be up to 4 numbers, separated by periods. The level number and the pointer to the head counters are initialized. \itempar``.-1.'' is appended to the parameter to act as an end of parameter signal. \NOTE 90: \\sethead@\#1. has as its parameter one of the num\-bers in the parameter to \\setlevelno. The first num\-ber it receives is put into the head counter for the first level. The second number goes into the head counter for the second level, etc. Processing is completed when -1 is received as a parameter, or when 4 levels have been done. \NOTE 91: \\head\#1 is called indirectly by \\level via \\headA@, or \\headB@, etc. It oversees adjusting the \\levelno according to the level of the new heading. Its parameter is the level of the new heading. \itempar If the new heading is on a level inferior to the current heading, \\uplevel@ is called, otherwise \\headlevel is set to the level of the new heading and that head counter for that level is incremented. \itempar\\head@ is called to update \\levelno. \NOTE 92: \\uplevel@\#1 does what is necessary to add a level that has a higher number than the current level. \#1 is the level of the new heading. \NOTE 93: \\head@ defines \\levelno. \NOTE 94: These allocate token registers for each level description, and define a corresponding \\headA@ (or \\headB@ etc.) that calls \\head with the appropriate parameter, and accesses the tokens for that headlevel. \NOTE 95: \\level\#1\#2 takes two parameters: \#1 is the level of the heading, and \#2 becomes the definition of \\title. A case statement is used to invoke the appropriate choice of \\headA@, \\headB@, etc. \section{CONTENTS FILE MACROS} \NOTE 96: ``\\content@'' can now be written with \\write \NOTE 97: \\ctswrite\#1 writes its parameter into a file along with the current page number. If the file does not already exist, one is created. When the file is read at a later time, @ will not be a character. \\{\_} is redefined so that it can be read from the contents file. \\content@ is defined with @ no longer a character so that it can be read from the contents file. \NOTE 98: \\contents adds the table of contents if a contents file was created. \section{FOOTNOTES AND INSERTIONS} \NOTE 99: The \\vfootnote\#1 of PLAIN has been modified to accommodate multi-column format by the insertion of \\realhsize to restore the original \\hsize and by adding ``1\\baselineskip'' to remove any glue from \\baselineskip. \NOTE 100: \\note generates footnotes with sequential numbers. \NOTE 101: \\midinsert has been changed from the definition in PLAIN by the insertion of \\p@gefalse. \NOTE 102: \\@ins has been changed from the definition in PLAIN by adding a return to the normal \\hsize and \\vsize. \NOTE 103: The \\endinsert of PLAIN has been modified. The ``room left on page'' calculation has been expanded to handle multi-column format: if there is room, the columns are balanced and the insertion is appended. The penalty (first item in the \\insert) is set to -100 if the insertion cannot fit on the current page, this keeps the page from stretching if the insertion can't fit on the page. \section{COLUMN MACROS} \NOTE 104: The column macros and output routines are interrelated. Every time the number of columns changes, a false output routine is invoked. This routine takes the current page (and splits it up if necessary) and appends it to the contrib box. The \\hsize is then reduced (or restored) and the \\vsize is multiplied (or restored). Then, to every insert which was not void during the false output routine a null insert is made. This restores the page goal (in case there are no bona fide insertions, one insertion is always made, it is called \\hacker@). A new page total is then calculated from the height of the contrib box. The two macros employed to do this work are \\balance@ and \\newtotal@. Under no circumstances should the one be used without the other. \NOTE 105: \\balance invokes the false output routine which has the effect of balancing the columns if in multi-column mode. The page goal is then updated by \\newtotal@. \NOTE 106: \\balance@ invokes the false output routine by setting \\ifreal@ to false, and forcing an eject. \NOTE 107: \\newtotal@ restores the page total. \NOTE 108: \\multicol@\#1 is called by the \\BEGIN command for multi-column format. It takes as its only parameter the number of columns requested. It provides error checking and ignores the command if already in multi-column mode. If the command is legal, then the current page is balanced, and the \\hsize and \\vsize are adjusted. The insertion registers are modified, the page total is adjusted, and stretch is added to \\baselineskip. \section{OUTPUT ROUTINES} \NOTE 109: The output routines are complex. It is recommended that anyone wanting to understand how they work examine the LOG file of a file with \\tracingmacros=1 and \\tracingcommands=2. \itempar There are two types of output routines: \\realoutput@ produces a \\shipout and \\fakeoutput@ does not. \itempar The \\toks registers associated with each insert are now reserved (as were \\dimen, \\skip and \\count). Any tokens in these registers will be destroyed when the \\output routine is active. \NOTE 110: \\realoutput puts the current page into \\out@. If currently in one-column mode, it goes in directly, otherwise the current page is first split into columns. Box 255 is then set to \\contrb@ with \\old@ appended to it. The glue for insertions, \\hsize, \\vsize, \\leftskip, and \\rightskip are returned to normal for the \\shipout. After the \\shipout, the flags and counters for the logical page macros are updated. \NOTE 111: \\fakeoutput takes the current page, balances it if necessary, and puts it into \\out@. \\out@ is then appended to \\contrb@. \itempar If any column must be shorter due to balancing, it ought to be the rightmost. The \\vsplit primitive, however, will usually make the rightmost column longer. To avoid this problem, columns are split a little more than 1/2 or 1/3 down. Experimentation shows that adding 1.16667 baselines to the total height for 2 columns, and adding 2 baselines to the total height for 3 columns affords the greatest probability of an aesthetic break. \NOTE 112: The ``@'' is no longer a letter. \bye