Installation notes for OzTeX 2.1
================================

Andrew Trevorrow, August 1996

E-mail: akt@kagi.com
World Wide Web: <http://www.kagi.com/authors/akt/>


CONTENTS:
Introduction
System and memory requirements
How to install OzTeX
How to print the OzTeX User Guide
Important changes
Choosing an editor
A minimal OzTeX system
Future plans


Introduction
------------

OzTeX is a Macintosh implementation of Donald Knuth's TeX typesetting system.
This file explains how to install OzTeX and print out the OzTeX User Guide.
OzTeX is shareware, so if you like it and decide to keep it then please pay
the shareware fee; see the "Shareware Fee" item in OzTeX's Help menu for
payment details.

OzTeX is normally distributed as a set of BinHex files:

oztex.hqx     * - the OzTeX application (68000 and PowerPC code).
ozmf.hqx      * - the OzMF application (ditto).
ozdvips.hqx   * - the OzDVIPS application (ditto).
correct.hqx     - the Correct file (to check the installation).
configs.hqx   * - the Configs folder.
help.hqx      * - the Help-files folder.
texdocs.hqx     - the TeX-docs folder (contains useful test files).
latexdocs.hqx * - the LaTeX-docs folder (contains the OzTeX User Guide).
inputs.hqx    * - the TeX-inputs folder.
formats.hqx   * - the TeX-formats folder.
fonts.hqx       - the TeX-fonts folder.
vf.hqx        * - the VF-files folder.
ps.hqx          - the PS-files folder.
pk.hqx          - the PK-files folder.
dvips.hqx     * - the DVIPS folder (used by OzDVIPS).
metafont.hqx  * - the Metafont folder (used by OzMF).
ams.hqx         - the AMS folder (for AMS-TeX and AMS-LaTeX).
alphalite.hqx * - AlphaLite 6.2 by Pete Keleher.
bibtex.hqx    * - BibTeX 1.06 by Vince Darley.
makeindex.hqx   - MakeIndex 1.1 by Rick Zaccone.
excalibur.hqx   - Excalibur 2.2.2 by Rick Zaccone and Robert Gottshall.
register.hqx    - Register (to pay the shareware fee).
xwords.hqx    * - X-Words (a meta-Scrabble-like word game).

NB. Users of OzTeX 2.0 only need to get the files marked by an asterisk.


System and memory requirements
------------------------------

OzTeX, OzMF and OzDVIPS run on all Macintosh models from a Mac Plus to
a Power Mac (in native mode) and under all System versions from 4.1 up.
System 7 or later is preferred because OzTeX and OzDVIPS can then call OzMF
to make missing PK fonts on demand, and OzTeX can call OzDVIPS to convert
a DVI file to PostScript.  A colour monitor helps when previewing, but is
not essential.

As distributed, the preferred memory sizes for all applications add up
to about 3.9Mb (or 5.2Mb on a Power Mac with virtual memory turned off).
Typically you should only need two of the three applications running at any
given time.  If you are typesetting very large documents, like a book or a
thesis, then you will probably need to double the memory sizes for OzTeX and
OzDVIPS.  Only Metafont hackers should need to increase the memory for OzMF.

A typical OzTeX system uses about 10 to 15Mb of disk space, depending on
how many bells and whistles you want.  A minimal OzTeX system could probably
squeeze into 5Mb if you only want to run TeX and print/preview the occasional
document (a later section discusses how to set up such a system).


How to install OzTeX
--------------------

If you already have an older version of OzTeX then you should install this
new version in a new folder to avoid clobbering any of your own config files,
fonts, input files, etc.  After you have the new version up and running you
can merge in your own modifications.

Assuming you have enough disk space, carry out these steps:

1. Create a new folder anywhere on your disk and call it anything you like.
   "OzTeX" would be a good choice!

2. Put all the hqx files in the new folder and unpack them.  The easiest
   way to unpack everything is to select all the hqx files and drag them
   onto the icon for StuffIt Expander.  Other programs like Compact Pro
   or UnStuffIt will only convert the hqx files into sea files; just
   double-click on these self-extracting archives to unpack them.
   Delete all hqx/sea files after everything has been unpacked.

3. To check the installation, double-click on the Correct file.  This file
   is a TeachText/SimpleText document containing a picture of a correctly
   installed OzTeX folder.  Make sure your new folder looks the same!

That's it.  OzTeX, OzMF and OzDVIPS should now be ready to run.


How to print the OzTeX User Guide
---------------------------------

NB. Users of OzTeX 2.0 probably don't need to bother printing a new version
of the User Guide because only a few minor changes were made.

1. Start up OzTeX by double-clicking on the application.  It should load
   the Default configuration file, and then an encoding file.  (If you get
   any warning messages about unknown folders or files then you've made a
   mistake during installation, so go back and check the Correct file.)

2. OzTeX is set up to print on A4 paper.  If your printer uses US Letter
   paper then select "US Letter" from the Config menu.

3. Select "Page Setup..." from the File menu and check that the paper size
   and orientation are correct.

4. OzTeX's Default configuration file is set up for a 300 dpi printer.
   If you are using a StyleWriter (or any 360 dpi printer) then select
   the "StyleWriter" item in the Config menu.  If you have an ImageWriter
   (or any 144 dpi printer) then select the "ImageWriter" item.  There are
   also items for a Linotronic (at 1270 dpi) and a 600 dpi printer.

5. Select "Print DVI..." from the File menu and open ozuser.dvi in the
   LaTeX-docs folder.

6. When the print dialog box appears, select suitable options (you might
   want to reverse the page order if your printer stacks pages face up)
   and click on the Print button.

Once the User Guide is printed you might like to read it!


Important changes
-----------------

