summaryrefslogtreecommitdiff
path: root/obsolete/macros/hptex/hptex.doc
diff options
context:
space:
mode:
Diffstat (limited to 'obsolete/macros/hptex/hptex.doc')
-rw-r--r--obsolete/macros/hptex/hptex.doc751
1 files changed, 751 insertions, 0 deletions
diff --git a/obsolete/macros/hptex/hptex.doc b/obsolete/macros/hptex/hptex.doc
new file mode 100644
index 0000000000..4611efaa45
--- /dev/null
+++ b/obsolete/macros/hptex/hptex.doc
@@ -0,0 +1,751 @@
+This is the documentation for HP TeX, version A.00.00, Feb. 14, 1984.
+ Copyright 1984 Hewlett-Packard Co.
+
+NOTE 1: Plain is read in as a separate file.
+
+NOTE 2: "@" temporarily becomes a letter so that HP TeX can use the
+ internal control sequences of PLAIN, and to avoid conflict between
+ the internal control sequences of HP TeX and user names.
+
+NOTE 3: This defines leaders used in the table of contents macros.
+
+<<FONTS>>
+
+NOTE 4: HP TeX 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.
+
+<<MACROS TO SET FSTYLE>>
+
+NOTE 7: These macros set the family and the background style. Then using
+ \setfont they set the current font.
+
+<<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.
+
+<<MACROS TO SET CURRENT FONT USING FSTYLE AND FSIZE>>
+
+NOTE 9: \tryfont#1 sets \nofont@ to true if the control sequence determined
+ 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 HP TeX.
+
+ \ffam will be a third factor in determining the current font when
+ other font families become available.
+
+<<DEFAULTS>>
+
+NOTE 11: The default values in HP TeX 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.
+
+<<LINE MACROS>>
+
+NOTE 12: These line setting macros take \leftskip and \rightskip into
+ account.
+
+<<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.
+
+ \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 an \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.
+
+<<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 \ifinvalid@ to determine if #1 is a valid
+ blockname. If it is, a block (group) is begun and \blockname@
+ stores #1 as 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 \ifinvalid@ 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: \ifinvalid@#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.
+
+<<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.
+
+<<DATE AND TIME MACROS>>
+
+NOTE 25: \mon sets the current month with the current font.
+
+NOTE 26: \date sets the current date: <month> <day>, <year>.
+
+NOTE 27: \hour sets the current time of day in 12 hour format:
+ <hour>:<minutes> <AM or PM>.
+
+<<INDENTSTYLE>>
+
+NOTE 28: The switch \ifindent 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.
+
+<<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.
+
+<<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 \rightskip, 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 and
+ 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.
+
+
+<<ITEM TAG AND SUBITEM TAG MACROS>>
+
+NOTE 41: The definition of a tag must do three things:
+ 1. define a control sequence \reset[sub]items which will be
+ used to restart tag allocation between lists;
+ 2. restart tag allocation;
+ 3. define a control sequence \[sub]itemtag to produce a tag.
+
+ \icount@ (\scount@) holds the value used to determine the current
+ item (subitem) tag for numbered and lettered tags.
+
+ \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 of
+ \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.
+
+<<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 indentation
+ 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.
+
+<<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.
+
+
+<<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.
+
+ 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@.
+
+ '\ ' is made into an active character, and given the meaning of
+ \lumpspace@. \lumpspace@ accumulates sequential spaces into
+ one lump of horizontal glue in \skip@.
+
+<<PAGE CONTROL MACROS>>
+
+NOTE 56: \newpage first balances multi-column format which transfers the
+ contents of \box 255 to \contrib@, so it always looks like the
+ page is empty immediately afterwards. The box \contrb@ is checked
+ to see if the page is really empty.
+
+ 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).
+
+ The same problem occurs with \evenpage and \oddpage, and
+ the same workaround is effective.
+
+<<HEADING AND FOOTING MACROS>>
+
+NOTE 57: Headlines and footlines are constructed as follows:
+
+ (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.
+
+ (2) inside and outside headings and footings have priority over
+ left and right headings and footings. \buildline takes care of
+ this.
+
+ Notice that if the tokens in an \hbox have width 0pt, it is
+ assumed they are empty.
+
+ 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.
+
+ 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.
+
+ \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.
+
+ 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.
+
+ 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 the
+ 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.
+
+<<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{...}.
+ \boxit uses \halign to center the lines of text, separated by \cr,
+ within the box.
+
+ 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.
+
+<<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.
+
+ \globalspecial writes the parameter to the postamble of the
+ PIF file.
+
+ \copycnt contains the number of the register that the PIF server
+ will look in to find the number of copies desired.
+
+ \oldcopy contains the number of copies desired. The default is
+ two, so if \copieson is invoked before the user has used \copies<n>,
+ two copies will be generated.
+
+<<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.
+
+ \nextlp@ holds the page control number to be put into
+ \count\lpcount@.
+
+ 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.
+
+ If an LPC macro occurs when the "empty@" flag is true, \nextlp@
+ is updated, its value is put into \count\lpcount@, and the flag
+ is set to false.
+
+ If an LPC macro occurs when the "empty@" flag is false, \nextlp@
+ is updated, but the value in \count\lpcount@ is not changed. After
+ the next shipout, \count\lpcount@ is updated by the output routine.
+
+ The codes for \lpreset and \lpexit will, if left alone, only endure
+ for one page.
+
+<<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 small table created with \tracingmacros=1 and \tracingcommands=2.
+
+ 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.
+
+ 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.
+
+ \span is temporarily redefined during the execution of either a
+ \tablerow or \tablebar macro to allow spanning of multiple columns.
+
+ The standard table specifications are \leftline, \rightline,
+ \centerline and (for internal columns) \paragraph. You can also
+ make your own. There are only two rules:
+ (1) your macro will have one parameter (the text)
+ (2) your macro will yield a box of width \hsize.
+
+
+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.
+
+ \tableformat first calls \tablelet with the three parameters
+ \just@, \just@, and \relax.
+
+ Next, \parse@ (which has been assigned the meaning of \parseline@)
+ is called and sent one parameter, which is delimited by ~. This
+ effectively sends the contents of the parameter of \tableformat up
+ to the first ~ 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 ~ for an
+ invisible bar.
+
+ 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 \tablespace, 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.
+
+ \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 ~ deliminating the parameter.
+
+NOTE 77: \tform@@#1#2~ 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.
+
+ Box0, 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~ 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 ~ . 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.
+
+ 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 ~ as its parameter.
+
+NOTE 86: \parsecol@#1 is called by \parseline@ and has as its parameter that
+ 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 AND HEADING MACROS>>
+
+NOTE 88: These macros are used for head or section level control.
+
+ \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.
+
+ \headlevel keeps track of the level of the current heading.
+
+ To add a fifth level, do the following:
+ (1) Change the "\advance\count10by4" command to
+ "\advance\count10by5". This allocates
+ the counters for the level number.
+
+ (2) Change "\ifnum\hdlevel<4 " to "\ifnum\hdlevel<5
+ in the \sethead@ macro.
+
+ (3) Allocate a new token register, \fifthlevelhead, and
+ define a corresponding \headE@
+ (e.g., \def\headE@{\head5\the\fifthlevelhead}).
+
+ (4) Modify the \level macro so that it includes \headE@.
+
+ (5) Load \fifthlevelhead with some appropriate tokens.
+
+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.
+
+ .-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 numbers in the
+ parameter to \setlevelno. The first number 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.
+
+ 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.
+
+ \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.
+
+<<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.
+
+<<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.
+
+<<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.
+
+<<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
+ short file with \tracingmacros=1 and \tracingcommands=2.
+
+ There are two types of output routines: \realoutput@ produces a
+ \shipout and \fakeoutput@ does not.
+
+ 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 are updated for the
+ logical page macros.
+
+
+NOTE 111: \fakeoutput takes the current page, balances it if necessary, and
+ puts it into \out@. \out@ is then appended to \contrb@.
+
+ 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.