OzTEX User Guide

Version 1.3, September 1990 Andrew Trevorrow

1-3-37 5th St., Habsiguda Hyderabad 500007, India

OzTEX is a public domain version of TEX for the Macintosh. This document assumes you know how to use a Macintosh. It also assumes you are familiar with TEX, the typesetting system developed by Donald Knuth at Stanford University. An understanding of PostScript, the page description language developed by Adobe Systems, is not essential but would be useful, especially if you want to include graphics in your documents.

OzTEX aims to provide a standard TEX environment for the Macintosh that can be easily extended or customized. If you already have access to TEX on some other computer, particularly a VAX/VMS or UNIX mainframe, then the way OzTEX works shouldn’t be too surprising.

Your comments, bug reports and suggestions are all welcome. I am still interested in doing further development of OzTEX and would like to hear from people willing to sponsor such work.

Contents

1 Installing OzTEX 1 1.1 What you should have . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 Where to put things . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.3 Installing the editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.4 Changing the default configuration file . . . . . . . . . . . . . . . . . . . . . . . . 3 1.5 Creating other configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.6 Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.6.1 TFM files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.6.2 PK files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.6.3 Macintosh screen fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.7 Transferring TFM/PK/DVI files . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2 A quick tour of OzTEX 7 2.1 Starting OzTEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.2 Editing a TEX input file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.3 Running TEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.4 Viewing a DVI file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.4.1 Paper coordinates and the scale factor . . . . . . . . . . . . . . . . . . . . 9 2.4.2 Zooming in and out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.4.3 Scrolling around . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.4.4 Checking for errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.4.5 Selecting pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.5 Printing a DVI file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.5.1 Changing print options . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.5.2 The printing process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.5.3 Saving output in a file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.5.4 Positioning pages correctly . . . . . . . . . . . . . . . . . . . . . . . . . . 11

3 OzTEX’s menus 12 3.1 The File Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.2 The Edit Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.3 The TEX Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.4 The View Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.5 The Config menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 3.6 The Help Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4 Mixing PostScript and TEX 18 4.1 Using PostScript fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 4.2 Including PostScript graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

5 Recovering from errors 20 5.1 Errors when running TEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 5.2 Errors when viewing a DVI file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 5.3 Errors when printing a DVI file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

6 Further reading 22

1 Installing OzTEX

OzTEX should work on any Macintosh Plus, SE, II or newer model. It will not work on a 128K or 512K Mac. Because of the large amount of memory required to run OzTEX and the large amount of disk space needed to store all the font information, the minimum hardware configuration is probably a Mac Plus with 1MB of RAM and a 20MB hard disk

OzTEX can only print on a PostScript-compatible printer. If you plan to use an Apple LaserWriter (any model) then installation should be straightforward. (People with some other type of printer, like an ImageWriter, should try James Walker’s DVIM72-Mac program. Note that you’ll need a set of PK files to match your printer’s resolution.)

1.1 What you should have

OzTEX is distributed on ten 800K disks. Here is a brief description of what each disk should contain:

1. The OzTeX disk has a StuffIt archive which contains the OzTEX application and the following folders:

• Configs, containing various configuration files.

• TeX-fonts, containing TFM files.

• Help-files, containing a few short text files.

• PS-files, containing various PostScript files.

• TeX-docs, containing examples of TEX input files.

• LaTeX-docs, containing LaTEX input files (including this User Guide).

• ΣEdit, containing the ΣEdit desk accessory and its documentation.

• DVIM72-Mac, containing the DVIM72-Mac program and its documentation.

• PK-files, empty and waiting to receive the folders stored in disks PK-1 to PK-5.

This disk also contains a Read-Me file and UnStuffIt for unpacking StuffIt archives.

2. The Formats disk has a StuffIt archive which contains the TeX-formats folder. This is the default location for TEX’s fmt files and the TeX.pool file read by INITEX.

3. The Inputs disk has a StuffIt archive which contains the TeX-inputs folder. TEX looks for input files in this folder if it can’t find them in your current folder.

4. PK-1 contains the folders 300 and 746.

5. PK-2 contains the folders 329 and more-746.

6. PK-3 contains the folders 360 and 622.

7. PK-4 contains the folders 432 and more-622.

8. PK-5 contains the 518 folder. The name of each folder in these last five disks indicates the “size” of the PK files kept within the folder. See section 1.6.2 for how this size is calculated and for more information about PK files.

9. The Sources disk has a StuffIt archive which contains the Modula-2 and MPW source files for OzTEX. (SPECIAL BONUS OFFER — this disk also contains LifeLab.)

10. The WEBtoMOD disk has a StuffIt archive which contains the MPW tools and scripts used to translate tex.web into Modula-2.

None of the files on the last two disks are actually needed to run OzTEX, so forget them if you’re not interested. See the OzTEX System Guide if you are interested.

1.2 Where to put things

Assuming you have enough disk space, carry out the following steps:

1. Create an empty folder somewhere on your hard disk and call it anything you like.

2. Copy the contents of disks OzTeX, Formats and Inputs into this folder. Use UnStuffIt to unpack the sit files.

3. Copy the contents of disks PK-1 to PK-5 into the PK-files folder.

4. Open the PK-files folder and move the files inside more-746 into 746, and the files inside more-622 into 622, and then delete the emptied folders.

Your screen should now look something like this:

You may not have enough disk space to store everything, so let’s consider the bare essentials needed for a working OzTEX system:

• You’ll need the OzTEX application of course, and the Configs folder.

• Most of the files in TeX-fonts, Help-files and PS-files are quite small so you won’t save much disk space by pruning these folders.

• TeX-docs and LaTeX-docs contain OzTEX’s documentation and sample input files, none of them critical. Remove both these folders if it makes you happier. Note however that nasty.tex is used in the quick tour below.

• The ΣEdit folder can be deleted after you’ve used the Font/DA Mover to install ΣEdit (assuming you want to use it).

• The DVIM72-Mac folder can be deleted if you don’t need this program.

• If you only ever use one format then remove the other format files in TeX-formats. Don’t delete TeX.pool though — it’s needed by INITEX.

• If you don’t use LaTEX then remove all the *.sty and *.doc files in TeX-inputs.

• The best way to save disk space is to forget about installing any PK files until you discover which ones you actually need. When viewing a DVI file, the “Page Info” item displays a list of all the fonts used in that document. Any font marked “DOES NOT EXIST” should be copied into the indicated folder in PK-files. Note however that the required PK file may not be supplied with OzTEX, especially if it has a large size (or if you asked for an unusual magnification).

1.3 Installing the editor

OzTEX does not contain an integrated text editor. Instead, a desk accessory editor called ΣEdit is supplied. The ΣEdit folder contains documentation (written by Leonard Rosenthol, the author of ΣEdit) and a DA file that can be used by the Font/DA Mover to install ΣEdit into your System file. You may of course prefer to use another editor. If so, you might as well throw away the ΣEdit folder.

