<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
   <TITLE>The e-TeX Short Reference Manual</TITLE>
   <META NAME="GENERATOR" CONTENT="Mozilla/3.0Gold (Win95; I) [Netscape]">
</HEAD>
<BODY>


<CENTER><P>The e-TeX Short Reference Manual<//P></CENTER>

<CENTER><P>NTS team<BR>
October 1996</CENTER>

<P>Derived from a paper originally presented as:

<CENTER><P>Philip Taylor, "e-TeX: a 100%-compatible successor to TeX"<BR>
(Following humbly in the footsteps of the Grand Wizard) </CENTER>

<P>in: Proceedings of the Ninth European TeX Conference EuroTeX'95, September
4-8, 1995, Arnhem, The Netherlands, pp. 359-370. 

<P>
<HR>

<H2>Table of Contents</H2>

<OL>
<LI><A HREF="#Introduction">Introduction</A> </LI>

<LI><A HREF="#Installation">Installation</A> </LI>

<LI><A HREF="#NewFeatures">The new features</A> </LI>

</OL>

<P>
<HR>

<H2>Table of new commands</H2>

<UL>
<LI><TT><A HREF="#beginL">\beginL</A></TT> </LI>

<LI><TT><A HREF="#beginR">\beginR</A></TT> </LI>

<LI><TT><A HREF="#botmarks">\botmarks</A></TT> </LI>

<LI><TT><A HREF="#detokenize">\detokenize</A></TT> </LI>

<LI><TT><A HREF="#endL">\endL</A></TT> </LI>

<LI><TT><A HREF="#endR">\endR</A></TT> </LI>

<LI><TT><A HREF="#eTeXrevision">\eTeXrevision</A></TT> </LI>

<LI><TT><A HREF="#eTeXversion">\eTeXversion</A></TT> </LI>

<LI><TT><A HREF="#everyeof">\everyeof</A></TT> </LI>

<LI><TT><A HREF="#firstmarks">\firstmarks</A></TT> </LI>

<LI><TT><A HREF="#currentgrouplevel">\currentgrouplevel</A></TT> </LI>

<LI><TT><A HREF="#currentgrouptype">\currentgrouptype</A></TT> </LI>

<LI><TT><A HREF="#ifcsname">\ifcsname</A></TT> </LI>

<LI><TT><A HREF="#ifdefined">\ifdefined</A></TT> </LI>

<LI><TT><A HREF="#interactionmode">\interactionmode</A></TT> </LI>

<LI><TT><A HREF="#lastnodetype">\lastnodetype</A></TT> </LI>

<LI><TT><A HREF="#marks">\marks</A></TT> </LI>

<LI><TT><A HREF="#middle">\middle</A></TT> </LI>

<LI><TT><A HREF="#predisplaydirection">\predisplaydirection</A></TT> </LI>

<LI><TT><A HREF="#protected">\protected</A></TT> </LI>

<LI><TT><A HREF="#readline">\readline</A></TT> </LI>

<LI><TT><A HREF="#scantokens">\scantokens</A></TT> </LI>

<LI><TT><A HREF="#showgroups">\showgroups</A></TT> </LI>

<LI><TT><A HREF="#showtokens">\showtokens</A></TT> </LI>

<LI><TT><A HREF="#splitfirstmarks">\splitfirstmarks</A></TT> </LI>

<LI><TT><A HREF="#splitbotmarks">\splitbotmarks</A></TT> </LI>

<LI><TT><A HREF="#TeXXeTstate">\TeXXeTstate</A></TT> </LI>

<LI><TT><A HREF="#topmarks">\topmarks</A></TT> </LI>

<LI><TT><A HREF="#tracingassigns">\tracingassigns</A></TT> </LI>

<LI><A HREF="#AdditionalTracingInformation"><TT>\tracingcommands</TT></A> </LI>

<LI><TT><A HREF="#tracinggroups">\tracinggroups</A></TT> </LI>

<LI><TT><A HREF="#tracingifs">\tracingifs</A></TT> </LI>

<LI><TT><A HREF="#tracingscantokens">\tracingscantokens</A></TT> </LI>

<LI><TT><A HREF="#unexpanded">\unexpanded</A></TT> </LI>

<LI><TT><A HREF="#unless">\unless</A></TT> </LI>
</UL>

<P>
<HR><A NAME="Introduction"></A>

<H1>1 Introduction</H1>

<P>e-TeX is the first concrete result of an international research &amp;
development project, the <I>NTS</I> Project, which was established under
the &aelig;gis of DANTE e.V. during 1992. The aims of the project are to perpetuate
and develop the spirit and philosophy of TeX, whilst respecting Knuth's
wish that TeX should remain frozen. 

<P>The group were very concerned that unless there existed some evolutionary
flexibility within which TeX could react to changing needs and environments,
it might all too soon become eclipsed by more modern yet less sophisticated
systems. Accordingly they agreed to investigate a possible successor or
successors to TeX, successors which would enshrine and encapsulate all
that was best in TeX whilst being freed from the evolutionary constraints
which Knuth had placed on TeX itself. To avoid any suggestion that it was
TeX which the group sought to develop against Knuth's wishes, a working
title of <I>NTS</I> (for New Typesetting System) was chosen for the project.


