| 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} |