The "etex.src" file and its adjuncts: V2.0

# The e-TEX format source file `"etex.src" (V2.0)`

The primary e-TeX format source file, `"etex.src"`, is in principle merely a wrapper for `"plain.tex"`, providing modified definitions for some Plain TeX commands (at present, just one: `\tracingall`), improving and generalising the register allocation mechanism, and adding new commands

In so doing, we have taken the opportunity to (a) provide intrinsic support for multiple-language typesetting (by deferring the processing of patterns and exceptions until a rudimentary language-handling environment has been defined), (b) provide a local as well as a global register allocation mechanism, (c) provide for the allocation of blocks of registers as well as single registers, (d) provide a means of allocating and accessing vectors (monodimensional arrays) of registers, and finally (e) provide a simple but effective module-handling system, to allow e-TeX ancilliary source files to be structured as libraries rather than as flat linear text files.

As the new commands and other features are not documented elsewhere, a brief explanation of their syntax and semantics is provided here.

`\tracingall`
  The definition is augmented to enable tracing for the new e-TeX tracing primitives `\tracingassigns`, `\tracinggroups`, `\tracingifs`, `\tracingnesting` and `\tracingscantokens`; the numeric value assigned to the TeX primitives `\tracingcommands` and `\tracinglostchars` is increased as e-TeX will report additional detail in these circumstances.

`\eTeX`
  A simple implementation of the e-TeX logo; a more sophisticated version, capable of being used in maths sub/superscripts for example, may find its way into `etexdefs.lib` in due course.

`\loggingall`
  This command is equivalent to the sequence `\tracingall` `\tracingonline = 0` .

`\tracingnone`
  This command restores the initial state of the various `\tracing...` primitives following use of `\tracingall` or `\loggingall`.

`\newmarks`
  As e-TeX provides 215 `\marks` rather than the single `\mark` of TeX, an allocator mechanism is required; we believe that `\marks` are closer to `\box`es than to (say) `\count`s or `\dimen`s and so have provided an analogous allocation mechanism, in that `\newmarks` <`control sequence or active character`> assigns a numeric value to the parameter rather than making it a synonym for an actual `\mark`; this numeric value can then be used to access individual `\marks`, `\topmarks`, `\splitbotmarks`, etc., as in

              \newmarks \rectomarks
               . . .
              \marks \rectomarks {This may form part of the recto running head}
               . . .
              \leftline {\topmarks \rectomarks}

  It should be noted that as `\marks 0` is synonymous with `\mark`, `\newmarks` will never allocate that particular value.
  Note: This command was called `\newmark` in V1.1; the alternative spelling has been retained for compatibility, although it is now classed as deprecated.

`\globbox`, `\globcount`, `\globdimen`, `\globmarks`, `\globmuskip`, `\globskip`, `\globtoks`
  Analogous to TeX's `\newbox` (etc), these commands globally allocate registers from e-TeX's extended register pool (i.e. from the register range from 20 (for \marks) or from 28 (for all other classes) to 215-1). Registers are globally allocated from the lower end of the range.

`\locbox`, `\loccount`, `\locdimen`, `\locmarks`, `\locmuskip`, `\locskip`, `\loctoks`
  Analogous to `\globbox` (etc), these commands locally allocate registers from e-TeX's extended register pool (i.e. from the register range from 20 (for \marks) or from 28 (for all other classes) to 215-1). Registers are locally allocated from the upper end of the range.

`\globboxblk`, `\globcountblk`, `\globdimenblk`, `\globmarksblk`, `\globmuskipblk`, `\globskipblk`, `\globtoksblk`
  These commands extend `\globbox` (etc) by globally allocating contiguous blocks of registers from e-TeX's extended register pool. The syntax used is:

              \glob(whatever)blk <control sequence or active char> n

  where n specifies the length of the desired block. As n is parsed as an undelimited parameter, it must be expressed as a balanced text if it exceeds a single token. The <control sequence or active character> will be `\mathchardef`'d to the ordinal of the lowest register allocated.

`\locboxblk`, `\loccountblk`, `\locdimenblk`, `\locmarksblk`, `\locmuskipblk`, `\locskipblk`, `\loctoksblk`
  These commands extend `\locbox` (etc) by locally allocating contiguous blocks of registers from e-TeX's extended register pool. The syntax used is:

              \loc(whatever)blk <control sequence or active char> n

  where n specifies the length of the desired block. As n is parsed as an undelimited parameter, it must be expressed as a balanced text if it exceeds a single token. The <control sequence or active character> will be `\mathchardef`'d to the ordinal of the lowest register allocated.

