Last updated and validated 24-MAR-1998 19:45:12 /PT
"etex.src" (V2.0)
The primary e-TeX format source file, "etex.src", is in principle
merely a wrapper for "plain.tex", providing modified definitions
for some Plain TeX commands (at present, just
one: \tracingall), improving and generalising
the register allocation mechanism, and adding new commands
In so doing, we have taken the opportunity to (a) provide intrinsic support for multiple-language typesetting (by deferring the processing of patterns and exceptions until a rudimentary language-handling environment has been defined), (b) provide a local as well as a global register allocation mechanism, (c) provide for the allocation of blocks of registers as well as single registers, (d) provide a means of allocating and accessing vectors (monodimensional arrays) of registers, and finally (e) provide a simple but effective module-handling system, to allow e-TeX ancilliary source files to be structured as libraries rather than as flat linear text files.
As the new commands and other features are not documented elsewhere, a brief explanation of their syntax and semantics is provided here.
\tracingall\tracingassigns,
\tracinggroups, \tracingifs,
\tracingnesting
and \tracingscantokens; the numeric value assigned
to the TeX primitives \tracingcommands and
\tracinglostchars is increased
as e-TeX will report additional detail in these circumstances.
\eTeXetexdefs.lib in due course.
\loggingall\tracingall
\tracingonline = 0 .
\tracingnone\tracing... primitives following use of
\tracingall or \loggingall.
\newmarks\marks rather than the single
\mark of TeX, an allocator mechanism is required; we
believe that \marks are closer to
\boxes than to (say) \counts or
\dimens and so have provided an analogous allocation
mechanism, in that \newmarks <control
sequence or active character> assigns a numeric
value to the parameter rather than making it a synonym for an
actual \mark; this numeric value can then be used to access
individual \marks, \topmarks,
\splitbotmarks, etc., as in
\newmarks \rectomarks
. . .
\marks \rectomarks {This may form part of the recto running head}
. . .
\leftline {\topmarks \rectomarks}
It should be noted that as \marks 0 is synonymous with
\mark, \newmarks will never allocate that
particular value.
\newmark in V1.1; the alternative
spelling has been retained for compatibility, although it is now classed
as deprecated.
\globbox,
\globcount,
\globdimen,
\globmarks,
\globmuskip,
\globskip,
\globtoks
\newbox (etc), these commands globally allocate
registers from e-TeX's extended register pool (i.e. from the register
range from 20 (for \marks) or from 28
(for all other classes) to 215-1). Registers are globally
allocated from the lower end of the range.
\locbox,
\loccount,
\locdimen,
\locmarks,
\locmuskip,
\locskip,
\loctoks
\globbox (etc), these commands locally allocate
registers from e-TeX's extended register pool (i.e. from the register
range from 20 (for \marks) or from 28
(for all other classes) to 215-1). Registers are locally
allocated from the upper end of the range.
\globboxblk,
\globcountblk,
\globdimenblk,
\globmarksblk,
\globmuskipblk,
\globskipblk,
\globtoksblk
\globbox (etc) by globally allocating
contiguous blocks of registers from e-TeX's extended register pool.
The syntax used is:
\glob(whatever)blk <control sequence or active char> n
where n specifies the length of the desired block. As
n is parsed as an undelimited parameter, it must be
expressed as a balanced text if it exceeds a single token.
The <control sequence or active character> will be
\mathchardef'd to the ordinal of the lowest register allocated.
\locboxblk,
\loccountblk,
\locdimenblk,
\locmarksblk,
\locmuskipblk,
\locskipblk,
\loctoksblk
\locbox (etc) by locally allocating
contiguous blocks of registers from e-TeX's extended register pool.
The syntax used is:
\loc(whatever)blk <control sequence or active char> n
where n specifies the length of the desired block. As
n is parsed as an undelimited parameter, it must be
expressed as a balanced text if it exceeds a single token.
The <control sequence or active character> will be
\mathchardef'd to the ordinal of the lowest register allocated.
\globcountvector,
\globdimenvector,
\globmuskipvector,
\globskipvector,
\globtoksvector
\globcountblk (etc), these commands use
e-TeX's arithmetic expression capabilities to globally allocate
vectors of boxes (etc) from e-TeX's extended register pool.
The syntax used is:
\glob(whatever)vector <control sequence or active char> n
where n specifies the length of the desired block. As
n is parsed as an undelimited parameter, it must be
expressed as a balanced text if it exceeds a single token. Once the
vector has been defined, element m can be accessed in both left-
and right-hand contexts as
<control sequence or active char> m
where 0 <= m < n. As with n, m
must be expressed as a balanced text if it exceeds a single token.
\globboxvector,
\globmarksvector,
\glob(box-or-marks)vector <control sequence or active char> n
where n specifies the length of the desired block. As
n is parsed as an undelimited parameter, it must be
expressed as a balanced text if it exceeds a single token. Once the
vector has been defined, element m can be accessed in left-hand
contexts as
<box-or-marks-referencer> <control sequence or active char> m
and in right-hand contexts as
<box-or-marks-dereferencer> <control sequence or active char> m
where 0 <= m < n. As with n, m
must be expressed as a balanced text if it exceeds a single token.
The significance of <box-or-marks-(de)referencer> is that
boxes and marks are unlike other registers in that there exists a whole family
of (de)referencers, one of which must be used in order to access
the particular element required. For boxes, the sole referencer is
\setbox, whilst the possible dereferencers include
\box,
\copy,
\unhbox,
\unvbox,,
\unhcopy and
\unvcopy.
For marks, the sole referencer is
\marks, whilst the possible dereferencers include
\topmarks,
\firstmarks,
\botmarks,
\splitfirstmarks and
\splitbotmarks.
\loccountvector,
\locdimenvector,
\locmuskipvector,
\locskipvector,
\loctoksvector
\loccountblk (etc), these commands use
e-TeX's arithmetic expression capabilities to locally allocate
vectors of boxes (etc) from e-TeX's extended register pool.
The syntax used is:
\loc(whatever)vector <control sequence or active char> n
where n specifies the length of the desired block. As
n is parsed as an undelimited parameter, it must be
expressed as a balanced text if it exceeds a single token. Once the
vector has been defined, element m can be accessed in both left-
and right-hand contexts as
<control sequence or active char> m
where 0 <= m < n. As with n, m
must be expressed as a balanced text if it exceeds a single token.
\locboxvector,
\locmarksvector,
\loc(box-or-marks)vector <control sequence or active char> n
where n specifies the length of the desired block. As
n is parsed as an undelimited parameter, it must be
expressed as a balanced text if it exceeds a single token. Once the
vector has been defined, element m can be accessed in left-hand
contexts as
<box-or-marks-referencer> <control sequence or active char> m
and in right-hand contexts as
<box-or-marks-dereferencer> <control sequence or active char> m
where 0 <= m < n. As with n, m
must be expressed as a balanced text if it exceeds a single token.
The significance of <box-or-marks-(de)referencer> is that
boxes and marks are unlike other registers in that there exists a whole family
of (de)referencers, one of which must be used in order to access
the particular element required. For boxes, the sole referencer is
\setbox, whilst the possible dereferencers include
\box,
\copy,
\unhbox,
\unvbox,,
\unhcopy and
\unvcopy.
For marks, the sole referencer is
\marks, whilst the possible dereferencers include
\topmarks,
\firstmarks,
\botmarks,
\splitfirstmarks and
\splitbotmarks.
\reserveinserts\reserveinserts n allows a package writer or user to
reserve an additional n insertions above and beyond those already
allocated. The syntax used is:
\reserveinserts n
n must be expressed as a balanced text if it exceeds a single token.
\load\inputting a complete file or for \reading a
file line-by-line, it makes no provision for any intermediate level of
file access. In e-TeX, we provide facilities for
\inputting one or more named modules from a
suitably structured library file. The syntax used is:
\load <module>[, <module>...] from <file>
whilst the library file itself should be structured as:
%% e-TeXlib Vx.y
\module {<name>}
. . .
\endmodule
\module {<name>}
. . .
\endmodule
etc.
The %% header is required, and the actual values in
Vx.y must correspond to the current version/revision
of e-TeX; for the current release, the header must therefore
be:
%% e-TeXlib V2.0
If a library file is changed during the lifetime of the system, it
is recommended (but not required) that this amendment be
recorded in a cycle number appended to the header;
a cycle number is of the form ;digit[s],
and thus a valid header for the current release of e-TeX might be
any of:
%% e-TeXlib V2.0
%% e-TeXlib V2.0;1
%% e-TeXlib V2.0;247
etc. The necessity for a perfect match between the library header
and the current version/revision of e-TeX may be relaxed in a future
release if it transpires that no changes in the structure of user
libraries are required for compatibility with future versions of e-TeX.
etexdefs.lib)grouptypes,
nodetypes,
interactionmodes and
iftypes. The standard format source, etex.src,
loads interactionmodes by default; the others can be loaded
using the appropriate one of the following:
\load grouptypes from etexdefs.lib \load nodetypes from etexdefs.lib \load iftypes from etexdefs.libOnce the relevant module has been loaded, the numeric values associated with each of the possible types/modes can be retrieved using one of the following commands with one of the parameters shewn:
\grouptypes
{simple}
{hbox}
{adjustedhbox}
{vbox}
{vtop}
{align}
{noalign}
{output}
{math}
{disc}
{insert}
{vcenter}
{mathchoice}
{semisimple}
{mathshift}
{mathleft}
\nodetypes
{char}
{hlist}
{vlist}
{rule}
{ins}
{mark}
{adjust}
{ligature}
{disc}
{whatsit}
{math}
{glue}
{kern}
{penalty}
{unset}
{maths}
\conditionaltypes
{charif}
{catif}
{numif}
{dimif}
{oddif}
{vmodeif}
{hmodeif}
{mmodeif}
{innerif}
{voidif}
{hboxif}
{vboxif}
{xif}
{eofif}
{trueif}
{falseif}
{caseif}
{definedif}
{csnameif}
{fontcharif}
\interactionmodes
{batch}
{nonstop}
{scroll}
{errorstop}
\language and
\setlanguage primitives with the advent of TeX 3.0, no
change was made to the Plain TeX source code to really exploit these
features with the single exception of the \newlanguage
command. In "etex.src", we defer the loading of
patterns and hyphenation exceptions until a
rudimentary language handling environment has been defined. We now
assume that the user (or rather the format-creator) will,
if required, modify the file
called "language.def" by adding the
various languages to be supported by the format. Each entry apart from
the last in "language.def" is of the form:
\addlanguage {<language>}
{<patterns file>}
{<exceptions file>}
{<left hyphen min>}
{<right hyphen min>} %%% shewn wrapped for clarity
The first line must be:
\addlanguage {USenglish}{hyphen.tex}{}{2}{3}
whilst the last must be
\uselanguage {USenglish}
to ensure that legacy documents not explicitly specifying a language
process in a manner identical to TeX (that is, using American English
patterns, exceptions and left- and right-hyphen minima).
In the absence of a suitable language.def
file, the default fallback mode (USenglish, with the canonical patterns,
exceptions and left- and right-hyphen minima for TeX) will be used.
Within the user document, \uselanguage {<some
language>} should be used to switch languages, which
will have the effect of loading appropriate patterns, exceptions, and
left- and right hyphen minima. To allow the use of more powerful
language-handling environments (e.g. Babel),
the \uselanguage command finishes by testing whether the
putative control sequence \uselanguage@hook is defined; if
it is, then it is expanded, passing as parameter the name of the
language to be used. It should be noted that \uselanguage
is automatically invoked during the expansion of
\addlanguage prior to the reading of patterns;
a further hook, \addlanguage@hook, is invoked in an
identical manner after the reading of patterns and exceptions
so as to allow (for example) category-codes to be changed for the
duration of the pattern- and exception-loading régime. This code is
still classed as experimental, and if it transpires that a superior
mechanism would improve the interface to
Babel
or LaTeX, it may be
enhanced in the future.
The e-TeX format source "etex.src" is a product of the NTS group.
Please notify any errors in this document to its creator;
Last updated and
validated
24-MAR-1998 19:45:12
/PT