TeX on Mac OS X

This is the R&A page on installing, configuring and running TeX on Mac OS X using i-Installer for the installation. It contains links to the current distribution and information that I think is useful for TeX users on Mac OS X. Other sources for TeX on Mac OS X info:

A list of questions I have been asked in relation to my distribution is here. You won't believe it, but this whole installation lack of a train wreck actually attracts fan mail. An edited selection of that fan mail can be found here

You can support my work on TeX distributions. Click to make a donation via PayPal (major credit cards accepted). The software is free, this is not shareware, you are allowed to use it without paying anything and my work on TeX for Mac OS X is a philantropic activity. But donations are welcome to limit the financial damage ;-).

Using TeX on Mac OS X

TeX is a typesetting language. Instead of visually formatting your text, you type your text combined with commands in a plain text file. That file is your TeX source. You then use TeX to produce the final layout. Contrary to a normal word processor, the source and the output are basically separated in two different files.

TeX itself consists of a set of programs and a huge collection of support files containing macros for all kind of layouts (presentations, books, articles, special graphical tricks, etc). These macros make life easy for you. Instead of doing everything yourself in basic TeX commands, the macros provide an easy-to-use set of commands. For instance, the widest used macro collection is called LaTeX and you could type something like:

Macros? Commands? Typesetting? Cant't understand a word of the technical gibberish so far? DON'T PANIC! I think this page is not (yet) for you. Please go here first and then return and start again at "Using TeX on Mac OS X". 

% comments start with the % character
\documentclass[11pt,a4paper]{article}  % selects the article macro set and 
                                       % uses A4 paper size and 11pt font size
\usepackage[english,dutch]{babel}      % use the babel multi-languages macros and 
                                       % select languages english and dutch (default)
\title{How to use \TeX}                % defines the title. This macro is defined by the 
                                       % article class. The \TeX macro is defined in plain TeX
\begin{document}                       % starts the actual document
\maketitle                             % Produce the title. This macro is defined by the
                                       % article class as well. The date is in dutch, our default
\section{How to use \TeX}              % section header, defined by article class

\TeX\ is a typesetting language. Instead of visually formatting your text, you type
your text combined with commands in a plain text file. 

You can use macro packages like \LaTeX.
TeX is a superb typesetter and is therefore very good at formulas: \[\Omega_0 = \left ( 
\frac{\alpha}{\beta} \right ) ^ 4\]

\end{document}

After running the TeX program on that source you will get something like this:

The above may seem complicated. But generally you have seen almost everything to make beautifully formatted documents. The rest is up to you: working in TeX frees you from thinking about visual layout almost completely. You can do what you should do: think about content. It is like having your own personal professional typesetter who worries about layout and does a very good job at it.

So, to use TeX you need basically 3 things:

TeX is able to produce PDF (Portable Document Format, a type of file that can be viewed and printed on most computer systems) directly from TeX sources. This is called pdfTeX.

TeX originally was only capable of producing the device independent DVI file format from the ASCII TeX source. To view or print DVI, the device independent data needs to be translated to a device. For instance an X11 or Windows user interface, or a PostScript or Laserjet printer. Sometimes, the users have to produce a printer format first (like PostScript), which then again is rendered on the screen by a PostScript viewer (like GhostView).

