diff options
author | Karl Berry <karl@freefriends.org> | 2006-01-09 00:40:28 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2006-01-09 00:40:28 +0000 |
commit | fd423d0bb64fe29a2be1fbae5baaf4bc386cc274 (patch) | |
tree | 6bf20bbdf3d9741134f6ea40b30c1b3722fa0cd1 /Master/texmf-dist/doc/etex/base/etex_ref.html | |
parent | 0afd1aaf73fc909c6604939dcaf4ccc983b7277e (diff) |
doc 1
git-svn-id: svn://tug.org/texlive/trunk@77 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/etex/base/etex_ref.html')
-rw-r--r-- | Master/texmf-dist/doc/etex/base/etex_ref.html | 917 |
1 files changed, 917 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/etex/base/etex_ref.html b/Master/texmf-dist/doc/etex/base/etex_ref.html new file mode 100644 index 00000000000..2adbbb00d76 --- /dev/null +++ b/Master/texmf-dist/doc/etex/base/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 & +development project, the <I>NTS</I> Project, which was established under +the æ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 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 & <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é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 &Plain +</PRE> + +<P>and + +<pRE> evirtex &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 &etex +</PRE> + +<P>and + +<PRE> eVirTeX &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 implementation, for example, this +is accomplished by using the prefix "etex_" for each logical +name which defines the e-TeX environment, in contrast to the prefix "tex_" +which defines the analogous TeX environment; the "etex_*" 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><general text></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><balanced text></I> of the unexpanded <I><general text>></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><general text></I> within a ré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><general text></I>, expands to yield the +<I><balanced text></I> of the unexpanded <I><general text></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><general text></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égimes. </DD> + +<DT><A NAME="scantokens"></A><TT>\scantokens</TT>, </DT> + +<DD>when followed by a <I><general text></I>, decomposes the <I><balanced +text></I> of the <I><general text></I> into the corresponding +sequence of characters as if the <I><balanced text></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é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><general text></I> as in TeX, in e-TeX one writes <TT>\marks</TT> +<I>8-bit number</I> <I><general text></I>. For example, +<TT>\marks 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 0</TT> and <TT>\mark</TT> are in fact identical, as are +<TT>\topmarks 0</TT> and \<TT>topmark</TT>, \<TT>botmarks 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><general text></I>, displays a sequence +of characters corresponding to the decomposition of the <I><balanced +text></I> of the unexpanded <I><general text></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><balanced +text></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ö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> |