% LaTeX input for the "OzTeX User Guide".
% Non-LaTeX cross-references are flagged by "XREF".
% Unfinished or uncertain portions are flagged by "!!!" or "???".

\documentstyle[11pt]{article}

% 1in margins at left and right
\oddsidemargin=0in
\evensidemargin=0in
\textwidth=6.25in              % A4 paper is 8.25in wide

% 1in margins at top and bottom
\headheight=0pt
\headsep=0pt
\topmargin=0in
\textheight=9.7in              % A4 paper is 11.7in high

\input OzTeX                   % \OzTeX logo definition

\font\logo=logo10 at 11pt
\def\mf{{\logo METAFONT}}
\def\texbook{{\sl The \TeX book\/}}
\def\initex{{\tt INITEX}}

\def\ozdisk{{\tt OzTeX}}
\def\fmtdisk{{\tt Formats}}
\def\indisk{{\tt Inputs}}
\def\srcdisk{{\tt Sources}}
\def\webdisk{{\tt WEBtoMOD}}
\def\pk#1{{\tt PK-#1}}
\def\configs{{\tt Configs}}
\def\globalps{{\tt global.ps}}
\def\oztext{{\tt Oz.text}}
\def\ozps{{\tt Oz.ps}}
\def\pool{{\tt TeX.pool}}
\def\texthdr{{\tt TEXTtoPS.ps}}
\def\dvihdr{{\tt DVItoPS.ps}}
\def\pkfiles{{\tt PK-files}}
\def\psfiles{{\tt PS-files}}
\def\texfonts{{\tt TeX-fonts}}
\def\texinputs{{\tt TeX-inputs}}
\def\texformats{{\tt TeX-formats}}
\def\helpfiles{{\tt Help-files}}
\def\texdocs{{\tt TeX-docs}}
\def\latexdocs{{\tt LaTeX-docs}}
\def\dvimac{{\tt DVIM72-Mac}}
\def\sedit{$\Sigma$Edit}
\def\ttsedit{{\tt \char'6 Edit}}

\raggedbottom

\begin{document}

\typeout{--------------------------------------------------------------------}
\typeout{A note to non-LaTeX users:}
\typeout{Don't worry about the warning messages that appear on the first run.}
\typeout{LaTeX simply needs another run to fix up the cross-references.}
\typeout{--------------------------------------------------------------------}

\null
\vfil

\centerline{\hbox to 30bp{\special{pntg=ozicon.pntg}\hfil}}
\bigskip

\begin{center}
\Huge\bf
\OzTeX\ User Guide\\ [3mm]
\normalsize\bf
Version 1.4, January 1992\\ [3mm]
\rm
Andrew Trevorrow\\
c/- Research School of Earth Sciences\\
Australian National University\\
GPO Box 4, Canberra 2601, Australia\\ [3mm]
E-mail: akt150@huxley.anu.edu.au
\end{center}

\bigskip
\bigskip

\noindent
\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.

\vfil

\thispagestyle{empty}

\pagenumbering{roman}

\newpage

\tableofcontents

\newpage

\pagenumbering{arabic}


\section{Introduction}

Assuming you correctly carried out the installation instructions in the
{\tt Read-Me} file supplied with \OzTeX, your screen should display
something like this:\label{folders}

% include bitmap showing contents of folders;
% note that 0.72 = 3 * 0.24 where 0.24 = 72/300; multiples of 0.24 are
% recommended for getting nicely scaled bitmaps on a 300dpi printer
\vbox to 3.4in{\vfil
\noindent\hskip 1.0in\special{pntg=folders.pntg scale=0.72}}

\bigskip

\noindent
Here is a brief description of the various folders:
\begin{itemize}
\item
The \configs\ folder contains a number of configuration files.
\item
The \texfonts\ folder contains a standard set of TFM files.
These files are required by \TeX\ to carry out typesetting;
see section \ref{tfm-sec} for more information about TFM files.
\item
The \texformats\ folder contains some format files used by \TeX\ and
the \pool\ file read by \initex.
Section \ref{ini-sec} describes how to create format files.
\item
The \texinputs\ 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.
\item
The \helpfiles\ folder contains a number of text files.
\item
The \psfiles\ folder contains various PostScript files.
\item
The \texdocs\ folder contains examples of \TeX\ input files,
including \verb|nasty.tex| which is used in the quick tour of \OzTeX.
\item
The \latexdocs\ folder contains the source files for this User Guide.
\item
The \ttsedit\ folder contains the \sedit\ desk accessory and its documentation.
\item
The \dvimac\ folder contains the \dvimac\ program and its documentation.
\item
The \pkfiles\ folder contains PK files stored in various sub-folders.
The name of a sub-folder indicates the ``size'' of the PK files kept
within it; see section \ref{pk-sec} for how this size is calculated
and for more information about PK files.
\end{itemize}

\subsection{Changing the default configuration file}

\OzTeX\ reads a configuration file called \verb|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:
\begin{itemize}

\item
A list of the configuration files that will appear in the Config menu.
This list should only appear in the \verb|Default| file; it will be ignored
in every other configuration file.

\item
A list of the formats that will appear in the \TeX\ menu.
Place your preferred format first.

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

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

\item
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 \verb|Default| values specify A4 paper in portrait mode.

\item
The names of certain special folders:
\texformats, \texinputs, \texfonts, \helpfiles, \psfiles\ and \pkfiles.
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 ``\verb|MyDisk:PK-files:|''.

\item
The names and locations of special files: \texthdr, \dvihdr, \pool, etc.

\item
The colours of various elements seen when viewing a DVI file
(paper edges, \verb|\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 \verb|\special| markers invisible).

\item
The values of important \TeX\ parameters that determine how much memory will be
allocated for certain arrays.
The \verb|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
\verb|mem_top|, \verb|hash_size|, \verb|hash_prime| or \verb|hyf_size|
will require the format file(s) you use to be rebuilt
(see section \ref{ini-sec}).

\item
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.

\end{itemize}
The \verb|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 \verb|Default| file you can then remove all the comments so that
\OzTeX\ starts up a little faster.

\subsection{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 \verb|Default| file.
To help keep configuration files short and simple, a couple
of special characters can be used:
\begin{enumerate}
\item
If ``\verb|?|'' is the first character of a parameter's value
then the parameter is not changed and the rest of the line is ignored.

\item
``\verb|!|'' is similar but in addition all remaining parameters are
left unchanged (the rest of the file is ignored).

\end{enumerate}
Note that these characters are not recognized as special in the
\verb|Default| file since every parameter must be given a value
(even if empty).


\section{A quick tour of \OzTeX}

The aim of this section is to get you quickly acquainted with
\OzTeX's major features.

\subsection{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 \verb|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.

\subsection{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 \texdocs\ folder.
There is nothing special about this folder, or \latexdocs.
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 \verb|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 \verb|nasty.tex| in the \texdocs\ folder.
The only change we'll make to \verb|nasty.tex| is to add a deliberate error:
insert the illegal command \verb|\xxx| at the start of the file.
Save this change before switching back to \OzTeX.

\subsection{Running \TeX}

Let's now typeset \verb|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 \verb|Default| configuration file.
This is the format required by \verb|nasty.tex| so we don't need to change it.
(To change the current format you simply select a different one.)

Choose ``\TeX\,\ldots'' from the \TeX\ menu and open \verb|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 ``\verb|?|'' prompt.
This block cursor always appears when \TeX\ is waiting for you to type something.
The \OzTeX\ window should look like this:

\bigskip

\indent\verb|This is TeX, Version 3.14 (no format preloaded)|\\
\indent\verb|**&Plain nasty.tex|\\
\indent\verb|(nasty.tex|\\
\indent\verb|! Undefined control sequence.|\\
\indent\verb|l.5 \xxx|\\
\indent\\
\indent\verb|? |{\tt\vrule width .4em height .7em depth .15em}

\bigskip

\noindent
Chapter 6 in \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 \verb|nasty.tex| is not very nice, you shouldn't see any more
\TeX\ errors.  A 19-page DVI file called \verb|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 (\verb|nasty.tex| in this case) so you can
easily typeset the same file many times.

\subsection{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 \verb|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\,\ldots''
in section \ref{view-menu} 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 \verb|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.

\subsubsection{Paper coordinates and the scale factor}
\label{paper-coords}

An understanding of the coordinate system used by \OzTeX\ to display
(and print) a DVI page would be useful.
You may have noticed the ``\verb|px|'' units mentioned in
the \verb|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/\verb|\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.

\subsubsection{Zooming in and out}

Certain View menu items change the current scale factor:
\begin{itemize}
\itemsep=0pt
\item
``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.
\item
``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).
\item
``Zoom In'' halves the current scale factor.
\item
``Zoom Out'' doubles the current scale factor.
\end{itemize}
You can also change the scale factor by clicking in the view window
in a variety of ways:
\begin{itemize}
\itemsep=0pt
\item
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).
\item
A simple click will zoom in by halving the scale factor.
\item
Command-click will zoom in by decrementing the scale factor.
\item
Option-click will zoom out by incrementing the scale factor.
\item
Shift-click will zoom out by doubling the scale factor.
\item
A beep occurs if you can't zoom in or out any further.
\end{itemize}
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\null.
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.

\subsubsection{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''.

\subsubsection{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 \verb|\special| commands on the current page,
showing their locations and arguments.

\subsubsection{Selecting pages}

There are a number of interesting pages in \verb|nasty.dvi|.
Use ``Previous Page'', ``Next Page'' or ``Select Page\,\ldots'' 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:
\begin{itemize}
\item
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.
\item
\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.
\item
The view window is updated in the following manner.
Visible paper edges are drawn first, then \verb|\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.
\item
Page 3 has examples of \verb|\special| commands.
\OzTeX\ is able to preview included files of type PICT, PNTG or EPSF\null.
The location of each \verb|\special| is indicated with a small marker.
Note that the size of this marker does not change as you zoom in or out.
\item
Page 9 uses a couple of PostScript fonts.
\item
All the fonts used on page 12 are deliberately missing.
\end{itemize}
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.

\subsection{Printing a DVI file}

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

\subsubsection{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\,\ldots'' in section \ref{file-menu}.
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 \verb|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.

\subsubsection{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 \verb|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 \verb|\special| file will prevent any further pages being printed.
(\OzTeX\ may start translating page~18 before the error is seen.)

\subsubsection{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 \ozps.
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.)

\subsubsection{Positioning pages correctly}

When printing a DVI file, \OzTeX\ changes the PostScript coordinate system
to match the paper coordinate system described in section \ref{paper-coords}.
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 \verb|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 \dvihdr; search for the string ``\verb|TeX origin|'' in that file).


\section{Fonts}

\OzTeX\ uses the following sources of font information in the
process of typesetting, previewing and printing a document:
TFM files (usually stored in \texfonts),
PK files (usually stored in various folders nested within \pkfiles),
and Macintosh screen fonts (normally found in the System file).

\subsection{TFM files}
\label{tfm-sec}

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 \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 \texfonts\ folder.
Most of the TFM file names in \texfonts\ begin with ``{\tt cm}''.
These letters stand for Computer Modern, a family of fonts created by
Donald Knuth using \mf\null.
All the PostScript TFM files supplied with \OzTeX\ have names beginning
with ``{\tt 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).

\subsection{PK files}
\label{pk-sec}

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:
$$
\hbox{\sl size} = \hbox{\sl resolution} \times \hbox{\sl magnification}
$$
where {\sl resolution\/} is either the printer resolution or the
viewing resolution, and {\sl magnification\/} is the overall font magnification
(i.e., the DVI magnification times the individual font scaling).
The {\sl size\/} is then rounded up to the nearest integer and should
equal ($\pm 1$) one of the folder names in \pkfiles\ 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 \verb|\magstep| values.
See Chapters~4 and 10 of \texbook\ for more details.
For example, assuming a {\sl resolution\/} of 300 and no document magnification:
\begin{tabbing}
\indent \= \verb|\font\rb=cmr10 scaled\magstephalf|\qquad \= $1.5\times1.2^{0.5}$\qquad \=\kill
\> \TeX\ input                             \> {\sl size}          \> PK file\\ [6pt]
\> \verb|\font\ra=cmr10|                   \> $300\times1.2^0$    \> \verb|:|\pkfiles\verb|:300:cmr10|\\
\> \verb|\font\rb=cmr10 scaled\magstephalf|\> $300\times1.2^{0.5}$\> \verb|:|\pkfiles\verb|:329:cmr10|\\
\> \verb|\font\rc=cmr10 scaled\magstep1|   \> $300\times1.2^1$    \> \verb|:|\pkfiles\verb|:360:cmr10|\\
\> \verb|\font\rd=cmr10 scaled\magstep2|   \> $300\times1.2^2$    \> \verb|:|\pkfiles\verb|:432:cmr10|\\
\> \verb|\font\re=cmr10 scaled\magstep3|   \> $300\times1.2^3$    \> \verb|:|\pkfiles\verb|:518:cmr10|\\
\> \verb|\font\rf=cmr10 scaled\magstep4|   \> $300\times1.2^4$    \> \verb|:|\pkfiles\verb|:622:cmr10|\\
\> \verb|\font\rg=cmr10 scaled\magstep5|   \> $300\times1.2^5$    \> \verb|:|\pkfiles\verb|:746:cmr10|
\end{tabbing}
\TeX's \verb|\magnification| command has a cumulative effect on font scaling:
\begin{verbatim}
   \magnification=\magstep1            % document magnification = 1.2
   \font\bigrm=cmr10 scaled\magstep2   % font magnification = 1.44
\end{verbatim}
The font size is now $ 300 \times 1.2 \times 1.44 = 518.4 $,
so \OzTeX\ will use \verb|:|\pkfiles\verb|:518:cmr10|.

\newpage

For compatibility with other \TeX\ systems, \OzTeX\ actually uses a more
complicated search scheme.
If \verb|foo| is a PostScript font then \OzTeX\ looks for \verb|foo.tfm| in the
current folder before looking in \texfonts.
If \verb|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:
\begin{tabbing}
\indent \= 1. \verb|:PK-files:300:foo.300pk|\qquad \=\kill
\> 1. \verb|foo.300pk|               \> (in the current folder)\\
\> 2. \verb|:PK-files:foo.300pk|     \> (relative to the location of \OzTeX)\\
\> 3. \verb|:PK-files:300:foo.300pk| \> (ditto)\\
\> 4. \verb|:PK-files:300:foo|       \> (ditto)
\end{tabbing}
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
\verb|\font\xxx=:myfonts:foo|.  In this case \TeX\ will look for
\verb|:myfonts:foo.tfm| in the current folder;
that is, it expects to find a file called \verb|foo.tfm|
in a sub-folder called \verb|myfonts|.
If not found then it gives up; it does NOT
look for \verb|foo.tfm| in the default \texfonts\ 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.

\verb|\magstep| values can also be used with \LaTeX's
\verb|\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 \verb|\magnification| command --- use
the \verb|11pt| and \verb|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, write-black 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.

\subsection{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 \verb|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\,\ldots'' from the File menu,
open the \psfiles\ folder, and send the file \verb|getfonts.ps|.
The list should appear in the \OzTeX\ window.
If you'd prefer to print the list then send \verb|fontlist.ps|.

There are some important differences between PostScript fonts and
the Computer Modern fonts created specifically for use with \TeX:
\begin{enumerate}
\item
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
``\verb|at| {\em dimen\/}'' size specification
(e.g., \verb|\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.
\item
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).
\item
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.
\item
The standard \TeX\ commands for accents and foreign letters need to be
redefined for a PostScript text font.  The file \verb|pstext.tex| in the
\texinputs\ folder contains the required macro definitions.
Another file, \verb|psfonts.tex| in \texdocs, inputs these macros and
illustrates the use (and abuse) of PostScript fonts in a \TeX\ document.
\end{enumerate}
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\null.
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.

\subsection{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 \verb|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 \verb|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.

\subsection{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 ``\verb|set file type binary|'' before using
the \verb|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 ``\verb|set file type fixed|'' before using the \verb|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\,\ldots'' or
``View DVI\,\ldots''.  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.

\newpage


\section{\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.

\subsection{The File menu}
\label{file-menu}

\subsubsection*{Print DVI\,\ldots}

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:
\begin{itemize}
\item
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]''.
\item
The paper orientation (landscape or portrait).
\item
The page order (reverse or normal).
\item
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 ``\verb|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.
\item
The paper source (manual feed or normal input tray).
\item
Whether or not to show statistics about font/rule/\verb|\special| usage.
\item
The number of copies of each page.
\item
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 {\em which\/} pages
are printed but simply changes the {\em order\/} in which they are done).
\item
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 \verb|\magstep| values; i.e.,
1000, 1095, 1200, 1440, etc.
See Chapters~4 and 10 in \texbook\ for details.
A document using only PostScript fonts can be printed at almost any
magnification (\OzTeX\ allows values from 1 to 10000).
\end{itemize}
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 \globalps\ in the current folder
and include its contents at the end of the PostScript prolog.
For example, \globalps\ in the \psfiles\ 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.

\subsubsection*{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\,\ldots'' or ``View DVI\,\ldots'',
or create a DVI file by running \TeX\null.
You can print the indicated DVI file even after moving to another folder.

\subsubsection*{Save \OzTeX\,\ldots}

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

\subsubsection*{Print Text\,\ldots}

Prints a selected text file.
This file is sent to the current printer after prefixing the
\texthdr\ prolog file kept in \psfiles.
If you know a little about PostScript then
you might like to modify \texthdr\ to suit your own needs.

\subsubsection*{Send PostScript\,\ldots}

Sends a selected text file, presumably a PostScript program, to the current
printer.
The \psfiles\ 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 \verb|errhandler.ps| first
so that any PostScript errors will be printed on paper.

\subsubsection*{Quit}

Quits \OzTeX.

\subsection{The Edit menu}

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

\subsection{The \TeX\ menu}

\subsubsection*{\TeX\,\ldots}

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 \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:
\begin{itemize}
\item
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 ``\verb|?|'' prompt.
If you hit Command-C or Command-Dot at this stage
(or whenever the block cursor is visible) then \TeX\ will immediately abort.
\item
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.
\end{itemize}

\subsubsection*{\TeX\ ?.tex}

Typesets the indicated input file using the current format.
This item is initially disabled; its name changes whenever you
choose ``\TeX\,\ldots''.
You can typeset the indicated file even after moving to another folder.

\subsubsection*{INITEX}
\label{ini-sec}

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 \verb|Plain.fmt|:
\begin{enumerate}
\item
Run \initex, wait for the ``\verb|**|'' prompt, type ``\verb|Plain\dump|''
and hit the Return key.
\TeX\ will begin reading \verb|plain.tex| from the \texinputs\ folder.
This takes a little while, so try to remain calm.
\item
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 \verb|Plain.fmt|.
The best location for format files is the \texformats\ folder.
\item
Note that \verb|plain.log| is created in the current folder.
It's not needed, so delete it.
\end{enumerate}
The steps needed to create \verb|LaTeX.fmt| are very similar:
\begin{enumerate}
\item
Run \initex, wait for the ``\verb|**|'' prompt, type ``\verb|lplain\dump|''
and hit Return.
\TeX\ will begin reading \verb|lplain.tex| from the \texinputs\ folder.
This takes even longer than above.    % XREF
\item
This time the standard dialog box will show
\verb|lplain.fmt|, so simply change the name to \verb|LaTeX.fmt|.
\item
\verb|lplain.log| is created in the current folder.  Delete it if you want to.
\end{enumerate}
If you decide to rename one of the existing formats,
or add a completely new format,
then remember to update your configuration file(s).

\subsubsection*{Different formats}

\OzTeX\ comes supplied with the two most popular formats:
Plain and \LaTeX\null.
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.

\subsection{The View menu}
\label{view-menu}

\subsubsection*{View DVI\,\ldots}

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:
\begin{itemize}
\item
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.
\item
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.
\item
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\,\ldots'' in
section \ref{file-menu} for more details.
\end{itemize}
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).     % XREF

\subsubsection*{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\,\ldots'' or ``View DVI\,\ldots'',
or create a DVI file by running \TeX\null.
You can preview the indicated file even after moving to another folder.

\subsubsection*{Show \OzTeX/View}

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

\subsubsection*{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:
\begin{itemize}
\item
The ten \TeX\ page counters stored with the current page (trailing
counters with zero values are not shown).
\item
The total number of pages, current resolution, DVI magnification and
paper dimensions.
\item
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 ``\verb|DOES NOT EXIST|''.
\item
The number of rules on the page.
\item
The location and argument of each \verb|\special| command on the page.
The location is expessed in terms of \OzTeX's paper coordinate system;
see section \ref{paper-coords}.
If the \verb|\special| command includes a valid PICT/PNTG/EPSF file then
the width and height of the bitmap is also displayed (unless it is empty).
\end{itemize}

\subsubsection*{Previous Page}

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

\subsubsection*{Next Page}

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

\subsubsection*{Select Page\dots}

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.

\subsubsection*{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.

\subsubsection*{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.

\subsubsection*{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.

\subsubsection*{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.

\subsection{The Config menu}

\subsubsection*{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\,\ldots'' from the File menu.

\subsubsection*{Default}

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

\subsubsection*{Other configuration files}

The remaining items in the Config menu are determined by information given in
the \verb|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.

\subsection{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 \helpfiles\ 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:
\begin{itemize}
\item
Don't use tabs.
\item
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.
\item
If you create a new file then remember to update your
configuration file(s).
\end{itemize}


\section{Including graphic files in \TeX}
\label{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 \verb|picture| environment, but it is very inefficient
and only suitable for small, simple diagrams.)

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

Note that using \verb|\special| can seriously reduce the portability of
your \TeX\ documents, since a given DVI-reading program can only understand
\verb|\special| commands that obey its own particular syntax.
One useful technique to enhance portability is to
hide the actual \verb|\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 \verb|\special|).
For an example of this approach see Larry Siebenmann's
\verb|BoxedEPSF.doc| in \texinputs. % XREF

A \verb|\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 \verb|\special|.
The ``Page Info'' item will display this location in paper coordinates
as well as the text of the \verb|\special| command.
Similar information is displayed if you choose the ``show statistics'' option
when printing a DVI file.

\newpage

\subsection{Including Macintosh graphic files}

\OzTeX\ allows the inclusion of three common types of Macintosh
graphic files:
\begin{itemize}

\item
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:

\verb|\special{pict: filename}|

\item
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:

\verb|\special{pntg: filename}|

\item
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:

\verb|\special{epsf: filename}|

\end{itemize}
The keywords and file names are case-insensitive;
``\verb|=|'' can be used instead of ``\verb|:|'' to terminate the keyword,
and spaces before the file name are ignored.
For example, \verb|\special{EPSF=FOO}| is the same as \verb|\special{epsf: foo}|.

All three \verb|\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:
\begin{enumerate}

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

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

\item
\TeX\ macros can be used to extract the bounding box information
in an EPSF file and position the image automatically.

\item
Encapsulated PostScript is supported on many other computers.

\end{enumerate}
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 \verb|\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 \verb|\special| and then includes the
encapsulated PostScript code verbatim (disabling any \verb|showpage| command).
When previewing, it converts the corresponding PICT resource into
a bitmap and places the bottom left corner at the \verb|\special| location.

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

\item
\verb|scale=|$n$ --
scales a picture by a factor $n$ ($n$ must be $\ge 0.0$ and $\le 100.0$).

\item
\verb|hscale=|$n$ --
sets the horizontal scale factor (and alters the aspect ratio).

\item
\verb|vscale=|$n$ --
sets the vertical scale factor (and alters the aspect ratio).

\item
\verb|width=|$bp$ --
sets the horizontal scale to get a picture at the desired width
($bp$ is a number $\ge 0.0$ and $\le 7200.0$ in bp units, where 72\,bp = 1\,in).
If no previous \verb|height| keyword has been used then the vertical scale is
set to the new horizontal scale to preserve the aspect ratio.

\item
\verb|height=|$bp$ --
sets the vertical scale to get a picture at the desired height.
If no previous \verb|width| keyword has been used then the horizontal scale is
set to the new vertical scale to preserve the aspect ratio.

\end{itemize}
If a particular keyword is used more than once in a single \verb|\special|
command then the last value is used.
An illegal keyword or value will produce a warning message when previewing
but cause the entire \verb|\special| to be ignored when printing.
(The moral is: preview before you print.)
Synonyms exist for most keywords:
\begin{tabbing}
\indent \= \verb|vscale|\quad \=\kill
\> \verb|epsf|   \> = \quad \verb|eps| or \verb|epsfile| or \verb|psfile|\\
\> \verb|pict|   \> = \quad \verb|pictfile|\\
\> \verb|pntg|   \> = \quad \verb|macpaint|\\
\> \verb|hscale| \> = \quad \verb|xscale|\\
\> \verb|vscale| \> = \quad \verb|yscale|\\
\> \verb|width|  \> = \quad \verb|wd|\\
\> \verb|height| \> = \quad \verb|ht|
\end{tabbing}
Here are some examples of how to use the new \verb|\special| commands:
\begin{enumerate}

\item
To include a picture at ``normal'' size:

\leavevmode\rlap{\hskip 4in
      \special{pntg: ozicon.pntg}}%
\verb|\special{pntg: ozicon.pntg}|

\item
To halve the size:

\leavevmode\rlap{\hskip 4in
      \special{pntg: ozicon.pntg scale=0.5}}%
\verb|\special{pntg: ozicon.pntg scale=0.5}|

\item
To double the width:

\leavevmode\rlap{\hskip 4in
      \special{pntg: ozicon.pntg hscale=2}}%
\verb|\special{pntg: ozicon.pntg hscale=2}|.

\item
To set the height to 0.2\,in and the width to 2\,in:

\leavevmode\rlap{\hskip 4in
      \special{pntg: ozicon.pntg ht=14.4 wd=144}}%
\verb|\special{pntg: ozicon.pntg ht=14.4 wd=144}|.

\item
To set the height to 0.5\,in and preserve the aspect ratio:

\leavevmode\rlap{\hskip 4in
      \special{pntg: ozicon.pntg ht=36}}%
\verb|\special{pntg: ozicon.pntg ht=36}|.

\end{enumerate}
The figure on page~\pageref{folders} of this User Guide was created by
using
\begin{verbatim}
   \special{pntg=folders.pntg scale=0.72}
\end{verbatim}
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.

\subsection{Including PostScript files}

\OzTeX\ allows you to include a ``raw'' PostScript file
using \TeX's \verb|\special| command.  However, if you have a choice then
any of the methods described in the previous section % XREF
are preferable because \OzTeX\ cannot preview a PostScript file.

Assuming you have a file called \verb|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:
\begin{verbatim}
   \special{fig.ps}
\end{verbatim}
When printing the DVI file, \OzTeX\ interprets the \verb|\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 \psfiles.
Don't worry about removing any \verb|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 \verb|\special|.
You can move the figure about by shifting the \verb|\special| position,
or by using a \verb|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 \verb|initgraphics| in the PostScript
file.  The position of the \verb|\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 {\em start\/} of
the given file.
For example,
\begin{verbatim}
   \special{fig.ps 2 1 scale}
\end{verbatim}
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 \verb|\special| functionality.
Many DVI-to-PostScript translators allow you to do things like
use one \verb|\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 \verb|\special|s are collected in separate lists
for later processing, so any sequential connection between these
various page elements is lost.


\section{Recovering from errors}

\OzTeX\ can report errors in two different ways:
\begin{enumerate}
\item
By displaying a message in the \OzTeX\ window.
\item
By displaying a message in a dialog box near the top right corner
of the screen.
There are actually three types of dialog boxes:
\begin{enumerate}
\item
Status messages appear while sending output to the current printer.
\item
Warning messages such as ``Couldn't open font\,\ldots'' appear in a box
with a single Continue button.
\item
Fatal messages such as ``Sorry, not enough memory.'' appear in a box
with a Quit button (which will quit \OzTeX).
\end{enumerate}
\end{enumerate}
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.

\subsection{Errors when running \TeX}

Nearly all the errors you'll see when running \TeX\ will be the
result of mistakes in your input file.
\texbook\ is the best place to look for solutions, especially Chapters~6 and 27.
The \LaTeX\ manual also has a section devoted to errors.

\subsubsection*{Can't find file}

There are a number of likely reasons why \TeX\ can't find a file:
\begin{enumerate}
\item
The file does not exist in either the current folder or in \texinputs\ (or
\texformats\ if it was looking for a format file).
\item
You could have spelt the file name incorrectly.
\item
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\null.
\end{enumerate}
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.

\subsubsection*{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.

\subsection{Errors when viewing a DVI file}

\subsubsection*{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 \ref{pk-sec} for details.

Another possibility is that the PK file was not supplied with \OzTeX\null.
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.

\subsubsection*{Page off paper}

If \OzTeX\ detects that any part of a DVI page (including a \verb|\special|)
is off the paper then it will beep and show a full view.
\TeX\ will often catch these errors
(e.g., overfull \verb|\hbox| or \verb|\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.

\subsubsection*{{\tt\char'134special}-related errors}

When interpreting a DVI page \OzTeX\ will check any \verb|\special| commands
and warn you about the following problems:
\begin{itemize}
\itemsep=0pt
\item
An unknown keyword.
\item
A file that can't be opened.
\item
A file type that does not match the first keyword (PICT/PNTG/EPSF).
\item
A bad value after an optional keyword.
\end{itemize}

\subsection{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.

\subsubsection*{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.

\subsubsection*{Ignoring bad {\tt\char'134special} command}

If \OzTeX\ detects any sort of syntax error in a \verb|\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
\verb|\special| command.  See section \ref{graphics} for the syntax and
semantics supported by \OzTeX.

\subsubsection*{Can't open {\tt\char'134special} file}

\OzTeX\ expects the argument of a \verb|\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 \psfiles\ if you're including a raw PostScript file).

\subsubsection*{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 \verb|\special|.
(You can always tell which is the culprit by commenting out the \verb|\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. % XREF
Debugging a PostScript program can be a frustrating experience.
If the problem is not obvious then use 
PostScript's \verb|print| and \verb|flush| commands to isolate just where
the error is occurring.
Also, try downloading the error handler stored in \verb|errhandler.ps|.


\section{Further information}

{\sl The \TeX book}, by Donald E. Knuth.

\def\nextbook{\vskip 4pt \noindent}

\nextbook
{\sl A Gentle Introduction to \TeX}, by Michael Doob.
(The plain \TeX\ source file for this public domain document can be found in
the \texdocs\ folder.  \TeX\ beginners should find it a useful companion
to {\sl The \TeX book}.)

\nextbook
{\sl \LaTeX: A Document Preparation System}, by Leslie Lamport.

\nextbook
{\sl PostScript Language Reference Manual}, by Adobe Systems Inc.

\nextbook
{\sl PostScript Language Program Design}, by Adobe Systems Inc.

\bigskip

\noindent
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:

\bigskip

\indent \TeX\ Users Group\\
\indent P.O. Box 9506\\
\indent Providence, RI 02940, U.S.A.\\[4pt]
\indent Telephone: (401) 751 7760\\
\indent E-mail: tug@math.ams.com (Internet)

\end{document}
