Getting Started With TEX* on Mac OS X

Joseph C. Slater†

November 17, 2008

*...or other variants
†With input from Jérôme Laurens, and many others on the MacTEX mailing list.

Please note that this document is being phased out. It is not being maintained anymore, and will be superceded by the TEX on Mac Wiki. This document can be downloaded in its entirety. If you are reading this as a web page, good. You have your first example of a web page generated from LATEX using TEX4ht. Editing the .tex file inside the zip archive as described below will get you started with an example.

Getting started with TEX and/or variants* can be an intimidating process for those who not only have to overcome the burden of learning a new way of document generation, but also have to learn how to get a working installation up and running. The goal of this document is to help you get going with a working installation on Mac OS X, not to teach TEX (or LATEX, ConTEX XeTEX etc.). That’s best left to references available on the MacTEX site (note that this document is hyperlinked... clicking on MacTEX site will take you right there!), the main repository for TEX, the Comprehensive TEX Archive Network (CTAN), and the TEX Users group (TUG), or more specifically TUGs MacTEX Homepage. However, if you want to get started with an example, this document is written in LATEX! Please see Section 6 where you can find a URL for downloading the originating LATEX document (with the extension .tex), and some instructions. That section also has an example document that you can type into your editor window and typeset using LATEX.

Arguments for using TEX are available at these locations as well. My personal “pitch” is that I used MS Word(R) for my masters thesis, my dissertation, and numerous papers. I used FrameMaker(R) for three years. I use LATEX now. My personal belief is that it’s better because it is written by the people who need to use it day in and day out, and these people just happen to be, in many cases, highly competent programmers (much more so than I). This is more eloquently described in A beginner’s introduction to typesetting with LATEX by Peter Flynn.

You should start by recognizing that many consider the hardest thing about LATEX to be the installation. Fortunately, this is no longer true. Many software authors have been working diligently for years to bring you what has become a group of the easiest to install and maintain distributions on any platform. With these installations, you can use TEX, LATEX, and many other variants. Because LATEX is the most common (and it’s what I know), I will use it for my examples.

Contents

1 Overview
2 TEXShop and iTEXMac: Unified environments
3 BBEdit, Alpha(X, Tk), TEXMaker, iStorm, and TextMate,…Mac-GUI-like editors.
4 UNIX editors
5 Quick Summary
6 Trying It Out: My First LATEXDocument
7 Conclusion, and getting programs

1 Overview

The first thing to note is that the specific details in this document will start to fall out of date rather quickly. Further, it is pretty well close to impossible to know everything that is available. Thus, you may find other solutions not mentioned here. If they are not listed the Mac-TeX Application Table, please let me know so that I can add them.

Further, whenever you disagree with one of my statements, you are right. The more you know, the more you will have preferences that differ with this document. The more that is the case, the less this document is intended for you.

You need one of each:

  1. The actual TEX distribution: On the Mac there is a significant number (see Mac-TeX Application Table). I recommend the use of either the i-Installer or the TUG MacTEX distribution. Distributions are switching to TEXLive, a superset of teTEX the long-time UNIX standard. Please note that in order for these to work, you must not have have used the option when installing Mac OS X to turn off BSD system1 installation. If you didn’t go through the hassle of turning it off during your Mac OS install, than everything should be fine.
  2. TEX editor: This is nothing more than a text editor. MS Word(R) will work (defeating the purpose of TEX to every extent, and a near-insane idea), but you want one with at least syntax highlighting, and better yet, one with macros and such from menus, and something with some level of integration with the TEX engine, and some integration with a viewer.
  3. A viewer. If you can’t see the formatted document, you’re at a significant loss. A formerly significant complaint of ex-users of TEX and variants was the lack of a viewer. Surprisingly, those folks have opinions that are nearly twenty years out of date. This has been more than rectified with the ability to view the results in DVI (device independent)2 , PS, and PDF formats, as well as, of course, on paper.
  4. The BSD subsystem. It is installed by default with Mac OS X, however, when you install Mac OS X, there is an option to not install this. Don’t do it! If you neglected to install it, go to your Mac OS X CDs and install it before installing i-Installer. Note that this is different from the developer tools, which are yet another collection of things. The typical user doesn’t need these. However, if you are using Fink or MacPorts you will, and you will need to do some reading on their websites. This isn’t the best place to start for most people.

Additionally, you will want a spell checker, but you can wait on this if you just want to get going, if not completely comfortable. The built-in Apple spell-checker can be used in the mean time. It will try to spell check things it shouldn’t/can’t understand, but that’s a secondary issue. However, you’re better off using CocoAspell to get started.

The following sections illustrate some example setups and try to define the type of user suitable for each. The reality is that you may find yourself drifting around trying many of them before settling on what you are most comfortable with. In fact, you may find yourself using different setups for different tasks (one for letters, one for presentations, another for papers, and another for your grocery list). Each scenario is primarily defined by the environment you will spend most of your time in, the editor. There is no right or wrong, simply better of worse for you.

If you have no idea what this section was about, Sections 2, 5 and 6 are for you. Don’t bother with the others until you are more comfortable.

