Setting up LaTeX on Mac OS X
Update (21 Sep 2007): TextMate's LaTeX bundle has been significantly improved and can now be configured using a Preferences dialog which is available from the Gear menu. My recommended preferences: set default Engine to pdflatex, enable use Latexmk.pl, set "View in" to Skim, enable "Show PDF automatically" and "Keep log window open".
I will write an updated article that includes all these changes when time permits.
Update (3 Aug 2007): PDFView, the PDF viewer application that has been recommended in a previous version of this article been discontinued. I have updated the article to use the Skim viewer, which is an excellent replacement for PDFView.
For using LaTeX on any computer system, you need 3 essential pieces of software:
- a text editor for editing your LaTeX source files,
- the LaTeX program for processing your LaTeX source files into typeset PDF documents, and
- a PDF viewer program for previewing and printing your documents.
There are plenty of text editors, PDF previewers and LaTeX distributions available for Mac OS X platform.
My suggestion is to base your LaTeX environment on the TextMate editor. TextMate is not only a highly customizable, general purpose text editor, it also provides excellent LaTeX support and integrates tightly with the Skim previewer. This combination of tools, lets you use LaTeX in a convenient and Mac-like way.
Installing the software
Install LaTeX
LaTeX is open-source software, hence you can download and install LaTeX for free. If you are already using Macports or Fink for installing Unix software under OS X, I recommend to install LaTeX using these package managers. Macport users install LaTeX with port install tetex, Fink users use the command fink install tetex.
If you are neither using Macports nor Fink, I recommend to download MacTeX, which is a precompiled LaTeX distribution for OS X. MacTeX provides a full LaTeX installation plus a number of additional tools. Quoting from the MacTex website:
MacTeX.dmg is an install package for Apple's installer. The package contains the complete TeX Live 2007 distribution of TeX, Ghostscript, ImageMagick, and the following front end programs : TeXShop, LaTeXiT, BibDesk, Excalibur, and i-Installer. A custom install option allows users to bypass some of these packages if desired.
Install Skim
I highly recommend to use Skim for viewing PDF files generated by LaTeX, since it supports tight integration with your LaTeX text editor. Skim is also an open-source application can be downloaded from the Skim website. Download and install Skim. Open Skim's preferences dialog, select the Sync tab and make sure that the "Check for file changes" option is enabled and that PDFSync support is set to the TextMate preset.
Install TextMate
TextMate is a popular text editor for OS X. While the editor itself is commercial, TextMate has a very lively open-source developer community that provides extensions, called bundles, for many different purposes. By default, TextMate ships with an excellent LaTeX bundle. You can download a free trial version from the Textmate Website and purchase a full version for 39€.
For my recommended setup you need to set a few preferences for TextMate and the LaTeX bundle. Open TextMates Preferences dialog and make the following settings:
In the Software Update dialog, enable automatic updates to the Cutting-Edge version for TextMate. This configures TextMate to update always to the latest versions of the application and the bundles. Don't be affraid, TextMate's cutting-edge versions are generally very stable.
In the Advanced menu and select the Shell Variables tab. Use the plus button to add two variables named TM_LATEX_COMPILER and TM_LATEX_VIEWER. Set TM_LATEX_COMPILER to the value "latexmk.pl" and set TM_LATEX_VIEWER to "Skim" (both without double quotes).
Your LaTeX editing environment is now setup and ready to be used.
Edit and compile your LaTeX documents to PDF
Run TextMate and start editing your LaTeX document. You may either start from an empty file or use one of the templates provided in the "File → New from Template → LaTeX" menu.
You can see the actions provided by the LaTeX bundle by clicking the gear symbol in the status bar
and selecting the LaTeX bundle. Each command is also labeled with its keyboard shortcut.Make sure, that the LaTeX language mode is enabled. You can select the language mode in the dropdown menu of TextMate's status bar.
For compiling your document with LaTeX press ?R. Alternatively, you could also select "Typeset & View PDF" in the LaTeX bundle menu. TextMate shows the log messages, warnings and errors generated during the compilation in a popup window. TextMate automatically opens Skim if the LaTeX compilation was successful.
If errors were raised during compilation, you can jump to the respective line in your LaTeX source by clicking on the error message in the compilation popup window.
For enabling the integration of TextMate and Skim you need to use the pdfsync package by including \usepackage{pdfsync} in the preamble of your document. With pdfsync enabled you can press ???O (or use the bundle's "Show in PDFViewer (pdfsync) command") to jump to the matching place in the PDF file. Vice versa, when Shift-Command-clicking on a location in Skim TextMate is showing the matching paragraph in the LaTeX source.
Detailed documentation on the LaTeX bundle and its configuration is available with the "Help" action of the LaTeX bundle.
Various remarks:
- TextMate provides very good support for UTF8 encoded text. If you are writing LaTeX texts in languages requiring accented letters or umlauts, you should add the following preamble to your document (replace french with your language):
\usepackage[utf8]{inputenc}
\usepackage[french]{babel}
\usepackage[T1]{fontenc}
The inputenc package allows you to directly type accented characters in the LaTeX source, i.e., you can simply type ä instead of "a. Further, the fontenc package ensures that hyphenation also works with words with accented letters.
- Since PDF is the standard file format for vector graphics and text in OS X it is natural to use the PDF-based pdflatex tool-flow, as suggested in this article. This implies, that all the graphics you are including with \includegraphics in the LaTeX document are expected to be also in PDF format.