`\globcountvector`, `\globdimenvector`, `\globmuskipvector`, `\globskipvector`, `\globtoksvector`
  An extension to `\globcountblk` (etc), these commands use e-TeX's arithmetic expression capabilities to globally allocate vectors of boxes (etc) from e-TeX's extended register pool. The syntax used is:

              \glob(whatever)vector <control sequence or active char> n

  where n specifies the length of the desired block. As n is parsed as an undelimited parameter, it must be expressed as a balanced text if it exceeds a single token. Once the vector has been defined, element m can be accessed in both left- and right-hand contexts as

              <control sequence or active char> m

  where 0 <= m < n. As with n, m must be expressed as a balanced text if it exceeds a single token.

`\globboxvector`, `\globmarksvector`,
  Analogous to but subtly different from the above, these commands use e-TeX's arithmetic expression capabilities to globally allocate vectors of boxes (etc) from e-TeX's extended register pool. The syntax used is:

              \glob(box-or-marks)vector <control sequence or active char> n

  where n specifies the length of the desired block. As n is parsed as an undelimited parameter, it must be expressed as a balanced text if it exceeds a single token. Once the vector has been defined, element m can be accessed in left-hand contexts as

              <box-or-marks-referencer> <control sequence or active char> m

  and in right-hand contexts as

              <box-or-marks-dereferencer> <control sequence or active char> m

  where 0 <= m < n. As with n, m must be expressed as a balanced text if it exceeds a single token.

  The significance of `<box-or-marks-(de)referencer>` is that boxes and marks are unlike other registers in that there exists a whole family of (de)referencers, one of which must be used in order to access the particular element required. For boxes, the sole referencer is `\setbox`, whilst the possible dereferencers include `\box`, `\copy,` `\unhbox,` `\unvbox,`, `\unhcopy` and `\unvcopy`. For marks, the sole referencer is `\marks`, whilst the possible dereferencers include `\topmarks`, `\firstmarks`, `\botmarks`, `\splitfirstmarks` and `\splitbotmarks`.

`\loccountvector`, `\locdimenvector`, `\locmuskipvector`, `\locskipvector`, `\loctoksvector`
  An extension to `\loccountblk` (etc), these commands use e-TeX's arithmetic expression capabilities to locally allocate vectors of boxes (etc) from e-TeX's extended register pool. The syntax used is:

              \loc(whatever)vector <control sequence or active char> n

  where n specifies the length of the desired block. As n is parsed as an undelimited parameter, it must be expressed as a balanced text if it exceeds a single token. Once the vector has been defined, element m can be accessed in both left- and right-hand contexts as

              <control sequence or active char> m

  where 0 <= m < n. As with n, m must be expressed as a balanced text if it exceeds a single token.

`\locboxvector`, `\locmarksvector`,
  Analogous to but subtly different from the above, these commands use e-TeX's arithmetic expression capabilities to locally allocate vectors of boxes (etc) from e-TeX's extended register pool. The syntax used is:

              \loc(box-or-marks)vector <control sequence or active char> n

  where n specifies the length of the desired block. As n is parsed as an undelimited parameter, it must be expressed as a balanced text if it exceeds a single token. Once the vector has been defined, element m can be accessed in left-hand contexts as

              <box-or-marks-referencer> <control sequence or active char> m

  and in right-hand contexts as

              <box-or-marks-dereferencer> <control sequence or active char> m

  where 0 <= m < n. As with n, m must be expressed as a balanced text if it exceeds a single token.

  The significance of `<box-or-marks-(de)referencer>` is that boxes and marks are unlike other registers in that there exists a whole family of (de)referencers, one of which must be used in order to access the particular element required. For boxes, the sole referencer is `\setbox`, whilst the possible dereferencers include `\box`, `\copy,` `\unhbox,` `\unvbox,`, `\unhcopy` and `\unvcopy`. For marks, the sole referencer is `\marks`, whilst the possible dereferencers include `\topmarks`, `\firstmarks`, `\botmarks`, `\splitfirstmarks` and `\splitbotmarks`.

`\reserveinserts`
  As there are now so many registers available, there is a risk that a macro package may allocate so many that there are none of the first 255 left for use by insertions (which cannot use the extended register set). `\reserveinserts` n allows a package writer or user to reserve an additional n insertions above and beyond those already allocated. The syntax used is:

              \reserveinserts n

  n must be expressed as a balanced text if it exceeds a single token.