2 TEXShop and iTEXMac: Unified environments

This scenario is for the person who is not UNIX-inclined, hasn’t used LATEX in classic Mac OS, and/or wants a completely free solution. It is likely the best place to start if you are a novice to TEX.

Choose one:

PIC
Figure 2: Screenshot of iTEXMac while editing this document.

Choose one:

I recommend installing both TEXShop and iTEXMac. and trying each of them. If you have difficulty with one, try the other. They each have example files that you can work with, iTEXMac’s being much more extensive.3

For this scenario, most users will find the TUG MacTEX distribution the best option because it’s a straightforward GUI-based installation process. It includes everything I think you need to get started, but I would also download CocoAspell. The Fink teTEX requires some command line usage, but the steps are very well explained on the web site. Fink Commander can make the process easier yet. Using one of the other distribution with TEXShop or iTEXMac doesn’t make much sense to me, although you may want them for their GUI in their own right.

i-Installer isn’t completely mindless to use. You have to decide what to install. Install at the very least the i-Package gwTEX. The rest can wait. It will take some time to download, so you will want access to high-speed internet if at all possible.

Choose one:

The in-line spell-checking capability of CocoAspell, Figure 3, is a nice feature, if not somewhat distracting at times. It acts as a service that can be used by applications enabled to use it. This is likely the best choice for use with these programs unless you do find the in-line spell-checking distracting.

PIC

Figure 3: Screenshot of CocoAspell controls in System Preferences.

Hyperlinks now work work in programs using Apple’s PDF code. However, you must be using thePIC mode (giving you the hand pointer) in order to work.

Both of these applications (TEXShop and iTEXMac) support the pdfsync.sty system for synchronizing at the current location of the viewed PDF file with the corresponding location in the TEX file - please see their respective manual for details on how to use this feature. Essentially, with a special click (like a double-click, or command-click) on the PDF will move you to the corresponding location of the source document. The reverse is possible as well. This is best illustrated in the iTEXMac Examples on Navigation in the iTEXMac distribution.

They both also support external editors, and the ability to support PDF synchronization with external editors is improving rapidly in iTEXMac. At least one user is reported to be synchronizing between the PDF view in iTEXMac and X11 Emacs thanks to support from iTEXMac author Jérôme Laurens.

3 BBEdit, Alpha(X, Tk), TEXMaker, iStorm, and TextMate,… Mac-GUI-like editors.

This scenario is for the person who is not UNIX-inclined, probably hasn’t used LATEX in classic Mac OS, but is comfortable working with an environment spread over multiple applications. Before Mac OS X, this was the only route for using TEX on the Mac. Some of these are multi-platform editors so you can use the same editing environment when not on your Mac. The nice thing about them is that their Mac origins show, and thus the interface is often more familiar than editors in the next section.

Choose one:

Each of these is a powerful programming editor. They will cost on the order of $0-$179. Some are designed to be used for more than just TEX.

Choose one:

PIC

Figure 4: Screenshot of OzTEX while editing this document.

For this scenario, most users will find i-Installer, TUG MacTEX MacPorts or Fink fine. OzTEX and CMacTEX add a integrated GUI to the TEX engines (over what i-Installer does, which is purely reside behind the scenes to be called by other GUIs), resulting in a much easier interface for a novice for special operations (e.g. putting multiple pages on a sheet…). OzTEX is designed as a handful (few) programs that run many TEX operations, while CMacTEX separates each operation out into its own. Each also has a DVI viewer, necessary when using non-PDF TEX.

Choose one:

If PDFTEX is used, any PDF(R) viewer can be used, but hyperlinks don’t work in viewers using Apple’s(R) PDF code (e.g. Preview, iTEXMac, TEXShop, Skim...), so you may want to have Adobe Reader(R) or Acrobat installed to test your hyperlinks.

Choose one (speller):

The in-line spell-checking capability of CocoAspell is a nice feature, if not somewhat intrusive at times. Excalibur spell-checks the entire document when commanded by the user, and is callable from Alpha, (at the very least), and others. The other editors can be scripted to send the document being edited to Excalibur, if they haven’t been already. Note that BBEdit has its own built-in spell-checker.

4 UNIX editors

These are usually for more hard-core UNIX folks (at least in mentality), but others enjoy the power and price, as well as the typically larger expert community. Emacs and vi are UNIX staples, but available on pretty much any platform. This makes them very available where ever you may find yourself. The war will rage to eternity regarding which is better. If you want one environment for all of your editing, TEX and code, choose the one that fits your personality. Note that AlphaTK also has the same platform independence, with matching power.

If you are bringing UNIX skills from another platform, this section simply illustrates that Mac OS X is UNIX. Apple’s web site has a technical brief just for you with the document name Mac OS X for UNIX users TB. For simplicity of maintaining installations, you may want to use Fink or MacPorts. If you are less UNIX inclined, these editors may still be of interest to you because they are free and very heavily supported by the free-software community (GNU, and non-GNU). Both Emacs and VI are available from the terminal, but there are Aqua-GUI versions, as well as X-Windows versions (where applicable). Both have a rather steep learning curves, but for those who use their full power it is well worth it. You may want X-windows installed under this scenario.

