path: root/macros/hptex/dochc.tex

% 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