When and why should I use % !TEX TS-program and % !TEX encoding?

Question

Occasionally, I see other people's documents starting with two lines like that:

% !TEX TS-program = xelatex
% !TEX encoding = UTF-8 Unicode

It's clear to me that the first line declares the engine that should be used for compilation, and the second lines states the text encoding of the input file. It's not clear to me, however, when and why I should use such expressions.

More detailed questions on this subject matter would be:

• How can I compile without determining which engine I want to use so that I would even need that comment?
• Which editors/programs pick up on these directives?
• Who introduced them?
• Is there any "documentation" of possible values etc.? Are there more such expressions? Are they standardized in any way?
• Can I add options to the compilation engine, e.g. pdflatex -enable-write18 or xelatex -interaction=nonstopmode?
• What does the "TS" in TS-program stand for?
• What additional value does the encoding line provide if I'm already using inputenc?
• Are there any downsides to using them or reasons not to use them?

_{Meta: Even though it technically contains multiple questions, I'm pretty sure this question conforms with our standards as a catch-all question on a narrow topic. I guess I know some partial answers to some of my questions, but I'll leave that up for people who have experience with these expressions. I just wanted to provide a question that allows for a maximal amount of information on this subject matter.}

Answer 1

The directives are understood by TeXShop, TeXWorks and TeXstudio. The TS stands for TeXShop, which was the IDE that first implemented them on the Mac. (Other editors have similar kinds of metadata.)

I'll comment on each directive separately, since I think they are not equally useful. My comments apply in principle to both TeXShop and TeXworks. J.C. Salomon's answer gives the details for TeXWorks. As he also points out, there are also two other useful directives that you can also use in TeXShop and TeXWorks. I've mentioned these too.

% !TEX TS-program =

This directive allows you to choose the engine that will process the file directly in the file itself. This is mainly useful if you use multiple engines in your work. The default engine in TeXShop is pdfLaTeX. I use a mixture of pdflatex, LuaTeX, XeTeX and LaTeX+dvips in my documents (depending on a variety of factors), so for me this directive is extremely useful, since I just specify the engine in the file and TeXShop automatically does the right thing with a single keystroke. It's much more annoying to have to choose the engine manually from the pull down menu.

If you only use one engine in your work, and you set TeXShop up to use that as its default, then there is no real advantage to using the directive. On the other hand, if you share documents with others, it might still be useful, since it will override their defaults (if they are using TeXShop/TeXworks) or minimally give them some indication of how they need to compile the shared file (if they are using another editor).

% !TEX encoding =

