TeXDoc.tioga
Pavel, October 12, 1985 4:13:06 pm PDT
TEX in CEDAR
CEDAR 6.0 — FOR INTERNAL XEROX USE ONLY
TEX
Donald E. Knuth, Michael Plass, Lyle Ramshaw, and Pavel Curtis
© Copyright 1985 Xerox Corporation. All rights reserved.
Abstract: The TeX82 document compiler has been ported from Pascal to Cedar, and this document describes how to run it in Cedar. This document is somewhat obsolete, but Pavel hasn't had time to update it sufficiently. Talk to Pavel if you have problems.
Created by: Donald E. Knuth, Michael Plass, Lyle Ramshaw
Maintained by: Pavel Curtis <Pavel.pa>
Keywords: TeX82, formatting, documents, typesetting
XEROX  Xerox Corporation
   Palo Alto Research Center
   3333 Coyote Hill Road
   Palo Alto, California 94304

For Internal Xerox Use Only
What is TeX?
TeX82 is a document compiler that does a good job of typesetting complex mathematical formulas. The definitive guide to TeX82 is a book entitled The TeXbook, written by the TeX's creator, Prof. Donald E. Knuth of Stanford University. Michael Plass and Lyle Ramshaw ported TeX82 from Pascal to Cedar, building on Edward McCreight's PasMesa, a Pascal-to-Mesa translator. This note describes how to run the Cedar incarnation of TeX.
How does one get started?
Getting the documentation
You won't get far running TeX without the official documentation. Acquire a copy of The TeXbook, and browse through it a little. You'll enjoy the illustrations at the start of each chapter, drawn by Duane Bibby.
Getting the right files
To get the files that you need to run TeX, find a CommandTool and execute the command ``Bringover -p [Cedar]<CedarChest6.0>Top>TeX.df''. Since you are reading this memo, perhaps you have already done such a Bringover, in which case all is well.
Setting up your user profile
Before you can run TeX, you must tell TeX where to look for certain auxiliary files by putting new entries into your user profile. Open a viewer on your user profile, and open another viewer on the file named TeX.profileSlice, which came over as part of the Bringover above. Copy the profile entry suggestions in TeX.profileSlice into your profile, and save the result.
Running TeX for the first time: Experiment 1
Turn to Chapter 6 of The TeXbook, and follow the instructions on page 23. You invoke TeX in Cedar by typing ``TeX'' to a CommandTool.
In Cedar, TeX writes a Press file rather than a DVI file. You can print a Press file named ``texput.press'' by typing ``TSetter Menlo texput.press'' to the Commander. (If you would rather have a DVI file for some reason, you can ask TeX to write its output in that format instead by changing one of the user profile options that you inserted above.)
Typesetting the sample story: Experiments 2-5
Turn to page 24 of The TeXbook. Now, I know that you are too lazy to type anything; but never fear! Another file that came over during the Bringover above was the file named ``story.tex'' given on page 24. Open a viewer on story.tex, and glance through it.
Does the third line look like this:
\centerline{\bf A SHORT STORY}
or like this:
\centerline{\bf A SHORT STORY} ?
If it looks like the former, just plunge on. But if it looks like the latter, something is wrong, because I prepared the file ``story.tex'' in TeX style. The style of a document tells Tioga how the information in that document should be displayedin particular, what font to use. TeX uses a different character coding scheme than the Xerox standard, and much confusion will probably result from this. One way to attempt to nip this confusion in the bud is to arrange that source files for TeX are always viewed in TeX style, which means that they will be displayed in a font (named AMTEX) with the TeX character code mapping. The TeX style is defined in the file ``TeX.style'', which came over in the Bringover along with everything else. If the third line of your story doesn't look like the former possibility right off, play around a while to see if you can fix it. You might try opening the EditTool, filling in the ``Style name:'' field with the string ``TeX'', and then clicking ``LoadStyleDefinition''. (If you brought over TeX to a local directory other than the root, you might have to put that working directory name in the ``Style name:'' field as well.) If the third line still looks wrong, make the viewer containing story.tex iconic and then open it again. If that doesn't fix it, consult a wizard.
Now you are ready to try Experiment 2, discussed on page 25. The result will be Story.press rather than Story.dvi, and you can get a hardcopy by issuing the command ``TSetter Menlo Story.press''.
You may type ``TeX story'' all on one line if you like, instead of waiting for the ``**'' prompt, as discussed in the paragraph at the top of page 26. In fact, you may go a little further and perform the whole of Experiment 2 by typing ``TeX story \end'' as one command; or go further still and repeat the whole of Experiment 1 by typing ``TeX \relax Hello? \end''.
After correcting the typographical error in story.tex, go on to Experiment 3. The Cedar implementation of TeX reports the locations of problems in your source file by giving character numbers instead of line numbers. To find the relevant place in your document, select the character count that TeX gives and then click the ``Position'' button at the top of the viewer containing your document. The left end of the thick black bar that appears when you click ``Position'' is the position that TeX is bringing to your attention; of course, in the case of errors, the real source of the error may be much earlier in your file. In TeX's messages, read the abbreviations ``c.'' as ``character'' and ``cc.'' as ``characters'', by analogy with ``p.'' for ``page'' and ``pp.'' for ``pages''.
Experiments 4 and 5 should proceed without any surprises, as discussed in The TeXbook. Note that the ``E'' response to an error message isn't very helpful in Cedar. Through the wonders of the multi-window Cedar interface, you can edit any file you please at any time without any special help from TeX.
Congratulations, you are now started as a user of TeX82.
What files are there?
When you do a Bringover of TeX, you will get the following files:
TeX.bcd: This is the code of TeX itself.
TeX.pool: This is an auxiliary file that TeX uses to get around the lack of decent strings in the Pascal programming language.
TeX.load: This is a command file that describes how to load TeX into a Cedar environment. TeX uses the same underlying utilities for writing Press files as the TSetter, so this load file loads the TSetter first, and then loads TeX. For good but subtle reasons related to the use of PasMesa, the start code of TeX doesn't register the real TeX commands. Instead, it registers a ``dummy command'' named (confusingly enough) ``TeX''. The last thing that the load file does is to execute this dummy command, which registers the three real TeX commands, which are discussed below.
TeX.profileSlice: TeX determines several default file directories and file names by looking for entries in your user profile. This file contains the standard settings for these options. If you are a beginner, just copy this file into your profile. The names and meanings of these profile entries are discussed in detail below.
TeX.style: The source files that you prepare when using TeX will use the ASCII character code, or an extension thereof, not the Xerox character code. In order to prevent confusion in the cases where these codes differ, it is helpful to look at your TeX sources in a font set up according to the ASCII codes. If you apply TeX.style to your source file, you will be looking at it in the font AMTEX10, which has the full TeX character set, an extension of ASCII. More details on this anon.
TeX.tip: The character code value 140 (octal) is a left single quote in both the Xerox and the ASCII codes. Unfortunately, there is no easy way to type this character to Tioga. In addition, there are valuable non-ASCII characters in the TeX character code that you might want to be able to type conveniently. You can achieve this goal by layering a new TIP table on top of the default TIP table. The file TeX.tip suggests what such a new layer might look like. Before you try using it, read the discussion of character codes below.
Story.tex: This is the example story from page 24 of The TeXbook, with the TeX style applied.
TeXDoc.tioga: The file you are reading now.
Plain.tex: This file contains all of the standard definitions that make up the Plain format for TeX.
Waits.tex: There was a version of TeX before TeX82, written in the programming language SAIL. In retrospect, it has been named TeX78. Source files that worked with TeX78 will not, in general, work with TeX82 because many things have changed. For example, where you said ``\biglp'' in TeX78, you must now say ``\bigl('' in TeX82. The file Waits.tex is a collection of macro definitions that may help you a little in the process of converting your TeX78 documents to TeX82. For example, it defines ``\biglp'' to be a control sequence that expands into ``\bigl(''.
TSetter and its friends: Since TeX82 needs these files because it loads the TSetter.
In addition, you will get an auxiliary DF file named TexWeb.df. This file describes all of the files that are distributed as part of the release of TeX from Stanford, and where to find them on our file servers. If you would like to see exactly what is available, look at the file named ``-read-.me'', described in TexWeb.df. I will just mention here a few files that might be intriguing:
-Read-.me: A description of all of the files in the TeX release from Stanford.
Tangle.web: The source of Knuth's Tangle processor, the Pascal-writing half of the Web programming system. Tangle is also available in Cedar, via the DF file Tangle.df.
Weave.web: The source of Knuth's Weave processor, the half of the Web system that produces TeX source for beautiful program listings. Weave is not yet available in Cedar, although it should only take a few days work to make it so, should someone be willing to try.
WebMac.tex: The macro definitions that are used by Weave when preparing pretty listings of Web programs.
PoolType.web, DviType.web, TFtoPL.web, PLtoTF.web: These utility programs are all available in Cedar via DF files with the corresponding names.
Tex82.dif: A description of the differences between TeX78 (the one in SAIL) and TeX82.
Hyphen.tex: A text file containing the hyphenation patterns used by Plain TeX.
Trip stuff: Files used to perform a thorough test of a port of TeX; the Cedar TeX has passed the TRIP test.
AmSTeX: The sources for Mike Spivak's extended format, written for the American Mathematical Society.
Errata.tex: A list of all the known bugs in The TeXbook.
What commands does TeX register?
Once you have loaded TeX, you will have access to three new commands: TeX, IniTeX, and InterruptTeX. The third is the easiest to explain, so we shall discuss it first. If TeX is in the middle of a long job, you can stop TeX dead in its tracks by clicking the ``STOP!'' button at the top of the CommandTool. But you might want to examine TeX's internal state, or you might want to make TeX pause in such a way that it could pick up again later. To do these things, get yourself another CommandTool (by clicking the ``Cmd'' button at the top of the screen) and execute the command ``InterruptTeX'' there. This will notify TeX that you would like it to pause and ask you for instructions at the next convenient opportunity.
By the way, TeX can only work on one job at a time, since it stores lots of information in its global frames. Suppose that you have one CommandTool, in which you have asked TeX to typeset a file. If you get yourself another CommandTool and ask TeX to start work on a second file while it is still chewing on the first one, the second request will just sit and wait until the first run is complete.
In order to understand the difference between the other two commands that TeX provides, we should discuss what happens on a standard timesharing machine. Such machines usually come with three versions of TeX. First, there is IniTeX, the most powerful of the three. IniTeX can read the ``pool'' file in order to initialize TeX's string-handling mechanisms; it can also take a set of hyphenation patterns and crunch them down into a compact data structure that can be searched at high speed; in general, it can build up a TeX world from scratch. The production version of TeX is named VirTeX. VirTeX can't do the initializations that IniTeX can, but, in compensation, VirTeX often has more memory capacity. VirTeX initializes itself by reading in a format file, with extension ``.fmt'', a snapshot of TeX's tables that IniTeX produces. In you take a VirTeX, load in the format file ``plain.fmt'', and then save the result away so that it can be reloaded rapidly, the result is the standard TeX.
In Cedar, the situation is somewhat different. The Cedar architecture has no provision for saving a program away with its tables initialized so that it can be loaded again rapidly (other than taking a Checkpoint, which is rather drastic). In addition, having code around that never gets executed is not very expensive in Cedar. As a result, there is only one TeX in Cedar rather than three, and it has all the power of IniTeX. But there are two different commands for invoking this one TeX, because TeX and IniTeX behave differently on startup. If you say ``TeX story'', TeX will initialize itself with your default format and then input the file ``story.tex''. If you say ``IniTeX story'', TeX will assume that ``story.tex'' is a macro file intended to produce a new format from scratch, and it will start reading it in without reading a format file first. Once the Cedar TeX is off and running, it behaves like an IniTeX no matter how you invoked it; that is, it is able to perform both ``\dump'' (which writes a format file) and ``\patterns'' (which builds a hyphenation trie).
One closing word about the capacities of things: I have set the various limits of the Cedar TeX on memory size, number of fonts, and the like to be at least as high as the current limits of TeX on TOPS-20 and TeX on VMS. Many of these limits could be expanded still further without much work by having a wizard recompile TeX.
What profile options do I have?
TeX looks for four parameters in your user profile.
TeX.PrintFileFormat: The legal values are Press or DVI, with the obvious meanings. The default value is Press.
TeX.DefaultInputsDirectory: When TeX is trying to read the input file ``foo.tex'', it first tries to open ``foo.tex'' in the current working directory. If this fails, it will try one more time, looking on the directory that you specify here instead. Note that the extension of input files defaults to ``.tex'', as specified in The TeXbook. If your input file name includes explicit directory information, the directory stuff will be stripped off during the second try when TeX looks in your default inputs directory. The default value for this is ``/Cyan/TeX/Inputs''.
TeX.DefaultFontMetricsDirectory: Each time that you declare a new font, TeX must read a ``TeX font metric'' file in order to find out how big the characters in that font are. The lookup of font metric files works differently than the lookup of regular input files discussed in the previous paragraph. TeX makes only one try for font metrics. If the font file name that you specify includes explicit directory information, TeX will try the file name that you gave. In the more common case where your font file name has no directory stuff, TeX will prepend the default font metrics directory that you have specified. The default value for this is ``///Fonts/FontMetrics/''.
TeX.DefaultFormatFile: This entry is used for two purposes. The entire entry is the name of the format file that TeX will try to load if you don't specify an explicit format name such as ``&myformat''. In addition, the directory portion of this name serves as the default directory for all format files, in a way analogous to the default inputs directory discussed above. The default value for this is ``/Cyan/TeX/Formats/Plain.fmt''.
Character codes
It is Don Knuth's official policy that source files for TeX be written in the ASCII character set or, if an extended character set is desirable, in a particular extended character set described in Appendix C of The TeXbook. We shall call this latter character set ``the TeX character set''; it was developed at MIT. The TeX character set is a strict superset of ASCII.
Most fonts at Xerox use a slightly different character set, which we shall call the Xerox character set. Sad to say, the Xerox set is not a strict superset of ASCII. In particular, there are conflicts concerning the character code values 136 (octal) and 137 (octal). In the Xerox character set, 136 is an up-arrow and 137 is a left-arrow. In ASCII, 136 is a circumflex and 137 is an underline. This discrepancy is an unfortunate thing; but we have to live with it. For all of the other printing character codes (from 040 through 176), the Xerox and ASCII systems agree.
I shall propose one way to handle this character set problem, based on the files TeX.style and TeX.tip. Other policies are possible, but I recomend that you read the following to understand the rationale behind my scheme before rushing out to design your own more wonderful scheme.
First, I propose that TeX in Cedar shall assume that its input files are given in the TeX character set, in accord with Knuth's policy mentioned above. This will dramatically improve the possibilities for shipping TeX source files between our machines and computers elsewhere and having everything work correctly. In order to avoid confusion about the characters associated with the codes 136 and 137, TeX source files should always be examined in a font with the correct character code mapping. There are currently two such fonts available: LPT, an MIT lineprinter font, and AMTEX, distributed with the TeX release. Both of these fonts are fixed-width fonts, I'm sorry to say. It would be relatively easy to produce a variable-width font with the correct character set for use on the screen; but getting such a font at printer resolution and installing it on printers would be much more work. I recommend that people look at TeX sources in the AMTEX font, which is what will happen if you apply TeX.style to your source files.
What about the codes 136 and 137? Well, no matter what you are typing, a TeX source file or anything else, you type the code value 137 by pushing the key with the two arrows on it and you type the code value 136 by pushing that key with the shift key held down. If you are typing to a file in the Xerox character set, the characters that appear will look like the arrows on the keytop. If you are typing a TeX source file in TeX.style, you will see an underline instead of a left-arrow and a circumflex instead of an up-arrow. Life is hard. Note that Plain TeX sets things up so that underline is a valid subscript character and circumflex is a valid superscript character. Thus, you can type subscripts and superscripts in one keystroke; they just look funnyjust as funny as in The TeXbook.
Left single quote is something of a problem. This character is assigned the code 140 (octal) in both the Xerox and the ASCII character mappings. But most people don't bother to use left single quotes when typing in Tioga, because there is no easy way to type one. The Tioga command SingleQuoteBrackets will surround the current selection by putting a left single quote on the left and a right single quote on the right. Thus, if the current selection is just the insertion caret, you can type a left single quote in two keystrokes as follows: first type <control><quote> to bracket the caret in single quotes; then type <shift><backspace> to delete the right single quote. But this is sort of a pain. I find that it is more convenient to be able to type a left single quote in one keystroke. This can be achieved by layering a new TIP table on top of the default TIP table. In TeX.tip, I suggest changing the behavior of the quote key as follows:
<quote>: inserts a right single quote character, just as before.
<shift><quote>: inserts a symmetric double quote character, just as before. This ugly character is useless when typing manuscripts, but is essential for typing in ropes in Cedar programs. Note that any changes you make to your TIP tables apply to all Tioga documents, not just to TeX source files.
<control><quote>: inserts a left single quote character, rather than invoking SingleQuoteBrackets.
<control><shift><quote>: invoke SingleQuoteBrackets, rather than DoubleQuoteBrackets (which is not as useful).
You may have other ideas about how to handle the problem of left single quote. If so, more power to you. But remember that you don't want to interfere with existing Tioga commands that you will want at other times. Also, there is substantial benefit to be had from keeping your user interface as simple, as consistent, and as much like everyone else's as possible.
A few comments about mechanics: TIP table specifications are pretty easy to write, and TeX.tip is a good example of how to do simple things. In order to layer TeX.tip on top of the default TIP table in your Cedar world, you must edit your user profile to say ``TiogaTIP: TeX.tip Default''. Then, you must invoke the command ``ReadTiogaTipTables'' in order to make the change take effect.
You have your choice about whether to use only ASCII or the extended TeX character set in your source files. The former choice improves portability to other TeX installations, while the latter is more convenient here. The extended character set includes various useful characters. It includes an up-arrow and a down-arrow at 013 (=^K) and 001 (=^A) respectively. Plain TeX sets things up so that these also act as a superscript and a subscript character; and they look better in your source files. There are only two problems with using them: first, they are not in standard ASCII, so you are hurting your portability; second, they are hard to type. You can type them in two keystrokes by typing {<K>; <control><K>} or {<A>; <control><K>}, but two keystrokes is a lot worse than one. You could change your TIP table so that they could be typed in one keystroke; but the problem then is what keytop to assign them to. Our keyboards are already pretty loaded, and most reasonable combinations of keys already mean something useful. Pushing the <arrows> key by itself gives 137, which you certainly need for Cedar programs even if you didn't want it for TeX; <shift><arrows> gives 136, also used in Cedar; and <control><arrows> and <shift><control><arrows> are useful for reading and writing the format of a Tioga node.
There are other extended characters that you might enjoy. I am particularly fond of the characters for not-equals, less-than-or-equals, and greater-than-or-equals. My suggested TIP table TeX.tip sets things up so that these characters can be typed by typing <control><equals>, <control><comma>, and <control><period> respectively. You might enjoy using these characters, or you might want to change your TIP table to get at different extended character codes in one keystroke.
Using Xerox fonts from TeX
Xerox fonts do not follow the magnification scheme that the AMR fonts do. If you want to typeset something in TimesRoman10, for example, you should ask for ``\font\tr=timesroman at 10truebp''. The name after the equals sign is the file name of the TeX font metric file. You can find out what TeX font metric files exist by listing the appropriate directory. Note that one metric file describes all sizes of TimesRoman, since the characters in TimesRoman just scale photographically to become different sizes. You should specify the size that you want by giving an ``at'' clause. And you should use ``truebp'' as the unit; ``true'' to prevent magnification from having effect, and ``bp'' because Xerox fonts are sized in ``big points'' rather than TeX ``pt'' small points. Be aware that Xerox fonts tend to run large; you have to magnify AMR10 by a half-step in order to make it look about the same size as TimesRoman10.
Notes for hackers and wizards
There are various more devious ways of trying to address the problem raised by character codes 136 and 137. For example, one might make up a font that was like AMTEX in every way except that 136 and 137 came out as arrows. Or even hackier still: it is rumored to be possible to call an arbitrary Cedar procedure from a TIP table. Hence, it might be possible to layer a TIP table on top of Default in which depressing the <arrows> key caused a proc to run which would look at the file name of the file in the selected viewer to see if the extension was ``.tex'' or not, and do different things in the two cases. The mind boggles at the levels of confusion that might result from this type of hackery.
There is a separate memo called BuildingTeX.tioga, available through TeX.df, which describes how to compile the Cedar TeX, in case its limits should need to be expanded or in case conversion to a new release of Cedar should become necessary.