Take the 2-minute tour ×
TeX - LaTeX Stack Exchange is a question and answer site for users of TeX, LaTeX, ConTeXt, and related typesetting systems. It's 100% free, no registration required.

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.

share|improve this question
    
If anybody knows a better term for these thingies, feel free to put it in places of my awkward descriptions of "such lines", "these expressions", "these directives" etc. –  doncherry Oct 17 '12 at 23:15
    
As I know the editor TeXshop on Mac or (I think) TeXWorks use those directives to compile files with the right engine and code. –  Kurt Oct 17 '12 at 23:18
2  
I'd go with metadata. :) –  Paulo Cereda Oct 17 '12 at 23:26
3  
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 –  Speravir Oct 18 '12 at 0:35
2  
Note that some other editors respect this setting, at least the TS-program setting, such as TextMate. –  jtbandes Oct 19 '12 at 19:55

3 Answers 3

up vote 53 down vote accepted

As Kurt mentions in the comments, the directives are understood by TeXShop and TeXWorks. 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 muythesis.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-CA

but to use the CocoAspell dictionary you would use

% !TEX spellcheck = French (France)
share|improve this answer
2  
Nice answer. Thanks for writing it (+1) –  Kurt Oct 18 '12 at 0:08
1  
+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. –  doncherry Oct 18 '12 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. –  Alan Munn Oct 18 '12 at 1:02
1  
@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.) –  Joseph Wright Oct 18 '12 at 6:09

Alan Munn’s answer covered most of the question 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 the them and get correct results.
  • % !TeX spellcheck =language〉:
    Sets the spell-check language to 〈language〉; e.g., en-US or de-DE.
share|improve this answer
1  
These four directives are not limited to TeXworks but are also available in TeXShop. –  meduz Oct 30 '12 at 11:24

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

Please expand!

Note: SublimeText supports Root via LaTeX-Tools

share|improve this answer
    
It seems that TextMate does not recognise the instructions if there are spaces between % ! and TEX. –  Guido Apr 21 '13 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. –  doncherry Apr 21 '13 at 14:06
    
Nice, it really works for TeXStudio. A feature I always dreamed of, but I never did research on it. –  quinmars Apr 21 '13 at 15:06

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.