diff options
Diffstat (limited to 'Build/source/texk/web2c/etexdir/etrip/etripman.tex')
-rw-r--r-- | Build/source/texk/web2c/etexdir/etrip/etripman.tex | 436 |
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 |