1.4 Changing the default configuration file

OzTEX reads a configuration file called Default when starting up. This file is kept in the Configs folder along with other configuration files. (The name and location of the default configuration file are stored as STR resources in the application file, so you can easily change them using a resource editor like ResEdit.)

A configuration file is a simple text file which you can edit and change various parameters that control OzTEX’s behaviour. Some of the more important parameters are:

• A list of the configuration files that will appear at the bottom of the Config menu. This list should only appear in the Default file; it is ignored in every other configuration file.

• A list of the formats that will appear at the bottom of the TEX menu. Place your preferred format first.

• A list of the help files that will make up the Help menu. Feel free to add your own help files or remove them entirely (the Help menu won’t appear if the list is empty).

• The printer resolution and viewing resolution. The former is used when printing a DVI file and the latter when previewing. If you have a set of 72 dpi PK files then you could set the viewing resolution to 72; this value matches the resolution of the standard Mac screen, resulting in a more readable display (it’s also faster and uses much less memory).

• The paper dimensions used to detect page-off-paper errors when printing or viewing a DVI file. If the paper width is greater than the height then OzTEX will switch to landscape mode. The Default values specify A4 paper in portrait mode.

• The names of certain special folders: Help-files, TeX-formats, TeX-inputs, TeX-fonts,

PK-files and PS-files. The supplied strings are partial path names relative to the location of the OzTEX application, but you might prefer to store certain files elsewhere. For example, you could tell OzTEX to look for PK files on a different volume by changing the path name of the PK folder to “MyDisk:PK-files:”.

• The names and locations of special files: TEXTtoPS.ps, DVItoPS.ps, TeX.pool, etc.

• The colours of various elements (paper edges, \special markers and missing fonts) seen when viewing a DVI file. The allowed colours are black, red, green, blue, cyan, magenta, yellow and white (white is allowed in case you want to do something like make \special markers invisible).

• The values of important TEX parameters that determine how much memory will be allocated for certain arrays. The Default values are suitable for a Mac with 1MB of memory. If you have more memory then you may want to increase many of the parameters. If you do then you’ll need to increase OzTEX’s application memory size for use with MultiFinder (see the “Get Info” item in the Finder’s File menu). Note also that a change to some parameters will require the format file(s) you use to be rebuilt; see section 3.3.

• A list of all PostScript TFM file names and their corresponding printer-resident font names and screen font names. Each screen font has an encoding scheme (Adobe or Macintosh) and an optional style.

The Default configuration file contains many comments describing the purpose of each parameter and how to go about changing them. Before doing so it might be a good idea to save a copy first. In your new Default file you can then remove all the comments so that OzTEX starts up a little faster.

1.5 Creating other configuration files

OzTEX’s Config menu lets you switch rapidly from one configuration file to another. This is especially useful if you have access to more than one PostScript printer, since each printer might require a separate configuration file (they might have different resolutions or support a different set of resident fonts).

There are other uses for multiple configuration files. See the examples supplied in the Configs folder. It is a simple matter to create your own and add them to the list in the Default file. To help keep configuration files short and simple, a couple of special characters can be used:

1. If “?” is the first character of a parameter’s value then the parameter is not changed and the rest of the line is ignored.

2. “!” has the same effect as “?” but in addition all remaining parameters are left unchanged (the rest of the file is ignored).

Note that these characters are not recognized as special in the Default file since every parameter must be given a starting value.

If you are an experienced TEX user and think you know enough to try OzTEX out then skip the next few pages and start the quick tour on page 7.

1.6 Fonts

There are three different sources of font information used by OzTEX in the process of typesetting, previewing and printing a document: TFM files (usually stored in TeX-fonts), PK files (usually stored in various folders nested within PK-files), and Macintosh screen fonts (normally found in the System file).

1.6.1 TFM files

A TEX Font Metric file contains the crucial typesetting information about a font, such as each character’s height, depth, and width. The actual character images are not stored in a TFM file (that information is kept in PK files in the case of a non-PostScript font). TFM files are the only source of font information used when running TEX, since it doesn’t need to know anything about character images to be able to create a DVI file. See The TEXbook by Donald Knuth if you want to know more about how TEX uses fonts, especially Chapter 4 and Appendix F.

TEX looks for a TFM file in the current folder before looking in TeX-fonts. When you print or view a DVI file containing a PostScript font, OzTEX uses the same method to find the corresponding TFM file.

Most of the TFM file names in TeX-fonts begin with “cm”. These letters stand for Computer Modern, a family of fonts created by Donald Knuth using . All the PostScript TFM files supplied with OzTEX have names beginning with “ps-”; this is not required but does make them easy to recognize. If you want to change their names then remember to update your configuration file(s).

1.6.2 PK files

PK (packed pixel) files store the character images needed to print or view a DVI file containing non-PostScript fonts (those not appearing in the list at the end of the current configuration file). For each such font there is usually a number of PK files, each one representing the same font but at a different size. This size, which has no relation to the font’s design size, is calculated as follows:

size = resolution × magnification

where resolution is either the printer resolution or the viewing resolution, and magnification is the overall font magnification (i.e., the DVI magnification times the individual font scaling). The size is then rounded up to the nearest integer and should match (±1) one of the folder

names in PK-files.

Although TEX allows you to request a font at virtually any magnification, it is obviously impossible to provide an infinite number of PK files. The compromise solution is to provide a range of sizes for each font. These sizes are in a geometric ratio based on powers of 1.2 and correspond to TEX’s \magstep values. See Chapters 4 and 10 of The TEXbook for more details. For example, assuming a resolution of 300 and no document magnification:

TEX input  size  PK file

   \font\ra=cmr10  300 × 1.2^{0}  :PK-files:300:cmr10
   \font\rb=cmr10 scaled\magstephalf  300 × 1.2^{0.5} :PK-files:329:cmr10
   \font\rc=cmr10 scaled\magstep1  300 × 1.2^{1}  :PK-files:360:cmr10

TEX’s \magnification command has a cumulative effect on font scaling:

   \magnification=\magstep1             % document magnification = 1.2
   \font\bigrm=cmr10 scaled\magstep2    % font magnification = 1.44

The font size is now 300 × 1.2 × 1.44 = 518.4, so OzTEX will use :PK-files:518:cmr10.

\magstep can also be used with LaTEX’s \newfont command but you won’t need to do this very often because LaTEX provides a large number of predefined font styles and sizes. Note that LaTEX has no \magnification command — use the 11pt and 12pt style options to increase the size of all fonts in a LaTEX document.

The above information assumes all PK files with the same size are kept in separate subfolders within PK-files. This is a sensible approach to managing a large set of PK files but it is not actually required. For compatibility with other TEX systems OzTEX uses a flexible method to search for PK files. For example, suppose your TEX input file contains \font\xxx=foo (where foo is a non-PostScript font). If we assume the calculated size is 300 and the default PK folder is :PK-files: then OzTEX will look for:

1. foo.300pk (in the current folder)

2. :PK-files:foo.300pk (relative to the location of OzTEX)

   3. :PK-files:300:foo.300pk (ditto)
   4. :PK-files:300:foo  (ditto)

In fact, at each step OzTEX will also add and subtract 1 from 300 because rounding errors can occur in the size calculation. Note that step 2 allows you to keep all PK files in a single folder. If the desired PK file can’t be found, OzTEX displays a warning message and the dummy TFM file specified in the current configuration file is used instead.

There is still another possibility to consider: a font name with an explicit location. For example, your TEX input file might contain \font\xxx=:myfonts:foo. In this case TEX will look for :myfonts:foo.tfm relative to the current folder. If not found then it gives up; it does not look for foo.tfm in the default TFM folder. Similarly, when you print or view the DVI file OzTEX only looks for :myfonts:foo.tfm if foo is a PostScript font. If not a PostScript font it only looks for :myfonts:foo.300pk (then 301 and 299), assuming a calculated size of 300. The use of an explicit location is not recommended as it decreases the portability of your TEX input file.

All the PK files supplied with OzTEX have been specifically generated for a 300 dpi, writeblack laser printer (like the Apple LaserWriter). If your printer doesn’t have the same characteristics then you’ll need to get the correct PK files from some other source. If you use TEX on another computer then you might be familiar with GF or PXL files. PK files contain the same information but in a highly compressed format. Most mainframe TEX systems provide tools for converting GF or PXL files into PK files.

1.6.3 Macintosh screen fonts

When previewing a DVI file containing PostScript fonts (or missing fonts), OzTEX uses Macintosh screen fonts to simulate the characters. Just which screen fonts are used depends on the information in the current configuration file — see the bottom of the Default file for details.

If you use PostScript fonts a lot then for best previewing results you should get the matching Adobe screen fonts listed in the Default configuration file. If you don’t have matching screen fonts then there is a good chance that the simulated characters will appear incorrect, especially if they are non-alphabetic. The same problem occurs for simulated characters from missing fonts.

Text in the OzTEX window is always displayed using 9 pt Monaco. This should be a fixedwidth font. The OzTEX application has FOND and FONT resources for this font to avoid the possibility of using modified System resources. If you haven’t modified the System resources for the Monaco font then you can use ResEdit to delete the redundant FOND and FONT resources from the OzTEX application; you’ll only save about 2K though.

1.7 Transferring TFM/PK/DVI files

OzTEX reads standard TFM and PK files, and reads and writes standard DVI files. If you have access to TEX on some other computer system, particularly a VAX/VMS or UNIX mainframe, you should be able to move such files to and fro without any further processing.

For the purposes of data transmission a TFM/PK/DVI file must be treated as a “binary” file; i.e., a stream of arbitrary 8-bit bytes. When using Kermit to transfer binary files from another computer to your Mac, remember to type “set file type binary” before using the send command. The same goes for receiving such files from your Mac, but with one exception: to transfer a DVI file created by OzTEX to a VAX/VMS host you’ll need to type “set file type fixed” before using the receive command.

If you want to print or view a DVI file created by another TEX system then hold down the Option key while selecting “Print DVI … ” or “View DVI … ”. All file types will then be available for selection. (An alternative solution is to use a program like ResEdit to change the file type to “ODVI”.) If the file you choose is not a valid DVI file then a warning message will appear complaining about a “bad id byte”.

Note that a DVI file contains TFM file names; this can be a cause for concern if you plan to transfer DVI files from one TEX system to another with a different set of TFM files. This incompatibility is most likely to occur if you use PostScript fonts, since there is little agreement on how their corresponding TFM files should be named. If you have a choice, it’s always safer to transfer the original TEX input file so you can edit any incorrect font names.

2 A quick tour of OzTEX

The aim of this section is to get you quickly acquainted with OzTEX’s major features.

2.1 Starting OzTEX

Assuming you’ve installed everything, double-click on the OzTEX application file to get things started. After a brief pause you should see a window with the title “OzTEX” and a message indicating the name of the default configuration file. (If you made a mistake during installation, especially when editing the Default file, then you might also be looking at a dialogue box from which you can only quit. The message displayed will hopefully give you some idea of how to fix the problem.) The OzTEX window is always present; note that it has no close box in the upper left corner. This window provides a terminal-like interface in which nearly all of OzTEX’s textual output will appear.

The production of a TEX document typically involves a number of iterations through the following cycle: edit, typeset, preview and print. People concerned about our dwindling forests will hopefully preview many more times than they print. Let’s go through this cycle step by step.

2.2 Editing a TEX input file

A TEX input file is a standard Macintosh text file. We won’t create an input file from scratch; instead we’ll use one of the sample files provided in the TeX-docs folder. There is nothing special about this folder, or LaTeX-docs. I simply like to keep my TEX and LaTEX input files in separate folders. You can keep your input files anywhere you like.

The file we’ll use is called nasty.tex. As the name suggests, it is not a typical TEX input file, but it does illustrate most of the things you’ll encounter when using OzTEX in the future.

If you installed ΣEdit then choose this DA from the Apple menu, open the TeX-docs folder, and then open nasty.tex. If you aren’t using MultiFinder then a new ΣEdit menu appears at the end of the OzTEX menus and the Edit menu items are enabled.

The only change we’ll make to nasty.tex is to add a deliberate error: insert the illegal command \xxx at the start of the file. Save this change by hitting Command-S or choosing “Save” in the ΣEdit menu. Feel free to scroll up and down and have a look at the rest of the file, but don’t worry too much if you don’t understand everything. You might like to make more changes and experiment with how ΣEdit works. Just make sure you Revert to the saved version before continuing.

2.3 Running TEX

Let’s now typeset nasty.tex. Before starting TEX we need to make sure that the correct format will be used. All the available formats appear at the end of the TEX menu. Check this menu and see which format item is ticked. It should be “Plain”, unless you changed the format list in the Default configuration file. This is the format required by nasty.tex so we don’t need to change it. (To change the current format you simply select a different one.)

Choose “TEX … ” from the TEX menu and open nasty.tex. The OzTEX window will be cleared and brought to the front (if it isn’t already) and after a short pause TEX will start up, load the Plain format, and begin reading the given input file.

