OzTEX User Guide

Version 1.4, January 1992

Andrew Trevorrow c/- Research School of Earth Sciences Australian National University GPO Box 4, Canberra 2601, Australia

E-mail: akt150@huxley.anu.edu.au

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.

OzTEX aims to provide a standard TEX environment for the Macintosh that can easily be extended or customized to suit your particular needs. If you have had experience with TEX on some other computer then the way OzTEX works shouldn’t be too surprising.

Comments, bug reports and suggestions are all welcome. I have plans for further development of OzTEX, but at this stage such work can only be carried out in my spare time. If anybody out there would like to sponsor such work then please get in touch.

Contents

1 Introduction 1 1.1 Changing the default configuration file . . . . . . . . . . . . . . . . . . . . . . . . 2 1.2 Creating other configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

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

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

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

3 Fonts 7 3.1 TFM files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.2 PK files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.3 PostScript fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.4 Macintosh screen fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.5 Transferring TFM/PK/DVI files . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4 OzTEX’s menus 11 4.1 The File menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.2 The Edit menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.3 The TEX menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.4 The View menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.5 The Config menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 4.6 The Help menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

5 Including graphic files in TEX 16 5.1 Including Macintosh graphic files . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 5.2 Including PostScript files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

6 Recovering from errors 19 6.1 Errors when running TEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 6.2 Errors when viewing a DVI file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 6.3 Errors when printing a DVI file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

7 Further information 22

1 Introduction

Assuming you correctly carried out the installation instructions in the Read-Me file supplied with OzTEX, your screen should display something like this:

Here is a brief description of the various folders:

• The Configs folder contains a number of configuration files.

• The TeX-fonts folder contains a standard set of TFM files. These files are required by TEX to carry out typesetting; see section 3.1 for more information about TFM files.

• The TeX-formats folder contains some format files used by TEX and the TeX.pool file read by INITEX. Section 4.3 describes how to create format files.

• The TeX-inputs folder contains a large number of TEX input files. TEX looks in this folder if it can’t find a given file in your current folder.

• The Help-files folder contains a number of text files.

• The PS-files folder contains various PostScript files.

• The TeX-docs folder contains examples of TEX input files, including nasty.tex which is used in the quick tour of OzTEX.

• The LaTeX-docs folder contains the source files for this User Guide.

• The ΣEdit folder contains the ΣEdit desk accessory and its documentation.

• The DVIM72-Mac folder contains the DVIM72-Mac program and its documentation.

• The PK-files folder contains PK files stored in various sub-folders. The name of a subfolder indicates the “size” of the PK files kept within it; see section 3.2 for how this size is calculated and for more information about PK files.

1.1 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 in the Config menu. This list should only appear in the Default file; it will be ignored in every other configuration file.

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

• A list of the help files that will appear in 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 to print a DVI file and the latter for 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/viewing a DVI file. If the paper width is greater than the height then OzTEX will print/view in landscape mode. The Default values specify A4 paper in portrait mode.

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

PS-files and PK-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 seen when viewing a DVI file (paper edges, \special markers and missing fonts). 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 or System 7 (see the “Get Info” item in the Finder’s File menu). Note also that a change to mem_top, hash_size, hash_prime or hyf_size will require the format file(s) you use to be rebuilt (see section 4.3).

• A list of all PostScript TFM file names and their corresponding printer-resident font names and screen font names. Each screen font has a particular 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.2 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. “!” is similar 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 value (even if empty).

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 the program 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 dialog 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 for OzTEX.

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.

Use any text editor to open nasty.tex in the TeX-docs folder. 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 before switching back to OzTEX.

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 a solid block cursor sits next to TEX’s “?” prompt. This block cursor always appears when TEX is waiting for you to type something. The OzTEX window should look like this:

   This is TeX, Version 3.14 (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 dialog. 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 dialog box has also appeared. It has a scroll bar that allows you to select any page in the DVI file. (The dialog 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 4.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 default 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. 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 roughly the right size (it’s only approximate because the scale factor is an integer value).

• “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.

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.

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:

• The current scale factor and page location will only change if the new page is off the paper, in which 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 default scale and location.

• 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 bitmaps and 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 examples of \special commands. OzTEX is able to preview included files of type PICT, PNTG or EPSF. The location of each \special is indicated with a small marker. Note that the size of this 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 when you run TEX, print a DVI file or read a 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 dialog.

2.5.1 Changing print options

OzTEX will present a dialog 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 4.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’re using A4 paper) 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 dialog 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” 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 some 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 a configuration file to shift the origin to the correct position. If you use more than one printer then you may need a separate configuration file for each.

Choose offset values based on the normal portrait paper orientation. The offsets are adjusted automatically so that the landscape origin should also be correct (if it isn’t then you’ll have to create a separate configuration file for landscape printing, or if you know a bit of PostScript then alter some numbers in DVItoPS.ps; search for the string “TeX origin” in that file).

3 Fonts

OzTEX uses the following sources of font information 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).