`\load`
  Although (Plain) TeX provides facilities for either `\input`ting a complete file or for `\read`ing a file line-by-line, it makes no provision for any intermediate level of file access. In e-TeX, we provide facilities for `\input`ting one or more named modules from a suitably structured library file. The syntax used is:

              \load <module>[, <module>...] from <file>

  whilst the library file itself should be structured as:

              %% e-TeXlib Vx.y
              \module {<name>}
               . . .
              \endmodule

              \module {<name>}
               . . .
              \endmodule

               etc.

  The %% header is required, and the actual values in `Vx.y` must correspond to the current version/revision of e-TeX; for the current release, the header must therefore be:

              %% e-TeXlib V2.0

  If a library file is changed during the lifetime of the system, it is recommended (but not required) that this amendment be recorded in a cycle number appended to the header; a cycle number is of the form `;`digit[s], and thus a valid header for the current release of e-TeX might be any of:

              %% e-TeXlib V2.0
              %% e-TeXlib V2.0;1
              %% e-TeXlib V2.0;247

  etc. The necessity for a perfect match between the library header and the current version/revision of e-TeX may be relaxed in a future release if it transpires that no changes in the structure of user libraries are required for compatibility with future versions of e-TeX.

Modules in the standard library (`etexdefs.lib`)
  e-TeX is distributed with a standard library which provides mnemonic names for the various values which can be returned by the new primitives. The library contains four modules: `grouptypes`, `nodetypes`, `interactionmodes` and `iftypes`. The standard format source, `etex.src`, loads `interactionmodes` by default; the others can be loaded using the appropriate one of the following:

      	\load grouptypes from etexdefs.lib
      	\load nodetypes from etexdefs.lib
      	\load iftypes from etexdefs.lib

  Once the relevant module has been loaded, the numeric values associated with each of the possible types/modes can be retrieved using one of the following commands with one of the parameters shewn:

      	\grouptypes
      			{simple}
      			{hbox}
      			{adjustedhbox}
      			{vbox}
      			{vtop}
      			{align}
      			{noalign}
      			{output}
      			{math}
      			{disc}
      			{insert}
      			{vcenter}
      			{mathchoice}
      			{semisimple}
      			{mathshift}
      			{mathleft}

      	\nodetypes
      			{char}
      			{hlist}
      			{vlist}
      			{rule}
      			{ins}
      			{mark}
      			{adjust}
      			{ligature}
      			{disc}
      			{whatsit}
      			{math}
      			{glue}
      			{kern}
      			{penalty}
      			{unset}
      			{maths}

      	\conditionaltypes
      			{charif}
      			{catif}
      			{numif}
      			{dimif}
      			{oddif}
      			{vmodeif}
      			{hmodeif}
      			{mmodeif}
      			{innerif}
      			{voidif}
      			{hboxif}
      			{vboxif}
      			{xif}
      			{eofif}
      			{trueif}
      			{falseif}
      			{caseif}
      			{definedif}
      			{csnameif}
      			{fontcharif}

      	\interactionmodes
      			{batch}
      			{nonstop}
      			{scroll}
      			{errorstop}

Multiple language typesetting
  When TeX gained `\language` and `\setlanguage` primitives with the advent of TeX 3.0, no change was made to the Plain TeX source code to really exploit these features with the single exception of the `\newlanguage` command. In "`etex.src`", we defer the loading of patterns and hyphenation exceptions until a rudimentary language handling environment has been defined. We now assume that the user (or rather the format-creator) will, if required, modify the file called "`language.def`" by adding the various languages to be supported by the format. Each entry apart from the last in "`language.def`" is of the form:

              \addlanguage {<language>}
                           {<patterns file>}
                           {<exceptions file>}
                           {<left hyphen min>}
                           {<right hyphen min>} %%% shewn wrapped for clarity

  The first line must be:

              \addlanguage {USenglish}{hyphen.tex}{}{2}{3}

  whilst the last must be

              \uselanguage {USenglish}

  to ensure that legacy documents not explicitly specifying a language process in a manner identical to TeX (that is, using American English patterns, exceptions and left- and right-hyphen minima). In the absence of a suitable `language.def` file, the default fallback mode (USenglish, with the canonical patterns, exceptions and left- and right-hyphen minima for TeX) will be used. Within the user document, `\uselanguage {<some language>}` should be used to switch languages, which will have the effect of loading appropriate patterns, exceptions, and left- and right hyphen minima. To allow the use of more powerful language-handling environments (e.g. Babel), the `\uselanguage` command finishes by testing whether the putative control sequence `\uselanguage@hook` is defined; if it is, then it is expanded, passing as parameter the name of the language to be used. It should be noted that `\uselanguage` is automatically invoked during the expansion of `\addlanguage` prior to the reading of patterns; a further hook, `\addlanguage@hook`, is invoked in an identical manner after the reading of patterns and exceptions so as to allow (for example) category-codes to be changed for the duration of the pattern- and exception-loading régime. This code is still classed as experimental, and if it transpires that a superior mechanism would improve the interface to Babel or LaTeX, it may be enhanced in the future.

The e-TeX format source "etex.src" is a product of the NTS group.

Please notify any errors in this document to its creator;
Last updated and validated 24-MAR-1998 19:45:12 /PT