\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.