3.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, or, in the case of a PostScript font, inside the printer). 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.

OzTEX also reads TFM files when printing or viewing a DVI file containing PostScript fonts (based on the list of TFM names at the end of your configuration file), or if a requested PK file can’t be found (in which case the dummy TFM file specified in your configuration file will be used).

OzTEX will look for a TFM file in the current folder before looking in the default TeX-fonts folder. 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).

3.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 your 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 equal (±1) one of the folder names in PK-files if you decide to keep PK files of the same size in separate folders.

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
   \font\rd=cmr10 scaled\magstep2  300 × 1.2^{2}  :PK-files:432:cmr10
   \font\re=cmr10 scaled\magstep3  300 × 1.2^{3}  :PK-files:518:cmr10
   \font\rf=cmr10 scaled\magstep4  300 × 1.2^{4}  :PK-files:622:cmr10
   \font\rg=cmr10 scaled\magstep5  300 × 1.2^{5}  :PK-files:746: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.

For compatibility with other TEX systems, OzTEX actually uses a more complicated search scheme. If foo is a PostScript font then OzTEX looks for foo.tfm in the current folder before looking in TeX-fonts. If foo is NOT a PostScript font then OzTEX looks for a PK file at the requested size. For example, if the calculated size is 300 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. If still not found, OzTEX gives up and displays a warning.

There is still another possibility to consider: a font name can include 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 in the current folder; that is, it expects to find a file called foo.tfm in a sub-folder called myfonts. If not found then it gives up; it does NOT look for foo.tfm in the default TeX-fonts folder. Similarly, when you print or view the DVI file, OzTEX uses the same search algorithm described above but does NOT look in the current folder. Note that the use of an explicit font location is not recommended as it decreases the portability of your TEX input file.

\magstep values 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.

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.

3.3 PostScript fonts

To be able to use a PostScript font in a TEX document, 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 (with very few empty).

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 a bit of luck you might not have to make any changes to your input file. Note that CM fonts are still used to typeset mathematics.

3.4 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 a configuration file — see the comments at the bottom of the Default file.

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.

