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

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.

• I'd go with metadata. :) Oct 17, 2012 at 23:26
• Ha, I could remember, that Joseph Wright wrote something about it, but couldn’t find it – till now: tug.org/TUGboat/tb32-1/tb100wright-texworks.pdf Oct 18, 2012 at 0:35
• Note that some other editors respect this setting, at least the TS-program setting, such as TextMate. Oct 19, 2012 at 19:55
• Sublime Text 2 (and 3) understands them too.
– twsh
Jun 29, 2013 at 17:09
• Regarding the "who introduced them" question, AUCTeX has been using local variables since 1993 circa (and Emacs implemented local variables about 35 years ago), but none of the others *TeX editors can recognize AUCTeX directives despite this being (probably) the first editor to introduce them. Jun 29, 2013 at 17:22

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 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 having 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 Simplified
• 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

% !TEX spellcheck = fr-CA

but to use the CocoAspell dictionary you would use

% !TEX spellcheck = French (France)
• Nice answer. Thanks for writing it (+1) Oct 18, 2012 at 0:08
• +1, thanks! A few details that I suggest incorporating into your answer: In my testing with TeXworks on Win7, the space between % and ! was crucial for the directive to work. It only seems to recognize (and subsequently use) engines that it knows, so % ! TEX TS-program = latexmk and = pdflatex -enable-write18 did not work. The article by Joseph Wright that Speravir links to also mentions root and spellcheck, which might be worth mentioning. Oct 18, 2012 at 0:47
• @doncherry w.r.t root, I'll add that; w.r.t the other comment, you've misunderstood the nature of engines: they are scripts which are not intended to have arguments passed to them, and they must be known to the editor (in TeXShop, for example, they must be in ~/Library/TexShop/Engines.) I'll need to do a bit more digging into TeXworks to update the answer it seems, as I don't know how TeXworks implements its engines. Oct 18, 2012 at 1:02
• @AlanMunn In TeXworks, the 'engines' option recognises those 'display names' you assign via the Typesetting preferences, and is case-insensitive. In exactly the same way as TeXshop, it can't be used to pass options. (For that, I'd use arara with !TS-progam = arara and a suitable arara directive comment.) Oct 18, 2012 at 6:09
• In TexStudio you can have a look at Options -> Configure TexStudio -> commands (screenshot) to see examples for commands you can use as % !TEX TS-program. E.g. use % !TEX TS-program = latexmk -pdf -silent -latexoption="-synctex=1" % for latexmk. The last percentage sign is very important! Apr 17, 2019 at 7:43

# 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 = yes       | | | Spellcheck
o = no        | | Root
? = ?         | Program
Encoding

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.

• It seems that TextMate does not recognise the instructions if there are spaces between % ! and TEX. Apr 21, 2013 at 8:07
• @Guido Great – in TeXWorks it seems to be just the other way round, cf. my comment When and why should I use % !TEX TS-program and % !TEX encoding?. Feel free to write up a small answer for TextMate. Perhaps we should try to contact the authors of the editors and suggest they allow for a bit more flexibility here. It seems that in TeXStudio, the capitaliztion of TeX matters. Apr 21, 2013 at 14:06
• Nice, it really works for TeXStudio. A feature I always dreamed of, but I never did research on it. Apr 21, 2013 at 15:06
• In Emacs this information uses three %%% instead of a single %. For example,` %%% TeX-engine: luatex, %%% TeX-master: "master"`. Note that .tex extension is absent. This is stored in Local Variables, more information here gnu.org/software/auctex/manual/auctex.html#Modes-and-Hooks Apr 4, 2020 at 15:09

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

• % !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.
• These four directives are not limited to TeXworks but are also available in TeXShop. Oct 30, 2012 at 11:24
• I also tested these in TeXStudio and they worked. May 24, 2015 at 4:55
• Although in TeXShop I had to have TEX with a capital E. Nov 4, 2021 at 13:53

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.

• From change note of version TeXstudio 2.10.8: "detection of magic comment % !TeX is more permissive concerning case sensitivity" - so maybe not a problem any more. Feb 25, 2016 at 22:15