1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
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>
|
