Debian Codegraph @

texmf-dist/doc/etex/base/etex_ref.html

raw
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
2 <HTML>
3 <HEAD>
4 <TITLE>The e-TeX Short Reference Manual</TITLE>
5 <META NAME="GENERATOR" CONTENT="Mozilla/3.0Gold (Win95; I) [Netscape]">
6 </HEAD>
7 <BODY>
8
9
10 <CENTER><P>The e-TeX Short Reference Manual<//P></CENTER>
11
12 <CENTER><P>NTS team<BR>
13 October 1996</CENTER>
14
15 <P>Derived from a paper originally presented as:
16
17 <CENTER><P>Philip Taylor, "e-TeX: a 100%-compatible successor to TeX"<BR>
18 (Following humbly in the footsteps of the Grand Wizard) </CENTER>
19
20 <P>in: Proceedings of the Ninth European TeX Conference EuroTeX'95, September
21 4-8, 1995, Arnhem, The Netherlands, pp. 359-370.
22
23 <P>
24 <HR>
25
26 <H2>Table of Contents</H2>
27
28 <OL>
29 <LI><A HREF="#Introduction">Introduction</A> </LI>
30
31 <LI><A HREF="#Installation">Installation</A> </LI>
32
33 <LI><A HREF="#NewFeatures">The new features</A> </LI>
34
35 </OL>
36
37 <P>
38 <HR>
39
40 <H2>Table of new commands</H2>
41
42 <UL>
43 <LI><TT><A HREF="#beginL">\beginL</A></TT> </LI>
44
45 <LI><TT><A HREF="#beginR">\beginR</A></TT> </LI>
46
47 <LI><TT><A HREF="#botmarks">\botmarks</A></TT> </LI>
48
49 <LI><TT><A HREF="#detokenize">\detokenize</A></TT> </LI>
50
51 <LI><TT><A HREF="#endL">\endL</A></TT> </LI>
52
53 <LI><TT><A HREF="#endR">\endR</A></TT> </LI>
54
55 <LI><TT><A HREF="#eTeXrevision">\eTeXrevision</A></TT> </LI>
56
57 <LI><TT><A HREF="#eTeXversion">\eTeXversion</A></TT> </LI>
58
59 <LI><TT><A HREF="#everyeof">\everyeof</A></TT> </LI>
60
61 <LI><TT><A HREF="#firstmarks">\firstmarks</A></TT> </LI>
62
63 <LI><TT><A HREF="#currentgrouplevel">\currentgrouplevel</A></TT> </LI>
64
65 <LI><TT><A HREF="#currentgrouptype">\currentgrouptype</A></TT> </LI>
66
67 <LI><TT><A HREF="#ifcsname">\ifcsname</A></TT> </LI>
68
69 <LI><TT><A HREF="#ifdefined">\ifdefined</A></TT> </LI>
70
71 <LI><TT><A HREF="#interactionmode">\interactionmode</A></TT> </LI>
72
73 <LI><TT><A HREF="#lastnodetype">\lastnodetype</A></TT> </LI>
74
75 <LI><TT><A HREF="#marks">\marks</A></TT> </LI>
76
77 <LI><TT><A HREF="#middle">\middle</A></TT> </LI>
78
79 <LI><TT><A HREF="#predisplaydirection">\predisplaydirection</A></TT> </LI>
80
81 <LI><TT><A HREF="#protected">\protected</A></TT> </LI>
82
83 <LI><TT><A HREF="#readline">\readline</A></TT> </LI>
84
85 <LI><TT><A HREF="#scantokens">\scantokens</A></TT> </LI>
86
87 <LI><TT><A HREF="#showgroups">\showgroups</A></TT> </LI>
88
89 <LI><TT><A HREF="#showtokens">\showtokens</A></TT> </LI>
90
91 <LI><TT><A HREF="#splitfirstmarks">\splitfirstmarks</A></TT> </LI>
92
93 <LI><TT><A HREF="#splitbotmarks">\splitbotmarks</A></TT> </LI>
94
95 <LI><TT><A HREF="#TeXXeTstate">\TeXXeTstate</A></TT> </LI>
96
97 <LI><TT><A HREF="#topmarks">\topmarks</A></TT> </LI>
98
99 <LI><TT><A HREF="#tracingassigns">\tracingassigns</A></TT> </LI>
100
101 <LI><A HREF="#AdditionalTracingInformation"><TT>\tracingcommands</TT></A> </LI>
102
103 <LI><TT><A HREF="#tracinggroups">\tracinggroups</A></TT> </LI>
104
105 <LI><TT><A HREF="#tracingifs">\tracingifs</A></TT> </LI>
106
107 <LI><TT><A HREF="#tracingscantokens">\tracingscantokens</A></TT> </LI>
108
109 <LI><TT><A HREF="#unexpanded">\unexpanded</A></TT> </LI>
110
111 <LI><TT><A HREF="#unless">\unless</A></TT> </LI>
112 </UL>
113
114 <P>
115 <HR><A NAME="Introduction"></A>
116
117 <H1>1 Introduction</H1>
118
119 <P>e-TeX is the first concrete result of an international research &amp;
120 development project, the <I>NTS</I> Project, which was established under
121 the &aelig;gis of DANTE e.V. during 1992. The aims of the project are to perpetuate
122 and develop the spirit and philosophy of TeX, whilst respecting Knuth's
123 wish that TeX should remain frozen.
124
125 <P>The group were very concerned that unless there existed some evolutionary
126 flexibility within which TeX could react to changing needs and environments,
127 it might all too soon become eclipsed by more modern yet less sophisticated
128 systems. Accordingly they agreed to investigate a possible successor or
129 successors to TeX, successors which would enshrine and encapsulate all
130 that was best in TeX whilst being freed from the evolutionary constraints
131 which Knuth had placed on TeX itself. To avoid any suggestion that it was
132 TeX which the group sought to develop against Knuth's wishes, a working
133 title of <I>NTS</I> (for New Typesetting System) was chosen for the project.
134
135
136 <P>During the initial meetings of the <I>NTS</I> group, it became clear
137 that there were two possible approaches to developments based on TeX: an
138 evolutionary path which would simply continue where Knuth had left off,
139 and which would use as its basis the source code of TeX itself (i.e. <TT><A HREF="#TeX.Web">TeX.Web</A></TT>);
140 the other a revolutionary path which would be based on a completely new
141 implementation of TeX, using a modern rapid-prototyping language which
142 could allow individual components of the system to be modified or replaced
143 in a simple and straightforward manner. The group agreed that the latter
144 (revolutionary) approach had much greater potential, but were aware that
145 the re-implementation would be non-trivial, and would require external
146 funding to bring it to fruition in finite time; accordingly they agreed
147 to concentrate their initial efforts on the former (evolutionary) path,
148 and set to work to specify and implement a direct derivative of TeX which
149 became known as e-TeX (the <I>e</I> of e-TeX may be read as <I>extended</I>,
150 <I>enhanced</I>, <I>evolutionary</I> or <I>European</I> at will(!), and
151 is also an acknowledgement of the parallel developments which have lead
152 the LaTeX&nbsp;3 team to modify their initial goal and to release an interim
153 LaTeX, LaTeX2e, which is directly derived from the LaTeX sources.
154
155 <P>The group took as the starting point for the development of e-TeX the
156 many contributions which had been made on <TT><A HREF="#NTS-L">NTS-L</A></TT>
157 (the open mailing list on which discussions pertinent to e-TeX &amp; <I>NTS</I>
158 take place), together with the extremely interesting list of ideas which
159 Knuth gives at the end of <TT><A HREF="#TeX82.Bug">TeX82.Bug</A></TT>,
160 and which he describes as <I>`Possibly nice ideas that will not be implemented'</I>
161 (and which he contrasts with <I>`Bad ideas that will not be implemented'</I>!).
162 Individual members of the group also contributed ideas of their own which
163 had not necessarily been discussed publicly. All proposals were then subjected
164 to a rigorous vetting procedure to ensure that they conformed to the e-TeX
165 philosophy, which may be summarised as follows:
166
167 <BLOCKQUOTE>
168 <P>e-TeX will in all ways demonstrate its affinity to, and derivation from,
169 Knuth's TeX; it will be implemented as a change-file to <TT><A HREF="#TeX.Web">TeX.Web</A></TT>,
170 and will not exploit features which could only be achieved by using a particular
171 implementation, operating system or language; it will be capable of being
172 used successfully on a machine as small as an 80286-based PC or similar.
173
174
175 <P>At format-generation time, a user will have the option of generating
176 either a TeX-compatible format or an e-TeX format; if the TeX-compatible
177 format is subsequently used in conjunction with e-TeX, the result will
178 be <A NAME="TripCompatible"></A><I>Trip-compatible</I> (i.e. indistinguishable
179 from TeX proper). If an e-TeX format is generated and used in conjunction
180 with e-TeX, then provided that none of the new e-TeX primitives are used,
181 the results will be identical to those which would be produced using TeX
182 proper. If an e-TeX format is used in conjunction with e-TeX and if one
183 or more of the new e-TeX primitives are used, then those portions of the
184 document which are affected by the new primitive(s) may be processed in
185 a manner unique to e-TeX; other portions of the document will be processed
186 in a manner identical to that of TeX proper. Only if an e-TeX format is
187 used in conjunction with e-TeX and if an explicit assignment is made to
188 one of the <A NAME="EnhancedMode"></A><I>enhanced-mode</I> variables to
189 enable that particular enhanced mode will e-TeX behave in a manner which
190 may be distinguishable from that of TeX even if no other reference to an
191 e-TeX primitive occurs anywhere in the document. (These modes of operation
192 are referred to as <A NAME="CompatibilityMode"></A><I>compatibility-mode</I>,
193 <A NAME="ExtendedMode"></A><I>extended-mode</I> and <I>enhanced-mode</I>
194 respectively.)
195
196 <P>All new e-TeX primitives will be syntactically identical to existing
197 TeX primitives: that is, they will be either <I>control-words</I> or <I>control-symbols</I>
198 within a normal category code r&eacute;gime. Where an analogous primitive exists
199 within TeX, the corresponding e-TeX primitive(s) will occupy the same syntactic
200 niche. Every effort will be made to ensure that new e-TeX primitives fit
201 into the existing set of TeX datatypes; no new datatype will be introduced
202 unless it is absolutely essential.
203 </BLOCKQUOTE>
204
205 <P>In brief, this implies that e-TeX will follow the principle of least
206 surprise: an existing TeX user, on using e-TeX for the first time, should
207 not be surprised by e-TeX's behaviour, and should be able to take advantage
208 of new e-TeX features without having either to unlearn some aspects of
209 TeX or to learn some new e-TeX philosophy.
210
211 <P>
212 <HR><A NAME="Installation"></A>
213
214 <H1>2 Installation</H1>
215
216 <P>It is intended that e-TeX be available ready-compiled for those systems
217 for which pre-compiled binaries are the norm (e.g. MS-DOS, VMS, ...); for
218 other systems such as Unix(TM), e-TeX is supplied as a change-file which
219 will need to be applied to <TT><A HREF="#TeX.Web">TeX.Web</A></TT> in the
220 normal way. However, since there will already be an implementation-specific
221 change-file for the system of interest, some means will be required of
222 merging <TT><A HREF="#TeX.Web">TeX.Web</A></TT> with not one but (at least)
223 two change-files; possibilities include <I><A HREF="#PatchWeb">PatchWeb</A></I>,
224 <I><A HREF="#Tie">Tie</A></I>, etc., but if none of these are available
225 then <I><A HREF="#WebMerge">WebMerge</A></I>, a TeX script, is supplied
226 and can be used as a slower but satisfactory alternative. In practice,
227 two or three change-files will be needed: the e-TeX system-independent
228 change-file, the TeX system-dependent change-file, and perhaps a small
229 e-TeX system-dependent change-file. The system-independent e-TeX change-file
230 is supplied as part of the e-TeX kit, and sample system-dependent e-TeX
231 change-files are also supplied which may be used as a guide to those places
232 at which system-dependent interactions are to be expected: an experienced
233 implementor should have little difficulty in modifying one of these to
234 produce an e-TeX system-dependent change-file for the system of interest.
235 Once e-TeX has been tangled and woven, it should be compiled and linked
236 in the normal way.
237
238 <P>Once a working binary (or binaries, for those systems which have separate
239 executables for <TT>IniTeX</TT> and <TT>VirTeX</TT>) has been acquired
240 or produced, the next step will be to generate a suitable format file or
241 files. Whilst e-TeX can be used in conjunction with <TT><A
242 HREF="src/plain.tex">Plain.TeX</A></TT> to produce a Plain <I>e-format</I>,
243 it is better to use the supplied <TT><A HREF="#etex.src">etex.src</A></TT> file
244 which supplements the e-TeX primitives with additional useful control
245 sequences.
246
247 <P>When generating the format file, and regardless of the format source
248 used, one fundamental decision must be made: is e-TeX to generate a <I><A HREF="#CompatibilityMode">compatibility
249 mode</A></I> format, or an <I><A HREF="#ExtendedMode">extended mode</A></I>
250 format? If the former, <I>all</I> e-TeX <A NAME="extension"></A>extensions
251 and <A NAME="enhancement"></A>enhancements will be disabled, the format
252 will contain only the TeX-defined set of primitives, and any subsequent
253 use of the format in conjunction with e-TeX will result in completely TeX-compatible
254 behaviour and semantics, including compatibility at the level of the <A HREF="#Trip">Trip</A>
255 test. If the latter option, however, is selected, then all extensions present
256 in e-TeX will automatically be activated, and the format file will contain
257 not only the TeX-defined set of primitives but also those defined by e-TeX
258 itself; any subsequent use of such a format in conjunction with e-TeX will
259 result in e-TeX operating in <I><A HREF="#ExtendedMode">extended mode</A></I>;
260 documents which contains no references to any of the e-TeX-defined primitives
261 will continue to generate results identical to those which would have been
262 produced were the document processed by TeX, but compatibility at the <A HREF="#Trip">Trip</A>-test
263 level can no longer be accomplished, and of course any document which makes
264 reference to an e-TeX primitive will generate results which could not have
265 been accomplished using TeX. It should be noted that neither a <I><A HREF="#CompatibilityMode">compatibility
266 mode</A></I> format nor an <I><A HREF="#ExtendedMode">extended mode</A></I>
267 format may be used in conjunction with TeX itself; they are only suitable
268 for use in conjunction with e-TeX, since formats are not in general portable.
269 Finally it should be emphasised that even if an <I><A HREF="#ExtendedMode">extended
270 mode</A></I> format is generated, any document processed using such a format
271 but not referencing any e-TeX-defined primitive will produce results identical
272 to those which would have been produced had the same document been processed
273 using TeX; only if the document makes an explicit assignment to one of
274 the <I><A HREF="#EnhancedMode">enhanced mode</A></I> state variables (<TT><A
275 HREF="#TeXXeTstate">\TeXXeTstate</A></TT> is the only instance of these in V1
276 of e-TeX) will compatibility with TeX be compromised: e-TeX is then said to be
277 operating in <I><A HREF="#EnhancedMode">enhanced mode</A></I> rather than <I><A
278 HREF="#ExtendedMode">extended mode</A></I>.
279
280
281 <P>The choice between generating a <I><A HREF="#CompatibilityMode">compatibility
282 mode</A></I> format and an <I><A HREF="#ExtendedMode">extended mode</A></I>
283 format is made at the point of specifying the format source file: assuming
284 that the operating system supports command-line entry with parameters,
285 then a normal TeX format-generation command would probably resemble:
286
287 <PRE> initex plain \dump
288 </PRE>
289
290 <P>or if the more verbose interactive form is preferred:
291
292 <PRE> initex
293 **plain
294 *\dump
295 </PRE>
296
297 <P>With e-TeX, exactly the same command will achieve exactly the same effect,
298 and the format generated will be a <I><A HREF="#CompatibilityMode">compatibility-mode</A></I>
299 format; thus assuming that the Ini-version of e-TeX is invoked with the
300 command <TT>einitex</TT>, the following will both generate <I><A HREF="#CompatibilityMode">compatibility-mode</A></I>
301 formats:
302
303 <PRE> einitex plain \dump
304 </PRE>
305
306 <P>and
307
308 <PRE> einitex
309 **plain
310 *\dump
311 </PRE>
312
313 <P>In order to generate an <I><A HREF="#ExtendedMode">extended mode</A></I>
314 format, the file-specification for the format source file must be preceded
315 by an asterisk (<TT>*</TT>); whilst this may seem an inelegant mechanism,
316 it has the great advantage that it avoids almost all system dependencies
317 (Graphical user interface (GUI) systems excepted, of course), and the asterisk
318 as a component element of a filename is a very remote possibility (most
319 filing systems reserve the asterisk as a `wild card' character, which can
320 therefore not form a part of a real file name <I>per se</I>). Thus to generate
321 an <I><A HREF="#ExtendedMode">extended mode</A></I> Plain format, the following
322 dialogue may be used:
323
324 <PRE> einitex *plain \dump
325 </PRE>
326
327 <P>or
328
329 <PRE> einitex
330 ***plain
331 *\dump
332 </PRE>
333
334 <P>and to generate an <I><A HREF="#ExtendedMode">extended mode</A></I>
335 <TT>etex.src</TT> format, the following instead:
336
337 <PRE> einitex *etex.src \dump
338 </PRE>
339
340 <P>or
341
342 <PRE> einitex
343 ***etex.src
344 *\dump
345 </PRE>
346
347 <P>Once suitable formats have been generated, they can then be used in
348 conjunction both with <I>e-IniTeX</I> and <I>e-VirTeX</I> without further
349 formality: in particular, no asterisk is needed (nor should be used!) if
350 a format is specified, since the format implicitly defines (depending as
351 its mode of generation) in which mode (compatibilty or extended) e-TeX
352 will operate. Thus, for example, if a <TT>plain</TT> format had been generated
353 in <I><A HREF="#CompatibilityMode">compatibility mode</A></I>, and an <TT>etex</TT>
354 format had been generated in <I><A HREF="#ExtendedMode">extended mode</A></I>,
355 then both:
356
357 <pRE> einitex &amp;Plain
358 </PRE>
359
360 <P>and
361
362 <pRE> evirtex &amp;plain
363 </PRE>
364
365 <P>will cause e-TeX to process any subsequent commands in <I><A HREF="#CompatibilityMode">compatibility
366 mode</A></I>. On the other hand, both
367
368 <PRE> einitex &amp;etex
369 </PRE>
370
371 <P>and
372
373 <PRE> eVirTeX &amp;etex
374 </PRE>
375
376 <P>will cause e-TeX to process any subsequent commands in <I><A HREF="#ExtendedMode">extended
377 mode</A></I>, <B>but only because the <TT>etex</TT> format was generated
378 in <I><A HREF="#ExtendedMode">extended mode</A></I></B>: it is not the
379 <B>name</B> of the format, nor is it the contents of the <B>source</B>
380 of the format, which determine the mode of operation -- it is the <B>mode
381 of operation</B> which was used when the format was generated. Any format
382 generated in <I><A HREF="#CompatibilityMode">compatibility mode</A></I>
383 will cause e-TeX to operate in <I><A HREF="#CompatibilityMode">compatibility
384 mode</A></I> whenever it is used, whilst the equivalent format, built from
385 the same source but generated in <I><A HREF="#ExtendedMode">extended mode,</A></I>
386 will cause e-TeX to operate in <I><A HREF="#ExtendedMode">extended mode</A></I>
387 whenever it is used.
388
389 <P>Although e-TeX is completely TeX-compatible, and there is therefore
390 no real reason why any system should need both TeX and e-TeX, it is anticipated
391 that until complete confidence exists in the compatibility of e-TeX many
392 sites and users will prefer to retain instances of each. For this reason
393 it is intended that change-files and binaries should ensure that both TeX
394 and e-TeX can happily co-exist on any system by a careful choice of name-spaces.
395 In the case of the reference VMS&nbsp;implementation, for example, this
396 is accomplished by using the prefix &quot;etex_&quot; for each logical
397 name which defines the e-TeX environment, in contrast to the prefix &quot;tex_&quot;
398 which defines the analogous TeX environment; the &quot;etex_*&quot; logical
399 names are defined as search lists which first reference an e-TeX specific
400 location followed by the analogous location for TeX.
401
402 <P>
403 <HR><A NAME="NewFeatures"></A>
404
405 <H1>3 The new features</H1>
406
407 <P>Bearing in mind the contraints outlined in the introduction, the group
408 identified 35 new primitives which they believed would give
409 added functionality to e-TeX without compromising its compatibility with
410 TeX; of the 35 new primitives, 29 are extensions (which by definition
411 do not affect the semantics of existing TeX documents), whilst just six
412 (all concerned with the implementation of <A HREF="#TeX--XeT">TeX--XeT</A>)
413 are associated with an enhancement. In addition to the new primitives,
414 additional functionality was added to some existing primitives, and TeX's
415 behaviour in some unusual boundary conditions was made more robust (this
416 last has been subsumed in the most recent version of TeX, so this is no
417 longer e-TeX-specific).
418
419 <P>The new features are listed and briefly described below, clustered together
420 to indicate related functionality.
421 The technical terms used below to
422 describe syntax entities as defined in <I><TT><A
423 HREF="knuth/texbook.tex">The
424 TeXbook.</A></TT></I>
425
426 <H2>3.1 Additional control over expansion</H2>
427
428 <UL>
429 <LI><TT><A HREF="#protected">\protected</A></TT> </LI>
430
431 <LI><TT><A HREF="#detokenize">\detokenize</A></TT> </LI>
432
433 <LI><TT><A HREF="#unexpanded">\unexpanded</A></TT> </LI>
434 </UL>
435
436 <DL>
437 <DT><A NAME="protected"></A><TT>\protected</TT> </DT>
438
439 <DD>is a prefix, analogous to <TT>\long</TT>, <TT>\outer</TT>, and <TT>\global</TT>;
440 it associates with the macro being defined an attribute which inhibits
441 expansion of the macro in expansion-only contexts (for example, within
442 the parameter text of a <TT>\write</TT> or <TT>\edef</TT>); if, however,
443 the parser or command processor (TeX's `oesophagus' and `stomach', in
444 Knuth's alimentary paradigm) is currently demanding a <I>command</I>, then
445 the <TT>\protected</TT> macro will expand in the normal way. This behaviour
446 is identical to that displayed by the explicit expansion of a token-list
447 register through the use of <TT>\the</TT>; the same model is used elsewhere
448 in e-TeX to achieve a consistent paradigm for <I>partial expansion</I>.
449 </DD>
450
451 <DT><A NAME="detokenize"></A><TT>\detokenize</TT>, </DT>
452
453 <DD>when followed by a <I>&lt;general text&gt;</I>, expands to yield a
454 sequence of character tokens of <TT>\catcode</TT> 10 (<I>space</I>) or
455 12 (<I>other</I>) corresponding to a decomposition of the tokens of the
456 <I>&lt;balanced text&gt;</I> of the unexpanded <I>&lt;general text&gt;&gt;</I>;
457 c.f. <TT>\showtokens</TT>. The effect is rather as if <TT><A HREF="#scantokens">\scantokens</A></TT>
458 (q.v.) were applied to the <I>&lt;general text&gt;</I> within a r&eacute;gime
459 in which only <TT>\catcodes</TT> 10 and 12 existed. Note that in order
460 to preserve the boundaries between <I>control words</I> and any following
461 <I>letter</I>, a <I>space</I> is yielded after each control word including
462 the last. </DD>
463
464 <DT><A NAME="unexpanded"></A><TT>\unexpanded</TT>, </DT>
465
466 <DD>when followed by a <I>&lt;general text&gt;</I>, expands to yield the
467 <I>&lt;balanced text&gt;</I> of the unexpanded <I>&lt;general text&gt;</I>.
468 No further expansion will occur if e-TeX is currently performing a <TT>\write</TT>,
469 <TT>\edef</TT>, etc., but further expansion will occur if the parser or
470 command processor is currently demanding a <I>command</I>. The effect is
471 as if the <I>&lt;general text&gt;</I> were assigned to a token list register,
472 and the latter were then partially expanded using <TT>\the</TT>, but no
473 assignment actually takes place; thus <TT>\unexpanded</TT> can be used
474 in expansion-only contexts. </DD>
475 </DL>
476
477 <H2>3.2 Provision for re-scanning already read text</H2>
478
479 <UL>
480 <LI><TT><A HREF="#readline">\readline</A></TT> </LI>
481
482 <LI><TT><A HREF="#scantokens">\scantokens</A></TT> </LI>
483 </UL>
484
485 <DL>
486 <DT><A NAME="readline"></A><TT>\readline</TT> </DT>
487
488 <DD>is analogous to <TT>\read</TT>, but treats each character as if it
489 were currently of <TT>\catcode</TT> 10 (<I>space</I>) or 12 (<I>other</I>);
490 the text thus read is therefore suitable for being scanned and re-scanned
491 (using <TT><A HREF="#scantokens">\scantokens</A></TT>, q.v.) under different
492 <TT>\catcode</TT> r&eacute;gimes. </DD>
493
494 <DT><A NAME="scantokens"></A><TT>\scantokens</TT>, </DT>
495
496 <DD>when followed by a <I>&lt;general text&gt;</I>, decomposes the <I>&lt;balanced
497 text&gt;</I> of the <I>&lt;general text&gt;</I> into the corresponding
498 sequence of characters as if the <I>&lt;balanced text&gt;</I> were written
499 unexpanded to a file; it then uses TeX's <TT>\input</TT> mechanism to re-process
500 these characters under the current <TT>\catcode</TT> r&eacute;gime. As the <TT>\input</TT>
501 mechanism is used, even hex notation (<TT>^^xy</TT>) will be re-interpreted.
502 Parentheses and a single space representing the <I>pseudo-file</I> will
503 be displayed if <TT><A HREF="#tracingscantokens">\tracingscantokens</A></TT>
504 (q.v.) is positive and non-zero. </DD>
505 </DL>
506
507 <H2>3.3 Environmental enquiries</H2>
508
509 <UL>
510 <LI><TT><A HREF="#eTeXrevision">\eTeXrevision</A></TT> </LI>
511
512 <LI><TT><A HREF="#eTeXversion">\eTeXversion</A></TT> </LI>
513
514 <LI><TT><A HREF="#currentgrouplevel">\currentgrouplevel</A></TT> </LI>
515
516 <LI><TT><A HREF="#currentgrouptype">\currentgrouptype</A></TT> </LI>
517
518 <LI><TT><A HREF="#ifcsname">\ifcsname</A></TT> </LI>
519
520 <LI><TT><A HREF="#ifdefined">\ifdefined</A></TT> </LI>
521
522 <LI><TT><A HREF="#lastnodetype">\lastnodetype</A></TT> </LI>
523 </UL>
524
525 <DL>
526 <DT><A NAME="eTeXrevision"></A><TT>\eTeXrevision</TT>: </DT>
527
528 <DD>an primitive which expands to yield a sequence of character tokens
529 of <TT>\catcode</TT> 12 (<I>other</I>; these represent the minor component
530 of the combined version/revision number. Pre-release versions will be characterised
531 by an initial <I>minus</I> sign (<TT>-</TT>), whilst post-release versions
532 will be implicitly positive; both will contain an explicit leading decimal
533 point, which will follow any minus sign present. </DD>
534
535 <DT><A NAME="eTeXversion"></A><TT>\eTeXversion</TT>: </DT>
536
537 <DD>an internal read-only integer representing the major component of the
538 combined version/revision number. </DD>
539
540 <DT><A NAME="currentgrouplevel"></A><TT>\currentgrouplevel</TT>: </DT>
541
542 <DD>an internal read-only integer which returns the current group level
543 (i.e. depth of nesting). </DD>
544
545 <DT><A NAME="currentgrouptype"></A><TT>\currentgrouptype</TT>: </DT>
546
547 <DD>an internal read-only integer which returns the type of the innermost
548 group as an integer in the range 0..16. Textual definitions of these types
549 may be provided through an associated macro library, but it is intended
550 that these definitions shall be easily replaceable by national language
551 versions in environments within which English language texts are sub-optimal.
552 </DD>
553
554 <DT><A NAME="ifcsname"></A><TT>\ifcsname</TT>: </DT>
555
556 <DD>similar in effect to the sequence <TT>\unless</TT> <TT>\expandafter</TT>
557 <TT>\ifx</TT> <TT>\expandafter</TT> <TT>\relax</TT> <TT>\csname</TT> but
558 avoids the side-effect of the <I>cs-name</I> being ascribed the value <TT>\relax</TT>,
559 and also does not rely on <TT>\relax</TT> having its canonical meaning.
560 No hash-table entry is used if <I>cs-name</I> does not exist. (<TT><A HREF="#unless">\unless</A></TT>
561 is explained below.) </DD>
562
563 <DT><A NAME="ifdefined"></A><TT>\ifdefined</TT>: </DT>
564
565 <DD>similar in effect to <TT><A HREF="#unless">\unless</A></TT> <TT>\ifx</TT>
566 <TT>\undefined</TT>, but does not require <TT>\undefined</TT> to actually
567 be undefined, since no explicit comparison is made with any particular
568 control sequence. </DD>
569
570 <DT><A NAME="lastnodetype"></A><TT>\lastnodetype</TT>: </DT>
571
572 <DD>an internal read-only integer which returns the type of the last node
573 on the current list as an integer in the range -1..15+ (only values -1..15
574 are defined in the first release, but future releases may define additional
575 values). Textual definitions of these types may be provided through an
576 associated macro library. </DD>
577 </DL>
578
579 <H2>3.4 Generalisation of the <TT>\mark</TT> concept: a class of <TT>\marks</TT></H2>
580
581 <UL>
582 <LI><TT><A HREF="#marks">\marks</A></TT> </LI>
583
584 <LI><TT><A HREF="#botmarks">\botmarks</A></TT> </LI>
585
586 <LI><TT><A HREF="#firstmarks">\firstmarks</A></TT> </LI>
587
588 <LI><TT><A HREF="#topmarks">\topmarks</A></TT> </LI>
589
590 <LI><TT><A HREF="#splitfirstmarks">\splitfirstmarks</A></TT> </LI>
591
592 <LI><TT><A HREF="#splitbotmarks">\splitbotmarks</A></TT> </LI>
593 </UL>
594
595 <DL>
596 <DT><A NAME="marks"></A><TT>\marks</TT>: </DT>
597
598 <DD>this is one of Knuth's `possibly good ideas', listed at the end of <TT><A
599 HREF="#TeX82.Bug">TeX82.Bug</A></TT>; whereas TeX has only one <TT>\mark</TT>,
600 which has to be over-loaded if more than one class of information is to be
601 saved (e.g. over-loading is necessary if separate information for recto and
602 verso pages is to be maintained), e-TeX has a whole class of <TT>\marks</TT>
603 (256, in the first release); thus rather than writing <TT>\mark</TT>
604 <I>&lt;general text&gt;</I> as in TeX, in e-TeX one writes <TT>\marks</TT>
605 <I>8-bit number</I> <I>&lt;general text&gt;</I>. For example,
606 <TT>\marks&nbsp;0</TT> could be used to retain information for the verso page,
607 whilst <TT>\marks 1</TT> could retain information for the recto. There are
608 equivalent classes for the five <TT>\marks</TT> variables <A
609 NAME="botmarks"></A><TT>\botmarks</TT>, <A
610 NAME="firstmarks"></A><TT>\firstmarks</TT>, <A
611 NAME="topmarks"></A><TT>\topmarks</TT>, <A
612 NAME="splitfirstmarks"></A><TT>\splitfirstmarks</TT> and <A
613 NAME="splitbotmarks"></A><TT>\splitbotmarks</TT>. It should be noted that
614 <TT>\marks&nbsp;0</TT> and <TT>\mark</TT> are in fact identical, as are
615 <TT>\topmarks&nbsp;0</TT> and \<TT>topmark</TT>, \<TT>botmarks&nbsp;0</TT> and
616 <TT>\botmark</TT> and so on.</DD>
617 </DL>
618
619 <H2>3.5 Bi-directional typesetting: the <A HREF="#TeX--XeT">TeX--XeT</A>
620 primitives</H2>
621
622 <UL>
623 <LI><TT><A HREF="#TeXXeTstate">\TeXXeTstate</A></TT> </LI>
624
625 <LI><TT><A HREF="#beginL">\beginL</A></TT> </LI>
626
627 <LI><TT><A HREF="#beginR">\beginR</A></TT> </LI>
628
629 <LI><TT><A HREF="#endL">\endL</A></TT> </LI>
630
631 <LI><TT><A HREF="#endR">\endR</A></TT> </LI>
632
633 <LI><TT><A HREF="#predisplaydirection">\predisplaydirection</A></TT> </LI>
634 </UL>
635
636 <P><A HREF="#TeX--XeT">TeX--XeT</A> was developed by Peter Breitenlohner
637 based on the original <!--A HREF="TeX-XeT-TODO"-->TeX-XeT<!--/A--> of Donald Knuth
638 and Pierre MacKay; whereas <!--A HREF="#TeX-XeT"-->TeX-XeT<!--/A--> generated non-standard
639 <I>DVI</I> files, <A HREF="#TeX--XeT">TeX--XeT</A> generates perfectly
640 normal <I>DVI</I> files which can therefore be processed by standard <I>DVI</I>
641 drivers (assuming, of course, that the necessary fonts are available).
642 Both systems permit the direction of typesetting (conventionally left-to-right
643 in Western documents) to be reversed for part or all of a document, which
644 is particularly useful when setting languages such as Hebrew or Arabic.
645
646
647 <DL>
648 <DT><A NAME="beginL"></A><TT>\beginL</TT>: </DT>
649
650 <DD>indicates the start of a region (e.g. a section of text, or a pre-constructed
651 <I>box</I>) which should be set left-to-right; </DD>
652
653 <DT><A NAME="beginR"></A><TT>\beginR</TT>: </DT>
654
655 <DD>indicates the start of a region which should be set right-to-left;
656 </DD>
657
658 <DT><A NAME="endL"></A><TT>\endL</TT>: </DT>
659
660 <DD>indicates the end of a region which should be set left-to-right; </DD>
661
662 <DT><A NAME="endR"></A><TT>\endR</TT>: </DT>
663
664 <DD>indicates the end of a region which should be set right-to-left; </DD>
665
666 <DT><A NAME="TeXXeTstate"></A><TT>\TeXXeTstate</TT>: </DT>
667
668 <DD>an internal read/write integer, its value is zero or negative to indicate
669 that <A HREF="#TeX--XeT">TeX--XeT</A> features are not to be used; a positive
670 value indicates that they may be used. As the internal data structures
671 built by <A HREF="#TeX--XeT">TeX--XeT</A> differ from those built by TeX,
672 and as the typesetting of a document by <A HREF="#TeX--XeT">TeX--XeT</A>
673 may therefore differ from that performed by TeX, <TT>\TeXXeTstate</TT>
674 defaults to zero, and even if set positive during format creation will
675 be re-set to zero before the format is dumped. Explicit user action therefore
676 is required to enable <A HREF="#TeX--XeT">TeX--XeT</A> semantics, and <A HREF="#TeX--XeT">TeX--XeT</A>
677 is therefore classed as an <I><A HREF="#enhancement">enhancement</A></I>,
678 not simply an <I><A HREF="#extension">extension</A></I>. </DD>
679
680 <DT><A NAME="predisplaydirection"></A><TT>\predisplaydirection</TT>: </DT>
681
682 <DD>an internal read/write integer, initialised by e-TeX to indicate the
683 direction of the last partial paragraph before a display; it is used to
684 control the placement of elements such as equation numbers, and can be
685 explictly set to affect this placement. </DD>
686 </DL>
687
688 <H2>3.6 Additional debugging features</H2>
689
690 <UL>
691 <LI><TT><A HREF="#interactionmode">\interactionmode</A></TT> </LI>
692
693 <LI><TT><A HREF="#showgroups">\showgroups</A></TT> </LI>
694
695 <LI><TT><A HREF="#showtokens">\showtokens</A></TT> </LI>
696
697 <LI><TT><A HREF="#tracingassigns">\tracingassigns</A></TT> </LI>
698
699 <LI><TT><A HREF="#tracinggroups">\tracinggroups</A></TT> </LI>
700
701 <LI><TT><A HREF="#tracingifs">\tracingifs</A></TT> </LI>
702
703 <LI><TT><A HREF="#tracingscantokens">\tracingscantokens</A></TT> </LI>
704
705 <LI><A HREF="#AdditionalTracingInformation">Additional detail for <TT>\tracingcommands</TT></A>
706 </LI>
707 </UL>
708
709 <DL>
710 <DT><A NAME="interactionmode"></A><TT>\interactionmode</TT>: </DT>
711
712 <DD>whereas in TeX there exist only explicit commands such as <TT>\scrollmode</TT>,
713 <TT>\errorstopmode</TT>, etc., in e-TeX read/write access is provided via
714 <TT>\interactionmode</TT> (an internal integer); assigning a numeric value
715 sets the associated mode, whilst the current mode may be ascertained by
716 interrogating its value. Symbolic definitions of these values may be provided
717 through an associated macro library. </DD>
718
719 <DT><A NAME="showgroups"></A><TT>\showgroups</TT>: </DT>
720
721 <DD><I>(e-)TeX</I> has many different classes of <I>group</I>, which should
722 normally be properly balanced and nested; if a nesting or imbalance error
723 occurs, it can be <I>very</I> difficult to track down the source of the
724 problem. <TT>\showgroups</TT> causes e-TeX to display the level and type
725 of all active groups from the point within which it was called. </DD>
726
727 <DT><A NAME="showtokens"></A><TT>\showtokens</TT>, </DT>
728
729 <DD>when followed by a <I>&lt;general text&gt;</I>, displays a sequence
730 of characters corresponding to the decomposition of the <I>&lt;balanced
731 text&gt;</I> of the unexpanded <I>&lt;general text&gt;</I>; c.f. <TT><A HREF="#detokenize">\detokenize</A></TT>.
732 </DD>
733
734 <DT><A NAME="tracingassigns"></A><TT>\tracingassigns</TT>: </DT>
735
736 <DD><TT>\tracingassigns</TT>
737 (an internal read/write integer) causes e-TeX to display the
738 contents of registers <em>before</em> an assignment, as well
739 as after the assignment,
740 while set to a positive non-zero value. In standard TeX,
741 only the value <em>after</em> the assignment can be displayed
742 during a trace.
743 </DD>
744
745 <DT><A NAME="tracinggroups"></A><TT>\tracinggroups</TT>: </DT>
746
747 <DD>a further aid to debugging runaway-group problems, <TT>\tracinggroups</TT>
748 (an internal read/write integer) causes e-TeX to trace entry and exit to
749 every group while set to a positive non-zero value. </DD>
750
751 <DT><A NAME="tracingifs"></A><TT>\tracingifs</TT>: </DT>
752
753 <DD> <tt>\tracingifs</tt> is an aid to debugging the expansion of conditionals.
754 If it is set to a positive non-zero value, e-TeX traces the flow of
755 control through conditional statements.</DD>
756
757 <DT><A NAME="tracingscantokens"></A><TT>\tracingscantokens</TT>: </DT>
758
759 <DD>an internal read/write integer, assigning it a positive non-zero value
760 will cause an open-parenthesis and space to be displayed whenever <TT><A HREF="#scantokens">\scantokens</A></TT>
761 is invoked; the matching close-parenthesis will be recorded when the scan
762 is complete. If a traceback occurs during the expansion of <TT><A HREF="#scantokens">\scantokens</A></TT>,
763 the first displayed line number will reflect the logical line number of
764 the pseudo-file created from the parameter to <TT><A HREF="#scantokens">\scantokens</A></TT>;
765 thus enabling <TT>\tracingscantokens</TT> can assist in identifying why
766 an seemingly irrational line number is shewn as the source of error (the
767 traceback always continues until the line number of the actual source file
768 is displayed). </DD>
769
770 <DT><A NAME="AdditionalTracingInformation"></A>Additional tracing information:
771 </DT>
772
773 <DD>If <TT>\tracingcommands</TT> is greater than 2, additional information
774 is displayed (the maximum value defined in standard TeX is 2). </DD>
775 </DL>
776
777 <H2>3.7 Miscellaneous primitives</H2>
778
779 <UL>
780 <LI><TT><A HREF="#everyeof">\everyeof</A></TT> </LI>
781
782 <LI><TT><A HREF="#middle">\middle</A></TT> </LI>
783
784 <LI><TT><A HREF="#unless">\unless</A></TT> </LI>
785 </UL>
786
787 <DL>
788 <DT><A NAME="everyeof"></A><TT>\everyeof</TT>: </DT>
789
790 <DD>this is another of Knuth's `possibly good ideas', listed at the end of
791 <TT><A HREF="#TeX82.Bug">TeX82.Bug</A></TT>; analogous to the other
792 <TT>\every...</TT> primitives, it takes as parameter a <I>&lt;balanced
793 text&gt;</I>, the tokens of which are inserted when the end of a file (either
794 real or virtual, if <TT><A HREF="#scantokens">\scantokens</A></TT> is used) is
795 reached. This allows <TT>\input</TT> statements to be used within the
796 replacement text of <TT>\edef</TT>s, and allows totally arbitrary files to be
797 <TT>\input</TT> within an e-TeX conditional, since the necessary <TT>\fi</TT>
798 can be inserted before e-TeX complains that it has fallen off the end of the
799 file. It should be noted that the <code>\everyeof</code> tokens are <em>not</em>
800 inserted if the end-of-file is forced through the use of <code>\endinput</code>.
801 </DD>
802
803 <DT><A NAME="middle"></A><TT>\middle</TT>: </DT>
804
805 <DD>analogous to TeX's <TT>\left</TT> and <TT>\right</TT>, <TT>\middle</TT>
806 specifies that the following delimiter is to serve both as a right and
807 left delimiter; it will be set with spacing appropriate to a right delimiter
808 w.r.t. the preceding atom(s), and with spacing appropriate to a left delimiter
809 w.r.t. the succeeding atom(s). A particularly nice
810 <a href="http://vzdmzi.zdv.uni-mainz.de/~knappen/jk006.html">example</a>
811 of its use
812 has kindly been provided by
813 <a href="mailto:[email protected]">J&ouml;rg Knappen</a></DD>
814
815 <DT><A NAME="unless"></A><TT>\unless</TT>: </DT>
816
817 <DD>TeX has, by design, a rather sparse set of conditional primitives:
818 <TT>\ifeof</TT>, <TT>\ifodd</TT>, <TT>\ifvoid</TT>, etc., have no complementary
819 counterparts. Whilst this normally poses no problems since each accepts
820 both a <TT>\then</TT> (implicit) and an <TT>\else</TT> (explicit) part,
821 they fall down when used as the final <TT>\if...</TT> of a <TT>\loop ...
822 \if ... \repeat</TT> construct, since no <TT>\else</TT> is allowed after
823 the final <TT>\if...</TT>. <TT>\unless</TT> allows the sense of all Boolean
824 conditionals to be inverted, and thus (for example) <TT>\unless</TT>
825 <TT>\ifeof</TT> yields <I>true</I> iff end-of-file has <I>not</I> yet been
826 reached.
827 <a href="mailto:[email protected]"">David Kastrup</a> has
828 correctly pointed out that a similar effect can be achieved by macro
829 programming, but the solution is not sufficiently general to allow it to be
830 used unchanged in all contexts in which the new <tt>\unless</tt> primitive can
831 be used.</DD>
832 </DL>
833
834 <HR>
835
836 <H2>References:</H2>
837
838 <DL>
839 <DT><A NAME="TeX.Web"></A><B><TT>TeX.Web</TT></B> </DT>
840
841 <DD>CTAN: <A HREF="ftp://ftp.dante.de/tex-archive/systems/knuth/tex/tex.web">tex-archive/systems/knuth/tex/tex.web</A>
842 </DD>
843
844 <DT><A NAME="TeX82.Bug"></A><B><TT>TeX82.Bug</TT></B> </DT>
845
846 <DD>CTAN: <A HREF="ftp://ftp.dante.de/tex-archive/systems/knuth/errata/tex82.bug">tex-archive/systems/knuth/errata/tex82.bug</A>
847 </DD>
848
849 <DT><A NAME="Trip"></A><B><TT>Trip</TT> test</B> </DT>
850
851 <DD>CTAN: <A HREF="ftp://ftp.dante.de/tex-archive/systems/knuth/tex/tripman.tex">tex-archive/systems/knuth/tex/tripman.tex</A>
852 </DD>
853
854 <DT><A NAME="Plain.TeX"></A><B><TT>Plain.TeX</TT></B> </DT>
855
856 <DD>CTAN: <A HREF="ftp://ftp.dante.de/tex-archive/systems/knuth/lib/plain.tex">tex-archive/systems/knuth/lib/plain.tex</A>
857 </DD>
858
859 <DT><A NAME="TeX--XeT"></A><B>TeX--XeT</B> </DT>
860
861 <DD>CTAN: <A HREF="ftp://ftp.dante.de/tex-archive/systems/knuth/tex--xet/">tex-archive/systems/knuth/tex--xet</A>
862 </DD>
863
864 <dt><a name="etex.src"></a><b><tt>etex.src</tt></b></dt>
865
866 <dd><a href="src/etex.src">etex.src</a></dd>
867
868 <DT><A NAME="NTS-L"></A><B>Discussion List <TT>NTS-L</TT></B> </DT>
869
870 <DD>Subscribe with e-mail to the Listserver program
871 <A HREF="mailto:[email protected]">
872 [email protected]</A>
873 </DD>
874
875 <DT><A NAME="Tie"></A><B>Tie</B> (written in C) </DT>
876
877 <DD>CTAN: <A HREF="ftp://ftp.tex.ac.uk/tex-archive/web/tie/">tex-archive/web/tie</A>
878 </DD>
879
880 <DT><A NAME="WebMerge"></A><B>WebMerge</B> (written in TeX) </DT>
881
882 <DD><a href="webmerge.tex">webmerge.tex</a></DD>
883
884 <DT><A NAME="PatchWeb"></A><B>PatchWeb</B> (for PC, bundled with "dos-tp") </DT>
885
886 <DD>CTAN: <A HREF="ftp://ftp.dante.de/tex-archive/systems/msdos/dos-tp/">tex-archive/systems/msdos/dos-tp/</A>
887 </DD>
888 </DL>
889
890 <P>
891 <HR>
892
893 <ADDRESS>The NTS team</ADDRESS>
894
895 <hr>
896 Put on the WWW by Bernd Raichle, member of the NTS group;<br>
897 subsequently updated by Philip Taylor,
898 with corrections by Peter Breitenlohner.<br>
899 last updated: 30-JUL-1997 19:31:47 (PT)<br>
900 <FORM METHOD="POST" ACTION="http://www.webtechs.com/cgi-bin/html-check.pl">
901 <INPUT NAME="recommended" VALUE="0" TYPE="hidden">
902 <INPUT NAME="level" VALUE="Wilbur" TYPE="hidden">
903 <INPUT NAME="input" VALUE="0" TYPE="hidden">
904 <INPUT NAME="esis" VALUE="0" TYPE="hidden">
905 <INPUT NAME="render" VALUE="0" TYPE="hidden">
906 <a href="http://ugweb.cs.ualberta.ca/~gerald/validate
907 /?url=http://www.rhbnc.ac.uk/e-TeX/etex_ref.html">
908 <img src="/www/logos/invalid_html3_2.gif" alt="HTML 3.2 Checked!">
909 </a>
910 <INPUT NAME="URLs"
911 VALUE="http://www.rhbnc.ac.uk/e-TeX/etex_ref.html"
912 TYPE="hidden"
913 >
914 <INPUT TYPE="image" SRC="/www/logos/invalid_html_wilbur.gif">
915 </FORM>
916 </BODY>
917 </HTML>