When it sees the unknown commmand, TEX will print a suitable error message, beep, and wait for you to type something. Note that the normal mouse pointer has disappeared and a block cursor sits next to TEX’s “?” prompt. This cursor always appears when TEX is waiting for you to type something. The OzTEX window should look like this:

   This is TeX, Version 3.0 (no format preloaded)
   **&Plain nasty.tex
   (nasty.tex
   ! Undefined control sequence.
   l.5 \xxx
   ?

Chapter 6 in The TEXbook explains what you can do in such a situation. What we will do is simply ignore the error and continue by hitting the Return key. Although nasty.tex is not very nice, you shouldn’t see any more TEX errors. A 19-page DVI file called nasty.dvi should be created.

Have a look at the second item in both the File and View menus. Whenever a new DVI file is created its name will automatically appear in these items so you can quickly print or view the DVI file without going through the standard file dialogue. The second item in the TEX menu has also been updated with the name of the most recent input file (nasty.tex in this case) so you can easily typeset the same file many times.

2.4 Viewing a DVI file

After generating a DVI file, the next step is to preview it and check for problems that TEX may have missed, like missing fonts, bad page breaks, spelling mistakes, etc.

Let’s have a look at nasty.dvi by choosing the second item in the View menu. OzTEX creates a new window, called the “view” window, and sets its title to the selected DVI file. A dialogue box has also appeared. It has a scroll bar that allows you to select any page in the DVI file. (The dialogue box also allows you to change a couple of viewing options, but we’ll ignore them at this stage; see the description of “View DVI … ” in section 3.4 for details.) Play around with the scroll bar if you like but make sure it shows the 2nd DVI page before proceeding. To view this page simply click in the View button or hit the Return key.

The 2nd page in nasty.dvi contains a single rule with some text below it. Dotted lines representing the paper edges should also be visible. (On a colour monitor these lines will appear blue, or whatever colour has been specified in the Default configuration file.) OzTEX chooses the initial view based on the current size and shape of the view window and the current paper dimensions. It will try to show as much of the paper as possible. The top, left and right paper edges should all be visible (and maybe the bottom edge as well if you have a large screen).

Now is a good time to adjust the size and location of the OzTEX and view windows to suit your screen. When you quit, OzTEX will remember the current settings and use them the next time it starts up.

2.4.1 Paper coordinates and the scale factor

An understanding of the coordinate system used by OzTEX to display (and print) a DVI page would be useful. You may have noticed the “px” units mentioned in the Default configuration file. These are “paper pixels” and are OzTEX’s internal units. The resolution parameters in a configuration file define the number of paper pixels per inch; one parameter is only used when printing a DVI file and the other is only used when viewing a DVI file.

OzTEX uses a coordinate scheme in which the paper pixel at (0,0) is exactly one inch in from the top and left edges of the paper. This position is referred to as the “TEX origin” since it is also the origin of the coordinate system used in DVI files. Every rule/character/\special on a page has a specific location defined by a pair of paper pixels (h,v). Vertical coordinates increase down the paper and horizontal coordinates increase to the right.

If the view window is frontmost then the cursor is changed to a cross whenever it moves over the contents region. The current position of the cross is shown (in paper coordinates) in a box at the lower left corner of the view window. You can click in this box to change units.

A “scale factor” is used to display a DVI page at a particular size. It defines the number of paper pixels in each Macintosh screen pixel (both horizontally and vertically) and always has an integer value greater than or equal to 1.

2.4.2 Zooming in and out

Certain View menu items change the current scale factor:

• “Full View” sets the scale factor to its maximum value and displays the entire page and paper edges in the middle of the view window.

• “Actual Size” sets the scale factor so that the new view will show the page at the correct size (or as near as possible — it will only be accurate if the viewing resolution is an integer multiple of the screen resolution).

• “Zoom In” halves the current scale factor.

• “Zoom Out” doubles the current scale factor.

You can also change the scale factor by clicking in the view window in a variety of ways:

• Click-and-drag within the viewing area to zoom in to the selected rectangle. Cancel the operation by making the rectangle very thin (not small, because that may be interpreted as a simple click).

• A simple click will zoom in by halving the scale factor.

• Command-click will zoom in by decrementing the scale factor.

• Option-click will zoom out by incrementing the scale factor.

• Shift-click will zoom out by doubling the scale factor.

A beep occurs if you can’t zoom in or out any further. When you zoom in or out by clicking, OzTEX will try to make the point you clicked the middle of the new view. However, when you choose a menu item, OzTEX tries to keep the top left page location fixed. In both cases it is possible that the view may unexpectedly shift so that it remains within the scrolling limits set by OzTEX. Experiment with the various ways of zooming to see which methods you prefer.

The most precise display occurs when the scale factor is 1 since each screen pixel corresponds to exactly one paper pixel. OzTEX doesn’t allow you to zoom in any further than this. The standard Mac screen has a resolution of 72 dpi, so if you set the viewing resolution to 72 you won’t be able to zoom in any further than actual size.

2.4.3 Scrolling around

The view window has scroll bars that allow you to move over the page in the standard Macintosh manner. Note that the arrow keys can be used instead of clicking in the scroll arrows. OzTEX won’t let you get too far away from the page/paper boundaries. If you do manage to get lost just choose “Full View”.

2.4.4 Checking for errors

It is a good idea to select the “Page Info” item at least once while viewing a DVI file. This item displays its results in the OzTEX window. The display includes a list of all the fonts used in the DVI file and clearly indicates any that are missing.

It also lists any \special commands on the current page, showing their locations and arguments. This allows you to check the spelling of file names and the syntax of any additional PostScript code. See section 4.2 for more details about the use of \special.

2.4.5 Selecting pages

There are a number of interesting pages in nasty.dvi. Use “Previous Page”, “Next Page” or “Select Page … ” to have a look at some of them. Note that the current DVI/TEX page numbers are always displayed in the view window’s title. Here are some points of interest:

• When you select a new page the current scale factor and page location will only change if the new page is off the paper; in this case OzTEX will beep and display a full view. Pages 13 to 15 illustrate this behaviour. When you move from such a page to a normal page, OzTEX reverts back to the scale and location used to display the initial page.

• OzTEX may take a little while to interpret and display a selected page, depending on how complicated it is. Hit Command-C or Command-Dot if you get bored.

• The view window is updated in the following manner. Visible paper edges are drawn first, then \special markers, then rules, then characters on a font by font basis, starting with the font that has the least number of characters on the page. Try a full view of page 19.

• Page 3 has nothing but \special commands; OzTEX indicates the location of each with a small marker (grey on a black and white screen, or coloured on a colour monitor; the Default configuration file specifies green). The size of the marker does not change as you zoom in or out.

• Page 9 uses a couple of PostScript fonts.

• All the fonts used on page 12 are deliberately missing.

When you have finished previewing the DVI file just click in the view window’s close box. The view window is also closed automatically if you decide to run TEX, print a DVI file, or switch to a new configuration file.

2.5 Printing a DVI file

To print nasty.dvi choose either of the top two items in the File menu. Choosing the second item simply avoids the standard file dialogue.

2.5.1 Changing print options

OzTEX will present a dialogue box that lets you to change a variety of print options. Most of them should be fairly obvious — details can be found in the description of “Print DVI … ” in section 3.1. The option you’ll most often want to change is the page range. (If you find yourself changing a check box option nearly every time then you should probably change its default setting in the Default configuration file.) The two scroll bars control the first and final pages. OzTEX prevents you from choosing a first page greater than the final page. Play around with the scroll bars but restore their values so that every page will be printed. Click in the Print button or hit Return.

2.5.2 The printing process

OzTEX will look for the printer most recently selected by the Chooser. If this isn’t a PostScript printer then you won’t get very far. If the printer is found then a status box will appear and keep you up-to-date on your job’s progress and the state of the printer. As each page is translated into PostScript its DVI/TEX page numbers are displayed in the OzTEX window.

You can’t actually print every page in nasty.dvi because there is a deliberate error that makes this impossible. The first 11 pages should not cause any problems (assuming you’ve specified A4 paper and all fonts have been correctly installed) but the rest will generate nearly every type of error message you’re ever likely to encounter. You should eventually get up to page 17 where a deliberate PostScript error in a \special file will prevent any further pages being printed. OzTEX may start translating page 18 before the error is seen.

2.5.3 Saving output in a file

The print dialogue box also lets you send the PostScript output to a file instead of the printer. This file is an ordinary text file with a default name of Oz.ps. A warning: the PostScript code generated by OzTEX is resolution-dependent. If you send this code to a PostScript device with a resolution different to that of the current printer resolution parameter then the output will look a little strange! Use “Show Config” from the Config menu to see the current value of the printer resolution parameter.

2.5.4 Positioning pages correctly

When printing a DVI file OzTEX changes the PostScript coordinate system to match the paper coordinate system described in section 2.4.1. For your output to appear in precisely the right location on the paper the TEX origin must be exactly one inch (2.54 cm) in from the top and left paper edges. OzTEX can’t always set the TEX origin automatically to the correct position because many PostScript printers don’t provide an accurate way of of finding out the exact paper dimensions and the relative location of the PostScript origin.

Page 2 in nasty.dvi contains a thick rule with its top left corner exactly at the TEX origin. If the printed page shows a significant discrepancy then change the horizontal and vertical offsets in the current configuration file to shift the origin to the correct position. (Older versions of OzTEX also used these offsets when viewing DVI pages. This is no longer the case. Note that TEX’s \hoffset and \voffset commands can be used to adjust the positioning of pages.) If you use more than one printer then you may need a separate configuration file for each.

3 OzTEX’s menus

Let’s go through each menu and discuss each item in detail, concentrating on the things not mentioned in the quick tour.

3.1 The File Menu

Print DVI …

Prints a selected DVI file. After selecting the DVI file you’ll be presented with a dialogue box that lets you change various printing options:

• The page range. The first and final pages are controlled by separate scroll bars; their current values are displayed in the form “DVI-page/[TEX-page]”.

• The paper orientation: landscape or portrait.

• The page order: reverse or normal.

• Printer memory management: conserve VM or not. VM is PostScript’s “virtual memory” and the output generated by OzTEX can consume an awful lot of it, especially if your document uses a large number of non-PostScript fonts. If you get a “VMerror” when printing a document then try again with the conserve VM option checked. You should only need to do this for a very unusual document, like a font catalogue.

• The paper source: manual feed or normal input tray.

• Whether or not to include Laser Prep. If this option is selected then LaserPrep70.ps (or whatever is specified in the current configuration file) will be appended to DVItoPS.ps. LaserPrep70.ps is a modified version of Laser Prep — see the comments at the top of the file for details on how it was created. The PostScript code generated by OzTEX requires LaserPrep70.ps if your DVI file uses \special to include a PostScript file created by pressing Command-F after selecting OK in the Print dialogue box of some other Mac application. A number of modified versions of Laser Prep are supplied in PS-files in case LaserPrep70.ps doesn’t work with the PostScript code generated by your Mac.

• Whether or not to show statistics about font/rule/\special usage.

• The number of copies of each page.

• The page increment. The primary purpose of this option is to simplify the printing of a document on both sides of the paper. If the first page is 1 and an increment of 2 is chosen then OzTEX will print pages 1, 3, 5, 7, etc. Depending on how your printer stacks the output, you can then put these pages back into the input tray and print the DVI file again using the same increment but starting from the second DVI page (you might also need to reverse the page order; this will not effect which pages are printed but simply changes the order in which they are done).

• The DVI magnification expressed as an integer 1000 times the desired magnification. You should use the default value unless you know what you’re doing. If the DVI file uses non-PostScript fonts then you should probably stick to the numbers corresponding to TEX’s \magstep values; i.e., 1000, 1095, 1200, 1440, etc. See Chapters 4 and 10 in The TEXbook for details. A document using only PostScript fonts can be printed at almost any magnification; OzTEX allows values from 1 to 10000.

What happens next depends on which dialogue button you select. The default Print button will send the PostScript output to the current printer, or you might prefer to send the output to a given text file. Any change to a check box option will be remembered the next time you print or view a DVI file (but not if you Cancel the dialogue).

OzTEX will look for a file called global.ps in the current folder and include its contents at the end of the PostScript prologue. For example, global.ps in the PS-files folder shows how you can get the word “DRAFT” printed in the background on every page.

The DVI/TEX page numbers are displayed as each page is translated into PostScript. Any error messages or statistics apply to the most recently displayed page numbers. (This is not true for PostScript messages sent back by the printer as these occur asynchronously.) Printing can be cancelled by hitting Command-C or Command-Dot.

Print ?.dvi

Prints the indicated DVI file. Exactly the same dialogue box described above will appear. This item is initially disabled; its name changes whenever you select a DVI file via “Print DVI … ” or “View DVI … ”, or create a DVI file by running TEX. You can print the indicated DVI file even after moving to another folder.

Save OzTEX …

Saves the contents of the OzTEX window in a given text file. The default name is Oz.text. This item is disabled if the OzTEX window is empty.

Print Text …

Prints a selected text file. This file is sent to the current printer after prefixing the TEXTtoPS.ps prologue file kept in PS-files. If you know a little about PostScript then you might like to modify TEXTtoPS.ps to suit your own needs.

Send PostScript …

Sends a selected text file, presumably a PostScript program, to the current printer. The PS-files folder contains a number of interesting files that can be sent to almost any PostScript printer. If a file is sent to spooling software rather than directly to the printer then you probably won’t see any messages sent back. In such an environment it’s a good idea to send errhandler.ps first so that any PostScript errors will be printed on paper.

Transfer …

Quits OzTEX and starts a selected application without going back to the Finder.

Quit

Quits OzTEX.

3.2 The Edit Menu

OzTEX does not have an integrated editor, so the items in this menu remain disabled until you open a desk accessory (which may or may not support the various editing commands — the ΣEdit DA distributed with OzTEX does support them).

3.3 The TEX Menu

TEX …

Typesets a selected text file using the current format (so make sure the correct format is ticked before choosing this item). The OzTEX window acts like a terminal during a TEX session.

One of the nicest things about TEX is that it behaves the same way on a large range of different computer systems. Virtually everything you read in The TEXbook will apply to the version of TEX run by OzTEX, and the same goes for Leslie Lamport’s LaTEX manual if you use that format. Only a few special features have been added in OzTEX:

• You can interrupt a TEX session at any time by typing Command-C or Command-Dot. Depending on what it is currently doing, TEX usually responds immediately with a suitable message and the “?” prompt. If you hit Command-C or Command-Dot at this stage (or whenever the block cursor is visible) then TEX will immediately abort.

• TEX looks for a TFM file in the current folder before looking in the default TFM folder; this is consistent with the way input files and format files are located.

• Nearly all of TEX’s capacity parameters are set at run-time in a configuration file rather than at compile-time. If you get a “TEX capacity exceeded” error then you might be able to overcome the problem by increasing the appropriate parameter. A number of TEX’s error messages have been changed to reflect this possibility; see the comments at the bottom of TeX.pool if you’re interested.

• At the end of a TEX session the amount of memory allocated is displayed, as is the time taken.

TEX ?.tex

Typesets the indicated input file using the current format. This item is initially disabled; its name changes whenever you choose “TEX … ”. You can typeset the indicated file even after moving to another folder.

INITEX

Runs INITEX, a special version of TEX normally used to create format files. This is something you will need to do if you edit a configuration file and change any of the following TEX parameters: mem_top, hash_size, hash_prime or hyph_size. Creating a format file is easy. Here are the steps used to create Plain.fmt:

1. Run INITEX, wait for the “**” prompt, type “Plain\dump” and hit the Return key. TEX will begin reading plain.tex from the TeX-inputs folder.

2. You’ll eventually get a standard dialogue box allowing you to save the format information in the file and folder of your choice. The default file shown will be Plain.fmt. The best location for format files is the TeX-formats folder.

3. Note that plain.log is created in the current folder. It’s not needed, so delete it.

The steps needed to create LaTeX.fmt are very similar:

1. Run INITEX, wait for the “**” prompt, type “lplain\dump” and hit Return. TEX will begin reading lplain.tex from the TeX-inputs folder.

2. This time the standard dialogue box will show lplain.fmt, so simply change the name

     to LaTeX.fmt.

3. lplain.log is created in the current folder. Delete it if you want to.

If you decide to rename one of the existing formats, or add a completely new format, then remember to update your configuration file(s).

Different formats

OzTEX comes supplied with the two most popular formats: Plain and LaTEX. There is also a Times-LaTEX format for people that prefer to use PostScript text fonts instead of Computer Modern. Instructions for building this format file can be found in Times-LaTeX.tex in the

TeX-inputs folder.

The items below INITEX are read from the format list specified in the most recently selected configuration file. The current format is indicated by a tick and will be the one used when you typeset a file using either of the first two items in the TEX menu. To change the current format simply select a different format item. OzTEX automatically ticks the first format found when reading a configuration file, so place your preferred format first.

3.4 The View Menu

View DVI …

Previews a selected DVI file. OzTEX will open the view window and set its title to the name of the selected DVI file. You’ll then be presented with a dialogue box that lets you choose various viewing options:

• The initial page to display. A scoll bar allows you to locate any page in the DVI file; it will be inactive if there is only one page.

• The paper orientation (landscape or portrait). Any change to this option will be remembered the next time you print or view a DVI file, unless you Cancel the dialogue.

• The DVI magnification. You should only alter the default value if you plan to print the DVI file at a different magnification. See the description of “Print DVI … ” in section 3.1 for more details.

If you Cancel the dialogue then OzTEX will close the view window. If you select the View button then the current DVI/TEX page numbers will be appended to the DVI file name in the view window’s title and OzTEX will locate the requested page, interpret it and display it. You might have to wait a few seconds before seeing anything, especially if it is a complicated page.

OzTEX chooses an initial scale factor and page location based on the current size and shape of the view window. Using the paper dimensions in the current configuration file (automatically swapped if you chose the landscape option) it will try to show as much of the paper as possible, making sure that the top, left and right edges are visible. If any part of the page is off the paper then OzTEX will beep and show a full view instead; see the “Full View” item below.

View ?.dvi

Previews the indicated DVI file. Exactly the same sequence of events described above will occur. You can, however, bypass the dialogue by holding down the Shift key when selecting this item; OzTEX will then display the most recently viewed page (or page 1 if no page has been viewed).

This item is initially disabled; its name changes whenever you select a DVI file via “Print DVI … ” or “View DVI … ”, or create a DVI file by running TEX. You can preview the indicated file even after moving to another folder.

Show OzTEX/View

Brings either the OzTEX window or the view window (if open) to the front.

Page Info

Displays information about the current DVI page in the OzTEX window, bringing it to the front if necessary. This item is disabled if the view window is closed. The information displayed includes:

• The ten TEX page counters stored with the current page (trailing counters with zero values are not shown).

• The total number of pages, current viewing resolution, DVI magnification and paper dimensions.

• A list of all the fonts used in the entire DVI file. For each font appearing on the current page OzTEX will show the total number of characters used. Note that the order of fonts may change as you move from page to page; OzTEX sorts the list so that all those used on the current page appear first. A PostScript font is indicated by its corresponding TFM path name and the requested point size. A non-PostScript font is indicated by a PK path name. Missing fonts are flagged by the message “DOES NOT EXIST”.

• The number of rules on the page.

• The location and argument of each \special command on the page. The location is expessed in terms of OzTEX’s paper coordinate system; see section 2.4.1.

Previous Page

Displays the previous DVI page. This item is disabled if the view window is closed or currently displaying the first page.

Next Page

Displays the next DVI page. This item is disabled if the view window is closed or currently displaying the last page.

Select Page…

Brings up a dialogue box allowing you to select any DVI page for display. This item is disabled if the view window is closed or if the DVI file only has one page.

Full View

Changes the scale factor and location so that the entire DVI page and all paper edges are displayed in the middle of the current view window. The scroll bars are disabled and the scale factor is set to its maximum value. This item is disabled if the view window is closed or already displaying a full view of the page.

Actual Size

Changes the scale factor so that the DVI page is displayed as near as possible to its actual size. The top left corner of the view window will still show the same page location, unless shifting is necessary to keep within the scrolling limits. This item is disabled if the view window is closed or already displaying the page at its actual size.

The scale factor is rounded up to the nearest integer equal to the viewing resolution divided by the Mac screen resolution. A likely calculation is 300/72 = 4.17, so the scale factor is set to 4. In this case a 3 in wide rule in your TEX input file won’t appear exactly 3 in wide in the view window (it will however print correctly if the printer resolution parameter matches the actual resolution of your printer).

Zoom In

Halves the current scale factor. The top left corner of the view window will still show the same page location, unless shifting is necessary to keep within the scrolling limits. This item is disabled if the view window is closed or already displaying the page at minimum scale factor.

Zoom Out

Doubles the current scale factor. The top left corner of the view window will still show the same page location, unless shifting is necessary to keep within the scrolling limits. This item is disabled if the view window is closed or already displaying the page at maximum scale factor.

3.5 The Config menu

Show Config

Shows the current values of all configuration parameters in the OzTEX window. The output is displayed using the correct syntax for a configuration file; this makes it easy to create a new configuration file by selecting “Save OzTEX … ” from the File menu.

Default

The Default configuration file is read, resetting all parameters to their default values.

Other configuration files

The remaining items in the Config menu are read from the Default configuration file. The items should correspond to the names of text files in the Configs folder. Selecting one of these items causes the corresponding configuration file to be read and interpreted. Note that some parameter values will remain unchanged if the configuration file uses ? or !. A tick appears next to the most recently selected file.

3.6 The Help Menu

The items appearing in this menu are read from the help list in the current configuration file and should correspond to the names of text files in the Help-files folder. Selecting an item simply causes a copy of the matching file to appear in the OzTEX window.

Feel free to add more items to the Help menu. For example, you might like to create a file of TEX/LaTEX commands to refer to while editing an input file. If you want to add more help files, or modify the existing ones, then there are a few things to watch out for:

• Don’t use tabs.

• Avoid long lines. OzTEX uses 9 pt Monaco to display the text; on a Mac Plus screen there is room for up to 80 characters per line.

• If you create a new file then remember to update your configuration file(s).

4 Mixing PostScript and TEX

4.1 Using PostScript fonts

OzTEX allows the use of PostScript fonts within a TEX document. To be able to use a particular PostScript font, OzTEX needs to know the name of its corresponding TFM file. This information is specified at the end of a configuration file (see the Default file).

Each PostScript printer has a certain set of resident fonts. The font you wish to use may not exist in the current printer. To see an alphabetical list of the PostScript fonts available, choose “Send PostScript … ” from the File menu, open the PS-files folder, and send the file getfonts.ps. The list should appear in the OzTEX window. If you’d prefer to print the list

then send fontlist.ps.

There are some important differences between PostScript fonts and the Computer Modern fonts created specifically for use with TEX:

1. A PostScript font can be requested at virtually any size you like since there are no corresponding PK files to worry about. When asking for a PostScript font it is best to use an “at dimen” size specification (e.g., \font\helv=ps-helv at 14pt) otherwise TEX will use the design size stored in the TFM file. All the PostScript TFMs supplied with OzTEX have a design size of 10 pt but this may not be true for other TFMs you might acquire.

2. PostScript fonts usually contain up to 256 characters, with many empty locations. Computer Modern fonts can also contain up to 256 characters but typically use only the first 128 locations.

3. When a PostScript font is scaled to the same design size as a CM font it tends to look darker and larger. You need to be a bit careful about mixing the two font designs.

4. The standard TEX commands for accents and foreign letters need to be redefined for a PostScript text font. The file pstext.tex in the TeX-inputs folder contains the required macro definitions. Another file, psfonts.tex in TeX-docs, inputs these macros and illustrates the use (and abuse) of PostScript fonts in a TEX document.

If you are a LaTEX user and would like a document typeset with PostScript text fonts rather than Computer Modern, then try the Times-LaTEX format supplied with OzTEX. With any luck you might not have to make any changes to your input file. Note that CM fonts are still needed to typeset mathematics.

4.2 Including PostScript graphics

Creating figures and illustrations with TEX isn’t easy. Although it is theoretically possible to place small dots anywhere on a page and build up an arbitrarily complex picture, time and memory limitations make such a scheme impractical. (LaTEX provides a picture environment, but it is very inefficient and only suitable for small, simple diagrams.) OzTEX allows you to include PostScript graphics in a document using TEX’s \special command.

Let’s assume you have a file called fig.ps that contains PostScript code for generating some sort of figure. To include this figure in a TEX or LaTEX document, just type “\special{fig.ps}” after leaving sufficient space:

   % in a TeX input file                     % in a LaTeX input file
   \midinsert                                \begin{figure}[ht]
     \vskip 3in                                \vspace{3in}
     \special{fig.ps}                          \special{fig.ps}
     \centerline{Figure 1: Pie Sales}          \caption{Pie Sales}
   \endinsert                                \end{figure}

The \special command can appear almost anywhere in your input file. It behaves like an invisible box of zero height and width. TEX simply stores the given argument in the DVI file at the current page position. When printing the DVI file, OzTEX interprets the argument as a file name and then includes this file with the rest of the PostScript output. If it can’t find the file in the current folder then it looks in PS-files. Don’t worry about removing any showpage command at the end of your PostScript file since OzTEX temporarily disables it.

It may take a little practice to position the figure correctly. The default PostScript origin is at the bottom left corner of the paper. However, when you include a file, OzTEX automatically moves the origin to the position of the \special. You can move the figure about by shifting the \special position, or by using a translate command in the PostScript file. The latter option is faster because you don’t have to run TEX again. Alternatively, you may prefer to place your figure at an absolute position on the paper. Simply use a command like initgraphics in the PostScript file. The position of the \special command then becomes irrelevant; just make sure it’s on the right page!

OzTEX also allows arbitrary PostScript code to appear after the file name in a \special command. At least one space must be used to terminate the file name; further characters are included as a new line at the start of the given file. For example, “\special{fig.ps 2 1 scale}” could be used to double the width of the figure. This feature allows you to include the same PostScript file more than once, but with a different starting line each time — useful if you need to produce the same diagram many times but with slight variations.

The hardest part of the scheme is creating the PostScript file in the first place. You are faced with two possibilities:

1. Learn enough PostScript to be able to draw your own figures. You’ll need to read the PostScript books mentioned in section 6.

2. Use another application to create the illustration and then save it as a PostScript file. Most Mac programs will create a file called PostScript0 if you hold down Command-F soon after selecting OK in the standard Print dialogue box. If you include such a file then remember to select the “include Laser Prep” option when printing the DVI file (see “Print DVI … ” in section 3.1 for why this is necessary). The figure on page 2 of this User Guide was created by using \special to include the file folders.ps; see the comments at the top of this file if you’d like to do something similar. Note that a PostScript error is highly likely if the included Laser Prep doesn’t match the version required by the Command-F file.

Some Mac programs can create an EPS (Encapulated PostScript) file. Such a file doesn’t require Laser Prep to be included.

OzTEX does not attempt to interpret a PostScript file when viewing a DVI file; instead it draws a small marker indicating the location of each \special. The “Page Info” item will show the page position and arguments of each \special command. This information is also displayed if you choose the “show statistics” option when printing the DVI file.

OzTEX generates highly efficient PostScript code but it does so at the expense of some \special functionality. Many DVI-to-PostScript translators allow you to do things like use one \special to start rotating TEX text and another to stop the rotation. The way OzTEX interprets a DVI page makes this impossible. All the rules, fonts and \specials are collected in separate lists for later processing, so any sequential connection between these various page elements is lost.

5 Recovering from errors

OzTEX can report errors in two different ways:

1. By displaying a message in the OzTEX window.

2. By displaying a message in a dialogue box near the top right corner of the screen. There are actually three types of dialogue boxes:

(a) Status messages appear while sending output to the current printer.

(b) Warning messages (such as “Couldn’t open font … ”) appear in a box with a single Continue button.

(c) Fatal messages (such as “Sorry, not enough memory.”) appear in a box with two buttons: Quit, which will quit OzTEX, and Restart, which will restart OzTEX. (The Restart button may be disabled, depending on the nature of the problem).

Most errors, particularly the serious ones, are accompanied by a beep. Let’s now look at the most likely errors you’ll encounter and what you need to do to prevent them reoccurring.

5.1 Errors when running TEX

Nearly all the errors you’ll see when running TEX will be the result of mistakes in your input file. The TEXbook is the best place to look for solutions, especially Chapters 6 and 27. The LaTEX manual also has a section devoted to errors. Let’s consider some errors that are likely to be the result of OzTEX’s particular implementation of TEX.

Can’t find file

There are a number of likely reasons why TEX can’t find a file:

1. The file does not exist in either the current folder or in TeX-inputs (or TeX-formats if it was looking for a format file).

2. You could have spelt the file name incorrectly.

3. The file name might contain an illegal character. A Macintosh file name can contain just about any character, but TEX is not so flexible. Don’t use spaces and avoid non-alphabetic characters in all file names that might be seen by TEX.

If you see such an error then the best thing to do is hit Command-C or Command-Dot to abort TEX, and either rename the file or move it to the correct folder.

Bad TEX parameter

When you run TEX (or INITEX) a check is made of the current TEX parameters. If an error is detected you’ll be asked to fix the offending configuration file. The comments in the Default configuration file show the legal range of values for each parameter.

Fatal format file error

This error will occur if the current values of certain TEX parameters don’t match the values stored in the current format file. Either rebuild the format file or switch to the correct configuration file.

TEX capacity exceeded

The resulting error message indicates which TEX parameter has been exceeded. Before doing anything else, first check that the error is not the result of some other mistake, such as a missing } or an infinitely recursive macro. If the error really is the result of limited capacity, try increasing the appropriate parameter in the current configuration file.