This release consists mostly of bug fixes.  (There was a lot of new code
in 2.0, so it's not surprising that a few bugs snuck in.  Nevertheless, my
apologies for any inconvenience.)  I also took the opportunity to make a
few config file changes based on feedback from users of 2.0.  Here is a
summary of the important changes:

- OzTeX's pk_folders parameter has been replaced by pk_files.  Instead of a
  list of folders, pk_files has a list of PK file templates (like OzDVIPS).
  The new Default config file contains the same templates used by OzDVIPS.

- Similarly, OzMF's pk_folder parameter has been replaced by pk_file which
  now specifies a template for the PK files created by MakeTeXPK.  OzMF's
  new Default file contains ":PK-files:%f.%dpk" for compatibility with 1.0.

- OzMF's "No PK Folder" config file is now called "Make Local PK".  It sets
  pk_file to "%f.%dpk".

- All VF files in the VF-files folder have been rebuilt to remove redundant
  "MOVERIGHT R 0.0" commands.  Along with some extremely small differences
  in TFM/VF character widths, they caused OzTeX's Fix VFs item to slow down
  dramatically and create very large DVI files.  I've changed Fix VFs to
  prevent this happening.

- OzDVIPS has been modified to correctly handle DVI files created by OzTeX's
  Fix VFs code (or any other implementation of DVIcopy).  In the past it was
  possible to see what looked like very bad kerning if dvips was given a DVI
  file that had been created by DVIcopy.

- Fixed a bug in OzDVIPS that could prevent a non-resident PostScript font
  (LWFN file) from being included in the output.  This only happened if a
  psfonts.map line had multiple "<" entries and the LWFN file was not the
  first such entry (eg. <8r.enc <CMR10).

- Fixed a nasty bug in OzTeX that caused occasional mistakes when calculating
  the size of a PK file; this stuffed up MakeTeXPK when it tried to make
  the missing font.

- A number of bugs in DVIDVI have been fixed.

- MakeTeXPK will now keep processing if errors occur.  All error messages
  are appended to a MakeTeXPK.log file in the same folder as the .make file.

- OzMF has a new auto_quit parameter used by MakeTeXPK.  If true then OzMF
  quits after all lines in a .make file have been successfully processed.

- You can now drag .tfm/.pl/.vf/.vpl files to the OzMF icon and the files
  will be processed by TFtoPL/PLtoTF/VFtoVP/VPtoVF respectively.

- OzDVIPS has a new parameter called bypass_dialog.  If true then the dialog
  box for setting dvips options does not appear and the other dialog option
  parameters are used.

- Another new OzDVIPS parameter is called auto_quit.  If true then OzDVIPS
  automatically quits after a successful dvips run.

- OzTeX has a new parameter called dvips_options.  If "Use DVIPS" is ticked
  then the given string automatically appears in the extra options box in the
  DVIPS dialog.  The Default config sets dvips_options to an empty string,
  but the new Linotronic config file changes it to "-P linohi" and the
  600 dpi Printer config file changes it to "-P 600dpi".

For more details, select "Changes to OzTeX 2.0" from OzTeX's Help menu.


Choosing an editor
------------------

OzTeX does not contain an integrated text editor.  Instead, Pete Keleher's
AlphaLite program is supplied.  You might prefer to use another editor.
Nearly all the text files distributed with OzTeX are created by MPW (that's
the editor I prefer to use).  Note that AlphaLite lets you change the creator
of all text files in a selected folder.

If you are using System 7 or later then one of the first things you should do
after starting up OzTeX for the very first time is to select "Choose Editor"
from the Edit menu.  Use the standard file dialog to select the application
you'll be using to edit TeX/LaTeX input files.  If the application can
receive Apple events then OzTeX will remember its name and location
for later use.


A minimal OzTeX system
----------------------

You might be running short of space on your disk, so let's consider the
bare essentials needed for a working OzTeX system (before deleting any
files it would be a good idea to save a backup copy):

- Use a program like StripFat to remove unwanted 68000/PowerPC code
  from all applications.
- Delete the AlphaLite folder if you use a different text editor.
- Delete the Excalibur folder if you don't need a spelling checker.
- Delete the MakeIndex folder if you don't need to create an index.
- Delete the BibTeX folder if you don't need to create a bibliography.
- Delete OzDVIPS and the DVIPS folder if you don't have access to a
  PostScript printer.
- If you won't be using PostScript fonts then delete all files in the
  VF-files folder and delete the PS sub-folder in TeX-fonts.
- Delete OzMF and the Metafont folder if you have a full set of TFM and PK
  files, and you won't be needing any of the font related tools in OzMF.
- If you don't use LaTeX, delete the LaTeX, Graphics, PSNFSS and Tools
  sub-folders from TeX-inputs.  Also delete LaTeX.fmt from TeX-formats.
- If you don't use AMS-TeX or AMS-LaTeX, delete the AMS folder and AMSTeX.fmt.
  To avoid warning messages when OzTeX/OzMF/OzDVIPS start up, you also need
  to delete all paths containing "AMS" from the three Default files.
- TeX-docs and LaTeX-docs contain important documentation and example files,
  so don't delete any files from these folders until you've looked at them.
- Delete everything in the Help-files folder if you know it all by heart.
- Delete the X-Words folder if you don't like word games.
- Delete the Register folder after paying the shareware fee(s). :-)


Future plans
------------

No promises of course, but here are the high priority changes planned for
the next major release:

- Support HyperTeX \specials (for hypertext links in DVI files).
- Other improvements to previewing (eg. find a given string).
- Better support for colour (after I get a colour printer!).
- Make OzTeX/OzMF/OzDVIPS fully scriptable.


Happy OzTeXing!