3.5 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 (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. If the one 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.

4 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.

4.1 The File menu

Print DVI …

Prints a selected DVI file. After selecting the DVI file you’ll be presented with a dialog 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 catalog.

• The paper source (manual feed or normal input tray).

• 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 (and reversing 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 dialog button you select. The default Print button will send the PostScript output to the current printer. A status box will appear and indicate what is happening to your job and warn you about any printer problems. Instead, 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, unless you decide to Cancel the dialog.

OzTEX will look for a file called global.ps in the current folder and include its contents at the end of the PostScript prolog. 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 dialog 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 prolog 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.

Quit

Quits OzTEX.

4.2 The Edit menu

OzTEX does not have an integrated editor, so the items in this menu remain disabled until you switch to your editor.

4.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 book 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.

• Most 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.

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 may need to do if you edit a configuration file and change certain TEX parameters to suit your typesetting needs or your Mac’s memory capacity. 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. This takes a little while, so try to remain calm.

2. You’ll eventually get a standard dialog 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. This takes even longer than above.

2. This time the standard dialog 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 who prefer to use PostScript text fonts instead of Computer Modern.

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.

4.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 dialog 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 dialog.

• 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 4.1 for more details.

If you Cancel the dialog 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 your configuration file (swapped automatically 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. 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 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 fonts actually 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. If the \special command includes a valid PICT/PNTG/EPSF file then the width and height of the bitmap is also displayed (unless it is empty).

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 dialog 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 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 actually set to the nearest integer equal to the viewing resolution (defined in a configuration file) divided by the Mac screen resolution. A likely calculation is 300/72 = 4.17, so the scale factor is set to 4. Because of this approximation, a 3 in wide rule in your TEX input file won’t appear exactly 3 in wide in the view window. If this is a serious problem then switch to a configuration file that sets the viewing resolution to some multiple of 72; you’ll also need to get a corresponding set of PK files.

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.

4.5 The Config menu

Show Config

Shows the current values of all configuration parameters in the OzTEX window. The output is displayed with 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 determined by information given in 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. A tick appears next to the most recently selected file.

4.6 The Help menu

The items appearing in this menu are read from the help list in a 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).

5 Including graphic files in TEX

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.)

TEX does however provide a \special command which can be used to pass arbitrary information to the DVI interpreter. OzTEX’s printing and previewing code interprets a \special command using a simple syntax that allows inclusion of a given file.

Note that using \special can seriously reduce the portability of your TEX documents, since a given DVI-reading program can only understand \special commands that obey its own particular syntax. One useful technique to enhance portability is to hide the actual \special call inside a macro; then when you move your TEX file to another computer all you need to do is change the macro definition (assuming the DVI driver supports similar functionality in its handling of \special). For an example of this approach see Larry Siebenmann’s BoxedEPSF.doc

in TeX-inputs.

A \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 information in the DVI file at the current page position. When previewing a DVI file, OzTEX draws a small marker indicating the location of a \special. The “Page Info” item will display this location in paper coordinates as well as the text of the \special command. Similar information is displayed if you choose the “show statistics” option when printing a DVI file.

5.1 Including Macintosh graphic files

OzTEX allows the inclusion of three common types of Macintosh graphic files:

• PICT files can be generated by almost all drawing/painting programs on the Macintosh. A quick way to get a PICT file if you’re using System 7 is to type Shift-Command-3. To include a PICT file use a command of the form:

\special{pict: filename}

• PNTG files are also very common — they’re better known as MacPaint files. Shift-Command-3 on a Mac running System 6.x or earlier will create a screen dump in a file of type PNTG (note that if you have a colour monitor you’ll first need to set it to black and white). To include a PNTG file use a command of the form:

\special{pntg: filename}

• EPSF files are becoming increasingly common. They contain encapsulated PostScript code in the data fork which OzTEX uses when printing and a corresponding PICT image in the resource fork which OzTEX uses when previewing. To include an EPSF file use a command of the form:

\special{epsf: filename}

The keywords and file names are case-insensitive; “=” can be used instead of “:” to terminate the keyword, and spaces before the file name are ignored. For example, \special{EPSF=FOO}

is the same as \special{epsf: foo}.

All three \special commands allow you to preview graphics in your DVI file and should become the preferred way of including Mac-generated pictures in OzTEX. If you have a choice, EPSF files are probably the best because:

1. The printed output is determined by the PostScript code and should be of much higher quality than a similar PICT/PNTG image (which are printed as bitmaps scaled to the desired size).

2. A coloured EPSF picture will print correctly (assuming your printer supports colour) even though OzTEX will convert its PICT resource into a black and white bitmap when previewing. (A coloured PICT file is converted to a black and white bitmap for printing AND previewing.)

3. TEX macros can be used to extract the bounding box information in an EPSF file and position the image automatically.

4. Encapsulated PostScript is supported on many other computers.

When creating a PICT/PNTG file it doesn’t really matter where you position the picture; OzTEX will convert it to a black and white bitmap, find the bounding box of all black pixels in the bitmap, then place the bounding box so that the bottom left corner coincides with the location of the \special

OzTEX does NOT attempt to do this for an EPSF picture. When printing an EPSF picture it temporarily sets the PostScript origin to the location of the \special and then includes the encapsulated PostScript code verbatim (disabling any showpage command). When previewing, it converts the corresponding PICT resource into a bitmap and places the bottom left corner at the \special location.

OzTEX allows optional keyword=value pairs after the file name in a PICT/PNTG/EPSF \special. (The keyword can also be terminated by a colon or a space.) Here are the currently supported keywords:

• scale=n – scales a picture by a factor n (n must be ≥ 0.0 and ≤ 100.0).

• hscale=n – sets the horizontal scale factor (and alters the aspect ratio).

• vscale=n – sets the vertical scale factor (and alters the aspect ratio).

• width=bp – sets the horizontal scale to get a picture at the desired width (bp is a number ≥ 0.0 and ≤ 7200.0 in bp units, where 72 bp = 1 in). If no previous height keyword has been used then the vertical scale is set to the new horizontal scale to preserve the aspect ratio.

• height=bp – sets the vertical scale to get a picture at the desired height. If no previous width keyword has been used then the horizontal scale is set to the new vertical scale to preserve the aspect ratio.

If a particular keyword is used more than once in a single \special command then the last value is used. An illegal keyword or value will produce a warning message when previewing but cause the entire \special to be ignored when printing. (The moral is: preview before you print.) Synonyms exist for most keywords:

epsf  = eps or epsfile or psfile
pict  = pictfile
pntg  = macpaint
hscale = xscale
vscale = yscale
width = wd
height = ht

Here are some examples of how to use the new \special commands:

1. To include a picture at “normal” size:

\special{pntg: ozicon.pntg}

2. To halve the size:

\special{pntg: ozicon.pntg scale=0.5}

3. To double the width:

\special{pntg: ozicon.pntg hscale=2}.

4. To set the height to 0.2 in and the width to 2 in:

\special{pntg: ozicon.pntg ht=14.4 wd=144}.

5. To set the height to 0.5 in and preserve the aspect ratio:

\special{pntg: ozicon.pntg ht=36}.

The figure on page 1 of this User Guide was created by using

\special{pntg=folders.pntg scale=0.72}

to include an extract from a Macintosh screen dump (created by typing Shift-Command-3). The scale value of 0.72 was chosen because it is a multiple of 0.24 = 72/300, where 72 dpi is the resolution of the MacPaint bitmap and 300 dpi is the resolution of the printer. This technique can improve the print quality of scaled bitmaps.

5.2 Including PostScript files

OzTEX allows you to include a “raw” PostScript file using TEX’s \special command. However, if you have a choice then any of the methods described in the previous section are preferable because OzTEX cannot preview a PostScript file.

Assuming you have a file called fig.ps that contains PostScript code for generating some sort of figure, the following command can be used to include this figure in a TEX or LaTEX document:

   \special{fig.ps}

When printing the DVI file, OzTEX interprets the \special 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. 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.

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.

6 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 dialog box near the top right corner of the screen. There are actually three types of dialog 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 a Quit button (which will quit OzTEX).

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.

6.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.

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, then quit OzTEX and either rename the file or move it to the correct folder.

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 your configuration file. If you do run out of memory then try again after turning off any RAM cache and rebooting without installing any debugger or INITs. If that doesn’t work then you’ll have to decrease one or more TEX parameters.

If you are using MultiFinder or System 7 then you can 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.

6.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 will only appear once for each missing font. The “Page Info” item also indicates all missing fonts. The most likely reason for such an error is poor choice of font magnification, whether in the font specification or DVI magnification. See section 3.2 for details.

Another possibility is that the PK file was not supplied with OzTEX. This is quite likely for a PK file with size 622 or 746. Missing fonts are also likely when viewing a DVI file transferred from another 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) 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 changing the paper dimensions in a configuration file.

\special-related errors

When interpreting a DVI page OzTEX will check any \special commands and warn you about the following problems:

• An unknown keyword.

• A file that can’t be opened.

• A file type that does not match the first keyword (PICT/PNTG/EPSF).

• A bad value after an optional keyword.

6.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.

Ignoring bad \special command

If OzTEX detects any sort of syntax error in a \special command, or if the included file’s type does not match the keyword, then the above warning message will be displayed along with the offending \special command. See section 5 for the syntax and semantics supported by OzTEX.

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 doesn’t exist in the current folder (or in PS-files if you’re including a raw PostScript file).

PostScript errors

You shouldn’t see any errors in the PostScript code generated by OzTEX, but there may well be problems in a PostScript 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 below. 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.

7 Further information

The TEXbook, by Donald E. Knuth.

A Gentle Introduction to TEX, by Michael Doob. (The plain TEX source file for this public domain document can be found in the TeX-docs folder. TEX beginners should find it a useful companion to The TEXbook.)

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

E-mail: tug@math.ams.com (Internet)