diff options
Diffstat (limited to 'Master/texmf-dist/doc/etex/base/etex_src.html')
-rw-r--r-- | Master/texmf-dist/doc/etex/base/etex_src.html | 540 |
1 files changed, 540 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/etex/base/etex_src.html b/Master/texmf-dist/doc/etex/base/etex_src.html new file mode 100644 index 00000000000..e4e031adae2 --- /dev/null +++ b/Master/texmf-dist/doc/etex/base/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: <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) 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 <em>vectors</em> + (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. +<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> <<code><em>control + sequence or active character</em></code>> 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>, 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. 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. 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 <control sequence or active char> <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 <control sequence or active character> 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 <control sequence or active char> <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 <control sequence or active character> 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 <control sequence or active char> <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> + <control sequence or active char> <em>m</em> +</pre> +where 0 <= <em>m</em> < <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 <control sequence or active char> <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> + <box-or-marks-referencer> <control sequence or active char> <em>m</em> +</pre> +and in right-hand contexts as +<pre> + <box-or-marks-dereferencer> <control sequence or active char> <em>m</em> +</pre> +where 0 <= <em>m</em> < <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><box-or-marks-(de)referencer></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 <control sequence or active char> <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> + <control sequence or active char> <em>m</em> +</pre> +where 0 <= <em>m</em> < <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 <control sequence or active char> <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> + <box-or-marks-referencer> <control sequence or active char> <em>m</em> +</pre> +and in right-hand contexts as +<pre> + <box-or-marks-dereferencer> <control sequence or active char> <em>m</em> +</pre> +where 0 <= <em>m</em> < <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><box-or-marks-(de)referencer></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 <<em>module</em>>[, <<em>module</em>>...] from <<em>file</em>> +</pre> + whilst the library file itself should be structured as: +<pre> + %% e-TeXlib Vx.y + \module {<<em>name</em>>} + . . . + \endmodule + + \module {<<em>name</em>>} + . . . + \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 {<<em>language</em>>} + {<<em>patterns file</em>>} + {<<em>exceptions file</em>>} + {<<em>left hyphen min</em>>} + {<<em>right hyphen min</em>>} %%% 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 {<<em>some + language</em>>}</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. <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> |