Debian Codegraph @

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

raw
1 % etex_man.tex
2 % Copyright (c) 1994-2015 Peter Breitenlohner (deceased 2015)
3 % Copyright (c) 2024 NTS Team and successors
4
5 \documentclass[11pt]{article}
6 \usepackage{fullpage} % fewer pages is better
7 \usepackage{etex_man}
8 \usepackage[hidelinks]{hyperref}
9
10 \begin{document}
11
12 \begin{center}
13 {\huge\bf The \eTeX\ manual\footnote{%
14 This document is released under the license used by Donald Knuth for
15 \TeX\ (\texttt{https://ctan.org/license/knuth}); the present source
16 filename is \texttt{etex\char`\_man.tex}).}}
17 \\[6pt]
18 {\sl Version 2, February 1998 (updated March 2024)}
19 \\[18pt]
20 %
21 by The \NTS\ Team\footnote{%
22 The preparation of the original report was supported in part by
23 {\sc Dante}, Deutschsprachige Anwendervereinigung \TeX\ e.V.}
24 \\[6pt]
25 Peter Breitenlohner, Max-Planck-Institut f\"ur Physik, M\"unchen\footnote{%
26 Peter Breitenlohner died in 2015. The March 2024 update was prepared
27 by David Carlisle and Karl Berry for \TeX\,Live, where \eTeX\ has been
28 maintained for many years.\raggedright}
29 \end{center}
30
31 \section{Introduction}
32
33 The \eTeX\ program was intended to fill the gap between \TeX3 and the
34 \NTS\ which was planned as the successor to \TeX3.
35 It consists of a series of features extending the capabilities of
36 \TeX3.
37
38 Since compatibility between \eTeX\ and \TeX3 has been a main concern,
39 \eTeX\ has two modes of operation:\\
40 (1)~In \TeX\ compatibility mode it fully deserves the name \TeX\ and
41 there are neither extended features nor additional primitive commands.
42 That means in particular that \eTeX\ passes the \|TRIP| test
43 \cite{tripman} without any restriction. There are, however, a few
44 minor modifications that would be legitimate in any implementation of
45 \TeX.\\
46 (2)~In extended mode there are additional primitive commands and the
47 extended features of \eTeX\ are available. This mode is triggered by the
48 first non-blank input character to the extended \texttt{initex} being a
49 \texttt{*}.
50
51 We have tried to make \eTeX\ as compatible with \TeX\ as possible
52 even in extended mode. In a few cases there are, however, some subtle
53 differences described in detail later on. Therefore the \eTeX\ features
54 available in extended mode are grouped into two categories:\\
55 (1)~Most of them have no semantic effect as long as none of the
56 additional primitives are executed; these `extensions' are permanently
57 enabled.\\
58 (2)~The remaining optional \eTeX\ features (`enhancements') can be
59 individually enabled and disabled; initially they are all disabled.
60 For each enhancement there is a state variable \|\...state|; an
61 enhancement is enabled or disabled by assigning a positive or
62 non-positive value respectively to that state variable.
63
64 For \eTeX\ Versions~1 and~2 there is just one such enhancement: mixed
65 direction typesetting (\hbox{\TeXXeT}) with the state variable \|\TeXXeTstate|.
66
67 Version~1.1 of \eTeX\ was released in November 1996, Version~2.0 in
68 February 1998.
69 It was expected that there would be be about one \eTeX\ version per year,
70 where each later version adds new features. However, nowadays, \eTeX\
71 is considered completely stable and further changes are not planned.
72
73 In practice most current \texttt{etex} programs are an incarnation of
74 pdf\TeX\ running in DVI mode. As such, they include several additional
75 commands that are documented in the pdf\TeX\ manual, not in this
76 document. As a point of information: the \LaTeX\ format requires that
77 the underlying \TeX\ implementation provide the functionality of some of
78 these additional commands, beyond \eTeX.
79
80 With each \eTeX\ version there will be an \|e-TRIP| test \cite{etripman}
81 in order to help to verify that a particular implementation deserves the
82 name \eTeX\ in the same way as the \|TRIP| test \cite{tripman} helps to
83 verify that an implementation deserves the name \TeX.
84
85 \section{Generating \eTeX}
86
87 \subsection{Generating the \eTeX\ Program}
88
89 An implementation of \TeX\ consists of a WEB change file \|tex.ch|
90 containing all system-dependent changes for a particular system. The
91 WEB system program \|TANGLE| applies this change file to the
92 system-independent file \|tex.web| defining the \TeX\ program in order to
93 generate a \TeX\ Pascal file for that system \cite{webman}. Similarly
94 an implementation of \eTeX\ consists of a system-dependent change file
95 \|etex.sys| to be applied to the system-independent file \|e-tex.web|
96 defining the \eTeX\ program. Since \eTeX\ differs from \TeX\ by a
97 relatively small fraction of its code \|e-tex.web| does, however, not
98 exist as a physical file; it is instead defined in terms of a
99 system-independent change file \|e-tex.ch| to be applied to \|tex.web|.
100 Similarly it should be possible to define the system-dependent change
101 file \|etex.sys| for a particular system in terms of its deviations
102 from the corresponding file \|tex.ch| \cite{etexgen}.
103
104 \subsection{Generating Format Files for \eTeX}
105
106 When (the INITEX or VIRTEX version of) the \TeX\ program is started, it
107 analyzes the first non-blank input line from the command line or (with
108 the \|**| prompt) from the terminal: The first non-blank character of
109 that input line may be an \|&| followed immediately by the name of the
110 format to
111 be loaded; otherwise VIRTEX uses a default format whereas INITEX starts
112 without loading a format file.
113
114 For eINITEX (the INITEX version of \eTeX) there is an additional
115 possibility: If the first non-blank input character is an \|*|
116 (immediately followed what would be the first non-blank input character
117 for INITEX), the program starts in extended mode without loading a
118 format file. If the first non-blank character is neither \|&| nor \|*|
119 then eINITEX starts without loading a format but in compatibility mode.
120 Whenever a format file is loaded by eINITEX or eVIRTEX the mode
121 (compatibility or extended) is inherited from the format.
122
123 It is recommended that the input file \|etex.src| be used instead of
124 \|plain.tex| when generating an \eTeX\ format in extended mode. That
125 file will first read \|plain.tex| (without reading \|hyphen.tex|) and
126 will then supply macro definitions supporting \eTeX\ features.
127
128 \section{\eTeX\ Extensions}
129
130 \subsection{Compatibility and Extended Mode}
131
132 Once \eTeX\ has entered compatibility mode it behaves as any other
133 implementation of \TeX. All of \eTeX's additional commands are absent;
134 it is therefore impossible to access any of the extensions or
135 enhancements. The ability of eINITEX to initially choose between
136 compatibility and extended mode is, however, by itself a feature not
137 present in any \TeX\ implementation.
138
139 The remainder of this document is devoted to a detailed and mostly
140 technical description of all aspects where \eTeX\ (in extended mode)
141 behaves differently from \TeX. It will be assumed that the reader is
142 familiar with \TeXbook\ \cite{texbook} describing \TeX's behaviour in
143 quite some detail.
144
145 All of \eTeX's extensions and enhancements available in extended mode are
146 activated by either executing some new primitive command or by assigning
147 a nonzero value to some new integer parameter or state variable. Since
148 all these new variables are initially zero,%
149 \footnote{To be precise all state variables are zero when eINITEX or eVIRTEX
150 is started; integer parameters that are not state variables are zero when
151 eINITEX is started without loading a format file or inherited from the
152 format file otherwise.}
153 \eTeX\ behaves as \TeX\ as long as none of \eTeX's new control sequences
154 are used, with the following exceptions which should, however, have
155 no effect on the typesetting of error-free \TeX\ documents (produced with
156 error-free formats):\\
157 (1) When \|\tracingcommands| has a value of~3 or more, or\\
158 when \|\tracinglostchars| has a value of~2 or more, \eTeX\ will display
159 additional information not available in \TeX.\\
160 (2) When using a count, dimen, skip, muskip, box, or token register number
161 in the range 256--32767, \eTeX\ will access one of its additional registers
162 whereas \TeX\ will produce an error and use register number zero.
163
164 \subsection{Optimization}
165
166 When a value is assigned to an \<internal quantity> within a save group,
167 the former value is restored when the group ends, provided the
168 assignment was not global. This is achieved by saving the former value
169 on \TeX's `save stack'. \eTeX\ refrains from creating such save stack
170 entries when the old and new value are the same (`reassignments').
171
172 \|\aftergroup| tokens are also kept on \TeX's save stack. When the
173 current group ends, \TeX\ converts each \|\aftergroup| token into a
174 token list and inserts this list as new `input level' into the input stack.
175 \eTeX\ collects all \|\aftergroup| tokens from one group into one token
176 list and thus conserves input levels.
177
178 When a completed page is written to the DVI file (shipped out), \TeX\
179 multiplies the relevant stretch or shrink components of glue nodes in a
180 box by the glue expansion factor of that box and converts the product to
181 DVI units. In order to avoid overflow each resulting value $x$ is
182 artificially limited to the range $|x|\le10^9$.
183 Consider the example:
184 \begin{verbatim}
185 \shipout\vbox to100pt{
186 \hrule width10pt
187 \vskip 0pt plus1000fil
188 \vskip 0pt plus1000fil
189 \vskip 0pt plus-2000fil
190 \hrule
191 \vskip 0pt plus0.00005fil
192 }
193 \end{verbatim}
194 Here the three glues between the two rules add up to zero; when \TeX\
195 converts each stretch component individually they will, however, add up
196 to $10^9$ DVI units due to the truncation mentioned above. \eTeX, however,
197 accumulates the relevant stretch or shrink components of consecutive
198 glue nodes (possibly separated by insert, mark, adjust, kern, and
199 penalty nodes) before converting them to DVI units. During this process
200 glue nodes may be converted into equivalent kern nodes and some glue
201 specifications may be recycled; this may affect the memory usage
202 statistics displayed after the page has been shipped out.
203
204 \subsection{Tracing and Diagnostics}
205
206 When \|\tracingcommands| has a value of~3 or more, the commands
207 following a prefix (\|\global|, etc.) are shown as well, e.g.:
208 \begin{verbatim}
209 \global\count0=0 => {\global}
210 {\count}
211 \end{verbatim}
212
213 When \|\tracinglostchars| has a value of~2 or more, missing characters
214 are displayed on the terminal even if the value of \|\tracingonline| is
215 0~or less.
216
217 When \|\tracingscantokens| has a value of~1 or more, the opening and
218 closing of pseudo-files (generated by \|\scantokens|) is recorded as for
219 any other file, with `\verb*| |' as filename.
220
221 When the program is compiled with the code for collecting statistics and
222 \|\tracingassigns| has a value of~1 or more, all assignments subject to
223 \TeX's grouping mechanism are traced, e.g.:
224 \begin{verbatim}
225 \def\foo{\relax} => {changing \foo=undefined}
226 {into \foo=macro:->\relax }
227 \global\count17=7 => {globally changing \count17=0}
228 {into \count17=7}
229 \count17=7 => {reassigning \count17=7}
230 \end{verbatim}
231
232 When \|\tracingifs| has a value of~1 or more, all conditionals
233 (including \|\unless|, \|\or|, \|\else|, and \|\fi|) are traced, together
234 with the starting line and nesting level; the \|\showifs| command displays
235 the state of all currently active conditionals. Thus the input
236 \begin{verbatim}
237 \unless\iffalse
238 \iffalse
239 \else
240 \showifs
241 \fi
242 \fi
243 \end{verbatim}
244 might yield
245 \begin{verbatim}
246 {\unless\iffalse: (level 1) entered on line 1}
247 {\iffalse: (level 2) entered on line 2}
248 {\else: \iffalse (level 2) entered on line 2}
249 ### level 2: \iffalse\else entered on line 2
250 ### level 1: \unless\iffalse entered on line 1
251 {\fi: \iffalse (level 2) entered on line 2}
252 {\fi: \unless\iffalse (level 1) entered on line 1}
253 \end{verbatim}
254
255 When \|\tracinggroups| has a value of~1 or more, the start and end of
256 each save group is traced, together with the starting line and grouping
257 level; the \|\showgroups| command displays the state of all currently
258 active save groups. Thus the input
259 \begin{verbatim}
260 \begingroup
261 {
262 \showgroups
263 }
264 \endgroup
265 \end{verbatim}
266 might yield
267 \begin{verbatim}
268 {entering semi simple group (level 1) at line 1}
269 {entering simple group (level 2) at line 2}
270 ### simple group (level 2) entered at line 1 ({)
271 ### semi simple group (level 1) entered at line 1 (\begingroup)
272 ### bottom level
273 {leaving simple group (level 2) entered at line 2}
274 {leaving semi simple group (level 1) entered at line 1}
275 \end{verbatim}
276
277 Occasionally conditionals and/or save groups are not properly nested
278 with respect to \|\input| files. Although this might be perfectly
279 legitimate, such anomalies are mostly unintentional and may cause quite
280 obscure errors. When \|\tracingnesting| has a value of~1 or more,
281 these anomalies are shown; when \|\tracingnesting| has a value of~2 or more,
282 the current context (traceback) is shown as well. Thus the input
283 \begin{verbatim}
284 \newlinechar=`\^^J
285 \begingroup
286 \iftrue
287 \scantokens{%
288 \endgroup
289 ^^J\fi
290 ^^J\bgroup
291 ^^\tracingnesting=2
292 ^^J\iffalse
293 ^^J\else
294 }%
295 \egroup
296 \fi
297 \end{verbatim}
298 might yield%
299 \footnote{The \cs{scantokens} command will be discussed later.}
300 \begin{verbatim}
301 Warning: end of semi simple group (level 1) entered at line 2 of
302 a different file
303 Warning: end of \iftrue entered on line 3 of a different file
304 Warning: end of file when simple group (level 1) entered at line
305 3 is incomplete
306 Warning: end of file when \iffalse\else entered on line 5 is inc
307 omplete
308 l.7 \else
309
310 l.11 }
311 %
312 \end{verbatim}
313
314 The command \|\showtokens{|\<token list>\|}| displays the token list, and
315 allows the display of quantities that cannot be displayed by \|\show| or
316 \|\showthe|, e.g.:
317 \begin{verbatim}
318 \showtokens\expandafter{\jobname}
319 \showtokens\expandafter{\topmarks 27}
320 \end{verbatim}
321
322 \subsection{Status Enquiries}
323
324 A number of \TeX's internal quantities can be assigned values but
325 these values cannot be retrieved in \TeX. \eTeX\ introduces several new
326 primitives that allow the retrieval of information about its internal state.
327
328 \noindent
329 \|\eTeXversion| returns \eTeX's (major) version number;\\
330 \|\eTeXrevision| expands into a list of character tokens representing
331 the revision (minor version) number. Thus
332 \begin{verbatim}
333 \message{\number\eTeXversion\eTeXrevision}
334 \end{verbatim}
335 should write the complete version as shown when \eTeX\ is started.
336
337 \noindent
338 When used as number, \|\interactionmode| returns one of the
339 values 0~(batchmode), 1~(nonstopmode), 2~(scrollmode),
340 or~3~(errorstopmode). Assigning one of these values to
341 \|\interactionmode| changes the current interaction mode accordingly;
342 such assignments are always global.
343
344 \noindent
345 \|\currentgrouplevel| returns the current save group level;\\
346 \|\currentgrouptype| returns a number representing the type of the
347 innermost group:
348 \begin{multilist}{2}{\hfil\qquad#:&\quad#\qquad\hfil}
349 \item 0&bottom level (no group)\cr
350 \item 1&simple group\cr
351 \item 2&hbox group\cr
352 \item 3&adjusted hbox group\cr
353 \item 4&vbox group\cr
354 \item 5&vtop group\cr
355 \item 6&align group\cr
356 \item 7&no align group\cr
357 \item 8&output group\cr
358 \item 9&math group\cr
359 \item 10&disc group\cr
360 \item 11&insert group\cr
361 \item 12&vcenter group\cr
362 \item 13&math choice group\cr
363 \item 14&semi simple group\cr
364 \item 15&math shift group\cr
365 \item 16&math left group\cr
366 \end{multilist}
367
368 \noindent
369 \|\currentiflevel| returns the number of currently active
370 conditionals;\\
371 \|\currentifbranch| indicates which branch of the innermost conditional
372 is taken: 1~`then branch', $-1$~`else branch', or 0~not yet decided;\\
373 \|\currentiftype| returns 0~if there are no active conditionals, a
374 positive number indicating the type of the innermost active conditional,
375 or the negative of that number when the conditional was prefixed by
376 \|\unless|:
377 \begin{multilist}{3}{\hfil\qquad#:&\quad#\qquad\hfil}
378 \item 1&\cs{if}\cr
379 \item 2&\cs{ifcat}\cr
380 \item 3&\cs{ifnum}\cr
381 \item 4&\cs{ifdim}\cr
382 \item 5&\cs{ifodd}\cr
383 \item 6&\cs{ifvmode}\cr
384 \item 7&\cs{ifhmode}\cr
385 \item 8&\cs{ifmmode}\cr
386 \item 9&\cs{ifinner}\cr
387 \item 10&\cs{ifvoid}\cr
388 \item 11&\cs{ifhbox}\cr
389 \item 12&\cs{ifvbox}\cr
390 \item 13&\cs{ifx}\cr
391 \item 14&\cs{ifeof}\cr
392 \item 15&\cs{iftrue}\cr
393 \item 16&\cs{iffalse}\cr
394 \item 17&\cs{ifcase}\cr
395 \item 18&\cs{ifdefined}\cr
396 \item 19&\cs{ifcsname}\cr
397 \item 20&\cs{iffontchar}\cr
398 \end{multilist}
399
400 \noindent
401 \|\lastnodetype| returns a number indicating the type of the last node,
402 if any, on the current (vertical, horizontal, or math) list:
403 \begin{multilist}{2}{\hfil\qquad#:&\quad#\qquad\hfil}
404 \item -1&none (empty list)\cr
405 \item 0&char node\cr
406 \item 1&hlist node\cr
407 \item 2&vlist node\cr
408 \item 3&rule node\cr
409 \item 4&ins node\cr
410 \item 5&mark node\cr
411 \item 6&adjust node\cr
412 \item 7&ligature node\cr
413 \item 8&disc node\cr
414 \item 9&whatsit node\cr
415 \item 10&math node\cr
416 \item 11&glue node\cr
417 \item 12&kern node\cr
418 \item 13&penalty node\cr
419 \item 14&unset node\cr
420 \item 15&math mode nodes\cr
421 \end{multilist}
422
423 \noindent
424 The commands \|\fontcharht|, \|\fontcharwd|, \|\fontchardp|, and
425 \|\fontcharic| followed by a font specification and a character code,
426 return a dimension: the height, width, depth, or italic correction of the
427 character in the font, or \[0pt] if no such character exists;
428 the conditional \|\iffontchar| tests the existence of that character.
429
430 \noindent
431 When used as number, \|\parshape| returns the number of lines of the current
432 parshape specification (or zero).\\
433 \eTeX's \|\parshapeindent|, \|\parshapelength|, and \|\parshapedimen|,
434 followed by a number $n$ return the dimensions of the parshape
435 specification:\\
436 \[0pt] for $n\le0$ or when no parshape is currently active, otherwise\\
437 \|\parshapeindent|$\,n$ and \|\parshapedimen|$\,2n-1$ both return the
438 indentation of line $n$ (explicitly specified or implied by repeating the
439 last specification),\\
440 \|\parshapelength|$\,n$ and \|\parshapedimen|$\,2n$ both return the length
441 of line $n$.
442
443 \subsection{Expressions}
444
445 \eTeX\ introduces the notion of expressions of type number, dimen, glue, or
446 muglue, that can be used whenever a quantity of that type is needed. Such
447 expressions are evaluated by \eTeX's scanning mechanism; they are initiated
448 by one of the commands \|\numexpr|, \|\dimexpr|, \|\glueexpr|, or \|\muexpr|
449 (determining the type~$t$) and optionally terminated by one \|\relax| (that
450 will be absorbed by the scanning mechanism). An expression consists of one
451 or more terms of the same type to be added or subtracted; a term of type~$t$
452 consists of a factor of that type, optionally multiplied and\slash or
453 divided by numeric factors; finally a factor of type~$t$ is either a
454 parenthesized subexpression or a quantity (number, etc.) of that type.
455 Thus, the conditional
456 \begin{verbatim}
457 \ifdim\dimexpr (2pt-5pt)*\numexpr 3-3*13/5\relax + 34pt/2<\wd20
458 \end{verbatim}
459 is true if and only if the width of box~20 exceeds 32\[pt]. Note the use of
460 \|\relax| to terminate the inner (numeric) expression, the outer (dimen)
461 expression is terminated automatically by the token \|<|$_{12}$ that does
462 not fit into the expression syntax.
463
464 The arithmetic performed by \eTeX's expressions does not do much that could
465 not be done by \TeX's arithmetic operations \|\advance|, \|\multiply|, and
466 \|\divide|, although there are some notable differences: Each factor is
467 checked to be in the allowed range, numbers must be less than $2^{31}$ in
468 absolute value, dimensions or glue components must be less than
469 $2^{14}$\[pt], \[mu], \[fil], etc.\ respectively. The arithmetic operations
470 are performed individually, except for `scaling' operations (a
471 multiplication immediately followed by a division) which are performed as
472 one combined operation with a 64-bit product as intermediate value. The
473 result of each operation is again checked to be in the allowed range.
474 Finally the results of divisions and scalings are rounded, whereas \TeX's
475 \|\divide| truncates.
476
477 The important new feature is, however, that the evaluation of expressions
478 does not involve assignments and can therefore be performed in
479 circumstances where assignments are not allowed, e.g., inside an \|\edef| or
480 \|\write|. This also allows the definition of purely expandable loop constructions:
481 \begin{verbatim}
482 \def\foo#1#2{\number#1
483 \ifnum#1<#2,
484 \expandafter\foo
485 \expandafter{\number\numexpr#1+1\expandafter}%
486 \expandafter{\number#2\expandafter}%
487 \fi}
488 \end{verbatim}
489 such that, e.g., `\|\foo{7}{13}|' expands into `\|7, 8, 9, 10, 11, 12, 13|'.
490
491 The commands \|\gluestretch| and \|\glueshrink| are to be followed by a glue
492 specification and return the stretch or shrink component of that glue as
493 dimensions (with \[fil] etc.\ replaced by \[pt]), the commands
494 \|\gluestretchorder| and \|\glueshrinkorder| return the order of infinity:
495 0~for \[pt], 1~for \[fil], 2~for \[fill], and 3~for \[filll].
496
497 The commands \|\gluetomu| and \|\mutoglue| convert glue into muglue
498 and vice versa by simply equating 1\[pt] with 1\[mu], precisely what \TeX\
499 does (in addition to an error message) when the wrong kind of glue is used.
500
501 \subsection{Additional Registers and Marks}
502
503 \eTeX\ increases the number of \TeX's count, dimen, skip, muskip, box, and
504 token registers from 256 to 32768. The additional registers, numbered
505 256--32767, can be used exactly as the first 256, except that they can
506 not be used for insertion classes.
507
508 As in \TeX, the first 256 registers of each kind are realized as static
509 arrays that are part of the `table of equivalents'; values to be restored
510 when a save group ends are kept on the save stack. The additional registers
511 are realized as sparse arrays built from \TeX's main memory and are
512 therefore less efficient. They use a four-level index structure and
513 individual registers are present only when needed. Values to be restored
514 when a particular save group ends are kept in a linked list (again built
515 from main memory) with one save stack entry pointing to that list.%
516 \footnote{With the effect that the order of restoring (or discarding) saved
517 values may be somewhat surprising.}
518
519 \medskip
520 \eTeX\ generalizes \TeX's mark concept to mark classes 0--32767, with mark
521 class~0 used for \TeX's marks.\\
522 The command \|\marks| followed by a mark class~$n$ and a mark text appends a
523 mark node to the current list; \|\marks0| is synonymous with \|\mark|. The
524 page builder and the \|\vsplit| command record information about the mark nodes
525 found on the page or box produced, separately for each mark class. The
526 information for mark class~0 is kept in a small static array as in \TeX, the
527 information for the additional mark classes is again kept in a sparse array
528 with entries present only when needed.\\
529 The command \|\firstmarks|$\,n$ expands to the mark text for mark class~$n$
530 first encountered on the most recent page, etc., and again \|\firstmarks0|
531 is synonymous with \|\firstmark|.
532
533 \subsection{Input Handling}
534
535 The command \|\readline|\<number>\[to]\<control sequence> defines the
536 control sequence as parameterless macro whose replacement text is the
537 contents of the next line read from the designated file, as for \|\read|.
538 The difference is that the current category codes are ignored and all
539 characters on that line (including an endline character) are converted to
540 character tokens with category 12 (`other'), except that the character
541 code~32 gets category 10 (`space').
542
543 The command \|\scantokens{...}| absorbs a list of unexpanded tokens,
544 converts it into a character string that is treated as if it were an
545 external file, and starts to read from this `pseudo-file'. A rather
546 similar effect can be achieved by the commands
547 \begin{verbatim}
548 \toks0={...}
549 \immediate\openout0=file
550 \immediate\write0{\the\toks0}
551 \immediate\closeout0
552 \input file
553 \end{verbatim}
554 In particular every occurrence of the current newline character is
555 interpreted as start of a new line, and input characters will be converted
556 into tokens as usual.
557 The \|\scantokens| command is, however, expandable and does not use token
558 registers, write streams, or external files. Furthermore the conversion from
559 \TeX's internal ASCII codes to external characters and back to ASCII codes
560 is skipped. Finally the current context (traceback) shown, e.g., as part
561 of an error message continues beyond an input line from a pseudo-file until
562 an input line from a real file (or the terminal) is found.
563
564 When \eTeX's input mechanism attempts to read beyond the end of an \|\input|
565 file or a \|\scantokens| pseudo-file, and before checking for `runaway'
566 conditions and closing the file, it will first read a list of tokens that
567 has been predefined by the command \|\everyeof={|\<token list>\|}|.
568
569 \subsection{Breaking Paragraphs into Lines}
570
571 Traditional typesetting with lead type used to adjust (stretch or shrink)
572 the interword spaces in the last line of a paragraph by the same amount as
573 those in the preceding line. With \TeX\ the last line is, however, usually
574 typeset at its natural width due to infinitely stretchable parfillskip glue.
575 \eTeX\ allows interpolation between these two extremes by specifying a
576 suitable value for \|\lastlinefit|. For a value of~0 or less, \eTeX\
577 behaves as \TeX, values from~1 to 1000 indicate a glue adjustment fraction
578 $f$ times 1000, values above 1000 are interpreted as $f=1$.
579
580 The new algorithm is used only if\\
581 1. \|\lastlinefit| is positive;\\
582 2. \|\parfillskip| has infinite stretchability; and\\
583 3. the stretchability of \|\leftskip| plus \|\rightskip| is finite.%
584 \footnote{As usual for parameters influencing \TeX's line-breaking algorithm,
585 the values current at the end of the (partial) paragraph are used.}\\
586 Thus the last line of a paragraph would normally be typeset at its
587 natural width and the stretchability of parfillskip glue would be used to
588 achieve the desired line width. The algorithm proceeds as usual, considering
589 all possible sequences of feasible break points and accumulating demerits for
590 the stretching or shrinking of lines as well as for visually incompatible
591 lines. When a candidate for the last line has been reached, the following
592 conditions are tested:\\
593 4. the previous line was not `infinitely bad' and was stretched with positive
594 finite stretchability or was shrunk with positive shrinkability;\\
595 5. the last line has infinite stretchability entirely due to parfillskip
596 glue;\\
597 6. if the previous line was stretched or shrunk the last line has
598 positive finite stretchability or shrinkability respectively.\\
599 If all three conditions are satisfied, a glue adjustment factor of $f$ times
600 that of the preceding line will be applied to the relevant stretch or
601 shrink components of all glue nodes in the last line, and the corresponding
602 demerits are computed. (The last line will, however, not be stretched beyond
603 the desired line width.)
604
605 When all possible candidates for the last line of the paragraph have been
606 examined, the one having fewest accumulated demerits is chosen. If \eTeX's
607 modified algorithm was applied to that last line, the actual stretching or
608 shrinking is achieved by suitably modifying the parfillskip glue node.
609
610 All computations described so far are performed with machine-independent
611 integer arithmetic. Note, however, that the actual stretching requires
612 machine-dependent floating point arithmetic. Therefore, when a paragraph is
613 interrupted by a displayed equation and the line preceding the display is
614 subject to the adjustment just described, the display will in general be
615 preceded by abovedisplayskip and not by abovedisplayshortskip glue.
616
617 \medskip
618
619 After breaking a paragraph into lines, \TeX\ computes the interline
620 penalties by adding the values of:\\
621 \|\interlinepenalty| between any two lines,\\
622 \|\clubpenalty| after the first line of a (partial) paragraph,\\
623 \|\widowpenalty| before the last line of the paragraph,\\
624 \|\displaywidowpenalty| before the line immediately preceding a displayed
625 equation, and\\
626 \|\brokenpenalty| after lines ending with a discretionary break.\\
627 \eTeX\ generalizes the concept of interline, club, widow, and display widow
628 penalty by allowing their replacement by arrays of penalty values with the
629 commands\\
630 \|\interlinepenalties|,\\
631 \|\clubpenalties|,\\
632 \|\widowpenalties|, and\\
633 \|\displaywidowpenalties|.\\
634 Each of these commands is to be followed by an optional equal sign and a
635 number $n$. If $n\le0$ the respective array is reset and \TeX's
636 corresponding single value is used as usual; a positive value $n$
637 declares an array of length $n$ and must be followed by $n$ penalty
638 values. When one of these arrays has been set, its values are used
639 instead of \TeX's corresponding single values as follows (repeating the
640 last value when necessary):\\
641 the $i^{\rm th}$ interline penalty value is used after line $i$ of the
642 paragraph;\\
643 the $i^{\rm th}$ club penalty value is used after line $i$ of a partial
644 paragraph;\\
645 the $i^{\rm th}$ widow penalty value is used after line $m-i$ of a
646 paragraph without displayed equations or the last partial paragraph of
647 length $m$;\\
648 the $i^{\rm th}$ display widow penalty value is used after line $m-i$ of a
649 partial paragraph of length $m$ that is followed by a displayed equation.
650
651 Note that \|\interlinepenalties| is reset (like \|\parshape|)
652 at any \|\par| (blank line) in the input. The other |\...penalties|
653 arrays are not reset at \|\par|.
654
655 When used after \|\the| or in situations where \TeX\ expects to see a
656 number, the same four commands serve to retrieve the arrays of penalties.
657 Specifying, e.g., \|\clubpenalties|\<number> with a number $n$, returns~0
658 for $n<0$ or when the club penalty array has been reset, the length of the
659 declared club penalty array for $n=0$, or the $n^{\rm th}$ club penalty
660 value for $n>0$ (again repeating the last value when necessary).
661
662 \subsection{Math Formulas}
663
664 \TeX's \|\left|\<delimiter>\|...\right|\<delimiter> produces two delimiters
665 with a common size adjusted to the height and depth of the enclosed material.
666 In \eTeX\ this can be generalized by occurrences of \|\middle|\<delimiter>
667 dividing the enclosed material into segments resulting in a sequence
668 of delimiters with a common size adjusted to the maximal height and depth of
669 all enclosed segments. The spacing between a segment and the delimiter to
670 its left or right is as for \TeX's left or right delimiter respectively.
671
672 \subsection{Hyphenation}
673
674 \TeX\ uses the \|\lccode| values for two quite unrelated purposes:\\
675 (1) when \|\lowercase| converts character tokens to their lower-case
676 equivalents (in the same way as \|\uppercase| uses the \|\uccode| values);
677 and\\
678 (2) when hyphenation patterns or exceptions are read, and when words are
679 hyphenated during the line-breaking algorithm.
680
681 \eTeX\ introduces the concept of (language-dependent) hyphenation codes that
682 are used instead of the \|\lccode| values for hyphenation purposes. In order
683 to explain the details of \eTeX's behaviour, we need some technical aspects
684 of hyphenation patterns. When INITEX starts without reading a format file,
685 the (initially empty) hyphenation patterns are in a form suitable for
686 inserting new patterns specified by \|\patterns| commands; when INITEX
687 attemps hyphenation or prepares to write a format file, they are compressed
688 into a more compact form suitable for finding hyphens. Only these compressed
689 patterns can be read from a format file (by INITEX or VIRTEX).
690
691 In \eTeX\ the hyphenation patterns are supplemented by hyphenation codes.
692 When eINITEX starts without reading a format file both are initially empty;
693 when a \|\patterns| command is executed and \|\savinghyphcodes| has a positive
694 value, the current \|\lccode| values are saved as hyphenation codes for the
695 current language. These saved hyphenation codes are later compressed together
696 with the patterns and written to or read from a format file. When the
697 patterns have been compressed (always true for eVIRTEX) and hyphenation
698 codes have been saved for the current language, they are used
699 instead of the \|\lccode| values for hyphenation purposes (reading
700 hyphenation exceptions and hyphenating words).
701
702 \subsection{Discarded Items}
703
704 When \TeX's page builder transfers (vertical mode) material from the `recent
705 contributions' to the `page so far', it discards glue, kern, and penalty
706 nodes (discardable items) preceding the first box or rule on the page under
707 construction and inserts a topskip glue node immediately before that box or
708 rule. Note, however, that this topskip glue need not be the first node on
709 the page, it may be preceded by insertion, mark, and whatsit nodes.
710 Similarly when the \|\vsplit| command has split the first part off a vbox,
711 discardable items are discarded from the top of the remaining vbox and a
712 splittopskip glue node is inserted immediately before the first box or rule.
713
714 When \eTeX's parameter \|\savingvdiscards| has been assigned a positive
715 value, these `discarded items' are saved in two lists and can
716 be recovered by the commands \|\pagediscards| and \|\splitdiscards| that
717 act like `unvboxing' hypothetical box registers containing a vbox with the
718 discarded items.
719
720 The list of items discarded by the page builder is emptied at the end of
721 the output routine and by the \|\pagediscards| command; new items may
722 be added as long as the new `page so far' contains no box or rule.
723
724 The list of items discarded by the \|\vsplit| command is emptied at the
725 start of a vsplit operation and by the \|\splitdiscards| command; new items
726 are added at the end of a vsplit operation.
727
728 \subsection{Expandable Commands}
729
730 Chapter~20 of \TeXbook\ gives complete lists of all expandable \TeX\
731 commands and of all cases where expandable tokens are not expanded.
732 For \eTeX\ there are these additional conditionals:
733
734 \begin{itemize}
735 \item
736 \|\ifdefined|\<token>\quad(test if token is defined)
737 \end{itemize}
738 \noindent
739 True if \<token> is defined; creates no new hash table entry.
740
741 \begin{itemize}
742 \item
743 \|\ifcsname...\endcsname|\quad(test if control sequence is defined)
744 \end{itemize}
745 \noindent
746 True if the control sequence \|\csname...\endcsname| would be defined;
747 creates no new hash table entry.
748
749 \begin{itemize}
750 \item
751 \|\iffontchar|\<font>\<8-bit number>\quad(test if char exists)
752 \end{itemize}
753 \noindent
754 True if \|\char|\<8-bit number> in \|\font|\<font> exists.
755
756 These are \eTeX's additional expandable commands:
757
758 \begin{itemize}
759 \item\|\unless|.\\
760 The next (unexpanded) token must be a boolean conditional
761 (i.e., not \|\ifcase|); the truth value of that conditional is reversed.
762
763 \item\|\eTeXrevision|.\\
764 The expansion is a list of character tokens of category 12 (`other')
765 representing \eTeX's revision (minor version) number, e.g., `.0' or
766 `.1'.
767
768 \item\|\topmarks|\<15-bit number>,
769 \|\firstmarks|\<15-bit number>,\\
770 \|\botmarks|\<15-bit number>,
771 \|\splitfirstmarks|\<15-bit number>, and\\
772 \|\splitbotmarks|\<15-bit number>.\\
773 These commands generalize \TeX's \|\topmark| etc.\ to 32768 distinct
774 mark classes; the special case \|\topmarks0| is synonymous with
775 \|\topmark| etc.
776
777 \item\|\unexpanded|\<general text>.\\
778 The expansion is the token list \<balanced text>.
779
780 \item\|\detokenize|\<general text>.\\
781 The expansion is a list of character tokens representing the token list
782 \<balanced text>. As with the lists of character tokens produced by \TeX's
783 \|\the| and \eTeX's \|\readline|, these tokens have category 12 (`other'),
784 except that the character code~32 gets category 10 (`space').
785
786 \item\|\scantokens|\<general text>.\\
787 The expansion is null; but \eTeX\ creates a pseudo-file containing the
788 characters representing the token list \<balanced text> and prepares to
789 read from this pseudo-file before looking at any more tokens from its
790 current source.
791
792 \end{itemize}
793
794 These are the additional \eTeX\ cases when expandable tokens are not
795 expanded:
796
797 \begin{itemize}
798 \item
799 When \eTeX\ is reading the argument token for \|\ifdefined|.
800
801 \item
802 When \eTeX\ is absorbing the token list for \|\unexpanded|,
803 \|\detokenize|, \|\scantokens|, or \|\showtokens|.
804
805 \item
806 Protected macros (defined with the \|\protected| prefix) are not
807 expanded when building an expanded token list (for \|\edef|, \|\xdef|,
808 \|\message|,
809 \|\errmessage|, \|\special|, \|\mark|, \|\marks| or when writing the
810 token list for \|\write| to a file) or when looking ahead in an
811 alignment for \|\noalign| or \|\omit|.%
812 \footnote{Whereas protected macros were introduced with \eTeX\ Version~1,
813 suppression of their expansion in alignments was introduced with Version~2.}
814
815 \item
816 When building an expanded token list, the tokens resulting from the
817 expansion of \|\unexpanded| are not expanded further (this is the same
818 behaviour as is exhibited by the tokens resulting from the expansion of
819 \|\the|\<token variable> in both \TeX\ and \eTeX).{\hfuzz=1.4pt\par}
820
821 \end{itemize}
822
823 \section{\eTeX\ Enhancements}
824
825 The execution of most new primitives related to enhancements is
826 disallowed when the corresponding enhancement is currently disabled and
827 will lead to an `\|Improper...|' error message. The offending command
828 may nevertheless already have had some effect such as, e.g., bringing
829 \eTeX\ into horizontal mode.
830
831 \subsection{Mixed-Direction Typesetting}
832
833 This feature supports mixed left-to-right and right-to-left typesetting
834 and introduces the four text-direction primitives \|\beginL|, \|\endL|,
835 \|\beginR|, and \|\endR|. The code is inspired by but different from
836 \TeXeT\ \cite{texet}.
837
838 In order to avoid confusion with \TeXeT\ the present implementation of
839 mixed-direction typesetting is called \TeXXeT. It uses the same text-direction
840 primitives, but differs from \TeXeT\ in several important aspects:\\
841 (1)~Right-to-left text is reversed explicitly by \eTeX\ and is written
842 to a normal DVI file without any \|begin_reflect| or \|end_reflect|
843 commands;\\
844 (2)~a math node is (ab)used instead of a whatsit node to record the text-direction
845 primitives in order to minimize the influence on the line-breaking
846 algorithm for pure left-to-right text;\\
847 (3)~right-to-left text interrupted by a displayed equation is
848 automatically resumed after that equation;\\
849 (4)~display math material is always printed left-to-right, even in
850 constructions such as:
851 \begin{verbatim}
852 \hbox{\beginR\vbox{\noindent$$abc\eqno(123)$$}\endR}
853 \end{verbatim}
854
855 \TeXXeT\ is enabled or disabled by assigning a positive or non-positive
856 value respectively to the \|\TeXXeTstate| state variable. As long as
857 \TeXXeT\ is disabled, \eTeX\ and \TeX3 build horizontal lists and
858 paragraphs in exactly the same way. Even \TeXXeT\ will, in general,
859 produce the same results as \TeX3 for pure left-to-right text. There
860 are, however, circumstances where some differences may arise. This is
861 best illustrated by an example:
862 \begin{verbatim}
863 \vbox{\noindent
864 $\hfil\break
865 \null\hfil\break
866 \null$\par
867 \end{verbatim}
868 Here \TeX\ will produce three lines containing the following nodes:\\
869 1. mathon, hfil glue, break penalty, and rightskip glue;\\
870 2. empty hbox, hfil glue, break penalty, and rightskip glue;\\
871 3. empty hbox, mathoff, nobreak penalty, parfillskip glue, and rightskip
872 glue.\\
873 These lines can be retrieved via:
874 \begin{verbatim}
875 \setbox3=\lastbox
876 \unskip\unpenalty
877 \setbox2=\lastbox
878 \unskip\unpenalty
879 \setbox1=\lastbox
880 \end{verbatim}
881 Later on these lines can be `unhboxed' as part of a new paragraph and
882 possibly their contents analyzed. As a consequence in \TeX\ (and \eTeX\
883 in compatibility mode) there may be horizontal lists where mathon
884 and mathoff nodes are not properly paired. Therefore \TeX\ might
885 attempt hyphenation of `words' originating from math mode or prevent
886 hyphenation of words originating from horizontal mode.
887
888 Math-mode material is always typeset left-to-right by \TeXXeT, even when
889 it is contained inside right-to-left text. Therefore \TeXXeT\ will
890 insert additional \|beginM| and \|endM| math nodes such that
891 material originating from math mode is always enclosed between properly
892 paired math nodes. Consequently \TeXXeT\ will never attempt hyphenation
893 of `words' originating from math mode nor prevent hyphenation of words
894 originating from horizontal mode.
895
896 The additional math nodes introduced by \TeXXeT\ are, however,
897 transparent to operations such as \|\lastpenalty| that inspect or remove
898 the last node of a horizontal list.%
899 \footnote{This was not the case for some earlier \TeXXeT\ implementations.}
900
901 When \TeXXeT\ is enabled or disabled during the construction of a box,
902 that box may contain text-direction directives or math nodes that are
903 not properly paired. Such unpaired nodes may cause warning messages
904 when the box is shipped out. It is, therefore, advisable that \TeXXeT\
905 be enabled or disabled only in vertical mode.
906
907 \section{Syntax Extensions for \eTeX}
908
909 \subsection{Mode-Independent Commands}
910
911 The syntax for \TeX's mode-independent commands, as described in the
912 first part of Chapter~24 of \TeXbook, is extended by modifications of
913 existing commands as well as by new commands.
914
915 First, \eTeX\ has 32768 \|\count|, \|\dimen|, \|\skip|, \|\muskip|,
916 \|\box|, and \|\toks| registers instead of \TeX's 256. Thus it allows
917 a \<15-bit number> instead of an \<8-bit number> in almost all syntax
918 constructions referring to these registers; the only exception to this is
919 the \|\insert| command: insertion classes are restricted to the range
920 0--254 in \eTeX\ as they are in \TeX.
921
922 Next, \eTeX\ extends the list of \TeX's internal quantities:
923 \begin{syntax}
924 <internal integer>\is\more \alt|\eTeXversion|
925 \alt|\interactionmode|\alt<penalties><number>
926 \alt|\lastnodetype|\alt|\currentgrouplevel|\alt|\currentgrouptype|
927 \alt|\currentiflevel|\alt|\currentiftype|\alt|\currentifbranch|
928 \alt|\gluestretchorder|<glue>\alt|\glueshrinkorder|<glue>
929 \alt|\numexpr|<integer expr><optional spaces and |\relax|>
930 <penalties>\is|\interlinepenalties|\alt|\clubpenalties|
931 \alt|\widowpenalties|\alt|\displaywidowpenalties|
932 <internal dimen>\is\more
933 \alt|\parshapeindent|<number>\alt|\parshapelength|<number>
934 \alt|\parshapedimen|<number>
935 \alt|\gluestretch|<glue>\alt|\glueshrink|<glue>
936 \alt|\fontcharht|<font><8-bit number>%
937 \alt|\fontcharwd|<font><8-bit number>
938 \alt|\fontchardp|<font><8-bit number>%
939 \alt|\fontcharic|<font><8-bit number>
940 \alt|\dimexpr|<dimen expr><optional spaces and |\relax|>
941 <internal glue>\is\more \alt|\mutoglue|<muglue>
942 \alt|\glueexpr|<glue expr><optional spaces and |\relax|>
943 <internal muglue>\is\more \alt|\gluetomu|<glue>
944 \alt|\muexpr|<muglue expr><optional spaces and |\relax|>
945 \end{syntax}
946
947 The additional possibilities for \<integer parameter> are:
948 \begin{paramlist}
949 \|\TeXXeTstate|\quad(positive if mixed-direction typesetting is enabled)
950
951 \|\tracingassigns|\quad(positive if showing assignments)
952
953 \|\tracinggroups|\quad(positive if showing save groups)
954
955 \|\tracingifs|\quad(positive if showing conditionals)
956
957 \|\tracingscantokens|\quad(positive
958 if showing the opening and closing of \|\scantokens| pseudo-files)
959
960 \|\tracingnesting|\quad(positive
961 if showing improper nesting of groups and conditionals within files)
962
963 \|\predisplaydirection|\quad(text direction preceding a display)
964
965 \|\lastlinefit|\quad(adjustment
966 ratio for last line of paragraph, times 1000)
967
968 \|\savingvdiscards|\quad(positive
969 if saving items discarded from vertical lists)
970
971 \|\savinghyphcodes|\quad(positive
972 if \|\patterns| saves \|\lccode| values as hyphenation codes)
973 \end{paramlist}
974 \noindent
975 Note that the \eTeX\ state variable \|\TeXXeTstate| (the only one so
976 far) is an \<integer parameter>. That need not be the case for all
977 future state variables; it might turn out that some future enhancements
978 can be enabled and disabled only globally, not subject to grouping.
979
980 The additional possibilities for \<token parameter> are:
981 \begin{paramlist}
982 \|\everyeof|\quad(tokens to insert when an \|\input| file ends)
983 \end{paramlist}
984
985 Here is the syntax for \eTeX's expressions:
986 \begin{syntax}
987 <integer expr>\is<integer term>
988 \alt<integer expr><add or sub><integer term>
989 <integer term>\is<integer factor>
990 \alt<integer term><mul or div><integer factor>
991 <integer factor>\is<number>
992 \alt<left paren><integer expr><right paren>
993 <dimen expr>\is<dimen term>
994 \alt<dimen expr><add or sub><dimen term>
995 <dimen term>\is<dimen factor>
996 \alt<dimen term><mul or div><integer factor>
997 <dimen factor>\is<dimen>
998 \alt<left paren><dimen expr><right paren>
999 <glue expr>\is<glue term>
1000 \alt<glue expr><add or sub><glue term>
1001 <glue term>\is<glue factor>
1002 \alt<glue term><mul or div><integer factor>
1003 <glue factor>\is<glue>
1004 \alt<left paren><glue expr><right paren>
1005 <muglue expr>\is<muglue term>
1006 \alt<muglue expr><add or sub><muglue term>
1007 <muglue term>\is<muglue factor>
1008 \alt<muglue term><mul or div><integer factor>
1009 <muglue factor>\is<muglue>
1010 \alt<left paren><muglue expr><right paren>
1011 <optional spaces and |\relax|>\is<optional spaces>
1012 \alt<optional spaces>|\relax|
1013 <add or sub>\is<optional spaces>\ot+\alt<optional spaces>\ot-
1014 <div or mul>\is<optional spaces>\ot*\alt<optional spaces>\ot/
1015 <left paren>\is<optional spaces>\ot(
1016 <right paren>\is<optional spaces>\ot)
1017 \end{syntax}
1018
1019 Next, \eTeX\ extends the syntax for assignments:
1020 \begin{syntax}
1021 <prefix>\is\more\alt|\protected|
1022 <simple assignment>\is\more
1023 \alt<penalties assignment>
1024 \alt|\readline|<number>[to]<control sequence>
1025 <penalties assignment>\is%
1026 <penalties><equals><number><penalty values>
1027 <interaction mode assignment>\is\more
1028 \alt|\interactionmode|<equals><2-bit number>
1029 \end{syntax}
1030 \noindent
1031 In a \<penalties assignment> for which the \<number> is $n$, the
1032 \<penalty values> are \<empty> if $n\le0$, otherwise they consist of $n$
1033 consecutive occurrences of \<number>.
1034
1035 Finally, the remaining mode-independent \eTeX\ commands:
1036
1037 \begin{itemize}
1038 \item
1039 \|\showgroups|, \|\showifs|, \|\showtokens|\<general text>.
1040 These commands are intended to help you figure out what \eTeX\ thinks it
1041 is doing.
1042 The \|\showtokens| command displays the token list \<balanced text>.
1043
1044 \item
1045 \|\marks|\<15-bit number>\<general text>. This command generalizes
1046 \TeX's \|\mark| command to 32768 distinct mark classes; the special case
1047 \|\marks0| is synonymous with \|\mark|.
1048
1049 \end{itemize}
1050
1051 \subsection{Vertical-Mode Commands}
1052
1053 The syntax for \TeX's vertical-mode commands, as described in the second
1054 part of Chapter~24 of \TeXbook, is extended by \eTeX\ as follows:
1055
1056 \begin{itemize}
1057 \item
1058 \|\pagediscards|, \|\splitdiscards|.
1059 These two commands are similar to \|\unvbox|.
1060 When \|\savingvdiscards| is positive, items discarded by the page
1061 builder and by the \|\vsplit| command are collected in two special
1062 lists. One of these special lists is appended to the current vertical
1063 list (in the same way as \|\unvbox| appends the vertical list inside a
1064 vbox) and becomes empty.
1065
1066 \item
1067 Here are the additional possibilities for \<horizontal command>:
1068 \begin{syntax}
1069 <horizontal command>\is\more
1070 \alt|\beginL|\alt|\endL|\alt|\beginR|\alt|\endR|
1071 \end{syntax}
1072
1073 \end{itemize}
1074
1075 \subsection{Horizontal-Mode Commands}
1076
1077 The syntax for \TeX's horizontal-mode commands, as described in
1078 Chapter~25 of \TeXbook, is extended by \eTeX\ as follows:
1079
1080 \begin{itemize}
1081 \item
1082 Here are the additional possibilities for \<vertical command>:
1083 \begin{syntax}
1084 <vertical command>\is\more
1085 \alt|\pagediscards|\alt|\splitdiscards|
1086 \end{syntax}
1087
1088 \item
1089 \|\beginL|, \|\endL|, \|\beginR|, \|\endR| (text-direction commands).\\
1090 The use of these commands is illegal when the \TeXXeT\ enhancement is
1091 currently disabled; otherwise a \|beginL|, etc.\ text-direction node (a
1092 new kind of math node) is appended to the current horizontal list.
1093 These nodes delimit the beginning and end of hlist segments containing
1094 left-to-right~(L) or right-to-left~(R) text. Before a paragraph is
1095 broken into lines, \|endL| and \|endR| nodes are added to terminate any
1096 unfinished L~or R~segments; when a paragraph is continued after display
1097 math mode, any such unfinished segments are automatically resumed,
1098 starting the new hlist with \|beginL| and \|beginR| nodes as necessary.
1099
1100 \item
1101 \|\marks|\<15-bit number>\<general text>. This command generalizes
1102 \TeX's \|\mark| command to 32768 distinct mark classes; the special case
1103 \|\marks0| is synonymous with \|\mark|.
1104
1105 \end{itemize}
1106
1107 \subsection{Math-Mode Commands}
1108
1109 The syntax for \TeX's math-mode commands, as described in Chapter~26 of
1110 \TeXbook, is extended by \eTeX\ as follows:
1111
1112 \begin{itemize}
1113 \item
1114 \|\left|\<delim>\<math mode material>\\
1115 \|\middle|\<delim>\<math mode material>\|...|\|\right|\<delim>\\
1116 (generalizing \TeX's
1117 \|\left|\<delim>\<math mode material>\|\right|\<delim>).\\
1118 For each \<math mode material> \eTeX\ begins a new group, starting out
1119 with a new math list (always in the same style) that begins with a left
1120 boundary item containing everything processed so far. This group must
1121 be terminated with either `\|\middle|' or `\|right|', at which time the
1122 internal math list is completed with a new boundary item containing the
1123 new delimiter. In the case of `\|\middle|', a new group is started
1124 again, in the case of `\|\right|', \eTeX\ appends an Inner atom to the
1125 current list; the nucleus of this atom contains the internal math list
1126 just completed.
1127
1128 \end{itemize}
1129
1130 \begin{thebibliography}{9}
1131
1132 \bibitem{tripman}
1133 {\sl A torture test for \TeX\/},
1134 by Donald E.~Knuth, Stanford Computer Science Report~1027.
1135
1136 \bibitem{etripman}
1137 {\sl A torture test for \eTeX\/},
1138 by The \NTS\ Team (Peter Breitenlohner and Bernd Raichle).
1139 Version~2, January 1998.
1140
1141 \bibitem{webman}
1142 {\sl The WEB system of structured documentation\/},
1143 by Donald E.~Knuth,\hfil\break Stanford Computer Science Report~980.
1144
1145 \bibitem{etexgen}
1146 {\sl How to generate \eTeX\/},
1147 by The \NTS\ Team (Peter Breitenlohner and Phil Taylor).
1148 Version~2, January 1998.
1149
1150 \bibitem{texbook}
1151 \TeXbook\ (Computers and Typesetting, Vol.~A),
1152 by Donald E.~Knuth,
1153 Addison Wesley, Reading, Massachusetts, 1986.
1154
1155 \bibitem{texet}
1156
1157 {\sl Mixing right-to-left texts with left-to-right texts\/},
1158 by Donald~E. Knuth and Pierre MacKay,
1159 {\sl TUGboat\/} {\bf 8}, 14--25, 1987.
1160
1161 \end{thebibliography}
1162
1163 \end{document}