Up and Running with TeXShop Engines

In the previous post, I talked you through setting up MacTeX and bundled Mac apps. In this post, I want to introduce you to TeXShop, a powerful piece of software that is so much more than a text editor.

At first glance, TeXShop is “just” a text editor. This shouldn’t surprise anyone since TeX or LaTeX files are just ASCII files and can be created and edited in any app that handles plain ASCII files. Word processors typically use proprietary binary files and/or files in some format other than ASCII so this is another reason to abandon word processors. Modern operating systems support Unicode characters and these can now be included in plain ASCII files with no problems. This means that on a Mac, you could, in principle, use the TextEdit app that comes bundled with the operating system or even a dedicated programming editor like BBEdit. In fact, you really don’t need a fancy text editor at all to process your documents; that was originally intended to be done from a command line anyway, and can certainly still be done that way. Creating a beautifully typeset document with TeX or LaTeX (which is a macro layer on top of the underlying TeX engine) is very much analogous to creating a computer program and an integrated development environment (IDE) could be handy. TeXShop provides such an environment on the Mac. TeXShop has a long history with many contributors over the years since 2000 when lead developer Richard Koch began the project. It was one of the earliest Cocoa apps for Mac OS X (now called simply macOS) and it was the main app I was interested in using when I switched to the Mac platform in May of 2002 (funny how I remember that date). The most frequent mistake I see newcomers to LaTeX and TeXShop make is trying to use TeXShop itself to process documents, which it cannot do. MacTeX must also be installed. Of course you can use TeXShop as an editor without having MacTeX, but that’s all. Again, MacTeX must be installed for TeXShop to process documents.

When you launch TeXShop the first time, it creates a folder structure in your ~/Library/TeXShop folder. I want to discuss three of these folders: bin, Engines, and Templates in that order. I assume readers are comfortable using Finder to navigate folders.

Users familiar with UNIX terminology might recognize bin as being a directory (aka folder) where executable code is stored. That’s also true in this case, but assuming you installed TeXShop when you installed MacTeX, the actual TeXShop app code is in your /Applications/TeX folder. Here’s why this new bin folder is needed. There is a popular command line utility called latexmk by John Collins. It’s a powerful Perl script that handles the drudgery of running your TeX or LaTeX engine the right number of times to resolve cross references. It is bundled with MacTeX. Users familiar with compiling C/C++ or FORTRAN programs from a command line will recognize it as an equivalent to the make utility. Well, TeXShop includes its own internally bundled installation of latexmk and it lives in the ~/Library/TeXShop/bin/tslatexmk folder. So when you install MacTeX and TeXShop, there are actually two installations of latexmk. However, the one bundled with TeXShop is visible only to TeXShop and can’t easily be accessed from the command line, thus the two installations don’t interfere with each other. The new bin folder also contains other executable bits and bobs TeXShop uses. The bottom line is that TeXShop uses its internally bundled version of latexmk to communicate with the engines that ultimately process your documents.

This brings us to the Engines folder. Upon opening this folder in Finder, you will see a Folder named Inactive and a few files with the file extension .engine (you may have Finder configured to hide filename extensions if you can’t see them).

Inside the Inactive folder, you will see more folders named for specific tools you may (or may not) need for various kinds of documents and for different ways of processing your documents.

Now I need to distinguish between an engine and a .engine file. In the TeX world, an engine is a piece of software that inputs your ASCII source file (always with a .tex extension) and outputs a beautifully typeset PDF file. Most LaTeX users use pdfLaTeX as the standard engine for creating PDF files, and before that used the original LaTeX engine (which output DVI files). TeX itself is both the name of an engine and the macro language used to program that engine via commands in one’s document. LaTeX is both the name of an engine and a set of macros that works on top of TeX to make creating documents more logical and straightforward. The modern, standard engine is now LuaLaTeX. You see, TeX and friends were invented long before PDF files were invented and it was only in the 1990s that TeX systems could output PDF files. That accounts for the name pdfLaTeX as opposed to the more generic LaTeX. Both LuaTeX and LuaLaTeX output PDF files by default so there’s no need to include PDF in its name. Incidentally, Lua is the Portuguese word for Moon but it’s also the name of a programming language originally designed in 1993 (the same year PDF files were invented). The LuaTeX and LuaLaTeX engines are also programmable via Lua commands in one’s document. I don’t know the Lua language so have no idea how to do this. Aside from that, the Lua engines should be your new default engines because they can do a few things that the older pdfLaTeX and TeX engines cannot do. One thing is they can make use of Unicode characters in files, and another is that they can use a wider variety of fonts. Be aware, though, that some professional publishers (think academic journals) require authors to use pdfLaTeX and this is unfortunate since it limits what can be done (the TeX community should push back against this). So, an engine is an actual piece of software that turns a source file into a typeset PDF document.

