diff options
Diffstat (limited to 'Build/source/texk/web2c/triptrap/tripman.tex')
| -rw-r--r-- | Build/source/texk/web2c/triptrap/tripman.tex | 413 |
1 files changed, 413 insertions, 0 deletions
diff --git a/Build/source/texk/web2c/triptrap/tripman.tex b/Build/source/texk/web2c/triptrap/tripman.tex new file mode 100644 index 00000000000..7634c8c9e78 --- /dev/null +++ b/Build/source/texk/web2c/triptrap/tripman.tex @@ -0,0 +1,413 @@ +% The TRIP manual: How to validate TeX --- last updated by D E Knuth on 4 Dec 89 +\font\eighttt= cmtt8 +\font\eightrm= cmr8 +\font\titlefont= cmr7 scaled\magstep5 +\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 =\ } + +\output{\shipout\box255\global\advance\pageno by 1} % for the title page only +\null +\vfill +\centerline{\titlefont A torture test for \TeX} +\vskip 18pt +\centerline{by Donald E. Knuth} +\centerline{Stanford University} +\vskip 6pt +\centerline{({\sl Version 3, January 1990\/})} +\vfill +\centerline{\vbox{\hsize 4in +\noindent Programs that claim to be implementations of \TeX82 are +supposed to be able to process the test routine contained in this +report, producing the outputs contained in this report.}} +\vskip 24pt +{\baselineskip 9pt +\eightrm\noindent +The preparation of this report was supported in part by the National Science +Foundation under grants IST-8201926 and MCS-8300984, +and by the System Development Foundation. +`\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. +People often think that their programs are ``debugged'' when large applications +have been run successfully. But system programmers know that a typical large +application tends to use at most about 50 per cent of the instructions +in a typical compiler. Although the other half of the code---which tends +to be the ``harder half''---might be riddled with errors, the system seems +to be working quite impressively until an unusual case shows up on the +next day. And on the following day another error manifests itself, and so on; +months or years go by before certain parts of the compiler are even +activated, much less tested in combination with other portions of the system, +if user applications provide the only tests. + +How then shall we go about testing a compiler? Ideally we would like to +have a formal proof of correctness, certified by a computer. +This would give us a lot of confidence, +although of course the formal verification program might itself be incorrect. +A more serious drawback of automatic verification is that the formal +specifications of the compiler are likely to be wrong, since they aren't +much easier to write than the compiler itself. Alternatively, we can +substitute an informal proof of correctness: The programmer writes his or +her code in a structured manner and checks that appropriate relations +remain invariant, etc. This helps greatly to reduce errors, but it cannot +be expected to remove them completely; the task of checking a large +system is sufficiently formidable that human beings cannot do it without +making at least a few slips here and there. + +Thus, we have seen that test programs are unsatisfactory if they are simply +large user applications; yet some sort of test program is needed because +proofs of correctness aren't adequate either. People have proposed schemes +for constructing test data automatically from a program text, but such +approaches run the risk of circularity, since they cannot assume that a +given program has the right structure. + +I have been having good luck with a somewhat different approach, +first used in 1960 to debug an {\mc ALGOL} compiler. The idea is to +construct a test file that is about as different from a typical user +application as could be imagined. Instead of testing things that people +normally want to do, the file tests complicated things that people would +never dare to think of, and it embeds these complexities in still +more arcane constructions. Instead of trying to make the compiler do the +right thing, the goal is to make it fail (until the bugs have all been found). + +To write such a fiendish test routine, one simply gets into a nasty frame +of mind and tries to do everything in the unexpected way. Parameters +that are normally positive are set negative or zero; borderline cases +are pushed to the limit; deliberate errors are made in hopes that the +compiler will not be able to recover properly from them. + +A user's application tends to exercise 50\%\ of a compiler's logic, +but my first fiendish tests tend to improve this to about 90\%. As the +next step I generally make use of frequency-counting software to identify +the instructions that have still not been called upon. Then I add ever more +fiendishness to the test routine, until more than 99\%\ of the code +has been used at least once. (The remaining bits are things that +can occur only if the source program is really huge, or if certain +fatal errors are detected; or they are cases so similar to other well-tested +things that there can be little doubt of their validity.) + +Of course, this is not guaranteed to work. But my experience in 1960 was +that only two bugs were ever found in that {\mc ALGOL} compiler after it +correctly translated that original fiendish test. And one of those bugs +was actually present in the results of the test; I simply had failed to +notice that the output was incorrect. Similar experiences occurred later +during the 60s and 70s, with respect to a few assemblers, compilers, +and simulators that I wrote. + +This method of debugging, combined with the methodology of structured +programming and informal proofs (otherwise known as careful desk checking), +leads to greater reliability of production software than any other +method I know. Therefore I have used it in developing \TeX82, and the +main bulk of this report is simply a presentation of the test program +that was used to get the bugs out of \TeX. + +Such a test file is useful also after a program has been debugged, since +it can be used to give some assurance that subsequent modifications don't +mess things up. + +The test file is called \.{TRIP.TEX}, because of my warped sense of humor: +\TeX\ is pronounced ``techhh'', so the name reminded me of a +triptych (and besides, I wanted to take a trip through the program while +tripping it up, etc.). + +The contents of this test file are so remote from what people actually +do with \TeX, I feel apologetic if I have to explain the correct +translation of \.{TRIP.TEX}; nobody really cares about most of the +nitty-gritty rules that are involved. Yet I believe \.{TRIP} exemplifies +the sort of test program that has outstanding diagnostic ability, as +explained above. + +If somebody claims to have a correct implementation of \TeX, I will not +believe it until I see that \.{TRIP.TEX} is translated properly. +I propose, in fact, that a program must meet two criteria before it +can justifiably be called \TeX: (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 \.{TRIP.TEX}. + +\TeX\ is in the public domain, and its algorithms are published; +I've done this since I do not want to discourage its use by placing +proprietary restrictions on the software. However, I don't want +faulty imitations to masquerade as \TeX\ processors, since users +want \TeX\ to produce identical results on different machines. +Hence I am planning to do whatever I can to suppress any systems that +call themselves \TeX\ without meeting conditions (1) and~(2). +I have copyrighted the programs so that I have some chance to forbid +unauthorized copies; I explicitly authorize copying of correct +\TeX\ implementations, and not of incorrect ones! + +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 a test of \TeX, given +a tape that contains copies of the other appendices. + +Appendix B is \.{TRIP.TEX}, the fiendish test file that has already +been mentioned. People who think that they understand \TeX\ are challenged +to see if they know what \TeX\ is supposed to do with this file. +People who know only a little about \TeX\ might still find it +interesting to study Appendix~B, just to get some insights into the +methodology advocated here. + +Appendix C is \.{TRIP.PL}, the property-list description of a +special font called \.{trip}. This is the only font used by \.{TRIP.TEX}. +There are no graphic characters associated with \.{trip} that could +possibly be printed; indeed, \.{TRIP.PL} describes the properties of a font +that is as weird as the ``document'' described by \.{TRIP.TEX}. + +Appendix D is \.{TRIPIN.LOG}, a correct transcript file \.{TRIP.LOG} +that results if \.{INITEX} is applied to \.{TRIP.TEX}. (\.{INITEX} is +the name of a version of \TeX\ that does certain initializations; +this run of \.{INITEX} also creates a binary format file called \.{TRIP.FMT}.) + +Appendix E is a correct transcript file \.{TRIP.LOG} that results if +\.{INITEX} or any other version of \TeX\ is applied to \.{TRIP.TEX} +with format \.{TRIP.FMT}. + +Appendix F is \.{TRIP.TYP}, the symbolic version of a correct output +file \.{TRIP.DVI} that was produced at the same time as the \.{TRIP.LOG} +file of Appendix~E. + +Appendix G is \.{TRIPOS.TEX}, a short file written out and read in +by \TeX\ when it processes \.{TRIP.TEX}. + +Appendix H is \.{TRIP.FOT}, an abbreviated version of Appendix E that +appears on the user's terminal during the run that produces \.{TRIP.LOG} +and \.{TRIP.DVI}. + +The debugging of \TeX\ and the testing of the adequacy of \.{TRIP.TEX} +could not have been done nearly as well as reported here except for +the magnificent software support provided by my colleague David R. Fuchs. +In particular, he extended our local Pascal compiler so that +frequency counting and a number of other important features were added +to its online debugging abilities. + +The method of testing advocated here has one chief difficulty that deserves +comment: I had to verify by hand that \TeX\ did the right things +to \.{TRIP.TEX}. This took many hours, and perhaps I have missed +something (as I did in 1960); I must confess that I have not checked +every single number in Appendices E and~F. However, I'm willing to pay +\$327.68 to the first finder of any remaining bug in \TeX, and I will +be surprised if that bug doesn't show up also in Appendix~E. (I plan to +write a technical report about all of the errors ultimately found in \TeX; that +report will tell whether any bugs are discovered between now and~then!) + +\vfill\eject + +\section Appendix A: How to test \TeX. + +\item{0.} Let's assume that you have a tape containing \.{TRIP.TEX}, +\.{TRIP.PL}, \.{TRIPIN.LOG}, \.{TRIP.LOG}, \.{TRIP.TYP}, and \.{TRIP.FOT}, +as in Appendices B, C, D, E, F, and~G. Furthermore, let's suppose that you +have a working \.{WEB} system, and that you have working programs \.{TFtoPL}, +\.{PLtoTF}, \.{DVItype}, as described in the \TeX ware report. + +\item{1.} Use \.{PLtoTF} to convert \.{TRIP.PL} into \.{TRIP.TFM}. +Then use \.{TFtoPL} to convert \.{TRIP.TFM} into \.{TMP.PL}. Check that +\.{TMP.PL} is identical to \.{TRIP.PL} (this is a partial test of \.{PLtoTF} +and \.{TFtoPL}). Install \.{TRIP.TFM} in the standard file area for +\TeX\ font metric files. + +\item{2.} Prepare a special version of \.{INITEX}. (This means that your \.{WEB} +change file should have {\bf init} and {\bf tini} defined to be null.) +The {\bf stat} and {\bf tats} macros should also be null, so that +statistics are kept and other special features are enabled. Set +\\{mem\_min} and \\{mem\_bot} equal to~1, and set \\{mem\_top} and +\\{mem\_max} equal to~3000, for purposes of this test version. Also set +$\\{error\_line}=64$, $\\{half\_error\_line}=32$, and +$\\{max\_print\_line}=72$; these parameters affect many of the lines of +the test output, so your job will be much easier if you use the same +settings that were used to produce Appendix~E. You probably should also +use the ``normal'' settings of other parameters found in \.{TEX.WEB} +(e.g., $\\{stack\_size}=200$, $\\{font\_max}=75$, etc.), since these show +up in a few lines of the test output. Your test version should not +change the default definition of unprintable characters (\S49 of the program). + +\item{3.} Run the \.{INITEX} prepared in step 2. In response to the first +`\.{**}' prompt, type carriage return (thus getting another `\.{**}'). +Then type `\.{\char`\\input trip}'. You should get an output that matches +the file \.{TRIPIN.LOG} (Appendix~D). Don't be alarmed by the error +messages that you see, unless they are different from those in Appendix~D. + +\def\sp{{\char'40}} +\item{4.} Run \.{INITEX} again. This time type `\.{\sp\&trip\sp\sp trip\sp}'. +(The spaces in this input help to check certain parts of \TeX\ that +aren't otherwise used.) You should get outputs \.{TRIP.LOG}, \.{TRIP.DVI}, +and \.{TRIPOS.TEX}; there will also be an empty file \.{8TERMINAL.TEX}. +Furthermore, your terminal should receive output that matches \.{TRIP.FOT} +(Appendix~H). During the middle part of this test, however, the terminal +will not be getting output, because \.{\char'134batchmode} is being +tested; don't worry if nothing seems to be happening for a while---nothing +is supposed to. + +\item{5.} Compare the \.{TRIP.LOG} file from step 4 with the ``master'' +\.{TRIP.LOG} file of step~0. (Let's hope you put that master file in a +safe place so that it wouldn't be clobbered.) 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 encourages +non-English help messages in versions of \TeX\ for people who don't +understand English as well as some other language. + +\itemitem{f)} The total number and length of strings at the end may well +be different. + +\itemitem{g)} If your \TeX\ uses a different memory allocation or +packing scheme or \.{DVI} output logic, the memory usage statistics may change. + +\item{6.} Use \.{DVItype} to convert your file \.{TRIP.DVI} to a file +\.{TRIP.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 \.{TRIP.TYP} file of step~0, +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~F. +(If your \.{DVI}-writing routines differ substantially from those in +\.{TEX.WEB}, you may want to write a \.{DVIcompare} program that +detects any substantive differences between two given \.{DVI} files. Such +a routine would be of general use besides. +On the other hand, if you have set \\{dvi\_buf\_size} to 800, then your +\.{DVI} file should be virtually identical to the one supplied.) + +\item{7.} You might also wish to test \.{TRIP} with other versions of +\TeX\ (i.e., \.{VIRTEX} or a production version with other fonts and +macros preloaded). It should work unless \TeX's primitives have been +redefined. However, this step isn't essential, since all the code of +\.{VIRTEX} appears in \.{INITEX}; you probably won't catch any more errors +this way, unless they would already become obvious from normal use of +the~system. + +\vfill\eject + +\section Appendix B: The \.{TRIP.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 B: \.{TRIP.TEX} (CONTINUED)} + +\vskip 8pt +\begingroup\count255=0 +\everypar{\global\advance\count255 by 1 + \hbox to 20pt{\sevenrm\hfil\the\count255\ \ }} +\verbatim{trip.tex} +\endgroup +\vfill\eject + +\section Appendix C: The \.{TRIP.PL} file. +The ``font'' defined here has only a few characters, but they include all +the complexities that \TeX\ must deal with: ligatures, kerns, +lists of characters, and extensible characters. Some of the dimensions +are negative, just to make things worse yet. (The format of property-list +files like this is explained in the documentation to \.{PLtoTF}, in +the \TeX ware report.) +\runninghead{APPENDIX C: \.{TRIP.PL} (CONTINUED)} + +\vskip8pt +\verbatim{trip.pl} +\vfill\eject + +\section Appendix D: The \.{TRIPIN.LOG} file. +When \.{INITEX} makes the \.{TRIP.FMT} file, it also creates a file called +\.{TRIP.LOG} that looks like this. +\runninghead{APPENDIX D: \.{TRIPIN.LOG} (CONTINUED)} + +\vskip8pt +\verbatim{tripin.log} +\vfill\eject + +\section Appendix E: The \.{TRIP.LOG} file. +Here is the major output of the \.{TRIP} test; it is generated by running +\.{INITEX} and loading \.{TRIP.FMT}, then reading \.{TRIP.TEX}. +\runninghead{APPENDIX E: \.{TRIP.LOG} (CONTINUED)} + +{\let\tt=\eighttt\leftskip 1in\baselineskip 9pt plus .1pt minus .1pt +\vskip8pt +\verbatim{trip.log} +} +\vfill\eject + +\section Appendix F: The \.{TRIP.TYP} file. +Here is another major component of the test. It shows the output of \.{DVItype} +applied to the file \.{TRIP.DVI} that was created at the same time +Appendix E was produced. +\runninghead{APPENDIX F: \.{TRIP.TYP} (CONTINUED)} + +{\let\tt=\eighttt\leftskip 1in\baselineskip 9pt plus .1pt minus .1pt +\vskip8pt +\verbatim{trip.typ} +} +\vfill\eject + +\section Appendix G: The \.{TRIPOS.TEX} file. +This short file was written out once and read in twice, during the time +Appendix E was being produced. There are only three lines, the first of +which is blank. +\runninghead{APPENDIX G: \.{TRIPOS.TEX} (CONTINUED)} + +\vskip8pt +\verbatim{tripos.tex} +\vfill\eject + +\section Appendix H: The \.{TRIP.FOT} file. +This shows what appeared on the terminal while Appendix E was being produced. +\runninghead{APPENDIX H: \.{TRIP.FOT} (CONTINUED)} + +\vskip8pt +\verbatim{trip.fot} + +\vfill\end |