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.tex129
1 files changed, 81 insertions, 48 deletions
diff --git a/systems/doc/hitex/hitexman.tex b/systems/doc/hitex/hitexman.tex
index 23694eb199..d54e89a637 100644
--- a/systems/doc/hitex/hitexman.tex
+++ b/systems/doc/hitex/hitexman.tex
@@ -33,13 +33,6 @@
\titletrue
-
-\def\setrevision$#1: #2 ${\gdef\lastrevision{#2}}
-\setrevision$Revision: 62515 $
-\def\setdate$#1(#2) ${\gdef\lastdate{#2}}
-\setdate$Date: 2022-03-08 14:02:10 +0100 (Tue, 08 Mar 2022) $
-
-
\null
\font\largetitlefont=cmssbx10 scaled\magstep4
@@ -103,7 +96,8 @@ Germany.
\medskip
{\tt ruckert\:@cs.hm.edu}
\medskip
-Revision: \lastrevision,\quad Date: \lastdate\par
+\def\lastrevision{Date: Mon Dec 4 15:00:09 2023}
+\lastrevision\par
}
\eject
\endgroup
@@ -123,7 +117,40 @@ Revision: \lastrevision,\quad Date: \lastdate\par
\def\opt#1{\rs$[{}$#1${}]$\rs}
\def\ctl#1{{\tt\BS #1}}
-\section{Hi\TeX\ primitives}
+\section{Introduction}
+When I started the \HINT\ project in 2017,
+I tried to keep the project as small as possible to increase the
+chances that I would be able to complete it. So one design decision
+was to keep things simple---or to quote Albert Einstein: ``Make things
+as simple as possible, but not simpler''. The other imperative was:
+keep things out of the viewer if possible because I do not know
+how much processing power or battery power is available.
+
+As a consequence, I focused on Donald Knuth' original \TeX,
+disregarding all later extensions like \eTeX\ or \LaTeX, and I
+decided that the \TeX\ interpreter would not need to run in the
+viewer.
+Of course \TeX's line breaking routine will run in the viewer
+and modifications of \TeX's page breaking routine.
+But the decision to keep the TeX interpreter
+out of the HINT viewer implies that \HINT\ files do
+not contain token lists and that there are
+neither output routines nor marks.
+To replace them, the \HINT\ file format includes
+page templates. I have described the technical
+means to specify page templates below and try to explain
+the rationale behind it, but \HINT's page templates
+are at the time of this writing a largely untested area.
+
+By now, the state of the \HINT\ project is far beyond of what
+I had expected then, and the processing power of even low-cost
+mobile devices is far better than expected especially when programming the
+graphics card directly using OpenEGL.
+
+The following sections will describe all the primitive control sequences
+that are special for Hi\TeX. I tried to be as close to similar primitives
+that have proven to be useful in other engines, notably pdftex, to make
+it easy for package writers to support the Hi\TeX\ engine.
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
@@ -132,7 +159,28 @@ the same primitives according to the same specification. The following is the fi
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.
+output format---not for the \TeX\ engine.
+
+It is common practice in other \TeX\ engines to support the \ctl{special}
+primitive to insert raw code snippets in the output. Using this primitive,
+it is possible to insert PostScript code into a PS file, or PDF code in a
+PDF output file. It is currently not planed to support this mechanism for
+\HINT\ output files for two reasons:
+First, the development of Hi\TeX\ is closely related to the development of
+the \HINT\ file format and therefore features that are part of the \HINT\
+file format will enjoy support in Hi\TeX\ by corresponding primitives.
+Everything that is not available through primitives in Hi\TeX\ should
+be considered ``internal'' and might change in the future.
+Second, Hi\TeX\ is not considered a replacement but
+a supplement to other engines. If your aim is the production of a printed
+book, your will probably target one of the engines that produce PDF output.
+But if, on occassion, you want to read what you wrote on a computer screen,
+you might just use Hi\TeX\ to process your source file. At this point you
+do not want to write \ctl{special} commands for the new target; you want
+Hi\TeX\ as a plug-in replacement for your main target engine, even if it
+is not completely faithful to your final printed book.
+
+\section{Hi\TeX\ primitives}
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
@@ -181,8 +229,8 @@ are enclosed in \opt{square brackets}.
\subsection{Version and Revision}
The control sequences \ctl{HINTversion}\index{HINTversion+\ctl{HINTversion}}
-and \ctl{HINTsubversion}\index{HINTsubversion+\ctl{HINTsubversion}} are
-used to determine the version and subversion numbers of the HINT output format
+and \ctl{HINTminorversion}\index{HINTminorversion+\ctl{HINTminorversion}} are
+used to determine the major and minor version 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
@@ -193,7 +241,8 @@ contains the following code:
\verbatim/
\newif\ifhint
-\expandafter\ifx\csname HINTversion\endcsname\relax
+\expandafter
+ \ifx\csname HINTversion\endcsname\relax
\hintfalse\else\hinttrue\fi/
@@ -234,6 +283,8 @@ 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.
@@ -446,45 +497,13 @@ If you are interested in the design decision that motivate the definitions that
be given in this section, you should read section~\secref{build}.
\section{Other Primitives}
-When I started the \HINT\ project in 2017,
-I tried to keep the project as small as possible to increase the
-chances that I would be able to complete it. So one design decision
-was to keep things simple---or to quote Albert Einstein: ``Make things
-as simple as possible, but not simpler''. The other imperative was:
-keep things out of the viewer if possible because I do not know
-how much processing power or battery power is available.
-As a consequence, I focused on Donald Knuth' original \TeX,
-disregarding all later extensions like \eTeX\ or \LaTeX, and I
-decided that the \TeX\ interpreter would not need to run in the
-viewer.
-
-By now, the state of the \HINT\ project is far beyond of what
-I had expected then, and the processing power of even low-cost
-mobile devices is far better than expected especially when programming the
-graphics card directly using OpenEGL.
-
-But the line breaking routine, which is running in the viewer, and the
-HINT file format, which specifies all the parameters for the
-line breaking algorithm, covers just the line breaking of
-Donald Knuth's original \TeX. Therefore the viewer will
-also do just that, and Hi\TeX\ can not produce files
-doing more than that. Of course that might not be so
-for ever.
-Similarly, the decision to keep the TeX interpreter
-out of the HINT viewer implies that \HINT\ files do
-not contain token lists. This means that there are
-no output routines and no marks.
-To replace them, the \HINT\ file format includes
-page templates. I have described the technical
-means to specify page templates above and try to explain
-the rationale behind it below, but \HINT's page templates
-are at the time of this writing a largely untested area.
Since I consider the support for \LaTeX\ to be crucial for
the success of the \HINT\ project, quite a few primitives
have been added to Hi\TeX\ that go beyond \TeX's original
specification.
+\subsection{\eTeX}
First, the primitives of \eTeX\ have been
added with the exception of those primitives that deal with
line breaking, with right to left reading, and with marks.
@@ -501,6 +520,7 @@ Here is a list of \eTeX\ primitives that are missing in Hi\TeX:
\item\ctl{topmarks} (multiple marks)
\enditemize
+\subsection{\LaTeX\ and \Prote}
Second, the primitives required to support
\LaTeX\ were added using Thierry Larondes implementation of \Prote.
@@ -521,6 +541,17 @@ Second, the primitives required to support
\enditemize
+\subsection{{\tt kpathsearch} and \ctl{input}}
+In Don Knuths implementation of \TeX, the \ctl{input} primitive
+will add the extension {\tt .tex} to any filename that does not have an
+extension. This implies that a file without extension can not be opened
+as an input file. The usual engines do not add such an extension but
+pass the filename as given to \verbatim/kpse_find_file/ function.
+Hi\TeX\ does the same. The {\tt kpathsearch} library will find files
+in a variety of directories and yes, it will also find files without
+extension. Using this library is just mandatory for any engine that
+wants to process \LaTeX\ input.
+
\section{Replacing \TeX's Page Builder}\label{build}
@@ -561,7 +592,8 @@ let me summarize \TeX's page builder.
\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
+whatsit\index{whatsit node} nodes do not really contribute
+anything\footnote*{This changes when images are implemented as whatsit nodes.} 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
@@ -583,7 +615,8 @@ 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}.
+{\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},