Choose one:

PIC

Figure 5: Screenshot of Enhanced Carbon Emacs while editing this document.

Choose one:

See the previous section for installing a TEX engine. OzTEX and CMacTEX add a GUI to the TEX engines, resulting in a much easier interface for a novice for special operations (e.g. putting multiple pages on a sheet…), not as well suited for the UNIX expert (but not bad to have on hand).

Choose one:

If PDFTEX is used, any PDF(R) viewer can be used, but hyperlinks don’t work in programs using Apple’s(R) PDF code so you may want to have Adobe Reader(R) or Acrobat(R) installed. xdvi and xpdf can be installed using fink, or i-Installer. DVI viewers are also available with MacTEX and OzTEX. Choose one (speller):

The in-line spell-checking capability of CocoAspell is a nice feature, but won’t work here. Excalibur spell-checks the entire document when commanded by the user, and is callable (open -a Excalibur filename). ispell and aspell allows spell-checking in-line in emacs. Enhanced Carbon Emacs has this set up ready for ispell when it’s installed.

5 Quick Summary

Some quick points:

6 Trying It Out: My First LATEX Document

The following is a simple document that you can type into your favorite text editor and save as myfirstexample.tex. If you use any of the editors listed in this document, then somewhere in the user interface is a method for calling LATEX.

In TEXShop, one can simply hit the “Typeset” button in the editor window, while in iTEXMac clicking on the big ‘T’ does the same. They will typeset the document. If you get any errors, you have a typo. You should just copy and past the following into the editor window. The output will be a PDF document displayed in a separate window within the application, presuming you didn’t change the default settings of either application.

In other editors/environments, the default behavior is usually to generate a DVI, or DeVice Independent, file. This file can later be converted to PS, PDF, or whatever is necessary for printing. It can be viewed in all known LATEX output viewers, TEXShop and iTEXMac by converting to a PDF first (automatically), and OxTEX, CMacTEX, xdvi, etc. directly. If it typesets to completion, it will automatically be displayed in most cases. If it doesn’t display, you can usually select a menu option to view the DVI file.

\begin{lstlisting}  
\documentclass{article}  
\author{me}  
\date{\today}  
\title{My First Document}  
 
\begin{document}  
\maketitle  
\section{My first section}  
     Now I’m up and running, see equation (\ref{eqn:random}).  
     \begin{equation}\label{eqn:random}  
          \alpha^{\beta}=\frac{\sqrt{\int_{0}^{\infty}x^2 dx}}{\beta}  
     \end{equation}  
     A paragraph  
 
     Another paragraph.  
     Still the same paragraph. In the formatted document, this paragraph  
     will not have a line break after the first sentence.  
     \subsection{In more detail}\label{sec:subsectionmoredetail}  
          Subsection text. The indents don’t have to be here,  
          but they help you see the document structure.  
\end{document}  
\end{lstlisting}  

Don’t get distracted setting up in margins and such. That’s the beauty of LATEX. You don’t worry about visual form. You worry about logical form. Things like eqn:random and sec:subsectionmoredetail above are just variables, for all intents and purposes. What you see above will be enough to get some experience even if you don’t ever read anything else (for now).

Adding figures requires some detail so I’ll spare you of that for now. It’s not hard, but the above concepts are more pressing when you first get started. Resources are available on the MacTEX site. You can use the above document as a template to get started. A good resource for getting started with LATEX is “A beginner’s introduction to typesetting with LATEX”. Additional links are available on the MacTEX site.

Additionally, this document is also available in its original LATEX form as well as a PDF document. If you choose to typeset the LATEX document, you will need the images from the figures. You can save them one at a time from the HTML version of this document at the MacTEX web site by control-clicking on each of them and saving them in the same folder where you put the .tex source file. You can typeset this document fine without them. LATEX will gripe about missing graphics, but you can always answer ‘Q’ (capital ‘Q’ without the quotes) to go into quiet mode. It will continue compiling without stopping to complain.

7 Conclusion, and getting programs

It would not surprise me if you just spent more time from the opening of this document, to getting to this point, then I spent writing it, so please correct me where I’m wrong. The statements above are my personal opinions, and are stated a little more cut-and-dry than the truth in order to help a novice get started. This isn’t intended to be a review of all options, but instead a simple listing of what options are available, with some guidance on what you need for a workable system. The above document gives hundreds of scenarios. The best thing to do is pick one that with the limited advice seems to fit you and your style. However, don’t forget the multitude of other options that exist, should you, expectedly, find your first choice wanting in some areas. The web sites for each of these packages inevitably will describe them much better than I ever could.

To get all/any of these fine programs, please go to the MacTEX web site. Additional resources, including documentation of TEX are posted there as well. In addition, please also consider the LATEX and Mac OS X page. For more information on TEX itself or variants, please go to the TEX Users Group site.

You can always find me and a slew of even more expert people on the Mac OS X TEX mail server. Sign-up is at the MacTEX web site. Good TEXing!