summaryrefslogtreecommitdiff
path: root/systems/doc/etex/etex_ref.html
diff options
context:
space:
mode:
Diffstat (limited to 'systems/doc/etex/etex_ref.html')
-rw-r--r--systems/doc/etex/etex_ref.html917
1 files changed, 917 insertions, 0 deletions
diff --git a/systems/doc/etex/etex_ref.html b/systems/doc/etex/etex_ref.html
new file mode 100644
index 0000000000..2adbbb00d7
--- /dev/null
+++ b/systems/doc/etex/etex_ref.html
@@ -0,0 +1,917 @@
+<!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>