This tells TeXShop to save the file using the specified encoding. I can see very little need for this, and don't use it myself, mainly because I use only UTF-8 for all my documents. But again, if you do need to work on files with multiple encodings (for example if you are collaborating with others who don't use UTF-8) it might be useful since when you save the file the encoding specification will override the default save encoding of TeXShop. (I'm not sure if TeXworks behaves the same way.)

There is very little relation between the encoding directive and what option you pass to the inputenc package (other than the fact that they should be identical). The option passed to inputenc tells TeX what to do (roughly); the encoding directive tells the editor what to do. In this respect they are completely independent of one another.

% !TEX root =

This directive set the root file for a document is included into a larger document using \include or \input. This is very useful since it allows you to edit the included file and just use the regular Typeset command to typeset the whole document (since you can't typeset the included file itself).

For example, suppose you have a main file mythesis.tex which has a bunch of chapters included with \include{chapter1}, \include{chapter2} ... etc.

In each of the chapter files, you would put the line:

% !TEX root = mythesis.tex

Then you can edit chapter1.tex and when you choose Typeset, it will typeset mythesis.tex. Used in conjunction the LaTeX's \includeonly facilities, you can easily edit and compile parts of a large document.

The file given in the root path can be relative to the included file. For example, suppose mythesis.tex is in your main folder, and each chapter is contained in its own folder. Then you could use:

% !TEX root = ../mythesis.tex

As with the Program and Encoding directives, TeXShop provides macro to choose the root file. When you choose Root from the Macros menu, you are presented with a file selection dialogue box. Navigate to the correct root file and choose it, and TeXShop will fill in the correct relative path. (So there is no requirement that you understand Unix paths.)

% !TEX spellcheck =

If you write documents in more than one language, you can also tell TeXShop which spelling dictionary to use for each source file. For example if your default dictionary is English, but you sometimes write in French, you can add:

% !TEX spellcheck = fr-FR

for French.

% !BIB TS-program =

This directive allows you to choose the bibliography processing backend (either bibtex or biber) It accepts an alternate syntax as well:

% !BIB program = 

Downsides

I can't think of any downsides to using them.

Possible values

*Engines*

There is a potentially infinite number of values for the TS-program directive, since the value is the actual name of an engine, and engines can be anything you can put in a shell script. TeXShop has a macro to choose the Engine from among all of the active engine files.

File Encoding

There is a finite number of values for the file encoding. In TeXShop there's a macro to choose from a list. The currently supported encodings are:

• MacOSRoman
• IsoLatin
• IsoLatin2
• IsoLatin5
• IsoLatin9
• IsoLatinGreek
• Mac Central European Roman
• MacJapanese
• DOSJapanese
• SJIS_X0213
• EUC_JP
• JISJapanese
• MacKorean
• UTF-8 Unicode
• Standard Unicode
• Mac Cyrillic
• DOS Cyrillic
• DOS Russian
• Windows Latin 1
• WindowsCentralEurRoman
• Windows Cyrillic
• KOI8_R
• Mac Chinese Traditional
• Mac Chinese Simplified
• DOS Chinese Traditional
• DOS Chinese Simplified
• GBK
• GB 2312

Root

The possible values are any valid path to a root .tex file. TeXShop has a macro to choose the root file via a standard file navigation dialogue.

Spellcheck

Here the possible values are dependent on whether you are using the built-in Apple spelling dictionaries, which follow the ISO 639-1 or ISO 639-2 language codes, or CocoAspell, in which case you need to use the names as shown in the System Preferences -> Spelling panel (not the names listed in the Language and Text preference).

So in the French example give above, to select the Apple dictionary you use:

% !TEX spellcheck = fr-FR

or for Canadian french:

% !TEX spellcheck = fr-CA

but to use the CocoAspell dictionary you would use

% !TEX spellcheck = French (France)

Answer 2

Editors that understand % ! TeX directives

              E P R S
TeXShop       x x x x
TeXStudio     x x x x
TextMate      ? x x ?
TeXworks      x x x x
SublimeText   o x x x
Atom          o x x o
Vim (vimtex)  o x x o
Overleaf      ? x x ?
              | | | |
x = yes       | | | Spellcheck
o = no        | | Root
? = ?         | Program
              Encoding

Please expand!

Note: SublimeText supports Root, Engine and Spellcheck via LaTeX-Tools. To use Spellcheck Dictionaries should also be installed.

Note: Atom supports Root and Engine via Atom-LaTeX

Note: Vim (vimtex) here implies using Vim with the vimtex plugin loaded.

Answer 3

Alan Munn’s answer covered most of the questions for TeXShop; I’ll explain them for TeXworks.

(This is adapted from Joseph Wright’s blog post TeXworks ‘magic comments’.)

• % !TeX program =〈program〉:
  〈program〉 should be one of the programs set up in TeXworks and is case-insensitive. (Note that the “TS-” in TS-program is optional in TeXworks.)
• % !TeX encoding =〈encoding〉:
  See Alan’s answer for possible values of 〈encoding〉.
• % !TeX root =〈file〉: TeXworks will typeset 〈file〉 instead of the current file. This is useful when you have a large document split into separate source files using \include or \input. If you put a pointer to the root document in the subsidiary files, you can use the Typeset button when editing them and get correct results.
• % !TeX spellcheck =〈language〉:
  Sets the spell-check language to 〈language〉; e.g., en-US or de-DE.

Answer 4

I use to be a TexShop user for a while, I had most of my documents with the % !TEX root= directive. This works great for big projects: Each chapter had it's own tex file and was located in different folder. I would have most files on Dropbox and I wouldn't need to open up the larger main file that had the \input commands when I was compiling from any chapter tex file.

But when I move to TexStudio I notice the directive is case sensitive On TexStudio the directive is % !TeX root=

So, if I need to open a file on another computer with another editor I need to be aware of this small difference. I am glad that TexStudio is cross-platform and works in all OSs.

Answer 5

If you use very oldie but goodie CompileTeX for Bbedit it will allow you to use some % !TeX features, for example I use it to add --shell-escape to lualatex. (MacOSX)

% !TEX TS-program = lualatex --shell-escape