If the TEX parameter can’t be increased then don’t give up. Chapter 27 of The TEXbook mentions various methods for making the most efficient use of TEX’s resources. One of the simplest methods is to split your document up into smaller chunks and TEX them separately.

Not enough memory

TEX requires a lot of memory but should run on any Mac with 1MB or more. The most likely time you could run out of memory is when using INITEX to create a format file. INITEX typically requires more memory than TEX — just how much more depends on the TEX parameters in the current configuration file. The memory allocated is displayed at the end of a session.

If you are using MultiFinder then you can tell it to reserve more memory for OzTEX by selecting the OzTEX icon, choosing “Get Info” from the Finder’s File menu, and increasing the number at the bottom of the box that appears.

If you don’t use MultiFinder then turn off the RAM cache and reboot without installing any debugger or INITs. If that doesn’t work then you’ll have to decrease one or more TEX parameters (or buy a bigger Mac).

5.2 Errors when viewing a DVI file

Missing fonts

During interpretation of a DVI page you may get a warning message if OzTEX can’t find a PK file; this message only appears once for each missing font. The “Page Info” item also indicates all missing fonts. If you set the viewing resolution to some value other than 300 then you must install a matching set of PK files.

Even if the viewing resolution is 300, missing font messages are possible due to a poor choice of font magnification (in the font specification or DVI magnification); see section 1.6.2 for details. Another possibility is that the PK file was not supplied with OzTEX, especially at sizes 622 and 746. Missing fonts are also likely when viewing a DVI file transferred from a TEX system that uses a different set of TFM files.

