| 1 |
% etex_gen.tex --- How to generate e-TeX --- last modified 06 Mar 1998 |
| 2 |
|
| 3 |
\font\eighttt= cmtt8 |
| 4 |
\font\eightrm= cmr8 |
| 5 |
\font\rtitlefont= cmr7 scaled\magstep5 |
| 6 |
\font\ititlefont= cmmi7 scaled\magstep5 |
| 7 |
\def\titlefont{\rtitlefont \textfont1=\ititlefont} |
| 8 |
\def\eTeX{$\varepsilon$-\TeX} |
| 9 |
\def\NTS{NTS} |
| 10 |
\let\mc=\eightrm |
| 11 |
\rm |
| 12 |
\let\mainfont=\tenrm |
| 13 |
|
| 14 |
\def\.#1{\hbox{\tt#1}} |
| 15 |
\def\\#1{\hbox{\it#1\/\hskip.05em}} % italic type for identifiers |
| 16 |
|
| 17 |
\parskip 2pt plus 1pt |
| 18 |
\baselineskip 12pt plus .25pt |
| 19 |
|
| 20 |
\output{\shipout\box255\global\advance\pageno by 1} % for the title page only |
| 21 |
\null |
| 22 |
\vfill |
| 23 |
\centerline{\titlefont How to generate \eTeX} |
| 24 |
\vskip 6pt |
| 25 |
\centerline{({\sl Version 2, March 1998\/})} |
| 26 |
\vskip 18pt |
| 27 |
\centerline{by The \NTS\ Team} |
| 28 |
\vskip 6pt |
| 29 |
\centerline{Peter Breitenlohner, Max-Planck-Institut f\"ur Physik, M\"unchen} |
| 30 |
\vskip 6pt |
| 31 |
\centerline{Philip Taylor, RHBNC, University of London} |
| 32 |
\vfill |
| 33 |
\centerline{\vbox{\hsize 4in |
| 34 |
\noindent Given an implementation of \TeX82 for a particular system, this |
| 35 |
report describes how to generate a corresponding implementation of |
| 36 |
\eTeX.}} |
| 37 |
\vskip 24pt |
| 38 |
{\baselineskip 9pt |
| 39 |
\eightrm\noindent |
| 40 |
The preparation of this report was supported in part by DANTE, |
| 41 |
Deutschsprachige Anwendervereinigung \TeX\ e.V.\hfil\break |
| 42 |
`\TeX' is a trademark of the American Mathematical Society. |
| 43 |
|
| 44 |
}\pageno=0\eject |
| 45 |
|
| 46 |
\output{\shipout\vbox{ % for subsequent pages |
| 47 |
\baselineskip0pt\lineskip0pt |
| 48 |
\hbox to\hsize{\strut |
| 49 |
\ifodd\pageno \hfil\eightrm\firstmark\hfil |
| 50 |
\mainfont\the\pageno |
| 51 |
\else\mainfont\the\pageno\hfil |
| 52 |
\eightrm\firstmark\hfil\fi} |
| 53 |
\vskip 10pt |
| 54 |
\box255} |
| 55 |
\global\advance\pageno by 1} |
| 56 |
\let\runninghead=\mark |
| 57 |
\outer\def\section#1.{\noindent{\bf#1.}\quad |
| 58 |
\runninghead{\uppercase{#1} }\ignorespaces} |
| 59 |
|
| 60 |
\section Introduction. |
| 61 |
Let us first review the process of generating an implementation of |
| 62 |
\TeX82 for a particular system from the source files as, e.g., described |
| 63 |
in the \.{WEB} manual [1]. The system-independent source file |
| 64 |
\.{tex.web} must remain unmodified. All changes to \.{tex.web} |
| 65 |
necessary for a particular operating system and\slash or compiler are to |
| 66 |
be collected in a system-dependent change file, typically named |
| 67 |
\.{tex.ch}. Both files \.{tex.web} and \.{tex.ch} are effectively |
| 68 |
merged when input by the \.{WEB} system programs \.{WEAVE} and |
| 69 |
\.{TANGLE}. When \.{WEAVE} processes this merged input, a file |
| 70 |
\.{tex.tex} is produced. Further processing by \TeX\ yields a `pretty |
| 71 |
printed' version of the input together with an index. |
| 72 |
|
| 73 |
When \.{TANGLE} processes the merged input, a string pool file |
| 74 |
\.{tex.pool} and a Pascal file \.{tex.pas} (or similar) are produced. |
| 75 |
The Pascal file can then be further processed by a suitable compiler |
| 76 |
and\slash or language converter such as \.{web2c}, and eventually yields |
| 77 |
an executable program. |
| 78 |
|
| 79 |
There are actually three versions of the program: First there is |
| 80 |
\.{INITEX} with its capability to initialize all of \TeX's tables and to |
| 81 |
write them in compact form to a format file. Next there is the |
| 82 |
production version \.{VIRTEX} requiring a format file as input. Finally |
| 83 |
there is \.{TRIPTEX}, a version of \.{INITEX} with special values for |
| 84 |
some of \TeX's parameters, for the \.{TRIP} test [2] that should be used |
| 85 |
to validate a \TeX\ implementation. Depending on the capabilities of |
| 86 |
the compiler, these three versions of the program are generated from |
| 87 |
three slightly different change files or they are generated from one |
| 88 |
change file with different compiler options. They might even be one and |
| 89 |
the same executable program used with different run time options. |
| 90 |
|
| 91 |
\vskip 24pt plus 24pt |
| 92 |
\section Generating \eTeX. |
| 93 |
The process of generating \eTeX\ is essentially the same as that of |
| 94 |
generating \TeX\ as described above. Conceptually there is a |
| 95 |
system-independent source file \.{etex.web} and a system-dependent change |
| 96 |
file \.{etex.sys}. Processing these two files by \.{TANGLE} yields a |
| 97 |
string pool file \.{etex.pool} as well as a Pascal file \.{etex.pas}, |
| 98 |
whilst processing by \.{WEAVE} produces a \TeX\ source file, \.{etex.tex}. |
| 99 |
|
| 100 |
It may, however, be necessary to increase some of the constants defined |
| 101 |
in \.{TANGLE} and \.{WEAVE}. The following values should suffice in |
| 102 |
most cases: |
| 103 |
$$ |
| 104 |
\vcenter{\halign{$#$\hfil\qquad&#\hfil\cr |
| 105 |
\\{max\_bytes}\times\\{ww}=100~000&\.{TANGLE} and \.{WEAVE}\cr |
| 106 |
\\{max\_texts}=2~500&\.{TANGLE} and \.{WEAVE}\cr |
| 107 |
\\{max\_toks}\times\\{zz}=180~000&\.{TANGLE}\cr |
| 108 |
\\{max\_names}=5~000&\.{TANGLE}\cr |
| 109 |
\\{max\_scraps}=3~000&\.{WEAVE}\cr |
| 110 |
\\{stack\_size}=300&\.{WEAVE}\cr |
| 111 |
}} |
| 112 |
$$ |
| 113 |
|
| 114 |
The source file \.{etex.web} for \eTeX\ does not, however, exist as a |
| 115 |
physical file. It is the hypothetical file obtained by applying the |
| 116 |
changes in the actual source file \.{etex.ch} to \.{tex.web}. Thus |
| 117 |
\.{etex.web} inherits the bulk of code from \.{tex.web}, whilst the |
| 118 |
system-independent source file \.{etex.ch} for \eTeX\ defines the |
| 119 |
differences between \.{etex.web} and \.{tex.web}. In order to generate |
| 120 |
an implementation of \eTeX\ two change files have to be applied to |
| 121 |
\.{tex.web}, one after the other (the actual file names may differ): |
| 122 |
$$ |
| 123 |
\vcenter{\halign{#\hfil&\qquad\.{#}\hfil&\qquad#\hfil\cr |
| 124 |
0.&tex.web&system-independent \.{WEB} source for \TeX\cr |
| 125 |
1.&etex.ch&system-independent changes for \eTeX\cr |
| 126 |
2.&etex.sys&system-dependent changes for \eTeX\cr |
| 127 |
}} |
| 128 |
$$ |
| 129 |
|
| 130 |
The process of merging several change files into \.{tex.web} should |
| 131 |
certainly not be performed by hand. There are programs such as \.{TIE} |
| 132 |
and \.{PATCHWEB} that perform this process automatically. If no such |
| 133 |
program is available, a \TeX\ program \.{WEBMERGE} can be used. |
| 134 |
\.{WEBMERGE} reads \.{tex.web} and up to nine change files and produces |
| 135 |
a merged change file that can then be processed, together with |
| 136 |
\.{tex.web}, by \.{TANGLE} and \.{WEAVE}. [On systems such as VMS, use |
| 137 |
of \.{WEBMERGE} can leave a large number of temporary files |
| 138 |
lying around; this can be avoided by setting a version limit (e.g.~1) on any |
| 139 |
existing versions of those files, or by setting a version limit on the |
| 140 |
directory in which they will be created. On other systems, it will probably |
| 141 |
leave one large temporary file.] |
| 142 |
|
| 143 |
Every implementor of \eTeX\ is responsible for creating and maintaining |
| 144 |
a suitable \.{etex.sys} in the same way as every implementor of \TeX\ |
| 145 |
is responsible for creating and maintaining \.{tex.ch}. Since the bulk |
| 146 |
of code in \.{etex.web} is identical to that in \.{tex.web} the bulk of |
| 147 |
the system-dependent changes in \.{etex.sys} for a particular system |
| 148 |
will be identical to those in \.{tex.ch} for the same system. In the |
| 149 |
following we try to give some hints where \.{etex.sys} for a particular |
| 150 |
system might deviate from the corresponding \.{tex.ch}. |
| 151 |
|
| 152 |
First, it might be necessary to increase the size of \TeX's string pool |
| 153 |
in order to accommodate \eTeX's additional strings (message texts as |
| 154 |
well as multi-letter control sequences). If this turns out to be |
| 155 |
necessary for \eTeX\ it would certainly not be harmful to do it for |
| 156 |
\TeX\ as well. \TeX\ and \eTeX\ use three constants related to the |
| 157 |
string pool: \\{max\_strings} the maximal number of strings, |
| 158 |
\\{pool\_size} the maximal number of string characters, and |
| 159 |
\\{string\_vacancies} the minimal number of available string characters |
| 160 |
in addition to those occupied by strings from the pool file. It is, |
| 161 |
therefore, sufficient to increase \\{pool\_size} (or reduce |
| 162 |
\\{string\_vacancies}) by the number of \eTeX's additional string |
| 163 |
characters and to increase \\{max\_strings} by the number of \eTeX's |
| 164 |
additional strings. The latter will, however, be unnecessary for most |
| 165 |
implementations as \\{max\_strings} is usually increased substantially |
| 166 |
beyond its standard value in order to accommodate large \TeX\ macro |
| 167 |
packages. |
| 168 |
|
| 169 |
For Version~2 of \eTeX, there are about 100 additional strings with |
| 170 |
about 1500 additional string characters. The precise numbers can be |
| 171 |
obtained by running \.{POOLTYPE} on \TeX's and \eTeX's pool files |
| 172 |
(\.{POOLTYPE} reports the total number of strings and string characters |
| 173 |
in a pool file). |
| 174 |
|
| 175 |
Next, \.{etex.sys} may contain a system-dependent modification of the |
| 176 |
\\{eTeX\_banner} string. The modified \\{eTeX\_banner} string must |
| 177 |
contain `\.{e-TeX}' as well as the \eTeX\ version number. Note, |
| 178 |
however, that the \\{banner} string modified by \.{tex.ch} will not be |
| 179 |
referenced by \eTeX\ unless the implementor intentionally changes that |
| 180 |
aspect of \eTeX's functionality: therefore \.{etex.sys} can modify the |
| 181 |
\\{banner} string in the same way as does \.{tex.ch}. |
| 182 |
|
| 183 |
Then, \.{etex.sys} might deviate from \.{tex.ch} in order to use a |
| 184 |
different pool file name and\slash or format file extension (see below). |
| 185 |
|
| 186 |
Finally, \.{etex.sys} will necessarily deviate whenever \.{etex.ch} |
| 187 |
and \.{tex.ch} try to change the same piece of \.{WEB} code or when the |
| 188 |
system-independent \eTeX\ changes from \.{etex.ch} and the |
| 189 |
system-dependent \TeX\ changes from \.{tex.ch} interfere in some other way. |
| 190 |
In case of any such interference implementors must first of all determine |
| 191 |
how to combine the respective changes from \.{etex.ch} and \.{tex.ch} |
| 192 |
in order to obtain \eTeX's functionality for a particular system. |
| 193 |
Obviously, this process cannot be automated since it requires human |
| 194 |
insight. |
| 195 |
|
| 196 |
The \NTS\ team has tried to formulate \.{etex.ch} such that |
| 197 |
interferences with system-dependent change files \.{tex.ch} are |
| 198 |
unlikely. Suggestions by implementors how any remaining such |
| 199 |
interferences could be avoided by a reformulation of \.{etex.ch} will |
| 200 |
be taken into serious consideration. Such interferences can be further |
| 201 |
reduced by reformulating the system-dependent change file \.{tex.ch} for |
| 202 |
\TeX, e.g.\ by reducing the range of change entries from entire modules |
| 203 |
to the pieces of code that are actually changed. |
| 204 |
|
| 205 |
Implementors might prefer to maintain the system-dependent change file |
| 206 |
\.{etex.sys} not as a physical file but as a hypothetical file defined |
| 207 |
through its deviation from \.{tex.ch}. If there are no interferences of |
| 208 |
the kind mentioned above, then the effect of applying the changes from |
| 209 |
the hypothetical \.{etex.sys} to the hypothetical \.{etex.web} can be |
| 210 |
achieved by applying 3 change files, one after the other, to \.{tex.web} |
| 211 |
(using some tool such as \.{TIE}, \.{PATCHWEB}, or \.{WEBMERGE}): |
| 212 |
$$ |
| 213 |
\vcenter{\halign{#\hfil&\qquad\.{#}\hfil&\qquad#\hfil\cr |
| 214 |
0.&tex.web&system-independent \.{WEB} source for \TeX\cr |
| 215 |
1.&etex.ch&system-independent changes for \eTeX\cr |
| 216 |
2.&tex.ch&system-dependent changes for \TeX\cr |
| 217 |
3.&tex.ech&additional system-dependent changes for \eTeX\cr |
| 218 |
}} |
| 219 |
$$ |
| 220 |
The third change file \.{tex.ech} will be rather short and contains just |
| 221 |
the differences between \.{etex.sys} and \.{tex.ch}. It is recommended |
| 222 |
that implementors try to remove all interferences between \.{etex.ch} |
| 223 |
and \.{tex.ch} and use this method to generate \eTeX. |
| 224 |
|
| 225 |
As with \TeX\ there are three versions of \eTeX: \.{e-INITEX}, |
| 226 |
\.{e-VIRTEX}, and \.{e-TRIPTEX}. Depending on the implementation they |
| 227 |
will again be generated from the three slightly different versions of |
| 228 |
\.{tex.ch} or with different compiler options or they may be one and the |
| 229 |
same program used with different run time options. |
| 230 |
|
| 231 |
\vskip 24pt plus 24pt |
| 232 |
\section \eTeX\ modes. |
| 233 |
In order to ensure maximal compatibility with \TeX, \eTeX\ can run in |
| 234 |
either compatibility mode or extended mode. The possibility of this |
| 235 |
choice is, of course, an extended feature of \eTeX. Once \eTeX\ has |
| 236 |
chosen compatibility mode it is, however, a legitimate implementation of |
| 237 |
\TeX\ (assuming the \TeX\ implementation itself is legitimate). The |
| 238 |
only differences between \eTeX\ in compatibility mode and \TeX\ are |
| 239 |
those allowed by D.~E.~Knuth [2] between different implementations of |
| 240 |
\TeX. |
| 241 |
|
| 242 |
An \.{e-TRIP} test suite [3] defines the criteria by which a program can |
| 243 |
qualify to use the name `\eTeX'. Part of the \.{e-TRIP} test consists |
| 244 |
of the standard \.{TRIP} test for \.{e-TRIPTEX} in compatibility and |
| 245 |
extended mode. |
| 246 |
|
| 247 |
\eTeX\ can therefore be used instead of \TeX\ without the necessity to |
| 248 |
maintain both programs. For the case that both programs should |
| 249 |
nevertheless co-exist on a system, it might be a good idea to name the |
| 250 |
pool file for \eTeX\ \.{etex.pool} instead of \.{tex.pool} and to use |
| 251 |
an extension other than \.{.fmt}, e.g., \.{.efmt} for \eTeX\ format |
| 252 |
files. (Format files for \TeX\ and \eTeX\ are incompatible). All this |
| 253 |
will require additional changes in the file \.{tex.ech}. |
| 254 |
|
| 255 |
When \.{INITEX} or \.{VIRTEX} start, they inspect the first non-blank |
| 256 |
character from the command line or in response to the \.{**} prompt. |
| 257 |
This may be an \.{\&} immediately followed by the name of a format file |
| 258 |
to be loaded. Otherwise \.{VIRTEX} loads a default format, whereas |
| 259 |
\.{INITEX} starts without loading a format. |
| 260 |
|
| 261 |
When \.{e-INITEX} or \.{e-VIRTEX} start, they inspect the first |
| 262 |
non-blank character from the command line or in response to the \.{**} |
| 263 |
prompt. This may again be an \.{\&} immediately followed by the name of |
| 264 |
a format file to be loaded; otherwise \.{e-VIRTEX} loads a default |
| 265 |
format. For \.{e-INITEX} the first non-blank character may be an \.{*} |
| 266 |
immediately followed by what would normally be the input for \.{INITEX} |
| 267 |
(without intervening blanks). \.{e-INITEX} enters extended mode in |
| 268 |
response to the \.{*}, or compatibility mode otherwise. This mode is |
| 269 |
recorded in format files produced by \.{e-INITEX} and entered again when |
| 270 |
such a format is loaded (by either \.{e-INITEX} or \.{e-VIRTEX}). |
| 271 |
|
| 272 |
\vskip 24pt plus 24pt |
| 273 |
\section References. |
| 274 |
\item {[1]} |
| 275 |
{\sl The \.{WEB} system of structured documentation\/}, |
| 276 |
by Donald E.~Knuth,\hfil\break Stanford Computer Science Report~980. |
| 277 |
|
| 278 |
\item {[2]} |
| 279 |
{\sl A torture test for \TeX\/}, |
| 280 |
by Donald E.~Knuth, Stanford Computer Science Report~1027. |
| 281 |
|
| 282 |
\item {[3]} |
| 283 |
{\sl A torture test for \eTeX\/}, |
| 284 |
by The \NTS\ Team (Peter Breitenlohner and Bernd Raichle). |
| 285 |
|
| 286 |
\end |