Mac OS X has a Unix core and it is therefore possible to use a Unix TeX distribution on Mac OS X. The source for TeX is TeX Live, the central TeX development system for Unix and other platforms (like Windows), which is published on CD once in a while. TeX Live is huge, programs (for a few platforms) and the foundation (macro's, fonts, etc.) together add up to 1 full DVD. The chief coordinator (there are quite a few maintainers of the various parts) of TeX Live is Sebastian Rahtz. A second very popular TeX (for Unix only) is teTeX, which has been created and is maintained by Thomas Esser. A big advantage of teTeX is that it comes with a well chosen set of support files: teTeX-texmf.

Apart from TeX (and GhostScript), the engine, you need a way to create the TeX source and view the output. If you are into basics and lack of comfort, you can use the existing TextEdit.app to edit your files, use the command line to run pdfTeX, and view the result with Preview.app or Acrobat. If you are less masochistically inclined, there are several frontends available that handle the edit-typeset-view phases for you. Some of them rely on the availability of a distribution like mine to do the work behind the scenes, other may be richer and pack their own TeX distribution. Here are a few frontends:

and tools that may be used when a TeX is installed: (links here are only added at the explicit request of the link owner, I do not maintain this list myself).

The gwTeX (re)distribution

My gwTeX (re)distribution combines TeX Live (for the programs and scripts), teTeX (for the basic foundation) and some additions/changes by myself. Most of it is a redistribution of work by others (like Thomas Esser). I provide TeX-related i-Packages for i-Installer.app, which is a generic open source software installer. That i-Package will offer a somewhat friendly GUI interface to the basic TeX configuration aspects, like hyphenation patterns for languages, paper size, and so forth. I do keep a (Sep 2002, so rather outdated) volume available for emergencies: A dmg (Mac OS X mountable disk image file) with the original TeXGSInstaller.app can be retrieved by FTP from ftp.nluug.nl: TeX-old.dmg. That distribution will not be updated, contains only Ghostscript 6, and at some time in the future it will most likely disappear.

TeX i-Packages

The i-Installer application download can be found here: II2.dmg. This will download a disk image. A disk image is a file that contains an image of a disk. Such a file can be used just like a disk can. You need to mount that disk image. Mounting a disk image can be done by double clicking it in the Finder.

When the disk image has been mounted, you will have an extra `disk' listed in your Finder window. On it you will find two files, a README file and the application itself. If you want i-Installer to be available permanently, copy the application on the mounted disk image to /Applications/Utilities by dragging it in the Finder.

Run i-Installer and (if you are connected to the internet) select the Known Packages submenu. You will be presented with a list of known packages.

The i-Installer volume is also mirrored. The following mirrors are available:

For TeX, you need the following i-Packages which you can open via the Known Packages window:

This will give you a working setup for pdfTeX only, as well as for any TeX Frontend that uses the DVI format (normal TeX). Dvips is also included, so your setup will be able to generate PostScript. If you choose to add TeX4ht during install, you also need to install some other packages, you will be informed during the install.
If you want to use TeX+dvips+ghostscript next to pdfTeX to produce PDF, you need If you want to use the type-1 (PostScript scalable) versions of the standard TeX Computer Modern fonts, you need to add to an existing TeX installation. Or you can use the Latin Modern set that is inside the main package (but it is still incomplete, e.g. math fonts are missing). Or you install both and you can use both.
And there is a continually (daily) updated (if necessary) i-Package for ConTeXt: If you want to use graphic conversions from within TeX sources, you need to add: to an existing TeX installation.

Alternatively, you can download TeX & Ghostscript 8 i-Packages and a copy of i-Installer.app on this 60MB() volume: TeX-fat.dmg (ftp.nluug.nl). This TeX volume is also mirrored:

You are hereby granted permission to mirror the TeX or i-Installer volume, under the following conditions:

TNH: TeX Know How

How and where do I report problems?

Get yourself on the Mac OS X TeX mailing list: Threaded list archives can be found at http://www.masda.vxu.se/~pku/MacOSX_TeX/. To subscribe, send email to info@email.esm.psu.edu with "subscribe macosx-tex" (without the quotes) in the body. For additional help, send email to info@email.esm.psu.edu with "help" (without the quotes) in the body.

In case of problems with i-Installer or with any of my packages, you may contact me. Note that this address may be protected by a home-brew anti SPAM system, in which case you'll normally get a robot-reply to tell you how to reach me.

To be able to help I will need:

i-Installer has a menu option Mail Report in the i-Package menu, which you should use preferably and if possible.

Where can I get generic Mac OS X TeX help?

Not from me. I am not a TeXpert. Get yourself on the Mac OS X TeX mailing list: Threaded list archives can be found at http://www.masda.vxu.se/~pku/MacOSX_TeX/. To subscribe, send email to info@email.esm.psu.edu with "subscribe macosx-tex" (without the quotes) in the body. For additional help, send email to info@email.esm.psu.edu with "help" (without the quotes) in the body.

Joseph Slater has put together a "getting started" page which might be helpful.

TeX Configuration hangs!

The TeX configuration stage checks for some of the mentioned sources of this problem, but there are more things you can do to damage your system setup than I can take care of (the original problem was because someone had used NetInfo to change his home directory settings and he had added a / character to his home directory setting. As it turned out his home directory was huge, so configuration took a week or so because it was searched entirely every time TeX tried to open a file.

First, sometimes TeX Configuration of one of my TeX i-Packages seems to hang. In fact it is only very slow. This may happen when

Secondly, configuration may actually hang if you have changed the environment variables for GUI apps such that these environment variables break the non-interactive use of teTeX scripts (which is what configuration relies on). This problems is unresolved and you should remove any TeX-related stuff from the GUI-app environment setting.

How do I set paper size in TeX?

Re-run the configuration stage of the TeX i-Package. You will be presented with various configuration options, amongst which setting the paper size.

Paper size value is "not in list"?

When you see the following when you try to set the paper size (e.g. letter size) (this problem has reported to me twice):
Error: value 'letter' not in list 'See'.
it is likely that your home directory contains an texconfig-incompatible copy of the configuration file for dvips (config.ps). The reason probably is that the file has classic Mac OS line endings, where texconfig expects unix line-endings. When you run texconfig, it finds that 'classic' copy first, and uses that for a starting point. It might have copied it to the texmf.local system tree already. If you want to be sure you use unix-eols, type the following commands in a Terminal window:
perl -pi -e "s/\r/\n/g;" ~/Library/texmf/dvips/config/config.ps
sudo perl -pi -e "s/\r/\n/g;" /usr/local/teTeX/share/texmf.local/dvips/config/config.ps
sudo texhash /usr/local/teTeX/share/texmf.local
Now, you can safely run the paper setting commands above.

texconfig also has a bug in that it finds and reads the file in your user-tree (in your home directory) but writes in the texmf.local system tree anyway. This will be fixed, I have been told, but I do not know when.

Hey! Your distribution is broken!

Before contacting me, make sure that you have read my README's in /Library/teTeX (README.howtexfindsfiles and README.texmf.gwtex, these links only work when you are accessing them from a system where my distribution is installed and if the second one does not work your installation is outdated). Also, if you have installed personal material in ~/Library/texmf, move it out of the way and try again, before contacting me. Read the output from TeX to find out what could be the error. It is a lot of output, but generally it is rather easy to notice strange things like missing files, files loaded from weird (not /usr/local/teTeX) locations, etc.

I do not deliver generic TeX support (I know relatively little about TeX), but if you really think you need to contact me, e-mail me at my address. Note that this address may be protected by a home-brew anti SPAM system, in which case you'll normally get a robot-reply to tell you how to reach me.

Unavailable macros and packages!

I ship the binaries from TeX Live combined with the basic texmf tree (containing TeX macros and packages) from teTeX to which I have added a few packages that are not in teTeX's distribution. What I ship is a mirror of what I am using myself, which has the advantage that broken things may get fixed before anyone runs into it but it has the disadvantage that errors introduced on my system get replicated. If a package is missing you can download and install it yourself, but you'll need to access the unix command line. Look for packages on Comprehensive TeX Archive Network, which also has a search engine.

If you really think the package should be in my distribution, contact me, e-mail me at my address. Note that this address is protected by a home-brew anti SPAM system, so you'll normally get a robot-reply to tell you how to reach me. If it installs out of the box and is not very big, I will probably add it to the distribution.

Help! TeX cannot find my file! / Where should I install any extra files?

It is possible to store additional style files, fonts, etc., in teTeX itself. But teTeX is owned by the system administrator and lives in /Library/teTeX. It is a good idea to keep this directory pure so it can be upgraded easily when later versions are released. It is better to construct a mirror image of the teTeX directory structure inside your Library folder and store personal files there.

Here is how this works. teTeX uses a directory structure invented by the tex working group. Suppose you want to add a extra style file named new.sty to the style files used by Latex. Look inside teTeX and notice that a natural spot for this file would be

So inside your home directory's Library folder, make a series of subdirectories as follows: and store "new.sty" inside this misc directory.

It is not necessary to replicate the directory nesting as deep as in this example. For .tex and .sty files and their like, using ~/Library/texmf/tex is normally enough depth. For font stuff, use ~/Library/texmf/fonts. Whatever you do below those levels is your choice and thus a matter of taste, it will not influence TeX's ability to find files. If you want to be certain however, copying the official structure is a good idea.

I use four (five) trees where files are stored:

  1. The first is /usr/local/teTeX/share/texmf; this is where program-related stuff is stored and it is upgraded when the TeX programs are updated.
  2. The second is /usr/local/teTeX/share/texmf.tetex; this is the original texmf tree maintained by Thomas Esser, and is kept as default as possible so it can be upgraded without destroying local modifications.
  3. The third tree is in /usr/local/teTeX/share/texmf.gwtex and contains Mac OS X specific settings and additional packages not in teTeX's foundation distribution. This tree is maintained by me.
  4. The fourth tree is in /usr/local/teTeX/share/texmf.local and is for the local TeX administrator (normally, you) to store system-wide additional files. To store in that area, you need System Administrator rights.
  5. In addition, individual users can store their own files in ~/Library/texmf, as explained in an earlier paragraph.

When you reinstall the TeX i-Package, files in the first three trees are overwritten. But files in /usr/local/teTeX/share/texmf.local and in user's home directories are normally left left alone (the exception being setup files created there by automated setup programs, which would break an upgrade if they remained in place).

teTeX looks for files in the following order:

If you followed all this advice and it still fails, one unixy thing is: Open /Applications/Utilities/Terminal.app. In the window that appears type (note: case is important):

sudo texhash
you will be asked for a password. Give your own password. Note: this only works when you are logged in as a user with administrator rights (e.g. the first user that was created on the system).

A final word of warning: Mac OS X is a hybrid system between case sensitiveness and case preservation/insensitiveness. The combination might sometimes lead to weird results. The safest is to create all your directories and files exactly as they are written here.

For details, read the file README.howtexfindsfiles (this link only works when you are accessing them from a system where my distribution is installed).

Help! TeX says it is "stymied"!

The version of your binaries and the version of your compiled formats are out of sync.

Re-run the configuration stage of the TeX i-Package. You will be presented with various configuration options, at the end choose to initialize TeX.

If this does not solve it, you might have another TeX installation in the Library/texmf subdirectory of your home directory. Due to the nature of teTeX, it writes its format files in the system wide location, so old format files in ~/Library/texmf will not be replaced and those may be out of date with respect to newer binaries in my distribution. To check which formats are actually being used and which binary is being used type in a Terminal window (case is important):

which latex
kpsewhich latex.fmt
The first command tells you which latex command (binary) will be used. The second tells you which format file is being used. The output should normally be:
/usr/local/teTeX/bin/powerpc-apple-darwin-current/latex
/usr/local/teTeX/share/texmf.local/web2c/latex.fmt

Help! TeX says there is a problem with a "pool" file!

The version of your binaries and the version of information for that binaries is out of sync. This means that there is a real problem with your installation. This might also be the result of having a second TeX system available. Read the second part of Help! TeX says it is "stymied"! on the possibility that you have another TeX on your system and how to find out about this.

Why does ghostscript not display my .ps file?

Displaying files is not part of the standard GhostScript distributions. You need a special program for that.

However, most frontends will let you display PostScript files. They use ghostscript behind the scenes to distill PostScript into PDF, which is easily displayed on Mac OS X. Tom Kiffe's TeXTools (see above) contains an actual DVI-previewer (which means it can directly render DVI output, without making use of intermediate formats like PostScript or PDF). Given that in certain cases, direct DVI rendering gives the ultimate result, that tool may be handy for you.

How do I configure my installation to use the CM-Super fonts?

Install the CM-Super i-Package.

Where are texbinaries-experimental.ii2 and texbinaries-X11.ii2?

These packages have been retired. They have been removed from my i-Directories and from the servers. texbinaries-X11.ii2 was only a temporary package while X11 support was being tested. texbinaries-experimental.ii2 might reappear when again a big difference appears between TeX Live's source and source.development trees and only when the source.development trees contains necessary fixes.

Where are the TeX Programs and TeX Foundation i-Packages?

As of i-Installer 2.27.0 these packages have been combined. They still exist but are not advertized anymore through the Known Packages window of i-Installer. The programs and foundation parts of TeX will still be separately updatable by me (so you do not need to download 77MB every time something is updated). There is a new combined package: TeX.

What environment variables do I need?

The simple answer is: None. Just install and use one of the GUIs, they will handle this for you. No unix fiddling required. Even the default command line will just work after an install and a restart of Terminal.app.

The more complex answer is: you need to add the binaries directory to your PATH environment variable to be able to use TeX. With respect to the command line, my i-Packages do that for the default Mac OS X shell. With respect to the GUI front ends, it is their responsibility to set the PATH before running a program. Some binaries will work when you call them with full path names and the PATH is not set, but most scripts will fail to work with an invalid PATH. Apart from PATH, I also add TeX to manpath.config. Note: when you update Mac OS X, these init files may be overwritten by Apple, in which case you need to re-run the configure stage.

If you get complaints about missing environment variables you probably have more than one TeX distribution on your system and they are in conflict.

How do I get a € symbol?

I use

\usepackage{marvosym}
in the preamble and then I can use \EUR in the text. Have a look at all the possible symbols in marvosym here.

Configuration error: "The settexpath command is missing from your TeX"

This problem does not exist for the new combined TeX i-Package.

The settexpath script adds your TeX's location to the startup/login environment of the major command line shells. It used to live in the TeX binaries location and it added both TeX and a generic directory (/usr/local/bin, where amongst others ghostscript may reside) to your login setup.

The settexpath command has been rewritten to only add TeX, and a separate script is used to add other directories. Both scripts have been imporved so that they can add and remove stuff at will. And this configuration stuff has been removed from TeX proper and has become part of the i-Packages themselves.

So, if you update your TeX Programs, you will lose the old settexpath from the TeX binaries directory. Instead you will gain the new scripts inside the i-Package. As a result, the old configuration phase will start to complain that it cannot find settexpath (which has been removed after all) and it will erroneously tell you to upgrade TeX Programs as settexpath used to be part of that i-Package. So, this error message was written without the possibility in mind that in the future I would remove the settexpath script.

The solution is:

What is this pdfTeX versus TeX thing?

Different output devices need different stuff to be able to create a display. For instance a 600 dots per inch printer needs a different piece of information to create a display then a 90 dots per inch screen. TeX normally produces DVI (device independent) output. Another process is needed to create something readable. A DVI previewer can translate this directly to a screen, for instance. A program called dvilj4 can translate it to instructions for a HP printer.

The screen in Mac OS X is written using a language called PDF, a language which is also used for documents that can be printed. To be able to display TeX on a Mac screen you therefore need PDF output. There are two ways:

More

Forthcoming: more answers to questions I get asked a lot and only if I have time to add them here...