Page off paper

If OzTEX detects that any part of a DVI page (including a \special marker) is off the paper then it will beep and show a full view. TEX will often catch these errors (e.g., overfull \hbox or \vbox) but there are quite a few situations where it can’t. TEX really has no idea about what paper size you intend to print its pages on.

If you’re sure the problem isn’t in your input file then use the “Page Info” item to see what OzTEX thinks the paper dimensions are. You could have forgotten to reset the landscape option or you might have made a mistake when specifying the paper dimensions in the current configuration file.

5.3 Errors when printing a DVI file

OzTEX detects basically the same set of errors whether it is viewing or printing a DVI file. In the latter case the error messages appear in the OzTEX window along with a beep. If you’ve been sensible and previewed the DVI file before printing it then you should have discovered nearly all the errors (and fixed them).

Note that if you go ahead and print a DVI file with missing fonts then OzTEX makes no attempt to do any sort of font substitution; you’ll simply see blank spaces. To avoid wasting paper you should always view a DVI file before printing it and choose “Page Info” to check for any missing fonts. Alternatively, you can send the output to a file instead of the printer and check for errors that way.

Printer errors

If you are sending output to a printer then the status box should indicate any problem with the printer, such as an empty paper tray. Once you’ve fixed the problem printing can normally continue.

