summaryrefslogtreecommitdiff
path: root/systems/doc/etex/etex_src.html
diff options
context:
space:
mode:
Diffstat (limited to 'systems/doc/etex/etex_src.html')
-rw-r--r--systems/doc/etex/etex_src.html540
1 files changed, 540 insertions, 0 deletions
diff --git a/systems/doc/etex/etex_src.html b/systems/doc/etex/etex_src.html
new file mode 100644
index 0000000000..e4e031adae
--- /dev/null
+++ b/systems/doc/etex/etex_src.html
@@ -0,0 +1,540 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
+<html>
+<head><title>The "etex.src" file and its adjuncts: V2.0</title>
+</HEAD><BODY>
+<H1>The e-T<sub><big>E</big></sub>X format source file
+<code>"etex.src" (V2.0)</code></H1>
+<p>
+The primary e-TeX format source file, <code>"etex.src"</code>, is in principle
+merely a wrapper for <code>"plain.tex"</code>, providing modified definitions
+for some Plain TeX commands (at present, just
+one:&nbsp;<code>\tracingall</code>), improving and generalising
+the register allocation mechanism, and adding new commands
+<p>
+In so doing, we have taken the opportunity to
+(a)&nbsp;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)&nbsp;provide a local as well as a global register allocation mechanism,
+(c)&nbsp;provide for the allocation of blocks of registers as well as single
+ registers,
+(d)&nbsp;provide a means of allocating and accessing <em>vectors</em>
+ (monodimensional arrays) of registers, and finally
+(e)&nbsp;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.
+<p>
+As the new commands and other features are not documented elsewhere,
+a brief explanation of their syntax and semantics is provided here.
+<p>
+<dl>
+<dt><code>\tracingall</code></dt>
+<dd>The definition is augmented to enable tracing for the new e-TeX
+ tracing primitives <code>\tracingassigns</code>,
+ <code>\tracinggroups</code>, <code>\tracingifs</code>,
+ <code>\tracingnesting</code>
+ and <code>\tracingscantokens</code>; the numeric value assigned
+ to the TeX primitives <code>\tracingcommands</code> and
+ <code>\tracinglostchars</code> is increased
+ as e-TeX will report additional detail in these circumstances.
+ <p>
+</dd>
+
+<dt><code>\eTeX</code></dt>
+<dd>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 <code>etexdefs.lib</code> in due course.
+ <p>
+</dd>
+
+<dt><code>\loggingall</code></dt>
+<dd>This command is equivalent to the sequence <code>\tracingall</code>
+ <code>\tracingonline = 0 </code>.
+ <p>
+</dd>
+
+<dt><code>\tracingnone</code></dt>
+<dd>This command restores the initial state of the various
+ <code>\tracing...</code> primitives following use of
+ <code>\tracingall</code> or <code>\loggingall</code>.
+ <p>
+</dd>
+
+<dt><code>\newmarks</code></dt>
+<dd>As e-TeX provides 2<sup>15</sup> <code>\marks</code> rather than the single
+ <code>\mark</code> of TeX, an allocator mechanism is required; we
+ believe that <code>\marks</code> are closer to
+ <code>\box</code>es than to (say) <code>\count</code>s or
+ <code>\dimen</code>s and so have provided an analogous allocation
+ mechanism, in that <code>\newmarks</code>&nbsp&lt;<code><em>control
+ sequence or active character</em></code>&gt; assigns a <em>numeric
+ value</em> to the parameter rather than making it a synonym for an
+ actual <code>\mark</code>; this numeric value can then be used to access
+ individual <code>\marks</code>, <code>\topmarks</code>,
+ <code>\splitbotmarks</code>,&nbsp;etc., as in
+<pre>
+ \newmarks \rectomarks
+ . . .
+ \marks \rectomarks {This may form part of the recto running head}
+ . . .
+ \leftline {\topmarks \rectomarks}
+</pre>
+ It should be noted that as <code>\marks 0</code> is synonymous with
+ <code>\mark</code>, <code>\newmarks</code> will never allocate that
+ particular value.
+ <br><em><strong>Note:</strong></em>
+ This command was called <code>\newmark</code> in V1.1; the alternative
+ spelling has been retained for compatibility, although it is now classed
+ as deprecated.
+ <p>
+</dd>
+
+<dt>
+<code>\globbox</code>,
+<code>\globcount</code>,
+<code>\globdimen</code>,
+<code>\globmarks</code>,
+<code>\globmuskip</code>,
+<code>\globskip</code>,
+<code>\globtoks</code>
+</dt>
+<dd>
+Analogous to TeX's <code>\newbox</code> (etc), these commands globally allocate
+registers from e-TeX's extended register pool (i.e.&nbsp;from the register
+range from 2<sup>0</sup> (for \marks) or from 2<sup>8</sup>
+(for all other classes) to 2<sup>15</sup>-1). Registers are globally
+allocated from the lower end of the range.
+<p>
+</dd>
+<dt>
+<code>\locbox</code>,
+<code>\loccount</code>,
+<code>\locdimen</code>,
+<code>\locmarks</code>,
+<code>\locmuskip</code>,
+<code>\locskip</code>,
+<code>\loctoks</code>
+</dt>
+<dd>
+Analogous to <code>\globbox</code> (etc), these commands locally allocate
+registers from e-TeX's extended register pool (i.e.&nbsp;from the register
+range from 2<sup>0</sup> (for \marks) or from 2<sup>8</sup>
+(for all other classes) to 2<sup>15</sup>-1). Registers are locally
+allocated from the upper end of the range.
+<p>
+</dd>
+<dt>
+<code>\globboxblk</code>,
+<code>\globcountblk</code>,
+<code>\globdimenblk</code>,
+<code>\globmarksblk</code>,
+<code>\globmuskipblk</code>,
+<code>\globskipblk</code>,
+<code>\globtoksblk</code>
+</dt>
+<dd>
+These commands extend <code>\globbox</code> (etc) by globally allocating
+contiguous blocks of registers from e-TeX's extended register pool.
+The syntax used is:
+<pre>
+ \glob(whatever)blk &lt;control sequence or active char&gt; <em>n</em>
+</pre>
+where <em>n</em> specifies the length of the desired block. As
+<em>n</em> is parsed as an undelimited parameter, it must be
+expressed as a balanced text if it exceeds a single token.
+The &lt;control sequence or active character&gt; will be
+<code>\mathchardef</code>'d to the ordinal of the lowest register allocated.
+<p>
+</dd>
+<dt>
+<code>\locboxblk</code>,
+<code>\loccountblk</code>,
+<code>\locdimenblk</code>,
+<code>\locmarksblk</code>,
+<code>\locmuskipblk</code>,
+<code>\locskipblk</code>,
+<code>\loctoksblk</code>
+</dt>
+<dd>
+These commands extend <code>\locbox</code> (etc) by locally allocating
+contiguous blocks of registers from e-TeX's extended register pool.
+The syntax used is:
+<pre>
+ \loc(whatever)blk &lt;control sequence or active char&gt; <em>n</em>
+</pre>
+where <em>n</em> specifies the length of the desired block. As
+<em>n</em> is parsed as an undelimited parameter, it must be
+expressed as a balanced text if it exceeds a single token.
+The &lt;control sequence or active character&gt; will be
+<code>\mathchardef</code>'d to the ordinal of the lowest register allocated.
+<p>
+</dd>
+<dt>
+<code>\globcountvector</code>,
+<code>\globdimenvector</code>,
+<code>\globmuskipvector</code>,
+<code>\globskipvector</code>,
+<code>\globtoksvector</code>
+</dt>
+<dd>
+An extension to <code>\globcountblk</code> (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:
+<pre>
+ \glob(whatever)vector &lt;control sequence or active char&gt; <em>n</em>
+</pre>
+where <em>n</em> specifies the length of the desired block. As
+<em>n</em> 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 <em>m</em> can be accessed in both left-
+and right-hand contexts as
+<pre>
+ &lt;control sequence or active char&gt; <em>m</em>
+</pre>
+where 0 &lt;= <em>m</em> &lt; <em>n</em>. As with <em>n</em>, <em>m</em>
+must be expressed as a balanced text if it exceeds a single token.
+<p>
+</dd>
+<dt>
+<code>\globboxvector</code>,
+<code>\globmarksvector</code>,
+</dt>
+<dd>
+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:
+<pre>
+ \glob(box-or-marks)vector &lt;control sequence or active char&gt; <em>n</em>
+</pre>
+where <em>n</em> specifies the length of the desired block. As
+<em>n</em> 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 <em>m</em> can be accessed in left-hand
+contexts as
+<pre>
+ &lt;box-or-marks-referencer&gt; &lt;control sequence or active char&gt; <em>m</em>
+</pre>
+and in right-hand contexts as
+<pre>
+ &lt;box-or-marks-dereferencer&gt; &lt;control sequence or active char&gt; <em>m</em>
+</pre>
+where 0 &lt;= <em>m</em> &lt; <em>n</em>. As with <em>n</em>, <em>m</em>
+must be expressed as a balanced text if it exceeds a single token.
+<p>
+The significance of <code>&lt;box-or-marks-(de)referencer&gt;</code> 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
+<code>\setbox</code>, whilst the possible dereferencers include
+<code>\box</code>,
+<code>\copy,</code>
+<code>\unhbox,</code>
+<code>\unvbox,</code>,
+<code>\unhcopy</code> and
+<code>\unvcopy</code>.
+For marks, the sole referencer is
+<code>\marks</code>, whilst the possible dereferencers include
+<code>\topmarks</code>,
+<code>\firstmarks</code>,
+<code>\botmarks</code>,
+<code>\splitfirstmarks</code> and
+<code>\splitbotmarks</code>.
+<p>
+</dd>
+<dt>
+<code>\loccountvector</code>,
+<code>\locdimenvector</code>,
+<code>\locmuskipvector</code>,
+<code>\locskipvector</code>,
+<code>\loctoksvector</code>
+</dt>
+<dd>
+An extension to <code>\loccountblk</code> (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:
+<pre>
+ \loc(whatever)vector &lt;control sequence or active char&gt; <em>n</em>
+</pre>
+where <em>n</em> specifies the length of the desired block. As
+<em>n</em> 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 <em>m</em> can be accessed in both left-
+and right-hand contexts as
+<pre>
+ &lt;control sequence or active char&gt; <em>m</em>
+</pre>
+where 0 &lt;= <em>m</em> &lt; <em>n</em>. As with <em>n</em>, <em>m</em>
+must be expressed as a balanced text if it exceeds a single token.
+<p>
+</dd>
+<dt><code>\locboxvector</code>,
+<code>\locmarksvector</code>,
+</dt>
+<dd>
+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:
+<pre>
+ \loc(box-or-marks)vector &lt;control sequence or active char&gt; <em>n</em>
+</pre>
+where <em>n</em> specifies the length of the desired block. As
+<em>n</em> 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 <em>m</em> can be accessed in left-hand
+contexts as
+<pre>
+ &lt;box-or-marks-referencer&gt; &lt;control sequence or active char&gt; <em>m</em>
+</pre>
+and in right-hand contexts as
+<pre>
+ &lt;box-or-marks-dereferencer&gt; &lt;control sequence or active char&gt; <em>m</em>
+</pre>
+where 0 &lt;= <em>m</em> &lt; <em>n</em>. As with <em>n</em>, <em>m</em>
+must be expressed as a balanced text if it exceeds a single token.
+<p>
+The significance of <code>&lt;box-or-marks-(de)referencer&gt;</code> 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
+<code>\setbox</code>, whilst the possible dereferencers include
+<code>\box</code>,
+<code>\copy,</code>
+<code>\unhbox,</code>
+<code>\unvbox,</code>,
+<code>\unhcopy</code> and
+<code>\unvcopy</code>.
+For marks, the sole referencer is
+<code>\marks</code>, whilst the possible dereferencers include
+<code>\topmarks</code>,
+<code>\firstmarks</code>,
+<code>\botmarks</code>,
+<code>\splitfirstmarks</code> and
+<code>\splitbotmarks</code>.
+<p>
+</dd>
+<dt><code>\reserveinserts</code></dt>
+<dd>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).
+<code>\reserveinserts</code> <em>n</em> allows a package writer or user to
+reserve an additional <em>n</em> insertions above and beyond those already
+allocated. The syntax used is:
+<pre>
+ \reserveinserts <em>n</em>
+</pre>
+<em>n</em> must be expressed as a balanced text if it exceeds a single token.
+<p>
+</dd>
+
+<dt><code>\load</code></dt>
+<dd>Although (Plain) TeX provides facilities for either
+ <code>\input</code>ting a complete file or for <code>\read</code>ing a
+ file line-by-line, it makes no provision for any intermediate level of
+ file access. In e-TeX, we provide facilities for
+ <code>\input</code>ting one or more named <em>modules</em> from a
+ suitably structured library file. The syntax used is:
+<pre>
+ \load &lt;<em>module</em>&gt;[, &lt;<em>module</em>&gt;...] from &lt;<em>file</em>&gt;
+</pre>
+ whilst the library file itself should be structured as:
+<pre>
+ %% e-TeXlib Vx.y
+ \module {&lt;<em>name</em>&gt;}
+ . . .
+ \endmodule
+
+ \module {&lt;<em>name</em>&gt;}
+ . . .
+ \endmodule
+
+ etc.
+</pre>
+ The %% header is required, and the actual values in
+ <code>Vx.y</code> must correspond to the current version/revision
+ of e-TeX; for the current release, the header must therefore
+ be:
+<pre>
+ %% e-TeXlib V2.0
+</pre>
+ If a library file is changed during the lifetime of the system, it
+ is <em>recommended</em> (but not required) that this amendment be
+ recorded in a <em>cycle number</em> appended to the header;
+ a <em>cycle number</em> is of the form <code>;</code><em>digit[s]</em>,
+ and thus a valid header for the current release of e-TeX might be
+ any of:
+<pre>
+ %% e-TeXlib V2.0
+ %% e-TeXlib V2.0;1
+ %% e-TeXlib V2.0;247
+</pre>
+ 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.
+ <p>
+</dd>
+
+<dt>Modules in the standard library (<code>etexdefs.lib</code>)</dt>
+<dd>
+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:
+<code>grouptypes</code>,
+<code>nodetypes</code>,
+<code>interactionmodes</code> and
+<code>iftypes</code>. The standard format source, <code>etex.src</code>,
+loads <code>interactionmodes</code> by default; the others can be loaded
+using the appropriate one of the following:
+<pre>
+ \load grouptypes from etexdefs.lib
+ \load nodetypes from etexdefs.lib
+ \load iftypes from etexdefs.lib
+</pre>
+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:
+<pre>
+ \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}
+</pre>
+</dd>
+
+<dt>Multiple language typesetting</dt>
+<dd>When TeX gained <code>\language</code> and
+ <code>\setlanguage</code> 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 <code>\newlanguage</code>
+ command. In "<code>etex.src</code>", we defer the loading of
+ <em>patterns</em> and <em>hyphenation exceptions</em> 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 "<code>language.def</code>" by adding the
+ various languages to be supported by the format. Each entry apart from
+ the last in "<code>language.def</code>" is of the form:
+<pre>
+ \addlanguage {&lt;<em>language</em>&gt;}
+ {&lt;<em>patterns file</em>&gt;}
+ {&lt;<em>exceptions file</em>&gt;}
+ {&lt;<em>left hyphen min</em>&gt;}
+ {&lt;<em>right hyphen min</em>&gt;} %%% shewn wrapped for clarity
+</pre>
+ The first line <em><strong>must</strong></em> be:
+<pre>
+ \addlanguage {USenglish}{hyphen.tex}{}{2}{3}
+</pre>
+ whilst the last must be
+<pre>
+ \uselanguage {USenglish}
+</pre>
+ 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 <code>language.def</code>
+ 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, <code>\uselanguage {&lt;<em>some
+ language</em>&gt;}</code> 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.&nbsp;<a
+ href="http://homepage.cistron.nl/~jlbraams/babel.html">Babel</a>),
+ the <code>\uselanguage</code> command finishes by testing whether the
+ putative control sequence <code>\uselanguage@hook</code> 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 <code>\uselanguage</code>
+ is automatically invoked during the expansion of
+ <code>\addlanguage</code> <em>prior</em> to the reading of patterns;
+ a further hook, <code>\addlanguage@hook</code>, is invoked in an
+ identical manner <em>after</em> 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
+ <a href="http://homepage.cistron.nl/~jlbraams/babel.html">Babel</a>
+ or <a href="http://www.tex.ac.uk/CTAN/latex/">LaTeX</a>, it may be
+ enhanced in the future.
+ <p>
+</dd>
+</dl>
+<p>
+The e-TeX format source "etex.src" is a product of
+<a href="/e-TeX/NTS-Group.Html">the NTS group</a>.
+<hr>
+<p>
+Please notify any errors in this document to <a
+href="http://www.vms.rhbnc.ac.uk/~chaa006/">its creator</a>;<br>
+Last updated and
+<a href="http://validator.w3.org/check?url=http://www.rhbnc.ac.uk/e-TeX/v2/src/etex_src.html">
+validated
+</a>
+ 24-MAR-1998 19:45:12
+/PT<br>
+<img src="/logos/vh40.gif" alt="W3C HTML 4.0 validated.">
+</body>
+</html>