summaryrefslogtreecommitdiff
path: root/systems/doc/hitex/hitexman.tex
diff options
context:
space:
mode:
Diffstat (limited to 'systems/doc/hitex/hitexman.tex')
-rw-r--r--systems/doc/hitex/hitexman.tex707
1 files changed, 707 insertions, 0 deletions
diff --git a/systems/doc/hitex/hitexman.tex b/systems/doc/hitex/hitexman.tex
new file mode 100644
index 0000000000..2c58f877c4
--- /dev/null
+++ b/systems/doc/hitex/hitexman.tex
@@ -0,0 +1,707 @@
+% This file is part of HINT
+% Copyright 2017-2021 Martin Ruckert, Hochschule Muenchen, Lothstrasse 64, 80336 Muenchen
+%
+% Permission is hereby granted, free of charge, to any person obtaining a copy
+% of this software and associated documentation files (the "Software"), to deal
+% in the Software without restriction, including without limitation the rights
+% to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+% copies of the Software, and to permit persons to whom the Software is
+% furnished to do so, subject to the following conditions:
+%
+% The above copyright notice and this permission notice shall be
+% included in all copies or substantial portions of the Software.
+%
+% THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+% IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+% FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+% COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+% WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT
+% OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+% THE SOFTWARE.
+%
+% Except as contained in this notice, the name of the copyright holders shall
+% not be used in advertising or otherwise to promote the sale, use or other
+% dealings in this Software without prior written authorization from the
+% copyright holders.
+
+\input cwebmac
+\input hint.sty
+
+\makeindex
+\maketoc
+
+\titletrue
+\pageno=-2
+
+\def\lastrevision{${}$Revision: 2541 ${}$}
+\def\lastdate{${}$Date: 2021-10-26 09:03:28 +0200 (Tue, 26 Oct 2021) ${}$}
+
+\font\largetitlefont=cmssbx10 scaled\magstep4
+\font\Largetitlefont=cmssbx10 at 40pt
+\font\hugetitlefont=cmssbx10 at 48pt
+\font\smalltitlefontit=cmbxti10 scaled\magstep3
+\font\smalltitlefont=cmssbx10 scaled\magstep3
+
+\hbox{}
+\vskip 0pt plus 1fill
+{
+ \baselineskip=1cm\parindent=0pt
+ \largetitlefont\raggedright Hi\TeX\par
+ \vskip 10pt plus 0.3fill
+ \leftline{\smalltitlefont User Manual}
+ \vskip-3pt
+ \vskip 10pt plus 0.3fill
+ \hskip 0pt plus 2fill \it F\"ur Beatriz\hskip 0pt plus 0.5fill\hbox{}
+ \vskip 10pt plus 3fill
+ \leftline{\smalltitlefont Version 1.1 (Draft)}
+ \bigskip
+ \raggedright\baselineskip=12pt
+ \bf MARTIN RUCKERT \ \it Munich University of Applied Sciences\par
+ \bigskip
+ \lastdate, \lastrevision\par
+ \smallskip
+}
+{\raggedright\advance\rightskip 3.5pc
+\def\:{\discretionary{}{}{}}
+\noindent
+Internet page {\tt http:\://hint.\:userweb.\:mwn.\:de/\:hint/\:format.html}
+may contain current information about this book, downloadable software,
+and news.
+
+\smallskip
+\noindent
+Copyright $\copyright$ 2022 by Martin Ruckert
+\smallskip
+}
+\frontmatter
+\pageno=-1
+
+\tableofcontent
+
+\mainmatter
+
+\def\rs{\hskip 2pt plus 3pt minus 2pt\penalty0\relax}
+\def\rule#1:#2.{\par{\hangindent32pt\hangafter1\parindent0pt\rightskip 0pt plus 60pt#1{\bf:}\quad%
+ \hskip 0pt plus 60pt\penalty-300\hskip 0pt plus -60pt#2{\bf.}\par}}
+\def\sym#1{\rs$<${\it #1\/}$>$\rs}
+\def\OR{\rs${}\vert{}$\rs}
+\def\opt#1{\rs$[{}$#1${}]$\rs}
+\def\cs#1{\.{\BS #1}}
+
+\section{Hi\TeX\ primitives}
+
+While currently Hi\TeX\ is the only \TeX\ engine that supports output in the \HINT\ file
+format, this might not be so forever. To avoid unnecessary complications for
+package writers, it is strongly suggested that all such \TeX\ engines implement
+the same primitives according to the same specification. The following is the first
+draft of this specification. All the primitives use {\tt HINT} as a prefix to
+avoid name conflicts. The prefix {\tt HINT}, as opposed to e.g. {\tt HiTeX},
+was chosen to stress the idea that these primitives are specific for the
+output format---not for the \TeX\ engine.
+
+Because this is the first specification that will reach a wider user base,
+it is reasonable to expect changes to occur in the future. Therefore it is
+recommended that these primitives should not be used directly in a
+\TeX\ document; instead they should be encapsulated in suitable
+macros so that the consequences of any change to the primitives will
+be local to these macros.
+
+\subsection{Syntax Description}
+In the following, we describe the syntax of primitive control sequences which were
+added to \TeX.
+
+\itemize
+\item We use a {\tt typewriter font}\index{typewriter font}
+for text that occurs \index{verbatim}verbatim in the \TeX\ document.
+\item We use \sym{italics} enclosed in pointed brakets to denote symbols\index{symbol+\sym{symbol}}.
+\item We use rules\index{rule} to define the meaning of symbols.
+A rule starts with the symbol
+to be explained, followed by a colon ``{\bf :}'', and then the text that this symbol
+stands for. A rule ends with a period ``{\bf .}''.
+\item Optional\index{optional+\opt{optional}} parts of the rule's text
+are enclosed in \opt{square brackets}.
+\item Alternatives\index{alternative} are seperated by a vertical bar ``\OR''\index{\OR}.
+\item Some symbols refere to text that is defined as part of standard \TeX. These are explained here by an example:
+
+\medskip
+\rule\sym{integer}: \index{integer+\sym{integer}}
+ an integer as in \cs{penalty}\sym{integer}.
+\rule\sym{normal dimension}:\index{normal dimension+\sym{normal dimension}}
+ a dimension as in \cs{hrule} \.{width} \sym{normal dimension}.
+\rule\sym{dimension}:\index{dimension+\sym{dimension}}
+ a dimension as in \cs{vskip} \.{0pt} \.{plus} \sym{dimension}.
+\rule\sym{name}:\index{dimension+\sym{dimension}}
+ a name as in \cs{input} \sym{name}.
+\rule\sym{vertical list}:\index{vertical list+\sym{vertical list}}
+ a token list with matching braces as in
+ \cs{vbox}\.{\LB}\sym{vertical list}\.{\RB}.
+\rule\sym{horizontal list}:\index{horizontal list+\sym{horizontal list}}
+ a token list with matching braces as in
+ \cs{hbox}\.{\LB}\sym{horizontal list}\.{\RB}.
+\rule\sym{general text}:\index{general text+\sym{general text}}
+ a token list with matching braces as in
+ \cs{write}\.{\LB}\sym{general text}\.{\RB}.
+\medskip
+\enditemize
+
+\subsection{Version and Revision}
+The control sequences \cs{HINTversion}\index{HINTversion+\cs{HINTversion}}
+and \cs{HINTsubversion}\index{HINTsubversion+\cs{HINTsubversion}} are
+used to determine the version and subversion numbers of the HINT output format
+that is generated by Hi\TeX. It can be used as part of the output as
+in \verbatim|\the\HINTversion|.
+The most important use, however, is testing whether the current \TeX\ engine
+will in fact produce \HINT\ output.
+As an example the file {\tt ifhint.tex}\index{ifhint.tex+{\tt ifhint.tex}}
+contains the following code:
+
+
+\verbatim/
+\newif\ifhint
+\expandafter\ifx\csname HINTversion\endcsname\relax
+ \hintfalse\else\hinttrue\fi/
+
+
+\subsection{Images}
+The primitive \cs{HINTimage}\index{HINTimage+\cs{HINTimage}}
+includes an image\index{image} in a document.
+The syntax is as follows:
+
+\medskip
+\cs{HINTimage} \opt{\.{=}} \sym{name}
+\opt{\sym{width}} \opt{\sym{height}}
+\medskip
+
+The optional equal sign can be added to make the code look nicer.
+The \sym{name} specifies the image file.
+The width specification determines the width of the image. If omitted,
+Hi\TeX\ tries to determine the image's width from the image file.
+The same holds for the height specification.
+
+\medskip
+\rule \sym{width}\index{width+\sym{width}}:\.{width} \sym{normal dimension}.
+\rule \sym{height}\index{height+\sym{height}}:\.{height} \sym{normal dimension}.
+\medskip
+
+Note that a \sym{normal dimension} that is computed from \cs{hsize}
+or \cs{vsize} retains this dependency when processed by Hi\TeX.
+This allows an image to adapt to the size of the viewing area.
+Scaling in the \HINT\ viewer will, however, never change the
+aspect ratio of an image. So it may become smaller or larger,
+but it will never be distorted.
+For this reason, Hi\TeX\ will inspect the image file to determine the
+aspect ratio\index{aspect ratio} of the stored image.
+The width and height values as given in the \TeX\ file serve
+as the maximum values for the actual width and height. When rendering,
+the image will become as large as possible within the given bounds.
+If \TeX\ does not specify neither width nor height, the image file
+must specify the absolute width and height of the image.
+It is considered an error if valid settings for the image's width and height
+can not be obtained.
+
+\subsection{Links, Labels, and Outlines}
+A link\index{link} in a \HINT\ document refers to another location in the same document.
+It can be used to navigate to that location.
+A link is defined using the primitives
+\cs{HINTstartlink}\index{HINTstartlink+\cs{HINTstartlink}}
+and \cs{HINTendlink}\index{HINTendlink+\cs{HINTendlink}}.
+Neither of them can be used in vertical mode.
+The text between the start and the end of the link
+constitutes the visible part of the link. Depending on the user interface, clicking
+or tapping or otherwise activating the link (e.g. pronouncing)
+will navigate to the destination of the link.
+The user interface might provide a visual clue to make the user aware of the
+available links but it also may choose to leave the visual clues to the author
+of the document (e.g. using a special image or a special font).
+
+The syntax is
+\cs{HINTstartlink} \sym{destination}
+and
+\cs{HINTendlink}
+with
+
+\medskip
+\rule \sym{destination}\index{destination+\sym{destination}}:\.{goto} \sym{label}.
+\rule \sym{label}\index{label+\sym{label}}:
+ \.{name} \.{\LB}\sym{general text}\.{\RB} \OR\ \.{num} \sym{integer}.
+\medskip
+
+As you can see, the link refers to its destination using a label
+which is either a name or a number.
+The destination can be defined by using the
+\cs{HINTdest}\index{HINTdest+\cs{HINTdest}} primitive.
+Forward and backward links are allowed; the definition of a lable can either
+preceede or follow the use of the label. If at the end of the document a label
+is undefined, a warning is given, and the label will reference the beginning of the
+document.
+
+The syntax is
+\cs{HINTdest} \sym{label} \opt{\sym{placement}}
+with
+
+\medskip
+\rule\sym{placement}\index{placement+\sym{placement}}:
+\.{top}\index{top+{\tt top}} \OR\ \.{bot}\index{bot+{\tt bot}}.
+\medskip
+
+The optional placement argument specifies how to build the page
+containing the destination location. \.{top} demands
+a page starting with the destination location. This is useful
+if the destination is for example the start of a section or chapter heading.
+Similarly \.{bot} asks for a page that ends with the destination location.
+The most common case is to omit the placement argument. In this case, the
+viewer will build a ``good'' page that includes the given destination.
+In case of a section heading, for example, it will most probably start the
+page with the section heading because section headings are usually preceded
+by a negative penalty that will convince the page builder that this is a good
+place to break the page. But if the section heading is immediately preceded
+by a chapter heading, the negative penalty found there will probably
+persuade the page builder to start with the chapter heading instead.
+
+There is a special label that has the form
+\.{name} \.{\LB}\.{HINT.home}\.{\RB}\index{HINT.home+{\tt HINT.home}}.
+It is used to mark the ``home page''\index{home page} of the document. User interfaces
+are encouraged to offer a button or keyboard shortcut to navigate to the
+document location labeled this way. The page should be a convenient
+starting point to explore the document. The typical place for this label
+would be the documents table of content.
+
+The labels that identify destinations in a document can also be used
+to define document outlines. A document outline\index{outline} is a document summary
+given as a hierarchical list of headings where each of them
+refers to a specific location in the document.
+
+The syntax is
+\cs{HINToutline}\index{HINToutline+\cs{HINToutline}}
+\sym{destination} \opt{\sym{depth}} \.{\LB}\sym{horizontal list}\.{\RB}.
+
+\medskip
+\rule \sym{depth}\index{depth+\sym{depth}}: \.{depth} \sym{integer}.
+\medskip
+
+The user interface can format the \sym{horizontal list} much like
+a \cs{hbox} would do and displays it to the user. When the user selects
+this text, the document will be repositioned to show the destination location
+in the same way as with a link. In order to support also simpler
+user interfaces, the current \HINT\ backend also extracts the characters
+(and spaces) from the horizontal list (in top-left to bottom-right order)
+and makes this character string available to the user interface.
+
+
+The order in which outline items are defined is important because
+this is the order in which they will be presented to the reader of the
+document. The optional depth argument allows to structure
+the list of outline items as a hierarchy. Outline items with a higher depth value are considered to be sub-items of items earlier in the list with lower
+depth values. If no depth value is given, the depth value is set to zero.
+It is not necessary to define depth values strictly consecutive.
+
+
+\subsection{Page Templates and Streams}\index{page template}\index{stream}
+
+To produce the final page, \TeX\ uses a special piece of program
+called the output routine\index{output routine}. Because a \HINT\
+file is pure data, it can not contain output routines. Instead it
+uses page templates to assemble pages from the main text, footnotes,
+floating illustrations, and other material. I start here by
+describing how \HINT's page templates work and the special syntax used
+to specify them in a \TeX\ file that is about to be processed with
+Hi\TeX. For those interested in how the design decision was made and
+how page templates relate to \TeX's page building mechanism, a
+separate section follows at the end.
+
+The syntax of a page template specification is:
+\cs{HINTsetpage}\index{HINTsetpage+\cs{HINTsetpage}}
+\sym{integer} \opt{\.{=}} \sym{name}
+\opt{\sym{priority}} \opt{\sym{width}} \opt{\sym{height}}
+\.{\LB}\sym{vertical list} \sym{stream definition list}\.{\RB}
+
+
+The \sym{integer} specifies the page templates number in the range 1
+to 255. The number 0 is reserved for the build in page template of
+the \HINT\ file format, which is used if no other page template has
+been defined. The page template 0 can not be redefined.
+The \sym{name} associates a name with the page template. The name can
+be displayed by the \HINT\ viewer to help the user selecting a
+suitable page template.
+
+After the name follows an optional priority; it is used to select the
+``best page template'' if multiple templates are available. The
+default value is~1. The build-in template has priority~0.
+
+\medskip
+\rule\sym{priority}\index{priority+\sym{priority}}: {\tt priority} \sym{integer}.
+\medskip
+
+
+After that follows an optional width and height of the full page
+including the margins. After subtracting \cs{hsize} from the width
+and \cs{vsize} from the height, the remainder is used for the margins
+around the displayed text. For example giving the width as
+1.2\cs{hsize} will leave 0.1\cs{hsize} for the margins on both sides.
+In this case the margins will grow together with the available width
+of the display. If the width is computed by adding 20pt
+to \cs{hsize}, the margin will be 10pt on both sides. In this case
+the margin will not grow with the size of the display, but it will
+grow with the magnification factor. Of course both methods can be
+used together. The default is \cs{hsize} for the width and \cs{vsize}
+for the height so there are no margins.
+
+The following \sym{vertical list} defines the page itself. It should assign suitable values
+to \cs{topskip} and \cs{maxdepth} because the values valid at the end of the vertical list
+are stored in the page template and are used in the page building process.
+The vertical list usually also specifies the insertion of content streams using a \sym{stream insert point}.
+
+\medskip
+\rule\sym{stream insert point}\index{stream insert point+\sym{stream insert point}}:
+ \cs{HINTstream} \sym{integer}.
+\medskip
+
+Here the \sym{integer} must be in the range 0 to 254. The value 255 is invalid;
+the value 0 indicates the main body of text (what \TeX's page builder would normally put into
+box 255 before calling the output routine).
+Otherwise, the \sym{integer} is TeX's insertion number, that is the number of \TeX's box
+containing the insertions. As usual, this box is filled using \TeX's \cs{insert} primitive.
+So after plain \TeX\ has defined \cs{footins},
+the footnotes for the current page can be inserted after the main body of text in the \sym{vertical list}
+by saying \cs{HINTstream}\.0 followed by \cs{HINTstream}\cs{footins}.
+Of course you might want to have a footnote rule and a small skip to separate the
+footnotes ---if there are any---from the main text. This can be achieved by a suitable
+\sym{stream definition} in the \sym{stream definition list}.
+
+\medskip
+\rule\sym{stream definition list}\index{stream definition list+\sym{stream definition list}}:
+ \OR\ \sym{stream definition list} \sym{stream definition}.
+\rule\sym{stream definition}\index{stream definition+\sym{stream definition}}:
+ \cs{HINTsetstream} \sym{integer} \opt{\.{=}}
+\opt{{\tt preferred} \sym{integer}}
+\opt{\.{next} \sym{integer}}
+\opt{\.{ratio} \sym{integer}} \.{\LB}\sym{vertical list}\.{\RB}.
+\medskip
+
+
+The first \sym{integer} is the streams insertion number $i$,
+and it must match the \sym{integer}
+previously used in the \sym{stream insert point}.
+Then follows the optional specification of a prefered stream with insertion number $p$,
+a next stream with insertion number $n$, and a split ratio $r$.
+If $r>0$, the contributions to stream $i$ are split between
+stream $p$ and $n$ in the ratio $r/1000$ for $p$ and $1-r/1000$ for $n$
+before contributing streams $p$ and $r$ to the page.
+Else if $p\ge0$ any insertion to stream $i$ is moved to stream $p$ as long as possible,
+and if $n\ge0$ we move an insert to stream $n$ if there is ``no room left'' in $p$ nor in $i$.
+How much ``room'' is available for the insertions is specified inside the vertical list
+that follows.
+Here \cs{dimen}$i$ should be set to the maximum total height of the insertions in class $i$ per page.
+\cs{count}$i$ should be set to the magnification factor $f$,
+such that inserting a box of height $h$ will contribute $h*f/1000$ to the main page;
+and \cs{skip}$i$ should be set to the extra space needed if an insertion in class $i$ is present.
+
+This extra space is usually taken up by material that is inserted before and after the insertions,
+such as for example the footnote rule. This material can be defined by a
+\sym{before list} and an \sym{after list}.
+
+\medskip\index{HINTbefore+\cs{HINTbefore}}\index{HINTafter+\cs{HINTafter}}
+\rule \sym{before list}\index{before list+\sym{before list}}:
+ \cs{HINTbefore} \opt{\.{=}} \.{\LB}\sym{vertical list}\.{\RB}.
+\rule \sym{after list}\index{after list+\sym{after list}}:
+ \cs{HINTafter} \opt{\.{=}} \.{\LB}\sym{vertical list}\.{\RB}.
+\medskip
+
+If you are interested in the design decision that motivate the definitions that have
+be given in this section, you should read the next section.
+
+
+\section{Replacing \TeX's Page Builder}
+
+\TeX\ uses an output\index{output routine} routine to finalize the page.
+The output outine takes the material which the page builder had accumulated in {\tt box255}
+and attaches headers, footers, and floating material
+like figures, tables, and footnotes. The latter material is specified by insert nodes
+while headers and footers are often constructed using mark nodes.
+Running an output routine requires the full power of the \TeX\ engine and is not
+part of the \HINT\ viewer. Therefore, \HINT\ replaces output routines by page templates\index{template}.
+\TeX\ can use different output routines for different parts of a book---for example
+the index might use a different output routine than the main body of text.
+
+\TeX\ uses insertions to describe floating content that is not necessarily displayed
+where it is specified. Three examples may illustrate this:
+\itemize
+\item Footnotes\footnote*{Like this one.} are specified in the middle of the text but are displayed at the
+bottom of the page. Several
+footnotes\index{footnote} on the same page are collected and displayed together. The
+page layout may specify a short rule to separate footnotes from the
+main text, and if there are many short footnotes, it may use two columns
+to display them. In extreme cases, the page layout may demand a long
+footnote to be split and continued on the next page.
+
+\item Illustrations\index{illustration} may be displayed exactly where specified if there is enough
+room on the page, but may move to the top of the page, the bottom of the page,
+the top of next page, or a separate page at the end of the chapter.
+
+\item Margin notes\index{margin note} are displayed in the margin on the same page starting at the top
+of the margin.
+\enditemize
+
+\HINT\ uses page templates and content streams to achieve similar effects.
+But before I describe the page building\index{page building} mechanisms of \HINT,
+let me summarize \TeX's page builder.
+
+\subsection{\TeX's page building mechanism}
+\TeX's page builder ignores leading glue\index{glue}, kern\index{kern},
+and penalty\index{penalty} nodes until the first
+box\index{box node} or rule\index{rule node} node is encountered;
+whatsit\index{whatsit node} nodes do not really contribute anything to
+a page; mark\index{mark node} nodes are recorded for later use. Once
+the first box, rule, or insert\index{insert node} arrives, \TeX\ makes
+copies of all parameters that influence the page building process and
+uses these copies. These parameters are the \.{page\_goal} and the
+\.{page\_max\_depth}. Further, the variables {\tt page\_total}, {\tt page\_shrink},
+{\tt page\_stretch}, {\tt page\_depth}, and {\tt in\-sert\_pe\-nal\-ties} are
+initialized to zero. The top skip\index{top skip} adjustment is made
+when the first box or rule arrives---possibly after an insert.
+Now the page builder accumulates material: normal material goes
+into {\tt box255}\index{box 255} and will change {\tt page\_total}, {\tt page\_shrink},
+{\tt page\_stretch}, and {\tt page\_depth}. The latter is adjusted so that
+is does not exceed {\tt page\_max\_depth}.
+
+The handling of inserts\index{insert node} is more complex.
+\TeX\ creates an insert class using {\tt newinsert}. This reserves a number $i$
+and four registers: {\tt box\hair$i$} for the inserted material,
+{\tt count\hair$i$} for the magnification factor $f$, {\tt dimen\hair$i$}
+for the maximum size per page $d$, and {\tt skip\hair$i$} for the
+extra space needed on a page if there are any insertions of class $i$.
+
+For example plain \TeX\ allocates $n=254$ for footnotes\index{footnote} and sets
+{\tt count254} to~$1000$, {\tt dimen254} to 8in, and {\tt skip254} to {\tt \BS big\-skip\-amount}.
+
+An insertion node will specify the insertion class $i$, some vertical material,
+its natural height plus depth $x$, a {\tt split\-\_top\-\_skip}, a {\tt split\-\_max\_depth},
+and a {\tt floa\-ting\-\_pe\-nal\-ty}.
+
+
+Now assume that an insert node with subtype 254 arrives at the page builder.
+If this is the first such insert, \TeX\ will decrease the {\tt page\_goal}
+by the width of {\tt skip254} and adds its stretchability and shrinkability
+to the total stretchability and shrinkability of the page. Later,
+the output routine will add some space and the footnote rule to fill just that
+much space and add just that much shrinkability and stretchability to the page.
+Then \TeX\ will normally add the vertical material in the insert node to
+{\tt box254} and decrease the {\tt page\_goal} by $x\times f/1000$.
+
+Special processing is required if \TeX\ detects that there is not enough space on
+the current page to accommodate the complete insertion.
+If already a previous insert did not fit on the page, simply the {\tt floating\_penalty}
+as given in the insert node is added to the total {\tt insert\_penalties}.
+Otherwise \TeX\ will test that the total natural height plus depth of {\tt box254}
+including $x$ does not exceed the maximum size $d$ and that the
+${\tt page\_total} + {\tt page\_depth} + x\times f/1000 - {\tt page\_shrink} \le {\tt page\_goal}$.
+If one of these tests fails, the current insertion
+is split in such a way as to make the size of the remaining insertions just pass the tests
+just stated.
+
+Whenever a glue node, or penalty node, or a kern node that is followed by glue arrives
+at the page builder, it rates the current position as a possible end of the page based on
+the shrinkability of the page and the difference between {\tt page\_total} and {\tt page\_goal}.
+As the page fills, the page breaks tend to become better and better until the
+page starts to get overfull and the page breaks get worse and worse until
+they reach the point where they become {\tt awful\_bad}. At that point,
+the page builder returns to the best page break found so far and fires up the
+output routine.
+
+
+\subsection{\HINT\ Page Templates}
+Let's look at the problems that show up when implementing a replacement for \TeX's
+page building mechanism.
+
+\enumerate
+\item
+An insertion node can not always specify its height $x$ because insertions may contain paragraphs that need
+to be broken in lines and the height of a paragraph depends in some non obvious way on
+its width.
+
+\item
+Before the viewer can compute the height $x$, it needs to know the width of the insertion. Just imagine
+displaying footnotes in two columns or setting notes in the margin. Knowing the width, it
+can pack the vertical material and derive its height and depth.
+
+\item
+\TeX's plain format provides an insert macro that checks whether there is still space
+on the current page, and if so, it creates a contribution to the main text body, otherwise it
+creates a {\tt topinsert}. Such a decision needs to be postponed to the \HINT\ viewer.
+
+\item
+\HINT\ has no output routines that would specify something like the space and the rule preceding the footnote.
+
+\item
+\TeX's output routines have the ability to inspect the content of the boxes,
+split them, and distribute the content over the page.
+For example, the output routine for an index set in two column format might
+expect a box containing index entries up to a height of $2\times\.{vsize}$.
+It will split this box in the middle and display the top part in the left
+column and the bottom part in the right column. With this approach, the
+last page will show two partly filled columns of about equal size.
+
+\item
+\HINT\ has no mark nodes that could be used to create page headers or footers.
+Marks, like output routines, contain token lists and need the full \TeX\ interpreter
+for processing them. Hence, \HINT\ does not support mark nodes.
+\endenumerate
+
+
+Instead of output routines, \HINT\ uses page templates.
+Page templates are basically vertical boxes with \sym{stream insert points} marking the
+positions where the content of the box registers, filled by the page builder,
+should appear.
+To output the page, the viewer traverses the page template,
+replaces the placeholders by the appropriate box content, and
+sets the glue.
+
+It is only natural to treat the page's main body,
+inserts, and marks using the same mechanism. We call this
+mechanism a content stream\index{stream}.
+Content streams are identified by a stream number in the range 0 to 254;
+the number 255 is used to indicate an invalid stream number.
+The stream number 0 is reserved for the main content stream; it is always defined.
+
+\medskip
+{\small \advance \leftskip by 30pt \advance \rightskip by 30pt
+It is planed to implement a replacement for \TeX's mark nodes using
+different types of streams:
+\itemize
+\item normal streams correspond to \TeX's inserts and accumulate content on the page,
+\item first\index{first stream} streams correspond to \TeX's first marks and will contain only the first insertion of the page,
+\item last\index{last stream} streams correspond to \TeX's bottom marks and will contain only the last insertion of the page, and
+\item top\index{top stream} streams correspond to \TeX's top marks. Top streams are not yet implemented.
+\enditemize
+\medskip
+}
+
+Nodes from the content section are considered contributions to stream~0 except
+for insert nodes which will specify the stream number explicitly.
+If the stream is not defined or is not used in the current page template, its content is simply ignored.
+
+The page builder needs a mechanism to redirect contributions from one content
+stream to another content stream based on the availability of space.
+Hence a \HINT\ content stream can optionally specify a preferred stream number,
+where content should go if there is still space available, a next stream number,
+where content should go if the present stream has no more space available, and
+a split ratio if the content is to be split between these two streams before
+filling in the template.
+
+Various stream parameters govern the treatment of contributions to the stream
+and the page building process.
+
+\itemize
+\item The magnification factor $f$: Inserting a box of height $h$ to this stream will contribute $h\times f/1000$
+to the height of the page under construction. For example, a stream
+that uses a two column format will have an $f$ value of 500; a stream
+that specifies notes that will be displayed in the page margin will
+have an $f$ value of zero.
+
+\item The height $h$: The extended dimension $h$ gives the maximum height this
+stream is allowed to occupy on the current page.
+To continue the previous example, a stream that will be split into two columns
+will have $h=2\cdot\.{vsize}$ , and a stream that specifies
+notes that will be displayed in the page margin will have
+$h=1\cdot\.{vsize}$. You can restrict the amount of space occupied by
+footnotes to the bottom quarter by setting the corresponding $h$ value
+to $h=0.25\cdot\.{vsize}$.
+
+\item The depth $d$: The dimension $d$ gives the maximum depth this
+stream is allowed to have after formatting.
+
+\item The width $w$: The extended dimension $w$ gives the width of this stream
+when formatting its content. For example margin notes
+should have the width of the margin less some surrounding space.
+
+\item The ``before'' list $b$: If there are any contributions to this
+stream on the current page, the material in list $b$
+is inserted {\it before\/} the material from the stream itself. For
+example, the short line that separates the footnotes from the main
+page will go, together with some surrounding space, into the list~$b$.
+
+\item The top skip glue $g$: This glue is inserted between the material
+from list $b$ and the first box of the stream, reduced
+by the height of the first box. Hence it specifies the distance between
+the material in $b$ and the first baseline of the stream content.
+
+\item The ``after'' list $a$: The list $a$ is treated like list $b$ but
+its material is placed {\it after\/} the material from the stream itself.
+
+\item The ``preferred'' stream number $p$: If $p\ne 255$, it is the number of
+the {\it preferred\/} stream. If stream $p$ has still
+enough room to accommodate the current contribution, move the
+contribution to stream $p$, otherwise keep it. For example, you can
+move an illustration to the main content stream, provided there is
+still enough space for it on the current page, by setting $p=0$.
+
+\item The ``next'' stream number $n$: If $n\ne 255$, it is the number of the
+{\it next\/} stream. If a contribution can not be
+accommodated in stream $p$ nor in the current stream, treat it as an
+insertion to stream $n$. For example, you can move contributions to
+the next column after the first column is full, or move illustrations
+to a separate page at the end of the chapter.
+
+\item The split ratio\index{split ratio} $r$: If $r$ is positive, both $p$ and $n$ must
+be valid stream numbers and contents is not immediately moved to stream $p$ or $n$ as described before.
+Instead the content is kept in the stream itself until the current page is complete.
+Then, before inserting the streams into the page template, the content of
+this stream is formatted as a vertical box, the vertical box is
+split into a top fraction and a bottom fraction in the ratio $r/1000$
+for the top and $(1000-r)/1000$ for the bottom, and finally the top
+fraction is moved to stream $p$ and the bottom fraction to stream
+$n$. You can use this feature for example to implement footnotes
+arranged in two columns of about equal size. By collecting all the
+footnotes in one stream and then splitting the footnotes with $r=500$
+before placing them on the page into a right and left column. Even
+three or more columns can be implemented by cascades of streams using
+this mechanism.
+\enditemize
+
+\HINT\ allows multiple page templates but Hi\TeX\ currently does not implement
+restricting them to individual page ranges and the viewer selects
+the page template with the highest priority. To support different output media, the page
+templates are named and a suitable user interface may offer the user a selection
+of possible page layouts. In this way, the page layout remains in the hands of the
+book designer, and the user has still the opportunity to pick a layout that best fits
+the display device.
+
+The build-in page template with number 0 is always defined and has priority 0.
+It will display just the main content stream. It puts a small margin
+of $\.{hsize}/8 -4.5\hbox{pt}$ all around it.
+Given a letter size page, 8.5 inch wide, this formula yields a margin of 1 inch,
+matching \TeX's plain format. The margin will be positive as long as
+the page is wider than $1/2$ inch. For narrower pages, there will be no
+margin at all. In general, the \HINT\ viewer will never set {\tt hsize} larger
+than the width of the page and {\tt vsize} larger than its height.
+
+%8.5 in should give 1 inch margin 2/17
+%612pt should give 72pt margin
+%72pt = 612/8-4.5pt
+%This would give a positive margin starting at 36pt or 1/2 inch
+
+
+%\appendix
+
+%\plainsection{References}
+
+%{\baselineskip=11pt
+%\def\bfblrm{\small\rm}%
+%\def\bblem{\small\it}%
+%\bibliography{../hint}
+%\bibliographystyle{plain}
+%}
+
+\plainsection{Index}
+{
+\def\_{{\tt \UL}} % underline in a string
+\catcode`\_=\active \let_=\_ % underline is a letter
+\input hitexman.ind
+}
+
+\write\cont{} % ensure that the contents file isn't empty
+% \write\cont{\catcode `\noexpand\@=12\relax} % \makeatother
+\closeout\cont% the contents information has been fully gathered
+\inx
+\fin
+\end