summaryrefslogtreecommitdiff
path: root/Build/source/texk/web2c/etexdir/etrip/etripman.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/texk/web2c/etexdir/etrip/etripman.tex')
-rw-r--r--Build/source/texk/web2c/etexdir/etrip/etripman.tex436
1 files changed, 436 insertions, 0 deletions
diff --git a/Build/source/texk/web2c/etexdir/etrip/etripman.tex b/Build/source/texk/web2c/etexdir/etrip/etripman.tex
new file mode 100644
index 00000000000..16464f8fb45
--- /dev/null
+++ b/Build/source/texk/web2c/etexdir/etrip/etripman.tex
@@ -0,0 +1,436 @@
+% The e-TRIP manual: How to validate e-TeX - last modified 25 Aug 2004
+%
+% some e-TeX numbers
+%
+\def\minps{32000} % minimum pool_size for e-TRIP test
+\def\minms{3200} % minimum max_string for e-TRIP test
+%
+\def\extracs{66} % additional multiletter control sequences
+\def\extrasv{2} % additional save stack positions
+\def\extrabf{23} % additional input buffer positions
+\def\extramw{38} % additional memory words dumped
+%
+\font\eighttt= cmtt8
+\font\eightrm= cmr8
+\font\rtitlefont= cmr7 scaled\magstep5
+\font\ititlefont= cmmi7 scaled\magstep5
+\def\titlefont{\rtitlefont \textfont1=\ititlefont}
+\def\eTeX{$\varepsilon$-\TeX}
+\def\NTS{NTS}
+\let\mc=\eightrm
+\rm
+\let\mainfont=\tenrm
+
+\def\.#1{\hbox{\tt#1}}
+\def\\#1{\hbox{\it#1\/\hskip.05em}} % italic type for identifiers
+
+\parskip 2pt plus 1pt
+\baselineskip 12pt plus .25pt
+
+\def\verbatim#1{\begingroup \frenchspacing
+ \def\do##1{\catcode`##1=12 } \dospecials
+ \parskip 0pt \parindent 0pt
+ \catcode`\ =\active \catcode`\^^M=\active
+ \tt \def\par{\ \endgraf} \obeylines \obeyspaces
+ \input #1 \endgroup}
+% a blank line will be typeset at the end of the file;
+% if you're unlucky it will appear on a page by itself!
+{\obeyspaces\global\let =\ }
+
+\def\verblines#1 {$$\frenchspacing \global\count255=-#1
+ \abovedisplayskip=0pt \belowdisplayskip=\abovedisplayskip
+ \def\do##1{\catcode`##1=12 }\dospecials
+ \def\par{\cr\noalign{\global\advance\count255by1 }%
+ \ifnum\count255<0 \else \egroup $$\fi}%
+ \obeylines \obeyspaces
+ \halign\bgroup\indent\tt##\hfil\cr}
+
+\output{\shipout\box255\global\advance\pageno by 1} % for the title page only
+\null
+\vfill
+\centerline{\titlefont A torture test for \eTeX}
+\vskip 6pt
+\centerline{({\sl Version 2.2, August 2004\/})}
+\vskip 18pt
+\centerline{by The \NTS\ Team}
+\vskip 6pt
+\centerline{Peter Breitenlohner, Max-Planck-Institut f\"ur Physik, M\"unchen}
+\vskip 6pt
+\centerline{Bernd Raichle, Institut f\"ur Informatik, Universit\"at Stuttgart}
+\vfill
+\centerline{\vbox{\hsize 4in
+\noindent Programs that claim to be implementations of \eTeX\ are
+supposed to be able to process the test routines described in this
+report, producing the outputs described in this report.}}
+\vskip 24pt
+{\baselineskip 9pt
+\eightrm\noindent
+The preparation of this report was supported in part by DANTE,
+Deutschsprachige Anwendervereinigung \TeX\ e.V.\hfil\break
+`\TeX' is a trademark of the American Mathematical Society.
+
+}\pageno=0\eject
+
+\output{\shipout\vbox{ % for subsequent pages
+ \baselineskip0pt\lineskip0pt
+ \hbox to\hsize{\strut
+ \ifodd\pageno \hfil\eightrm\firstmark\hfil
+ \mainfont\the\pageno
+ \else\mainfont\the\pageno\hfil
+ \eightrm\firstmark\hfil\fi}
+ \vskip 10pt
+ \box255}
+ \global\advance\pageno by 1}
+\let\runninghead=\mark
+\outer\def\section#1.{\noindent{\bf#1.}\quad
+ \runninghead{\uppercase{#1} }\ignorespaces}
+
+\section Introduction.
+The program \TeX82 by D.E.~Knuth is in the public domain, and its
+algorithms are published; he has done this since he does not want to
+discourage its use by placing proprietary restrictions on the software.
+However, he doesn't want faulty imitations to masquerade as \TeX\
+processors, since users want \TeX\ to produce identical results on
+different machines. He has copyrighted the programs so that he has some
+chance to forbid unauthorized copies; he explicitly authorizes copying
+of correct \TeX\ implementations, and not of incorrect ones! In order
+to determine, what is a correct implementation of \TeX, he has devised
+a test suite for \TeX, the \.{TRIP} test [1].
+
+The program \eTeX\ by `The \NTS\ Team' extends the capabilities of \TeX\
+by adding a relatively small amount (less than 10 per cent) of code; it
+is in the public domain, and its algorithms (beyond those of \TeX) are
+published. This report has been inspired by and is based on the
+\.{TRIP} manual. It describes the \.{e-TRIP} test, a test suite that
+allows one to determine whether what one has is a correct implementation
+of \eTeX.
+
+If somebody claims to have a correct implementation of \eTeX, we will
+not believe it until we see that the \.{e-TRIP} test is performed
+properly. We propose, in fact, that a program must meet two criteria
+before it can justifiably be called \eTeX: (1)~The person who wrote it
+must be happy with the way it works at his or her installation; and
+(2)~the program must produce the correct results from the \.{e-TRIP}
+test. Hence we are planning to do whatever we can to suppress any
+systems that call themselves \eTeX\ without meeting conditions (1)
+and~(2). We have copyrighted the program (1994,98 by The \NTS\ Team,
+1999-2004 by P.~Breitenlohner) so that we have some chance to forbid
+unauthorized copies; we explicitly authorize copying of correct \eTeX\
+implementations, and not of incorrect ones!
+
+The process of generating an \eTeX\ implementation for a particular
+system [2] is based on that of generating a \TeX\ implementation for the
+same system. Moreover, when \eTeX\ is used in compatibility mode, it is
+supposed to be 100 per cent compatible with \TeX. Thus a correct \eTeX\
+implementation, when running in compatibility mode, must pass the
+\.{TRIP} test. In fact, the first part of the \.{e-TRIP} test for a
+particular implementation of \eTeX\ consists in performing the standard
+\.{TRIP} test (a)~for \eTeX\ in compatibility mode and (b)~for \eTeX\ in
+extended mode. The deviations in the test output from step~(a) should,
+of course, be limited to those explicitly allowed by Knuth and described
+in Appendix~A, item~5 of the \.{TRIP} manual. Any additional deviations
+in the test output from step~(b) must be accounted for by \eTeX's
+additional algorithms and are described in detail in this report. Once
+an \eTeX\ implementation has passed these preliminary tests, it should be
+subjected to the second part of the \.{e-TRIP} test. There the extended
+features and algorithms of \eTeX\ are tested under normal circumstances
+as well as in situations a normal user would never dream of (in the
+spirit of the \.{TRIP} test).
+
+The remainder of this report consists of appendices, whose contents ought
+to be described briefly here:
+
+Appendix A explains in detail how to carry out the first part of the
+test of \eTeX, given copies of the files described in the \.{TRIP}
+manual.
+
+Appendix B explains how to carry out the \eTeX\ specific test, given
+copies of the files described in the other appendices.
+
+Appendix C is \.{eTRIP.TEX}, a fiendish test file for \eTeX.
+
+Appendix D is \.{eTRIP.PL}, the property-list description of a
+special font called \.{etrip}.
+
+Appendix E is \.{eTRIPIN.LOG}, a correct transcript file \.{eTRIP.LOG}
+that results if \.{e-TRIPTEX} is applied to \.{eTRIP.TEX}.
+This run of \.{e-TRIPTEX} also creates a binary format file called
+\.{eTRIP.FMT} (or similar).
+
+Appendix F is a correct transcript file \.{eTRIP.LOG} that results if
+\.{e-TRIPTEX} or any other version of \eTeX\ is applied to \.{eTRIP.TEX}
+with format \.{eTRIP.FMT}.
+
+Appendix G is \.{eTRIP.TYP}, the symbolic version of a correct output
+file \.{eTRIP.DVI} that was produced at the same time as the
+\.{eTRIP.LOG} file of Appendix~F.
+
+Appendix H is \.{eTRIP.OUT}, a short file written out and read in by
+\eTeX\ when it processes \.{eTRIP.TEX}.
+
+Appendix I is \.{eTRIP.FOT}, an abbreviated version of Appendix F that
+appears on the user's terminal during the run that produces
+\.{eTRIP.LOG}.
+
+\vskip 24pt plus 24pt
+\section References.
+\item {[1]}
+{\sl A torture test for \TeX\/},
+by Donald E.~Knuth, Stanford Computer Science Report~1027.
+
+\item {[2]}
+{\sl How to generate \eTeX\/},
+by The \NTS\ Team (Peter Breitenlohner and Phil Taylor).
+
+\item {[3]}
+{\sl The \.{WEB} system of structured documentation\/},
+by Donald E.~Knuth, Stanford Computer Science Report~980.
+
+\item {[4]}
+{\sl \TeX ware\/}, by Donald E.~Knuth and David R.~Fuchs,
+Stanford Computer Science Report~1097.
+
+\vfill\eject
+
+\section Appendix A: How to test \eTeX\ (part 1).
+
+\item{0.} Let's assume that you have copies of the files \.{TRIP.TEX},
+\.{TRIP.PL}, \.{TRIPIN.LOG}, \.{TRIP.LOG}, \.{TRIP.TYP}, and
+\.{TRIP.FOT} as described in Appendices~B, C, D, E, F, and~G of the
+\.{TRIP} manual [1] (in a safe place so that these ``master'' files will
+not be clobbered). Furthermore, let's suppose that you have a working
+\.{WEB} system [3], and that you have working programs \.{PLtoTF} and
+\.{DVItype}, as described in the \TeX ware report [4]. Finally let's
+assume that you are able to generate \eTeX\ as described in [2].
+
+\item{1.} Use \.{PLtoTF} to convert \.{TRIP.PL} into \.{TRIP.TFM};
+install \.{TRIP.TFM} in the standard file area for \TeX\ font metric
+files (or set a suitable environment variable or similar such that these
+files will be found by the program).
+
+\item{2.} Generate \.{e-TRIPTEX}, a special version of \.{e-INITEX}.
+The parameters for \.{e-TRIPTEX} should agree with those for \.{TRIPTEX}
+(as described in [1]), except that you should set \\{pool\_size} to a
+value $\ge\minps$ and \\{max\_strings} to a value $\ge\minms$.
+
+\item{3.} Perform the \.{TRIP} test as described in Appendix~A,
+items~3--7 of [1], with \.{e-TRIPTEX} as prepared in step~2. The program
+will run in compatibility mode and should therefore be fully compatible
+with \.{TRIPTEX} as described in [1]; apart from the allowed differences
+listed in item~5, the test output should deviate from the master files in
+the following \eTeX-specific point (and only in this one):
+
+\itemitem{a)} The name and version by which the program announces itself
+will be different; the extension of the format file produced during the
+first \.{e-TRIPTEX} run may be different.
+
+\def\bs{{\char`\\}}
+\def\sp{{\char'40}}
+
+\item{4.} Perform steps 3--7 of the \.{TRIP} test once again with
+\.{e-TRIPTEX}. During the first run type `\.{*\bs input\sp trip}'
+instead of `\.{\bs input\sp trip}', as a consequence \.{e-TRIPTEX} will
+run in extended mode. During the second run type `\.{\&trip\sp\bs
+toksdef\bs tokens=0\sp\bs input\sp trip}' instead of `\.{\sp\&trip\sp\sp
+trip\sp}'. The test output should differ from that of step~3 above in
+the following respects (and only in these):
+
+\itemitem{a)} The date and\slash or time will naturally be different.
+
+\itemitem{b)} The message `\.{entering extended mode}' will appear on
+the terminal and in the \.{TRIP.LOG} files.
+
+\itemitem{c)} The input `\.{*\bs input trip}' instead of
+`\.{\bs input trip}' is recorded in the first \.{TRIP.LOG} file;
+similarly the input `\.{\&trip\sp\bs toksdef\bs tokens=0\sp\bs input\sp
+trip}' instead of `\.{\sp\&trip\sp\sp trip\sp}' is recorded in the
+second \.{TRIP.LOG} file.
+
+\itemitem{d)} The following 6 lines (the last of them blank) will be
+missing from the first \.{TRIP.LOG} file\verblines 6
+! Bad register code (256).
+l.29 ...{1} \toksdef\tokens=256
+ \show\errorstopmode
+A register number must be between 0 and 255.
+I changed this one to zero.
+
+
+\itemitem{e)} The first \.{TRIP.LOG} file will report the dumping of
+\extramw~additional memory words.
+
+\itemitem{f)} If the date has changed, the number of string characters
+dumped by the first \.{e-TRIPTEX} run may vary by $\pm2$.
+
+\itemitem{g)} Both \.{e-TRIPTEX} runs report \extracs~additional
+multiletter control sequences (in the \.{TRIP.LOG} files).
+
+\itemitem{f)} The second \.{e-TRIPTEX} run reports the unfinished
+group(s) when the program terminates; there are three additional lines
+(the first of them blank) on the terminal and in the \.{TRIP.LOG}
+file\verblines 3
+
+### semi simple group (level 1) entered at line 429 (begingroup)
+### bottom level
+The second \.{TRIP.LOG} does not contain six lines\verblines 1
+{restoring \fam=-1}
+one line\verblines 1
+{restoring \displayindent=0.0pt}
+and one line\verblines 1
+{restoring current font=\ip}
+Ten lines displaying an \.{\bs hbox} contain the additional text
+`\.{, display}'.
+Finally the second \.{TRIP.LOG} reports the additional use of
+\extrabf~input buffer (\.{b}) and \extrasv~save (\.{s}) stack positions.
+
+\vfill\eject
+
+\section Appendix B: How to test \eTeX\ (part 2).
+
+\item{5.} Assume that you have copies of the ``master'' files
+\.{eTRIP.TEX}, \.{eTRIP.PL}, \.{eTRIPIN.LOG}, \.{eTRIP.LOG},
+\.{eTRIP.TYP}, \.{eTRIP.OUT}, and \.{eTRIP.FOT}, as in Appendices C, D,
+E, F, G, H, and~I (again in a safe place).
+
+\item{6.} Use \.{PLtoTF} to convert \.{eTRIP.PL} into \.{eTRIP.TFM};
+install \.{eTRIP.TFM} in the standard file area for \TeX\ font metric
+files (or set a suitable environment variable or similar).
+
+\item{7.} Run \.{e-TRIPTEX}; in response to the `\.{**}' prompt, type
+`\.{*etrip}'. You should get an output file \.{eTRIP.LOG} that matches
+the file \.{eTRIPIN.LOG} (Appendix~E). Contrary to the analogous step
+in the \.{TRIP} test (steps~3 and~4 above) there should be no error
+messages; lines in the output saying ``Emergency stop'' would indicate
+that you have performed this test with a standard \TeX\ or with \eTeX\
+in compatibility mode.
+
+\item{8.} Run \.{e-TRIPTEX} again; this time type
+`\.{\&etrip{\char'40}etrip}'. You should get outputs \.{eTRIP.LOG},
+\.{eTRIP.DVI}, and \.{eTRIP.OUT}. Furthermore, your terminal should
+receive output that matches \.{eTRIP.FOT} (Appendix~I). Once again, the
+terminal will be getting no output during the middle part of this test.
+
+\item{9.} Compare the \.{eTRIP.LOG} file from step 8 with the ``master''
+\.{eTRIP.LOG} file of step~5. There should be no lines saying
+``Emergency stop'' (see above) or ``Bug in your e-TeX implementation'';
+there should be perfect agreement between these files except in the
+following respects:
+
+\itemitem{a)} The dates and possibly the file names will naturally be
+different.
+
+\itemitem{b)} Glue settings in the displays of \TeX\ boxes are subject
+to system-dependent rounding, so slight deviations are permissible.
+However, such deviations apply only to the `\.{glue set}' values that
+appear at the end of an \.{\char'134hbox} or \.{\char'134vbox} line; all
+other numbers should agree exactly, since they are computed with integer
+arithmetic in a prescribed system-independent manner.
+
+\itemitem{c)} The amount of space in kerns that are marked ``for
+accent'' are, similarly, subject to system-dependent rounding.
+
+\itemitem{d)} If you had different values for \\{stack\_size},
+\\{buf\_size}, etc., the corresponding capacity values will be different
+when they are printed out at the end.
+
+\itemitem{e)} Help messages may be different; indeed, the author of
+\TeX\ encourages non-English help messages in versions of \TeX\ for
+people who don't understand English as well as some other language.
+Similarly, \eTeX\ could well be used with non-English help messages.
+
+\itemitem{f)} The total number and length of strings at the end may well
+be different.
+
+\itemitem{g)} If your \eTeX\ uses a different memory allocation or
+packing scheme or \.{DVI} output logic, the memory usage statistics may
+change.
+
+\item{10.} Use \.{DVItype} to convert your file \.{eTRIP.DVI} to a file
+\.{eTRIP.TYP}. The following options should be set when using
+\.{DVItype}:
+$$\vbox{\halign{#\hfil&\hfil#\cr
+Output level = 2\cr
+Starting page = \.{*.*.*.*.*.*.*.*.*.*}\hskip-20pt\cr
+Number of pages = 1000000&(this is the default)\cr
+Resolution = 7227/100&(this is one point per pixel)\cr
+New magnification = 0&(this is the default)\cr}}$$
+The resulting file should agree with the master \.{eTRIP.TYP} file of
+step~5, except that some of the values might be a little off due to
+floating-point rounding discrepancies. Furthermore there may be
+differences between `\\{right}' and `\\w' and `\\x' commands, and
+between `\\{down}' and `\\y' and `\\z'; the key thing is that all
+characters and rules and \\{xxx}'s should be in almost the same
+positions as specified in Appendix~G. If you have set
+\\{dvi\_buf\_size} to 800, then your \.{DVI} file should be virtually
+identical to the one supplied.)
+
+\vfill\eject
+
+\section Appendix C: The \.{eTRIP.TEX} file.
+The contents of the test routine are prefixed here with line numbers,
+for ease in comparing this file with the error messages printed later;
+the line numbers aren't actually present.
+\runninghead{APPENDIX C: \.{eTRIP.TEX} (CONTINUED)}
+
+\vskip 8pt
+\begingroup\count255=0
+\everypar{\global\advance\count255 by 1
+ \hbox to 20pt{\sevenrm\hfil\the\count255\ \ }}
+\verbatim{etrip.tex}
+\endgroup
+\vfill\eject
+
+\section Appendix D: The \.{eTRIP.PL} file.
+At the moment the \.{eTRIP.PL} file is just a copy of \.{TRIP.PL} as
+described in Appendix~C of [1].
+
+\section Appendix E: The \.{eTRIPIN.LOG} file.
+When \.{e-TRIPTEX} makes the \.{eTRIP.FMT} file, it also creates a file
+called \.{eTRIP.LOG} that looks like this.
+\runninghead{APPENDIX E: \.{eTRIPIN.LOG} (CONTINUED)}
+
+\vskip8pt
+\verbatim{etripin.log}
+\vfill\eject
+
+\section Appendix F: The \.{eTRIP.LOG} file.
+Here is the major output of the \.{e-TRIP} test; it is generated by
+running \.{e-TRIPTEX} and loading \.{eTRIP.FMT}, then reading
+\.{eTRIP.TEX}.
+\runninghead{APPENDIX F: \.{eTRIP.LOG} (CONTINUED)}
+
+{\let\tt=\eighttt\leftskip 1in\baselineskip 9pt plus .1pt minus .1pt
+\vskip8pt
+\verbatim{etrip.log}
+}
+\vfill\eject
+
+\section Appendix G: The \.{eTRIP.TYP} file.
+Here is another major component of the test. It shows the output of
+\.{DVItype} applied to the file \.{eTRIP.DVI} that was created at the
+same time Appendix F was produced.
+\runninghead{APPENDIX G: \.{eTRIP.TYP} (CONTINUED)}
+
+{\let\tt=\eighttt\leftskip 1in\baselineskip 9pt plus .1pt minus .1pt
+\vskip8pt
+\verbatim{etrip.typ}
+}
+\vfill\eject
+
+\section Appendix H: The \.{eTRIP.OUT} file.
+This short file was written out once and read in several times, during
+the time Appendix F was being produced. There are only four lines.
+\runninghead{APPENDIX H: \.{eTRIP.OUT} (CONTINUED)}
+
+\vskip8pt
+\verbatim{etrip.out}
+\vfill\eject
+
+\section Appendix I: The \.{eTRIP.FOT} file.
+This shows what appeared on the terminal while Appendix F was being
+produced.
+\runninghead{APPENDIX I: \.{eTRIP.FOT} (CONTINUED)}
+
+\vskip8pt
+\verbatim{etrip.fot}
+
+\vfill\end