<P>During the initial meetings of the <I>NTS</I> group, it became clear
that there were two possible approaches to developments based on TeX: an
evolutionary path which would simply continue where Knuth had left off,
and which would use as its basis the source code of TeX itself (i.e. <TT><A HREF="#TeX.Web">TeX.Web</A></TT>);
the other a revolutionary path which would be based on a completely new
implementation of TeX, using a modern rapid-prototyping language which
could allow individual components of the system to be modified or replaced
in a simple and straightforward manner. The group agreed that the latter
(revolutionary) approach had much greater potential, but were aware that
the re-implementation would be non-trivial, and would require external
funding to bring it to fruition in finite time; accordingly they agreed
to concentrate their initial efforts on the former (evolutionary) path,
and set to work to specify and implement a direct derivative of TeX which
became known as e-TeX (the <I>e</I> of e-TeX may be read as <I>extended</I>,
<I>enhanced</I>, <I>evolutionary</I> or <I>European</I> at will(!), and
is also an acknowledgement of the parallel developments which have lead
the LaTeX&nbsp;3 team to modify their initial goal and to release an interim
LaTeX, LaTeX2e, which is directly derived from the LaTeX sources. 

<P>The group took as the starting point for the development of e-TeX the
many contributions which had been made on <TT><A HREF="#NTS-L">NTS-L</A></TT>
(the open mailing list on which discussions pertinent to e-TeX &amp; <I>NTS</I>
take place), together with the extremely interesting list of ideas which
Knuth gives at the end of <TT><A HREF="#TeX82.Bug">TeX82.Bug</A></TT>,
and which he describes as <I>`Possibly nice ideas that will not be implemented'</I>
(and which he contrasts with <I>`Bad ideas that will not be implemented'</I>!).
Individual members of the group also contributed ideas of their own which
had not necessarily been discussed publicly. All proposals were then subjected
to a rigorous vetting procedure to ensure that they conformed to the e-TeX
philosophy, which may be summarised as follows: 

<BLOCKQUOTE>
<P>e-TeX will in all ways demonstrate its affinity to, and derivation from,
Knuth's TeX; it will be implemented as a change-file to <TT><A HREF="#TeX.Web">TeX.Web</A></TT>,
and will not exploit features which could only be achieved by using a particular
implementation, operating system or language; it will be capable of being
used successfully on a machine as small as an 80286-based PC or similar.


<P>At format-generation time, a user will have the option of generating
either a TeX-compatible format or an e-TeX format; if the TeX-compatible
format is subsequently used in conjunction with e-TeX, the result will
be <A NAME="TripCompatible"></A><I>Trip-compatible</I> (i.e. indistinguishable
from TeX proper). If an e-TeX format is generated and used in conjunction
with e-TeX, then provided that none of the new e-TeX primitives are used,
the results will be identical to those which would be produced using TeX
proper. If an e-TeX format is used in conjunction with e-TeX and if one
or more of the new e-TeX primitives are used, then those portions of the
document which are affected by the new primitive(s) may be processed in
a manner unique to e-TeX; other portions of the document will be processed
in a manner identical to that of TeX proper. Only if an e-TeX format is
used in conjunction with e-TeX and if an explicit assignment is made to
one of the <A NAME="EnhancedMode"></A><I>enhanced-mode</I> variables to
enable that particular enhanced mode will e-TeX behave in a manner which
may be distinguishable from that of TeX even if no other reference to an
e-TeX primitive occurs anywhere in the document. (These modes of operation
are referred to as <A NAME="CompatibilityMode"></A><I>compatibility-mode</I>,
<A NAME="ExtendedMode"></A><I>extended-mode</I> and <I>enhanced-mode</I>
respectively.) 

<P>All new e-TeX primitives will be syntactically identical to existing
TeX primitives: that is, they will be either <I>control-words</I> or <I>control-symbols</I>
within a normal category code r&eacute;gime. Where an analogous primitive exists
within TeX, the corresponding e-TeX primitive(s) will occupy the same syntactic
niche. Every effort will be made to ensure that new e-TeX primitives fit
into the existing set of TeX datatypes; no new datatype will be introduced
unless it is absolutely essential. 
</BLOCKQUOTE>

<P>In brief, this implies that e-TeX will follow the principle of least
surprise: an existing TeX user, on using e-TeX for the first time, should
not be surprised by e-TeX's behaviour, and should be able to take advantage
of new e-TeX features without having either to unlearn some aspects of
TeX or to learn some new e-TeX philosophy. 

<P>
<HR><A NAME="Installation"></A>

<H1>2 Installation</H1>

<P>It is intended that e-TeX be available ready-compiled for those systems
for which pre-compiled binaries are the norm (e.g. MS-DOS, VMS, ...); for
other systems such as Unix(TM), e-TeX is supplied as a change-file which
will need to be applied to <TT><A HREF="#TeX.Web">TeX.Web</A></TT> in the
normal way. However, since there will already be an implementation-specific
change-file for the system of interest, some means will be required of
merging <TT><A HREF="#TeX.Web">TeX.Web</A></TT> with not one but (at least)
two change-files; possibilities include <I><A HREF="#PatchWeb">PatchWeb</A></I>,
<I><A HREF="#Tie">Tie</A></I>, etc., but if none of these are available
then <I><A HREF="#WebMerge">WebMerge</A></I>, a TeX script, is supplied
and can be used as a slower but satisfactory alternative. In practice,
two or three change-files will be needed: the e-TeX system-independent
change-file, the TeX system-dependent change-file, and perhaps a small
e-TeX system-dependent change-file. The system-independent e-TeX change-file
is supplied as part of the e-TeX kit, and sample system-dependent e-TeX
change-files are also supplied which may be used as a guide to those places
at which system-dependent interactions are to be expected: an experienced
implementor should have little difficulty in modifying one of these to
produce an e-TeX system-dependent change-file for the system of interest.
Once e-TeX has been tangled and woven, it should be compiled and linked
in the normal way. 

<P>Once a working binary (or binaries, for those systems which have separate
executables for <TT>IniTeX</TT> and <TT>VirTeX</TT>) has been acquired
or produced, the next step will be to generate a suitable format file or
files. Whilst e-TeX can be used in conjunction with <TT><A
HREF="src/plain.tex">Plain.TeX</A></TT> to produce a Plain <I>e-format</I>,
it is better to use the supplied <TT><A HREF="#etex.src">etex.src</A></TT> file
which supplements the e-TeX primitives with additional useful control
sequences. 

<P>When generating the format file, and regardless of the format source
used, one fundamental decision must be made: is e-TeX to generate a <I><A HREF="#CompatibilityMode">compatibility
mode</A></I> format, or an <I><A HREF="#ExtendedMode">extended mode</A></I>
format? If the former, <I>all</I> e-TeX <A NAME="extension"></A>extensions
and <A NAME="enhancement"></A>enhancements will be disabled, the format
will contain only the TeX-defined set of primitives, and any subsequent
use of the format in conjunction with e-TeX will result in completely TeX-compatible
behaviour and semantics, including compatibility at the level of the <A HREF="#Trip">Trip</A>
test. If the latter option, however, is selected, then all extensions present
in e-TeX will automatically be activated, and the format file will contain
not only the TeX-defined set of primitives but also those defined by e-TeX
itself; any subsequent use of such a format in conjunction with e-TeX will
result in e-TeX operating in <I><A HREF="#ExtendedMode">extended mode</A></I>;
documents which contains no references to any of the e-TeX-defined primitives
will continue to generate results identical to those which would have been
produced were the document processed by TeX, but compatibility at the <A HREF="#Trip">Trip</A>-test
level can no longer be accomplished, and of course any document which makes
reference to an e-TeX primitive will generate results which could not have
been accomplished using TeX. It should be noted that neither a <I><A HREF="#CompatibilityMode">compatibility
mode</A></I> format nor an <I><A HREF="#ExtendedMode">extended mode</A></I>
format may be used in conjunction with TeX itself; they are only suitable
for use in conjunction with e-TeX, since formats are not in general portable.
Finally it should be emphasised that even if an <I><A HREF="#ExtendedMode">extended
mode</A></I> format is generated, any document processed using such a format
but not referencing any e-TeX-defined primitive will produce results identical
to those which would have been produced had the same document been processed
using TeX; only if the document makes an explicit assignment to one of
the <I><A HREF="#EnhancedMode">enhanced mode</A></I> state variables (<TT><A
HREF="#TeXXeTstate">\TeXXeTstate</A></TT> is the only instance of these in V1
of e-TeX) will compatibility with TeX be compromised: e-TeX is then said to be
operating in <I><A HREF="#EnhancedMode">enhanced mode</A></I> rather than <I><A
HREF="#ExtendedMode">extended mode</A></I>. 


<P>The choice between generating a <I><A HREF="#CompatibilityMode">compatibility
mode</A></I> format and an <I><A HREF="#ExtendedMode">extended mode</A></I>
format is made at the point of specifying the format source file: assuming
that the operating system supports command-line entry with parameters,
then a normal TeX format-generation command would probably resemble: 

<PRE>        initex plain \dump
</PRE>

<P>or if the more verbose interactive form is preferred: 

<PRE>        initex
        **plain
        *\dump
</PRE>

<P>With e-TeX, exactly the same command will achieve exactly the same effect,
and the format generated will be a <I><A HREF="#CompatibilityMode">compatibility-mode</A></I>
format; thus assuming that the Ini-version of e-TeX is invoked with the
command <TT>einitex</TT>, the following will both generate <I><A HREF="#CompatibilityMode">compatibility-mode</A></I>
formats: 

<PRE>        einitex plain \dump
</PRE>

<P>and 

<PRE>        einitex
        **plain
        *\dump
</PRE>

<P>In order to generate an <I><A HREF="#ExtendedMode">extended mode</A></I>
format, the file-specification for the format source file must be preceded
by an asterisk (<TT>*</TT>); whilst this may seem an inelegant mechanism,
it has the great advantage that it avoids almost all system dependencies
(Graphical user interface (GUI) systems excepted, of course), and the asterisk
as a component element of a filename is a very remote possibility (most
filing systems reserve the asterisk as a `wild card' character, which can
therefore not form a part of a real file name <I>per se</I>). Thus to generate
an <I><A HREF="#ExtendedMode">extended mode</A></I> Plain format, the following
dialogue may be used: 

<PRE>        einitex *plain \dump
</PRE>

<P>or 

<PRE>        einitex
        ***plain
        *\dump
</PRE>

<P>and to generate an <I><A HREF="#ExtendedMode">extended mode</A></I>
<TT>etex.src</TT> format, the following instead: 

<PRE>        einitex *etex.src \dump
</PRE>

<P>or 

<PRE>        einitex
        ***etex.src
        *\dump
</PRE>

<P>Once suitable formats have been generated, they can then be used in
conjunction both with <I>e-IniTeX</I> and <I>e-VirTeX</I> without further
formality: in particular, no asterisk is needed (nor should be used!) if
a format is specified, since the format implicitly defines (depending as
its mode of generation) in which mode (compatibilty or extended) e-TeX
will operate. Thus, for example, if a <TT>plain</TT> format had been generated
in <I><A HREF="#CompatibilityMode">compatibility mode</A></I>, and an <TT>etex</TT>
format had been generated in <I><A HREF="#ExtendedMode">extended mode</A></I>,
then both: 

<pRE>        einitex &amp;Plain
</PRE>

<P>and 

<pRE>        evirtex &amp;plain
</PRE>

<P>will cause e-TeX to process any subsequent commands in <I><A HREF="#CompatibilityMode">compatibility
mode</A></I>. On the other hand, both 

<PRE>        einitex &amp;etex
</PRE>

<P>and 

<PRE>        eVirTeX &amp;etex
</PRE>

<P>will cause e-TeX to process any subsequent commands in <I><A HREF="#ExtendedMode">extended
mode</A></I>, <B>but only because the <TT>etex</TT> format was generated
in <I><A HREF="#ExtendedMode">extended mode</A></I></B>: it is not the
<B>name</B> of the format, nor is it the contents of the <B>source</B>
of the format, which determine the mode of operation -- it is the <B>mode
of operation</B> which was used when the format was generated. Any format
generated in <I><A HREF="#CompatibilityMode">compatibility mode</A></I>
will cause e-TeX to operate in <I><A HREF="#CompatibilityMode">compatibility
mode</A></I> whenever it is used, whilst the equivalent format, built from
the same source but generated in <I><A HREF="#ExtendedMode">extended mode,</A></I>
will cause e-TeX to operate in <I><A HREF="#ExtendedMode">extended mode</A></I>
whenever it is used. 

<P>Although e-TeX is completely TeX-compatible, and there is therefore
no real reason why any system should need both TeX and e-TeX, it is anticipated
that until complete confidence exists in the compatibility of e-TeX many
sites and users will prefer to retain instances of each. For this reason
it is intended that change-files and binaries should ensure that both TeX
and e-TeX can happily co-exist on any system by a careful choice of name-spaces.
In the case of the reference VMS&nbsp;implementation, for example, this
is accomplished by using the prefix &quot;etex_&quot; for each logical
name which defines the e-TeX environment, in contrast to the prefix &quot;tex_&quot;
which defines the analogous TeX environment; the &quot;etex_*&quot; logical
names are defined as search lists which first reference an e-TeX specific
location followed by the analogous location for TeX.

<P>
<HR><A NAME="NewFeatures"></A>

<H1>3 The new features</H1>

<P>Bearing in mind the contraints outlined in the introduction, the group
identified 35 new primitives which they believed would give
added functionality to e-TeX without compromising its compatibility with
TeX; of the 35 new primitives, 29 are extensions (which by definition
do not affect the semantics of existing TeX documents), whilst just six
(all concerned with the implementation of <A HREF="#TeX--XeT">TeX--XeT</A>)
are associated with an enhancement. In addition to the new primitives,
additional functionality was added to some existing primitives, and TeX's
behaviour in some unusual boundary conditions was made more robust (this
last has been subsumed in the most recent version of TeX, so this is no
longer e-TeX-specific). 

<P>The new features are listed and briefly described below, clustered together
to indicate related functionality.
The technical terms used below to
describe syntax entities as defined in <I><TT><A 
HREF="knuth/texbook.tex">The
TeXbook.</A></TT></I> 

<H2>3.1 Additional control over expansion</H2>

<UL>
<LI><TT><A HREF="#protected">\protected</A></TT> </LI>

<LI><TT><A HREF="#detokenize">\detokenize</A></TT> </LI>

<LI><TT><A HREF="#unexpanded">\unexpanded</A></TT> </LI>
</UL>

<DL>
<DT><A NAME="protected"></A><TT>\protected</TT> </DT>

<DD>is a prefix, analogous to <TT>\long</TT>, <TT>\outer</TT>, and <TT>\global</TT>;
it associates with the macro being defined an attribute which inhibits
expansion of the macro in expansion-only contexts (for example, within
the parameter text of a <TT>\write</TT> or <TT>\edef</TT>); if, however,
the parser or command processor (TeX's `oesophagus' and `stomach', in
Knuth's alimentary paradigm) is currently demanding a <I>command</I>, then
the <TT>\protected</TT> macro will expand in the normal way. This behaviour
is identical to that displayed by the explicit expansion of a token-list
register through the use of <TT>\the</TT>; the same model is used elsewhere
in e-TeX to achieve a consistent paradigm for <I>partial expansion</I>.
</DD>

<DT><A NAME="detokenize"></A><TT>\detokenize</TT>, </DT>

<DD>when followed by a <I>&lt;general text&gt;</I>, expands to yield a
sequence of character tokens of <TT>\catcode</TT> 10 (<I>space</I>) or
12 (<I>other</I>) corresponding to a decomposition of the tokens of the
<I>&lt;balanced text&gt;</I> of the unexpanded <I>&lt;general text&gt;&gt;</I>;
c.f. <TT>\showtokens</TT>. The effect is rather as if <TT><A HREF="#scantokens">\scantokens</A></TT>
(q.v.) were applied to the <I>&lt;general text&gt;</I> within a r&eacute;gime
in which only <TT>\catcodes</TT> 10 and 12 existed. Note that in order
to preserve the boundaries between <I>control words</I> and any following
<I>letter</I>, a <I>space</I> is yielded after each control word including
the last. </DD>

<DT><A NAME="unexpanded"></A><TT>\unexpanded</TT>, </DT>

<DD>when followed by a <I>&lt;general text&gt;</I>, expands to yield the
<I>&lt;balanced text&gt;</I> of the unexpanded <I>&lt;general text&gt;</I>.
No further expansion will occur if e-TeX is currently performing a <TT>\write</TT>,
<TT>\edef</TT>, etc., but further expansion will occur if the parser or
command processor is currently demanding a <I>command</I>. The effect is
as if the <I>&lt;general text&gt;</I> were assigned to a token list register,
and the latter were then partially expanded using <TT>\the</TT>, but no
assignment actually takes place; thus <TT>\unexpanded</TT> can be used
in expansion-only contexts. </DD>
</DL>

<H2>3.2 Provision for re-scanning already read text</H2>

<UL>
<LI><TT><A HREF="#readline">\readline</A></TT> </LI>

<LI><TT><A HREF="#scantokens">\scantokens</A></TT> </LI>
</UL>

<DL>
<DT><A NAME="readline"></A><TT>\readline</TT> </DT>

<DD>is analogous to <TT>\read</TT>, but treats each character as if it
were currently of <TT>\catcode</TT> 10 (<I>space</I>) or 12 (<I>other</I>);
the text thus read is therefore suitable for being scanned and re-scanned
(using <TT><A HREF="#scantokens">\scantokens</A></TT>, q.v.) under different
<TT>\catcode</TT> r&eacute;gimes. </DD>

<DT><A NAME="scantokens"></A><TT>\scantokens</TT>, </DT>

<DD>when followed by a <I>&lt;general text&gt;</I>, decomposes the <I>&lt;balanced
text&gt;</I> of the <I>&lt;general text&gt;</I> into the corresponding
sequence of characters as if the <I>&lt;balanced text&gt;</I> were written
unexpanded to a file; it then uses TeX's <TT>\input</TT> mechanism to re-process
these characters under the current <TT>\catcode</TT> r&eacute;gime. As the <TT>\input</TT>
mechanism is used, even hex notation (<TT>^^xy</TT>) will be re-interpreted.
Parentheses and a single space representing the <I>pseudo-file</I> will
be displayed if <TT><A HREF="#tracingscantokens">\tracingscantokens</A></TT>
(q.v.) is positive and non-zero. </DD>
</DL>

<H2>3.3 Environmental enquiries</H2>

<UL>
<LI><TT><A HREF="#eTeXrevision">\eTeXrevision</A></TT> </LI>

<LI><TT><A HREF="#eTeXversion">\eTeXversion</A></TT> </LI>

<LI><TT><A HREF="#currentgrouplevel">\currentgrouplevel</A></TT> </LI>

<LI><TT><A HREF="#currentgrouptype">\currentgrouptype</A></TT> </LI>

<LI><TT><A HREF="#ifcsname">\ifcsname</A></TT> </LI>

<LI><TT><A HREF="#ifdefined">\ifdefined</A></TT> </LI>

<LI><TT><A HREF="#lastnodetype">\lastnodetype</A></TT> </LI>
</UL>

<DL>
<DT><A NAME="eTeXrevision"></A><TT>\eTeXrevision</TT>: </DT>

<DD>an primitive which expands to yield a sequence of character tokens
of <TT>\catcode</TT> 12 (<I>other</I>; these represent the minor component
of the combined version/revision number. Pre-release versions will be characterised
by an initial <I>minus</I> sign (<TT>-</TT>), whilst post-release versions
will be implicitly positive; both will contain an explicit leading decimal
point, which will follow any minus sign present. </DD>

<DT><A NAME="eTeXversion"></A><TT>\eTeXversion</TT>: </DT>

<DD>an internal read-only integer representing the major component of the
combined version/revision number. </DD>

<DT><A NAME="currentgrouplevel"></A><TT>\currentgrouplevel</TT>: </DT>

<DD>an internal read-only integer which returns the current group level
(i.e. depth of nesting). </DD>

<DT><A NAME="currentgrouptype"></A><TT>\currentgrouptype</TT>: </DT>

<DD>an internal read-only integer which returns the type of the innermost
group as an integer in the range 0..16. Textual definitions of these types
may be provided through an associated macro library, but it is intended
that these definitions shall be easily replaceable by national language
versions in environments within which English language texts are sub-optimal.
</DD>

<DT><A NAME="ifcsname"></A><TT>\ifcsname</TT>: </DT>

<DD>similar in effect to the sequence <TT>\unless</TT> <TT>\expandafter</TT>
<TT>\ifx</TT> <TT>\expandafter</TT> <TT>\relax</TT> <TT>\csname</TT> but
avoids the side-effect of the <I>cs-name</I> being ascribed the value <TT>\relax</TT>,
and also does not rely on <TT>\relax</TT> having its canonical meaning.
No hash-table entry is used if <I>cs-name</I> does not exist. (<TT><A HREF="#unless">\unless</A></TT>
is explained below.) </DD>

<DT><A NAME="ifdefined"></A><TT>\ifdefined</TT>: </DT>

<DD>similar in effect to <TT><A HREF="#unless">\unless</A></TT> <TT>\ifx</TT>
<TT>\undefined</TT>, but does not require <TT>\undefined</TT> to actually
be undefined, since no explicit comparison is made with any particular
control sequence. </DD>

<DT><A NAME="lastnodetype"></A><TT>\lastnodetype</TT>: </DT>

<DD>an internal read-only integer which returns the type of the last node
on the current list as an integer in the range -1..15+ (only values -1..15
are defined in the first release, but future releases may define additional
values). Textual definitions of these types may be provided through an
associated macro library. </DD>
</DL>

<H2>3.4 Generalisation of the <TT>\mark</TT> concept: a class of <TT>\marks</TT></H2>

<UL>
<LI><TT><A HREF="#marks">\marks</A></TT> </LI>

<LI><TT><A HREF="#botmarks">\botmarks</A></TT> </LI>

<LI><TT><A HREF="#firstmarks">\firstmarks</A></TT> </LI>

<LI><TT><A HREF="#topmarks">\topmarks</A></TT> </LI>

<LI><TT><A HREF="#splitfirstmarks">\splitfirstmarks</A></TT> </LI>

<LI><TT><A HREF="#splitbotmarks">\splitbotmarks</A></TT> </LI>
</UL>

<DL>
<DT><A NAME="marks"></A><TT>\marks</TT>: </DT>

<DD>this is one of Knuth's `possibly good ideas', listed at the end of <TT><A
HREF="#TeX82.Bug">TeX82.Bug</A></TT>; whereas TeX has only one <TT>\mark</TT>,
which has to be over-loaded if more than one class of information is to be
saved (e.g. over-loading is necessary if separate information for recto and
verso pages is to be maintained), e-TeX has a whole class of <TT>\marks</TT>
(256, in the first release); thus rather than writing <TT>\mark</TT>
<I>&lt;general text&gt;</I> as in TeX, in e-TeX one writes <TT>\marks</TT>
<I>8-bit number</I> <I>&lt;general text&gt;</I>. For example,
<TT>\marks&nbsp;0</TT> could be used to retain information for the verso page,
whilst <TT>\marks 1</TT> could retain information for the recto. There are
equivalent classes for the five <TT>\marks</TT> variables <A
NAME="botmarks"></A><TT>\botmarks</TT>, <A
NAME="firstmarks"></A><TT>\firstmarks</TT>, <A
NAME="topmarks"></A><TT>\topmarks</TT>, <A
NAME="splitfirstmarks"></A><TT>\splitfirstmarks</TT> and <A
NAME="splitbotmarks"></A><TT>\splitbotmarks</TT>. It should be noted that
<TT>\marks&nbsp;0</TT> and <TT>\mark</TT> are in fact identical, as are
<TT>\topmarks&nbsp;0</TT> and \<TT>topmark</TT>, \<TT>botmarks&nbsp;0</TT> and
<TT>\botmark</TT> and so on.</DD> 
</DL>

<H2>3.5 Bi-directional typesetting: the <A HREF="#TeX--XeT">TeX--XeT</A>
primitives</H2>

<UL>
<LI><TT><A HREF="#TeXXeTstate">\TeXXeTstate</A></TT> </LI>

<LI><TT><A HREF="#beginL">\beginL</A></TT> </LI>

<LI><TT><A HREF="#beginR">\beginR</A></TT> </LI>

<LI><TT><A HREF="#endL">\endL</A></TT> </LI>

<LI><TT><A HREF="#endR">\endR</A></TT> </LI>

<LI><TT><A HREF="#predisplaydirection">\predisplaydirection</A></TT> </LI>
</UL>

<P><A HREF="#TeX--XeT">TeX--XeT</A> was developed by Peter Breitenlohner
based on the original <!--A HREF="TeX-XeT-TODO"-->TeX-XeT<!--/A--> of Donald Knuth
and Pierre MacKay; whereas <!--A HREF="#TeX-XeT"-->TeX-XeT<!--/A--> generated non-standard
<I>DVI</I> files, <A HREF="#TeX--XeT">TeX--XeT</A> generates perfectly
normal <I>DVI</I> files which can therefore be processed by standard <I>DVI</I>
drivers (assuming, of course, that the necessary fonts are available).
Both systems permit the direction of typesetting (conventionally left-to-right
in Western documents) to be reversed for part or all of a document, which
is particularly useful when setting languages such as Hebrew or Arabic.


<DL>
<DT><A NAME="beginL"></A><TT>\beginL</TT>: </DT>

<DD>indicates the start of a region (e.g. a section of text, or a pre-constructed
<I>box</I>) which should be set left-to-right; </DD>

<DT><A NAME="beginR"></A><TT>\beginR</TT>: </DT>

<DD>indicates the start of a region which should be set right-to-left;
</DD>

<DT><A NAME="endL"></A><TT>\endL</TT>: </DT>

<DD>indicates the end of a region which should be set left-to-right; </DD>

<DT><A NAME="endR"></A><TT>\endR</TT>: </DT>

<DD>indicates the end of a region which should be set right-to-left; </DD>

<DT><A NAME="TeXXeTstate"></A><TT>\TeXXeTstate</TT>: </DT>

<DD>an internal read/write integer, its value is zero or negative to indicate
that <A HREF="#TeX--XeT">TeX--XeT</A> features are not to be used; a positive
value indicates that they may be used. As the internal data structures
built by <A HREF="#TeX--XeT">TeX--XeT</A> differ from those built by TeX,
and as the typesetting of a document by <A HREF="#TeX--XeT">TeX--XeT</A>
may therefore differ from that performed by TeX, <TT>\TeXXeTstate</TT>
defaults to zero, and even if set positive during format creation will
be re-set to zero before the format is dumped. Explicit user action therefore
is required to enable <A HREF="#TeX--XeT">TeX--XeT</A> semantics, and <A HREF="#TeX--XeT">TeX--XeT</A>
is therefore classed as an <I><A HREF="#enhancement">enhancement</A></I>,
not simply an <I><A HREF="#extension">extension</A></I>. </DD>

<DT><A NAME="predisplaydirection"></A><TT>\predisplaydirection</TT>: </DT>

<DD>an internal read/write integer, initialised by e-TeX to indicate the
direction of the last partial paragraph before a display; it is used to
control the placement of elements such as equation numbers, and can be
explictly set to affect this placement. </DD>
</DL>

<H2>3.6 Additional debugging features</H2>

<UL>
<LI><TT><A HREF="#interactionmode">\interactionmode</A></TT> </LI>

<LI><TT><A HREF="#showgroups">\showgroups</A></TT> </LI>

<LI><TT><A HREF="#showtokens">\showtokens</A></TT> </LI>

<LI><TT><A HREF="#tracingassigns">\tracingassigns</A></TT> </LI>

<LI><TT><A HREF="#tracinggroups">\tracinggroups</A></TT> </LI>

<LI><TT><A HREF="#tracingifs">\tracingifs</A></TT> </LI>

<LI><TT><A HREF="#tracingscantokens">\tracingscantokens</A></TT> </LI>

<LI><A HREF="#AdditionalTracingInformation">Additional detail for <TT>\tracingcommands</TT></A>
</LI>
</UL>

<DL>
<DT><A NAME="interactionmode"></A><TT>\interactionmode</TT>: </DT>

<DD>whereas in TeX there exist only explicit commands such as <TT>\scrollmode</TT>,
<TT>\errorstopmode</TT>, etc., in e-TeX read/write access is provided via
<TT>\interactionmode</TT> (an internal integer); assigning a numeric value
sets the associated mode, whilst the current mode may be ascertained by
interrogating its value. Symbolic definitions of these values may be provided
through an associated macro library. </DD>

<DT><A NAME="showgroups"></A><TT>\showgroups</TT>: </DT>

<DD><I>(e-)TeX</I> has many different classes of <I>group</I>, which should
normally be properly balanced and nested; if a nesting or imbalance error
occurs, it can be <I>very</I> difficult to track down the source of the
problem. <TT>\showgroups</TT> causes e-TeX to display the level and type
of all active groups from the point within which it was called. </DD>

<DT><A NAME="showtokens"></A><TT>\showtokens</TT>, </DT>

<DD>when followed by a <I>&lt;general text&gt;</I>, displays a sequence
of characters corresponding to the decomposition of the <I>&lt;balanced
text&gt;</I> of the unexpanded <I>&lt;general text&gt;</I>; c.f. <TT><A HREF="#detokenize">\detokenize</A></TT>.
</DD>

<DT><A NAME="tracingassigns"></A><TT>\tracingassigns</TT>: </DT>

<DD><TT>\tracingassigns</TT>
(an internal read/write integer) causes e-TeX to display the
contents of registers <em>before</em> an assignment, as well
as after the assignment,
while set to a positive non-zero value. In standard TeX, 
only the value <em>after</em> the assignment can be displayed
during a trace.
</DD>

<DT><A NAME="tracinggroups"></A><TT>\tracinggroups</TT>: </DT>

<DD>a further aid to debugging runaway-group problems, <TT>\tracinggroups</TT>
(an internal read/write integer) causes e-TeX to trace entry and exit to
every group while set to a positive non-zero value. </DD>

<DT><A NAME="tracingifs"></A><TT>\tracingifs</TT>: </DT>

<DD> <tt>\tracingifs</tt> is an aid to debugging the expansion of conditionals.
If it is set to a positive non-zero value, e-TeX traces the flow of
control through conditional statements.</DD>

<DT><A NAME="tracingscantokens"></A><TT>\tracingscantokens</TT>: </DT>

<DD>an internal read/write integer, assigning it a positive non-zero value
will cause an open-parenthesis and space to be displayed whenever <TT><A HREF="#scantokens">\scantokens</A></TT>
is invoked; the matching close-parenthesis will be recorded when the scan
is complete. If a traceback occurs during the expansion of <TT><A HREF="#scantokens">\scantokens</A></TT>,
the first displayed line number will reflect the logical line number of
the pseudo-file created from the parameter to <TT><A HREF="#scantokens">\scantokens</A></TT>;
thus enabling <TT>\tracingscantokens</TT> can assist in identifying why
an seemingly irrational line number is shewn as the source of error (the
traceback always continues until the line number of the actual source file
is displayed). </DD>

<DT><A NAME="AdditionalTracingInformation"></A>Additional tracing information:
</DT>

<DD>If <TT>\tracingcommands</TT> is greater than 2, additional information
is displayed (the maximum value defined in standard TeX is 2). </DD>
</DL>

<H2>3.7 Miscellaneous primitives</H2>

<UL>
<LI><TT><A HREF="#everyeof">\everyeof</A></TT> </LI>

<LI><TT><A HREF="#middle">\middle</A></TT> </LI>

<LI><TT><A HREF="#unless">\unless</A></TT> </LI>
</UL>

<DL>
<DT><A NAME="everyeof"></A><TT>\everyeof</TT>: </DT>

<DD>this is another of Knuth's `possibly good ideas', listed at the end of
<TT><A HREF="#TeX82.Bug">TeX82.Bug</A></TT>; analogous to the other
<TT>\every...</TT> primitives, it takes as parameter a <I>&lt;balanced
text&gt;</I>, the tokens of which are inserted when the end of a file (either
real or virtual, if <TT><A HREF="#scantokens">\scantokens</A></TT> is used) is
reached. This allows <TT>\input</TT> statements to be used within the
replacement text of <TT>\edef</TT>s, and allows totally arbitrary files to be
<TT>\input</TT> within an e-TeX conditional, since the necessary <TT>\fi</TT>
can be inserted before e-TeX complains that it has fallen off the end of the
file. It should be noted that the <code>\everyeof</code> tokens are <em>not</em>
inserted if the end-of-file is forced through the use of <code>\endinput</code>.
</DD> 

<DT><A NAME="middle"></A><TT>\middle</TT>: </DT>

<DD>analogous to TeX's <TT>\left</TT> and <TT>\right</TT>, <TT>\middle</TT>
specifies that the following delimiter is to serve both as a right and
left delimiter; it will be set with spacing appropriate to a right delimiter
w.r.t. the preceding atom(s), and with spacing appropriate to a left delimiter
w.r.t. the succeeding atom(s). A particularly nice 
<a href="http://vzdmzi.zdv.uni-mainz.de/~knappen/jk006.html">example</a> 
of its use
has kindly been provided by 
<a href="mailto:knappen@vkpmzd.kph.uni-mainz.de">J&ouml;rg Knappen</a></DD>

<DT><A NAME="unless"></A><TT>\unless</TT>: </DT>

<DD>TeX has, by design, a rather sparse set of conditional primitives:
<TT>\ifeof</TT>, <TT>\ifodd</TT>, <TT>\ifvoid</TT>, etc., have no complementary
counterparts. Whilst this normally poses no problems since each accepts
both a <TT>\then</TT> (implicit) and an <TT>\else</TT> (explicit) part,
they fall down when used as the final <TT>\if...</TT> of a <TT>\loop ...
\if ... \repeat</TT> construct, since no <TT>\else</TT> is allowed after
the final <TT>\if...</TT>. <TT>\unless</TT> allows the sense of all Boolean
conditionals to be inverted, and thus (for example) <TT>\unless</TT>
<TT>\ifeof</TT> yields <I>true</I> iff end-of-file has <I>not</I> yet been
reached. 
<a href="mailto:dak@neuroinformatik.ruhr-uni-bochum.de"">David Kastrup</a> has
correctly pointed out that a similar effect can be achieved by macro
programming, but the solution is not sufficiently general to allow it to be
used unchanged in all contexts in which the new <tt>\unless</tt> primitive can
be used.</DD> 
</DL>

<HR>

<H2>References:</H2>

<DL>
<DT><A NAME="TeX.Web"></A><B><TT>TeX.Web</TT></B> </DT>

<DD>CTAN: <A HREF="ftp://ftp.dante.de/tex-archive/systems/knuth/tex/tex.web">tex-archive/systems/knuth/tex/tex.web</A>
</DD>

<DT><A NAME="TeX82.Bug"></A><B><TT>TeX82.Bug</TT></B> </DT>

<DD>CTAN: <A HREF="ftp://ftp.dante.de/tex-archive/systems/knuth/errata/tex82.bug">tex-archive/systems/knuth/errata/tex82.bug</A>
</DD>

<DT><A NAME="Trip"></A><B><TT>Trip</TT> test</B> </DT>

<DD>CTAN: <A HREF="ftp://ftp.dante.de/tex-archive/systems/knuth/tex/tripman.tex">tex-archive/systems/knuth/tex/tripman.tex</A>
</DD>

<DT><A NAME="Plain.TeX"></A><B><TT>Plain.TeX</TT></B> </DT>

<DD>CTAN: <A HREF="ftp://ftp.dante.de/tex-archive/systems/knuth/lib/plain.tex">tex-archive/systems/knuth/lib/plain.tex</A>
</DD>

<DT><A NAME="TeX--XeT"></A><B>TeX--XeT</B> </DT>

<DD>CTAN: <A HREF="ftp://ftp.dante.de/tex-archive/systems/knuth/tex--xet/">tex-archive/systems/knuth/tex--xet</A>
</DD>

<dt><a name="etex.src"></a><b><tt>etex.src</tt></b></dt>

<dd><a href="src/etex.src">etex.src</a></dd>

<DT><A NAME="NTS-L"></A><B>Discussion List <TT>NTS-L</TT></B> </DT>

<DD>Subscribe with e-mail to the Listserver program 
<A HREF="mailto:listserv@vm.urz.uni-heidelberg.de">
listserv@urz.uni-heidelberg.de</A>
</DD>

<DT><A NAME="Tie"></A><B>Tie</B> (written in C) </DT>

<DD>CTAN: <A HREF="ftp://ftp.tex.ac.uk/tex-archive/web/tie/">tex-archive/web/tie</A>
</DD>

<DT><A NAME="WebMerge"></A><B>WebMerge</B> (written in TeX) </DT>

<DD><a href="webmerge.tex">webmerge.tex</a></DD>

<DT><A NAME="PatchWeb"></A><B>PatchWeb</B> (for PC, bundled with "dos-tp") </DT>

<DD>CTAN: <A HREF="ftp://ftp.dante.de/tex-archive/systems/msdos/dos-tp/">tex-archive/systems/msdos/dos-tp/</A>
</DD>
</DL>

<P>
<HR>

<ADDRESS>The NTS team</ADDRESS>

<hr>
Put on the WWW by Bernd Raichle, member of the NTS group;<br>
subsequently updated by Philip Taylor, 
with corrections by Peter Breitenlohner.<br>
last updated:  30-JUL-1997 19:31:47 (PT)<br>
<FORM METHOD="POST" ACTION="http://www.webtechs.com/cgi-bin/html-check.pl">
<INPUT NAME="recommended" VALUE="0" TYPE="hidden">
<INPUT NAME="level" VALUE="Wilbur" TYPE="hidden">
<INPUT NAME="input" VALUE="0" TYPE="hidden">
<INPUT NAME="esis" VALUE="0" TYPE="hidden">
<INPUT NAME="render" VALUE="0" TYPE="hidden">
<a href="http://ugweb.cs.ualberta.ca/~gerald/validate
	/?url=http://www.rhbnc.ac.uk/e-TeX/etex_ref.html">
<img src="/www/logos/invalid_html3_2.gif" alt="HTML 3.2 Checked!">
</a>
<INPUT NAME="URLs" 
       VALUE="http://www.rhbnc.ac.uk/e-TeX/etex_ref.html"
       TYPE="hidden"
>
<INPUT TYPE="image" SRC="/www/logos/invalid_html_wilbur.gif">
</FORM>
</BODY>
</HTML>