So what is a .engine file? Well, a .engine file is nothing more than a shell script that calls a particular document engine (e.g. LuaLaTeX) with various options supplied by the user. TeXShop uses .engine files to pass your ASCII source file to the chosen engine, which in turn produces your typeset PDF file. These shell scripts are how TeXShop communicates with the various engines via latexmk (if the script has mk in its name) or directly (no mk in the script name). You don’t have to understand anything about shell scripting to use any of this, although it’s a very powerful way to get things done if you’re comfortable using a command line (or Terminal in the Mac world). The .engine scripts can be edited and customized, but one must be careful because one mistake could render TeXShop unable to correctly do its job. I will not discuss editing .engine files or shell scripting any further. Read on to learn how to use .engine files in TeXShop.

TeXShop looks in the Engines folder to see what .engine files, and thus what typesetting engines, it will potentially use. Decide which ones you think you want to use and move the files from inside the Inactive folder hierarchy to the Engines folder. I recommend the set of .engine files in the screenshot above (they are LuaLaTeX.engine, lualatexmk.engine, LuaTeX.engine, pdflatexmk.engine, and dtxmk.engine). Again, unless you are doing LaTeX package development with DTX files, you will not need the dtxmk.engine file, but I do package development (see my mandi package, which is also included in MacTeX) so I need that file. Note that sometimes when a new version of TeXShop is released, the .engine files are updated and you will need to go through the process of moving your chosen files from the Inactive folders back into the Engines folder. Otherwise, you won’t get the updated files.

Now, here’s where all this pays off. When you launch TeXShop to create or edit a document (almost always an ASCII file with a .tex extension), there’s a button at the top of the window labeled Typeset. Immediately to the right of that button should be another button that lets you select an engine. You should see an entry for each .engine file in your Engines folder. There will be other options available, but don’t worry about them at this point.

So simply select the engine you want to use (e.g. lualatexmk) and then click the Typeset button. If you use an engine that works with latexmk, your document will be processed to completion with no further intervention required unless there are errors (I’m not getting into debugging in this post). If you select an engine that does not use latexmk (e.g. LuaLaTeX) you may need to manually press the Typeset button two or three times to process your document to completion.

Finally, let’s talk about templates. If you use LaTeX frequently, it is sometimes helpful to begin with a skeleton document containing essential parts already in place. TeXShop easily allows for that. Just created your skeleton document as though it were a complete document and save it in the ~/Library/TeXShop/Templates folder. Because TeXShop comes with a number of templates, and to make my own templates easier to find and maintain I created a ~/Library/TeXShop/Templates/Joe/ folder for mine. Quit TeXShop and launch it again, and you will be able to select your templates from the Templates button in the tool bar. When you click on one, it will immediately load into TeXShop. Remember to save it under a new name and in a new place to avoid overwriting the template file.

To end this post, I want to show you one last thing you can do in a template (or any other document source file) that is really cool. Here’s my most frequently used template.

% !TEX program = lualatexmk
% !TEX encoding = UTF-8 Unicode

\documentclass{article}

%\usepackage{amsmath}
%\usepackage{array}
%\usepackage{booktabs}
%\usepackage{enumitem}
%\usepackage{geometry}
%\usepackage{iftex}
%\usepackage[language=english]{lipsum}
%\usepackage{listings}
%\usepackage{mathtools}
%\usepackage{minted}
%\usepackage{mwe}
%\usepackage{nicematrix}
%\usepackage{numerica}
%\usepackage{pgfopts}
%\usepackage{pgfplots}
%\usepackage{qrcode}
%\usepackage{tabularray}
%\usepackage{tcolorbox}
%\usepackage{tensor}
%\usepackage{tikz}
%\usepackage{unicode-math}
%\usepackage{xcolor}
%\usepackage{hyperref}

\begin{document}


\end{document}

Note the first two lines. These are sometimes called “magic comments” and you may already be familiar with them within the context of Jupyter Notebook/Lab. The first one tells TeXShop to always process the current file with the lualatexmk .engine described above. The magic comment overrides your engine choice from the toolbar. It guarantees the document will always be processed the same way on any machine. The second magic comment defines the current file’s encoding and allows for using Unicode characters. Most LaTeX editors recognize magic comments and they should work across platforms.

I hope this post helps you better understand a bit about TeXShop’s inner workings and how it can be configured to use any of the various TeX engines. If you have questions or comments, please let me know.