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

\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\prep{{\tt LaserPrep70.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

\begin{center}
\Huge\bf
\OzTeX\ User Guide\\ [3mm]
\normalsize\bf
Version 1.3, September 1990\\
\bf
Andrew Trevorrow\\ [3mm]
\rm
1-3-37 5th St., Habsiguda\\
Hyderabad 500007, India
% ??? c/o Aston University Computing Service\\
% Aston Triangle, Birmingham B4 7ET, U.K.\\
% Email: \verb|a_trevorrow@uk.ac.aston| (JANET)
\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, especially if
you want to include graphics in your documents.

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

Your comments, bug reports and suggestions are all welcome.
I am still interested in doing further development of \OzTeX\ and would
like to hear from people willing to sponsor such work.
% ??? Peter Abbott at Aston University has very kindly offered to forward
% letters and email messages on to me.  

\vfil

\thispagestyle{empty}

\pagenumbering{roman}

\newpage

\tableofcontents

\newpage

\pagenumbering{arabic}

\section{Installing \OzTeX}

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

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

\subsection{What you should have}

\OzTeX\ is distributed on ten 800K disks.    % XREF
%???(Even if you obtained \OzTeX\ electronically you should still read
%the following to make sure you have everything.)
Here is a brief description of what each disk should contain:
\begin{enumerate}

\item
The \ozdisk\ disk has a StuffIt archive which contains
the \OzTeX\ application and the following folders:
\begin{itemize}
\setlength{\itemsep}{0pt}
\item \configs, containing various configuration files.
\item \texfonts, containing TFM files.
\item \helpfiles, containing a few short text files.
\item \psfiles, containing various PostScript files.
\item \texdocs, containing examples of \TeX\ input files.
\item \latexdocs, containing \LaTeX\ input files (including this User Guide).
\item \ttsedit, containing the \sedit\ desk accessory and its documentation.
\item \dvimac, containing the \dvimac\ program and its documentation.
\item \pkfiles, empty and waiting to receive the folders stored
in disks \pk1 to \pk5.
\end{itemize}
This disk also contains
a {\tt Read-Me} file and UnStuffIt for unpacking StuffIt archives.

\item
The \fmtdisk\ disk has a StuffIt archive which contains the \texformats\ folder.
This is the default location for \TeX's {\tt fmt} files
and the \pool\ file read by \initex.

\item
The \indisk\ disk has a StuffIt archive which contains the \texinputs\ folder.
\TeX\ looks for input files in this folder if it can't find them in your
current folder.

\item
\pk1 contains the folders {\tt 300} and {\tt 746}.

\item
\pk2 contains the folders {\tt 329} and {\tt more-746}.

\item
\pk3 contains the folders {\tt 360} and {\tt 622}.

\item
\pk4 contains the folders {\tt 432} and {\tt more-622}.

\item
\pk5 contains the {\tt 518} folder.
The name of each folder in these last five disks      % XREF
indicates the ``size'' of the PK files kept within the folder.
See section \ref{pk-sec} for how this size is calculated
and for more information about PK files.

\item
The \srcdisk\ disk has a StuffIt archive which contains
the Modula-2 and MPW source files for \OzTeX\null.
(SPECIAL BONUS OFFER --- this disk also contains LifeLab.)

\item
The \webdisk\ disk has a StuffIt archive which contains the MPW tools
and scripts used to translate \verb|tex.web| into Modula-2.
\end{enumerate}
None of the files on the last two disks are actually needed to run \OzTeX,
so forget them if you're not interested.
See the \OzTeX\ System Guide if you are interested.   % XREF

\subsection{Where to put things}

Assuming you have enough disk space, carry out the following steps:
\begin{enumerate}
\item
Create an empty folder somewhere on your hard disk and call it anything
you like.

\item
Copy the contents of disks \ozdisk, \fmtdisk\ and \indisk\ into this folder.
Use UnStuffIt to unpack the {\tt sit} files.

\item
Copy the contents of disks \pk1 to \pk5 into the \pkfiles\ folder.

\item
Open the \pkfiles\ folder and
move the files inside {\tt more-746} into {\tt 746},
and the files inside {\tt more-622} into {\tt 622},
and then delete the emptied folders.
\end{enumerate}
Your screen should now look something like this:\label{folders.ps}

% include bitmap image
\vbox to 5in{\special{folders.ps}\vfil}

\noindent
You may not have enough disk space to store everything,
so let's consider the bare essentials needed for a working \OzTeX\ system:
\begin{itemize}
\item
You'll need the \OzTeX\ application of course, and the \configs\ folder.

\item
Most of the files in \texfonts, \helpfiles\ and \psfiles\ are quite small
so you won't save much disk space by pruning these folders.

\item
\texdocs\ and \latexdocs\ contain \OzTeX's documentation and
sample input files, none of them critical.
Remove both these folders if it makes you happier.
Note however that \verb|nasty.tex| is used in the quick tour below.   % XREF

\item
The \ttsedit\ folder can be deleted after you've used the Font/DA Mover
to install \sedit\ (assuming you want to use it).

\item
The \dvimac\ folder can be deleted if you don't need this program.

\item
If you only ever use one format then remove the other
format files in \texformats.
Don't delete \pool\ though --- it's needed by \initex.

\item
If you don't use \LaTeX\ then remove all the {\tt *.sty} and {\tt *.doc} files
in \texinputs.

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

\subsection{Installing the editor}

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

\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 at the bottom of the Config menu.
This list should only appear in the \verb|Default| file; it is ignored
in every other configuration file.

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

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

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

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

\item
The names of certain special folders:
\helpfiles, \texformats, \texinputs, \texfonts, \pkfiles\ and \psfiles.
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
(paper edges, \verb|\special| markers and missing fonts)
seen when viewing a DVI file.
The allowed colours are black, red, green, blue, cyan, magenta, yellow
and white (white is allowed in case you want to do something like
make \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 (see the ``Get Info'' item in the Finder's File menu).
Note also that a change to some parameters
will require the format file(s) you use to be rebuilt; see section \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 an 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|!|'' has the same effect as ``\verb|?|''
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 starting value.

\bigskip

If you are an experienced \TeX\ user and think you know enough to try
\OzTeX\ out then skip the next few pages and start the quick tour
on page \pageref{tour}.

\newpage

\subsection{Fonts}

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

\subsubsection{TFM files}

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

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

Most of the TFM file names in \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).

\subsubsection{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 {\em not\/} appearing in the list at the end of
the current configuration file).
For each such font there is usually a number of PK files, each one
representing the same font but at a different size.
This size, which has no relation to the font's design size, is calculated
as follows:
$$
\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
match ($\pm 1$) one of the folder names in \pkfiles.

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

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

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

\bigskip

1. \verb|foo.300pk                 |(in the current folder)\par
2. \verb|:PK-files:foo.300pk       |(relative to the location of \OzTeX)\par
3. \verb|:PK-files:300:foo.300pk   |(ditto)\par
4. \verb|:PK-files:300:foo         |(ditto)

\bigskip

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

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

All the PK files supplied with \OzTeX\ have been specifically generated for
a 300\,dpi, 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.

\subsubsection{Macintosh screen fonts}

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

If you use PostScript fonts a lot then for best previewing results you should
get the matching Adobe screen fonts listed in the \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.
This should be a fixed-width font.
The \OzTeX\ application has FOND and FONT resources for this font
to avoid the possibility of using modified System resources.
If you haven't modified the System resources for the Monaco
font then you can use ResEdit to delete the redundant FOND and FONT resources
from the \OzTeX\ application; you'll only save about 2K though.

\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; i.e., a stream of arbitrary 8-bit bytes.
When using Kermit to transfer binary files from another computer to your Mac,
remember to type ``\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.
(An alternative solution is to use a program like ResEdit to
change the file type to ``ODVI''.)
If the file you choose is not a valid DVI file then a warning message will
appear complaining about a ``bad id byte''.

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

\section{A quick tour of \OzTeX}
\label{tour}

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 things started.
After a brief pause you should see a window with the title ``\OzTeX''
and a message indicating the name of the default configuration file.
(If you made a mistake during installation, especially when editing
the \verb|Default| file, then you might also
be looking at a dialogue box from which you can only quit.  The message
displayed will hopefully give you some idea of how to fix the problem.)
The \OzTeX\ window is always present; note that it has no close box
in the upper left corner.
This window provides a terminal-like interface in which nearly all of
\OzTeX's textual output will appear.

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

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

If you installed \sedit\ then choose this DA from the Apple menu,
open the \texdocs\ folder, and then open \verb|nasty.tex|.
If you aren't using MultiFinder then
a new \sedit\ menu appears at the end of the \OzTeX\ menus
and the Edit menu items are enabled.

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 by hitting Command-S or choosing ``Save'' in the \sedit\ menu.
Feel free to scroll up and down and have a look at the rest of the file,
but don't worry too much if you don't understand everything.
You might like to make more changes and experiment with how \sedit\ works.
Just make sure you Revert to the saved version before continuing.

\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 the normal mouse pointer
has disappeared and a block cursor sits next to \TeX's ``\verb|?|'' prompt.
This 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.0 (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 dialogue.
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 dialogue box has also appeared.  It has a scroll bar that allows you to
select any page in the DVI file.
(The dialogue box also allows you to change a couple of viewing options, but
we'll ignore them at this stage; see the description of ``View DVI\,\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 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.
(On a colour monitor these lines will appear blue, or whatever colour has been
specified in the \verb|Default| configuration file.)
\OzTeX\ chooses the initial view based on the current size and shape of
the view window and the current paper dimensions.
It will try to show as much of the paper as possible.
The top, left and right paper edges should all be visible (and maybe the
bottom edge as well if you have a large screen).

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

\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}
\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 the correct size (or as near as possible ---
it will only be accurate if the viewing resolution is an integer multiple
of the screen resolution).
\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}
\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.
\end{itemize}
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\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.
The standard Mac screen has a resolution of 72\,dpi,
so if you set the viewing resolution to 72 you won't be
able to zoom in any further than actual size.

\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.
This allows you to check the spelling of file names
and the syntax of any additional PostScript code.
See section \ref{ps-graphics} for more details about the use of \verb|\special|.

\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
When you select a new page
the current scale factor and page location will only change if the new page is
off the paper; in this case \OzTeX\ will beep and display a full view.
Pages 13 to 15 illustrate this behaviour.
When you move from such a page to a normal page, \OzTeX\ reverts back to
the scale and location used to display the initial page.
\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| 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 nothing but \verb|\special| commands; \OzTeX\ indicates the
location of each with a small marker (grey on a black and white screen,
or coloured on a colour monitor;
the \verb|Default| configuration file specifies green).
The size of the 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 if you decide
to run \TeX, print a DVI file, or switch to a new 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 dialogue.

\subsubsection{Changing print options}

\OzTeX\ will present a dialogue box that lets you to change
a variety of print options.
Most of them should be fairly obvious --- details can be found
in the description of ``Print DVI\,\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've specified A4 paper
and all fonts have been correctly installed)
but the rest will generate nearly every type of error message
you're ever likely to encounter.
You should eventually get up to page~17 where a deliberate PostScript error
in a \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 dialogue box also lets you send
the PostScript output to a file instead of the printer.
This file is an ordinary text file with a default name of \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'' from the Config menu
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 many PostScript printers don't provide an accurate way of
of finding out the exact paper dimensions and the relative location of the
PostScript origin.

Page 2 in \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 the current configuration file
to shift the origin to the correct position.
(Older versions of \OzTeX\ also used these offsets when viewing DVI pages.
This is no longer the case.
Note that \TeX's \verb|\hoffset| and \verb|\voffset| commands can be used
to adjust the positioning of pages.)
If you use more than one printer then you may need a separate
configuration file for each.


\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 dialogue 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 catalogue.
\item
The paper source: manual feed or normal input tray.
\item
Whether or not to include Laser Prep.
If this option is selected then \prep\ (or whatever is specified in
the current configuration file) will be appended to \dvihdr.
\prep\ is a modified version of Laser Prep --- see the comments at the top
of the file for details on how it was created.
The PostScript code generated by \OzTeX\ requires \prep\ if your
DVI file uses \verb|\special| to include a PostScript file created by
pressing Command-F after selecting OK in the Print dialogue box of some
other Mac application.
A number of modified versions of Laser Prep are supplied in \psfiles\ in case
\prep\ doesn't work with the PostScript code generated by your Mac.
\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
(you might also need to reverse 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 dialogue button you select.
The default Print button will send the PostScript output to the current
printer,
or you might prefer to send the output to a given text file.
Any change to a check box option will be remembered the next time you
print or view a DVI file (but not if you Cancel the dialogue).

\OzTeX\ will look for a file called \globalps\ in the current folder
and include its contents at the end of the PostScript prologue.
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 dialogue 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\ prologue 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*{Transfer\,\ldots}

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

\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 open a desk accessory (which may or may not
support the various editing commands --- the \sedit\ DA distributed with
\OzTeX\ does support them).

\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\ manual
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
\TeX\ looks for a TFM file in the current folder before looking in the default
TFM folder;
this is consistent with the way input files and format files are located.
\item
Nearly all of \TeX's capacity parameters are set at run-time in
a configuration file rather than at compile-time.
If you get a ``\TeX\ capacity exceeded'' error then you might be able to
overcome the problem by increasing the appropriate parameter.
A number of \TeX's error messages have been changed to reflect this possibility;
see the comments at the bottom of \pool\ if you're interested.
\item
At the end of a \TeX\ session the amount of memory allocated is displayed,
as is the time taken.
\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 will need to do if you edit a configuration file and
change any of the following \TeX\ parameters:
\verb|mem_top|, \verb|hash_size|, \verb|hash_prime| or \verb|hyph_size|.
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.
\item
You'll eventually get a standard dialogue box allowing you to save the format
information in the file and folder of your choice.
The default file shown will be \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.
\item
This time the standard dialogue 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 that prefer to use
PostScript text fonts instead of Computer Modern.
Instructions for building this format file can be found in
\verb|Times-LaTeX.tex| in the \texinputs\ folder.

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


\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 dialogue 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 dialogue.
\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 dialogue then \OzTeX\ will close the view window.
If you select the View button then
the current DVI/\TeX\ page numbers will be appended to the DVI file
name in the view window's title and
\OzTeX\ will locate the requested page, interpret it and display it.
You might have to wait a few seconds before
seeing anything, especially if it is a complicated page.

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

\subsubsection*{View ?.dvi}

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

This item is initially disabled; its name changes whenever you
select a DVI file via ``Print DVI\,\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 viewing 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 those used on the current page appear first.
A PostScript font is indicated by its corresponding TFM path name
and the requested point size.
A non-PostScript font is indicated by a PK path name.
Missing fonts are flagged by the message ``\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}.
\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 dialogue box allowing you to select any DVI page for display.
This item is disabled if the view window is closed or
if the DVI file only has one page.

\subsubsection*{Full View}

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

\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 rounded up to the nearest integer equal to the viewing
resolution divided by the Mac screen resolution.
A likely calculation is $300/72 = 4.17$, so the scale factor is set to~4.
In this case a 3\,in wide rule in your \TeX\ input file
won't appear exactly 3\,in wide in the view window
(it will however print correctly if the printer resolution parameter matches
the actual resolution of your printer).

\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 using 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 read from 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.
Note that some parameter values will remain unchanged if the configuration file
uses \verb|?| or \verb|!|.
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
the current 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{Mixing PostScript and \TeX}

\subsection{Using PostScript fonts}

\OzTeX\ allows the use of PostScript fonts within a \TeX\ document.
To be able to use a particular PostScript font, \OzTeX\ needs to know the
name of its corresponding TFM file.  This information is specified at the
end of a configuration file (see the \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.
\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 any luck you might not have to make any changes to your input file.
Note that CM fonts are still needed to typeset mathematics.

\subsection{Including PostScript graphics}
\label{ps-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.)
\OzTeX\ allows you to include PostScript graphics in a document
using \TeX's \verb|\special| command.

Let's assume you have a file called \verb|fig.ps| that contains
PostScript code for generating some sort of figure.
To include this figure in a \TeX\ or \LaTeX\ document, just type
``\verb|\special{fig.ps}|'' after leaving sufficient space:
\begin{verbatim}
   % in a TeX input file                     % in a LaTeX input file
   \midinsert                                \begin{figure}[ht]
     \vskip 3in                                \vspace{3in}
     \special{fig.ps}                          \special{fig.ps}
     \centerline{Figure 1: Pie Sales}          \caption{Pie Sales}
   \endinsert                                \end{figure}
\end{verbatim}
The \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 argument in the DVI file at the current
page position.  When printing the DVI file, \OzTeX\ interprets the argument as
a file name and then includes this file with the rest of the PostScript output.
If it can't find the file in the current folder then it looks in \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 in a
\verb|\special| command.  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, ``\verb|\special{fig.ps 2 1 scale}|'' could be used to double
the width of the figure.
This feature allows you to include the same PostScript file more than once,
but with a different starting line each time --- useful if you need to produce
the same diagram many times but with slight variations.

The hardest part of the scheme is creating the PostScript file in the first
place.  You are faced with two possibilities:
\begin{enumerate}
\item
Learn enough PostScript to be able to draw your own figures.
You'll need to read the PostScript books mentioned in section \ref{read-sec}.
\item
Use another application to create the illustration and then save it
as a PostScript file.
Most Mac programs will create a file called \verb|PostScript0| if you hold down
Command-F soon after selecting OK in the standard Print dialogue box.
If you include such a file then remember to select the ``include Laser Prep''
option when printing the DVI file (see ``Print DVI\,\ldots'' in
section \ref{file-menu} for why this is necessary).
The figure on page~\pageref{folders.ps} of this User Guide was created by
using \verb|\special| to include the file \verb|folders.ps|;
see the comments at the top of this file if you'd like to do something similar.
Note that a PostScript error is highly likely if the included Laser Prep
doesn't match the version required by the Command-F file.

Some Mac programs can create an EPS (Encapulated PostScript) file.
Such a file doesn't require Laser Prep to be included.
\end{enumerate}
\OzTeX\ does not attempt to interpret a PostScript file when viewing a DVI file;
instead it draws a small marker indicating the location of each \verb|\special|.
The ``Page Info'' item will show the
page position and arguments of each \verb|\special| command.
This information is also displayed if you choose the ``show statistics'' option
when printing the DVI file.

\OzTeX\ generates highly efficient PostScript code but it does so at the
expense of some \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.

\newpage

\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 dialogue box near the top right corner
of the screen.
There are actually three types of dialogue 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 two buttons: Quit, which will quit \OzTeX,
and Restart, which will restart \OzTeX\null.
(The Restart button may be disabled, depending on the nature of the problem).
\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.
Let's consider some errors that are likely to be the result
of \OzTeX's particular implementation of \TeX.

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

\subsubsection*{Bad \TeX\ parameter}

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

\subsubsection*{Fatal format file error}

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

\subsubsection*{\TeX\ capacity exceeded}

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

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

\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 the current configuration file.
The memory allocated is displayed at the end of a session.

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

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


\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 only appears once for each
missing font.  The ``Page Info'' item also indicates all missing fonts.
If you set the viewing resolution to some value other than 300 then
you must install a matching set of PK files.

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

\subsubsection*{Page off paper}

If \OzTeX\ detects that any part of a DVI page
(including a \verb|\special| marker)
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 specifying the paper dimensions in the current configuration file.

\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*{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 can't be found in either the current folder
or \psfiles.

\subsubsection*{PostScript errors}

You shouldn't see any errors in the PostScript code generated by \OzTeX,
but there may well be problems in a file included by \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 in section \ref{read-sec}.
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|.

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


\section{Further reading}
\label{read-sec}

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

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

\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

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 Email: tug@math.ams.com (Internet)

\typeout{------------------------------------------------------------------}
\typeout{Select the "Include Laser Prep" option when printing the DVI file.}
\typeout{------------------------------------------------------------------}

\end{document}
