Debian Codegraph @

texmf-dist/doc/etex/base/etex_gen.tex

raw
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