Can’t open \special file

OzTEX expects the argument of a \special command to contain a file name. It won’t be able to open the file if you spelt its name incorrectly or the file can’t be found in either the current folder or PS-files.

PostScript errors

You shouldn’t see any errors in the PostScript code generated by OzTEX, but there may well be problems in a file included by \special. (You can always tell which is the culprit by commenting out the \special argument.) If you are sending the output to a printer (rather than spooling software) then any PostScript error should cause a message to appear in the OzTEX window. Any further output will be flushed and printing cancelled.

So what can you do? For starters, read the PostScript books listed in section 6. Debugging a PostScript program can be a frustrating experience. If the problem is not obvious then use PostScript’s print and flush commands to isolate just where the error is occurring. Also, try downloading the error handler stored in errhandler.ps.

If you forget to include Laser Prep when printing a DVI file that uses a Command-F PostScript file then you’ll probably get an error message with “OffendingCommand: md”. (md is the name of the dictionary defined in Laser Prep. A different error might occur if md has already been dowloaded by another Mac application.)

6 Further reading

The TEXbook, by Donald E. Knuth.

LaTEX: A Document Preparation System, by Leslie Lamport.

PostScript Language Reference Manual, by Adobe Systems Inc.

PostScript Language Program Design, by Adobe Systems Inc.

These books (and many others) are all available through TUG, the TEX Users Group. Anybody planning to use TEX a lot is strongly advised to join. They produce an excellent newsletter called TUGboat that contains a vast amount of useful information. Back issues are available. Here is the address for general correspondence:

TEX Users Group

P.O. Box 9506

Providence, RI 02940, U.S.A.

Telephone: (401) 751 7760

Email: tug@math.ams.com (Internet)