| Current File : //usr/share/texlive/texmf-dist/doc/etex/base/etex_src.html |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html>
<head><title>The "etex.src" file and its adjuncts: V2.0</title>
</HEAD><BODY>
<H1>The e-T<sub><big>E</big></sub>X format source file
<code>"etex.src" (V2.0)</code></H1>
<p>
The primary e-TeX format source file, <code>"etex.src"</code>, is in principle
merely a wrapper for <code>"plain.tex"</code>, providing modified definitions
for some Plain TeX commands (at present, just
one: <code>\tracingall</code>), improving and generalising
the register allocation mechanism, and adding new commands
<p>
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 <em>vectors</em>
(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.
<p>
As the new commands and other features are not documented elsewhere,
a brief explanation of their syntax and semantics is provided here.
<p>
<dl>
<dt><code>\tracingall</code></dt>
<dd>The definition is augmented to enable tracing for the new e-TeX
tracing primitives <code>\tracingassigns</code>,
<code>\tracinggroups</code>, <code>\tracingifs</code>,
<code>\tracingnesting</code>
and <code>\tracingscantokens</code>; the numeric value assigned
to the TeX primitives <code>\tracingcommands</code> and
<code>\tracinglostchars</code> is increased
as e-TeX will report additional detail in these circumstances.
<p>
</dd>
<dt><code>\eTeX</code></dt>
<dd>A simple implementation of the e-TeX logo; a more sophisticated version,
capable of being used in maths sub/superscripts for example, may find
its way into <code>etexdefs.lib</code> in due course.
<p>
</dd>
<dt><code>\loggingall</code></dt>
<dd>This command is equivalent to the sequence <code>\tracingall</code>
<code>\tracingonline = 0 </code>.
<p>
</dd>
<dt><code>\tracingnone</code></dt>
<dd>This command restores the initial state of the various
<code>\tracing...</code> primitives following use of
<code>\tracingall</code> or <code>\loggingall</code>.
<p>
</dd>
<dt><code>\newmarks</code></dt>
<dd>As e-TeX provides 2<sup>15</sup> <code>\marks</code> rather than the single
<code>\mark</code> of TeX, an allocator mechanism is required; we
believe that <code>\marks</code> are closer to
<code>\box</code>es than to (say) <code>\count</code>s or
<code>\dimen</code>s and so have provided an analogous allocation
mechanism, in that <code>\newmarks</code> <<code><em>control
sequence or active character</em></code>> assigns a <em>numeric
value</em> to the parameter rather than making it a synonym for an
actual <code>\mark</code>; this numeric value can then be used to access
individual <code>\marks</code>, <code>\topmarks</code>,
<code>\splitbotmarks</code>, etc., as in
<pre>
\newmarks \rectomarks
. . .
\marks \rectomarks {This may form part of the recto running head}
. . .
\leftline {\topmarks \rectomarks}
</pre>
It should be noted that as <code>\marks 0</code> is synonymous with
<code>\mark</code>, <code>\newmarks</code> will never allocate that
particular value.
<br><em><strong>Note:</strong></em>
This command was called <code>\newmark</code> in V1.1; the alternative
spelling has been retained for compatibility, although it is now classed
as deprecated.
<p>
</dd>
<dt>
<code>\globbox</code>,
<code>\globcount</code>,
<code>\globdimen</code>,
<code>\globmarks</code>,
<code>\globmuskip</code>,
<code>\globskip</code>,
<code>\globtoks</code>
</dt>
<dd>
Analogous to TeX's <code>\newbox</code> (etc), these commands globally allocate
registers from e-TeX's extended register pool (i.e. from the register
range from 2<sup>0</sup> (for \marks) or from 2<sup>8</sup>
(for all other classes) to 2<sup>15</sup>-1). Registers are globally
allocated from the lower end of the range.
<p>
</dd>
<dt>
<code>\locbox</code>,
<code>\loccount</code>,
<code>\locdimen</code>,
<code>\locmarks</code>,
<code>\locmuskip</code>,
<code>\locskip</code>,
<code>\loctoks</code>
</dt>
<dd>
Analogous to <code>\globbox</code> (etc), these commands locally allocate
registers from e-TeX's extended register pool (i.e. from the register
range from 2<sup>0</sup> (for \marks) or from 2<sup>8</sup>
(for all other classes) to 2<sup>15</sup>-1). Registers are locally
allocated from the upper end of the range.
<p>
</dd>
<dt>
<code>\globboxblk</code>,
<code>\globcountblk</code>,
<code>\globdimenblk</code>,
<code>\globmarksblk</code>,
<code>\globmuskipblk</code>,
<code>\globskipblk</code>,
<code>\globtoksblk</code>
</dt>
<dd>
These commands extend <code>\globbox</code> (etc) by globally allocating
contiguous blocks of registers from e-TeX's extended register pool.
The syntax used is:
<pre>
\glob(whatever)blk <control sequence or active char> <em>n</em>
</pre>
where <em>n</em> specifies the length of the desired block. As
<em>n</em> 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
<code>\mathchardef</code>'d to the ordinal of the lowest register allocated.
<p>
</dd>
<dt>
<code>\locboxblk</code>,
<code>\loccountblk</code>,
<code>\locdimenblk</code>,
<code>\locmarksblk</code>,
<code>\locmuskipblk</code>,
<code>\locskipblk</code>,
<code>\loctoksblk</code>
</dt>
<dd>
These commands extend <code>\locbox</code> (etc) by locally allocating
contiguous blocks of registers from e-TeX's extended register pool.
The syntax used is:
<pre>
\loc(whatever)blk <control sequence or active char> <em>n</em>
</pre>
where <em>n</em> specifies the length of the desired block. As
<em>n</em> 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
<code>\mathchardef</code>'d to the ordinal of the lowest register allocated.
<p>
</dd>
<dt>
<code>\globcountvector</code>,
<code>\globdimenvector</code>,
<code>\globmuskipvector</code>,
<code>\globskipvector</code>,
<code>\globtoksvector</code>
</dt>
<dd>
An extension to <code>\globcountblk</code> (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:
<pre>
\glob(whatever)vector <control sequence or active char> <em>n</em>
</pre>
where <em>n</em> specifies the length of the desired block. As
<em>n</em> 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 <em>m</em> can be accessed in both left-
and right-hand contexts as
<pre>
<control sequence or active char> <em>m</em>
</pre>
where 0 <= <em>m</em> < <em>n</em>. As with <em>n</em>, <em>m</em>
must be expressed as a balanced text if it exceeds a single token.
<p>
</dd>
<dt>
<code>\globboxvector</code>,
<code>\globmarksvector</code>,
</dt>
<dd>
Analogous to but subtly different from the above, 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:
<pre>
\glob(box-or-marks)vector <control sequence or active char> <em>n</em>
</pre>
where <em>n</em> specifies the length of the desired block. As
<em>n</em> 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 <em>m</em> can be accessed in left-hand
contexts as
<pre>
<box-or-marks-referencer> <control sequence or active char> <em>m</em>
</pre>
and in right-hand contexts as
<pre>
<box-or-marks-dereferencer> <control sequence or active char> <em>m</em>
</pre>
where 0 <= <em>m</em> < <em>n</em>. As with <em>n</em>, <em>m</em>
must be expressed as a balanced text if it exceeds a single token.
<p>
The significance of <code><box-or-marks-(de)referencer></code> 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
<code>\setbox</code>, whilst the possible dereferencers include
<code>\box</code>,
<code>\copy,</code>
<code>\unhbox,</code>
<code>\unvbox,</code>,
<code>\unhcopy</code> and
<code>\unvcopy</code>.
For marks, the sole referencer is
<code>\marks</code>, whilst the possible dereferencers include
<code>\topmarks</code>,
<code>\firstmarks</code>,
<code>\botmarks</code>,
<code>\splitfirstmarks</code> and
<code>\splitbotmarks</code>.
<p>
</dd>
<dt>
<code>\loccountvector</code>,
<code>\locdimenvector</code>,
<code>\locmuskipvector</code>,
<code>\locskipvector</code>,
<code>\loctoksvector</code>
</dt>
<dd>
An extension to <code>\loccountblk</code> (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:
<pre>
\loc(whatever)vector <control sequence or active char> <em>n</em>
</pre>
where <em>n</em> specifies the length of the desired block. As
<em>n</em> 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 <em>m</em> can be accessed in both left-
and right-hand contexts as
<pre>
<control sequence or active char> <em>m</em>
</pre>
where 0 <= <em>m</em> < <em>n</em>. As with <em>n</em>, <em>m</em>
must be expressed as a balanced text if it exceeds a single token.
<p>
</dd>
<dt><code>\locboxvector</code>,
<code>\locmarksvector</code>,
</dt>
<dd>
Analogous to but subtly different from the above, 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:
<pre>
\loc(box-or-marks)vector <control sequence or active char> <em>n</em>
</pre>
where <em>n</em> specifies the length of the desired block. As
<em>n</em> 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 <em>m</em> can be accessed in left-hand
contexts as
<pre>
<box-or-marks-referencer> <control sequence or active char> <em>m</em>
</pre>
and in right-hand contexts as
<pre>
<box-or-marks-dereferencer> <control sequence or active char> <em>m</em>
</pre>
where 0 <= <em>m</em> < <em>n</em>. As with <em>n</em>, <em>m</em>
must be expressed as a balanced text if it exceeds a single token.
<p>
The significance of <code><box-or-marks-(de)referencer></code> 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
<code>\setbox</code>, whilst the possible dereferencers include
<code>\box</code>,
<code>\copy,</code>
<code>\unhbox,</code>
<code>\unvbox,</code>,
<code>\unhcopy</code> and
<code>\unvcopy</code>.
For marks, the sole referencer is
<code>\marks</code>, whilst the possible dereferencers include
<code>\topmarks</code>,
<code>\firstmarks</code>,
<code>\botmarks</code>,
<code>\splitfirstmarks</code> and
<code>\splitbotmarks</code>.
<p>
</dd>
<dt><code>\reserveinserts</code></dt>
<dd>As there are now so many registers available, there is a risk that a macro
package may allocate so many that there are none of the first 255
left for use by insertions (which cannot use the extended register set).
<code>\reserveinserts</code> <em>n</em> allows a package writer or user to
reserve an additional <em>n</em> insertions above and beyond those already
allocated. The syntax used is:
<pre>
\reserveinserts <em>n</em>
</pre>
<em>n</em> must be expressed as a balanced text if it exceeds a single token.
<p>
</dd>
<dt><code>\load</code></dt>
<dd>Although (Plain) TeX provides facilities for either
<code>\input</code>ting a complete file or for <code>\read</code>ing a
file line-by-line, it makes no provision for any intermediate level of
file access. In e-TeX, we provide facilities for
<code>\input</code>ting one or more named <em>modules</em> from a
suitably structured library file. The syntax used is:
<pre>
\load <<em>module</em>>[, <<em>module</em>>...] from <<em>file</em>>
</pre>
whilst the library file itself should be structured as:
<pre>
%% e-TeXlib Vx.y
\module {<<em>name</em>>}
. . .
\endmodule
\module {<<em>name</em>>}
. . .
\endmodule
etc.
</pre>
The %% header is required, and the actual values in
<code>Vx.y</code> must correspond to the current version/revision
of e-TeX; for the current release, the header must therefore
be:
<pre>
%% e-TeXlib V2.0
</pre>
If a library file is changed during the lifetime of the system, it
is <em>recommended</em> (but not required) that this amendment be
recorded in a <em>cycle number</em> appended to the header;
a <em>cycle number</em> is of the form <code>;</code><em>digit[s]</em>,
and thus a valid header for the current release of e-TeX might be
any of:
<pre>
%% e-TeXlib V2.0
%% e-TeXlib V2.0;1
%% e-TeXlib V2.0;247
</pre>
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.
<p>
</dd>
<dt>Modules in the standard library (<code>etexdefs.lib</code>)</dt>
<dd>
e-TeX is distributed with a standard library which provides mnemonic
names for the various values which can be returned by the new primitives.
The library contains four modules:
<code>grouptypes</code>,
<code>nodetypes</code>,
<code>interactionmodes</code> and
<code>iftypes</code>. The standard format source, <code>etex.src</code>,
loads <code>interactionmodes</code> by default; the others can be loaded
using the appropriate one of the following:
<pre>
\load grouptypes from etexdefs.lib
\load nodetypes from etexdefs.lib
\load iftypes from etexdefs.lib
</pre>
Once 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:
<pre>
\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}
</pre>
</dd>
<dt>Multiple language typesetting</dt>
<dd>When TeX gained <code>\language</code> and
<code>\setlanguage</code> 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 <code>\newlanguage</code>
command. In "<code>etex.src</code>", we defer the loading of
<em>patterns</em> and <em>hyphenation exceptions</em> 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 "<code>language.def</code>" by adding the
various languages to be supported by the format. Each entry apart from
the last in "<code>language.def</code>" is of the form:
<pre>
\addlanguage {<<em>language</em>>}
{<<em>patterns file</em>>}
{<<em>exceptions file</em>>}
{<<em>left hyphen min</em>>}
{<<em>right hyphen min</em>>} %%% shewn wrapped for clarity
</pre>
The first line <em><strong>must</strong></em> be:
<pre>
\addlanguage {USenglish}{hyphen.tex}{}{2}{3}
</pre>
whilst the last must be
<pre>
\uselanguage {USenglish}
</pre>
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 <code>language.def</code>
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, <code>\uselanguage {<<em>some
language</em>>}</code> 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. <a
href="http://homepage.cistron.nl/~jlbraams/babel.html">Babel</a>),
the <code>\uselanguage</code> command finishes by testing whether the
putative control sequence <code>\uselanguage@hook</code> 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 <code>\uselanguage</code>
is automatically invoked during the expansion of
<code>\addlanguage</code> <em>prior</em> to the reading of patterns;
a further hook, <code>\addlanguage@hook</code>, is invoked in an
identical manner <em>after</em> 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
<a href="http://homepage.cistron.nl/~jlbraams/babel.html">Babel</a>
or <a href="http://www.tex.ac.uk/CTAN/latex/">LaTeX</a>, it may be
enhanced in the future.
<p>
</dd>
</dl>
<p>
The e-TeX format source "etex.src" is a product of
<a href="/e-TeX/NTS-Group.Html">the NTS group</a>.
<hr>
<p>
Please notify any errors in this document to <a
href="http://www.vms.rhbnc.ac.uk/~chaa006/">its creator</a>;<br>
Last updated and
<a href="http://validator.w3.org/check?url=http://www.rhbnc.ac.uk/e-TeX/v2/src/etex_src.html">
validated
</a>
24-MAR-1998 19:45:12
/PT<br>
<img src="/logos/vh40.gif" alt="W3C HTML 4.0 validated.">
</body>
</html>