TeXShop has several build-in methods to typeset documents. But it is possible to add additional typesetting methods; these new methods are called "engines."
An engine can call any sequence of programs in a processing chain which starts from a tex source file and ends with a pdf output file. Strictly speaking, even this pdf output file is optional; one engine supplied with TeXShop uses the TeX Live program tex4ht to convert LaTeX source to an html file; the engine then opens this html file in Safari. Instructions for the sequence of programs called by an engine are given in a shell script.
There is a folder in ~/Library/TeXShop named Engines; the files in this folder are shell scripts which call typesetting programs. When TeXShop first starts, it examines this folder and adds the script names of files it contains to the pull-down typesetting menu. Choosing one of these items and pushing the Typeset button calls the script. Users can write their own scripts and add them to the Engines folder. Each such script must have a name without spaces, and extension ".engine", and have the executable bit set.
Items in ~/Library/TeXShop/Engines can be chosen as the default typesetting method in TeXShop Preferences. Notice that when a method is listed in Preferences, its name is given without the extension.
The default program can be set on one of the first twenty lines of the source code by writing a line like
There must be one space before and one space after the equal sign. A Macro supplied with TeXShop makes adding this line easy; the Macro lists all active engines, making it possible to select the desired engine from a dialog list.
This syntax was later adopted by TeXworks and other front ends. To make life easier when collaborating, TeXShop also accepts the TeXworks form of the command:
The "% !TEX TS-program = ..." line takes precedence over the typesetting method selected in the toolbar. For example, if the above line selecting "xelatex" is in the source document, then hitting the typeset button or selecting "Typeset" in the typesetting menu, or selecting the keyboard equivalent of this command, will typeset the document using xelatex, even if pdflatex is the default typesetting method selected in the toolbar's pulldown menu. If a project contains a root file and several associated chapter files, only the root file needs a "% !TEX TS-program " line.
When writing a new engine file, it is convenient to start by duplicating an existing engine in ~/Library/Engines. The resulting file will automatically have its execute bit set. The file can then be edited with TeXShop to create the new engine.
The ~/Library/TeXShop/Engines folder contains a subfolder named "Inactive" with many additional engine scripts. Examining these scripts will show by example how engine files are written. When an engine is called, the variable "$1" will contain a full path to the source file active when the engine was called. The extension of this file may or may not be ".tex". The engine script may contain many intermediate steps, creating various auxiliary files and processing them with alternate command line programs. TeXShop assumes that in the end a pdf file will be created with the same name as the source file but extension ".pdf". In that case TeXShop will automatically open the pdf file when the engine run ends and scroll to the same spot in this pdf file as in the previous pdf before typesetting. But if no pdf file is produced, TeXShop will ignore this step. In that case, it is up to the engine script to open the result in an appropriate program if desired.
Engine scripts can be written in any convenient language. Most engines use csh or tcsh, but scripts written in perl and other languages will also work.
Engines sometimes use the follow strategy: they typeset an input file, creating an auxiliary file with the same name but some other extension, and then process this auxiliary file using some other program. The sage engine in the "Inactive" folder shows an example; the auxiliary file has extension ".sage" and must be processed by the Sage symbolic mathematics engine. The following code snippet from the sage engine is useful in this kind of situation:
Here {filename:r} removes the extension from the name of a file, and ".sage" adds the sage extension.