Percent-Ampersand Is Not Shebang


%& is not a shebang.

Somewhere on the internets I picked up the idea that the first line of a tex file should specify what flavor of TeX it’s written in, where flavor was one of TeX, LaTeX, XeLaTeX, XeTeX, etc. I think was imagining that it was some kind of TeX-internal version of the “shebang” #! that tells a Unix shell what program to use to execute a script. Indeed my standard template file had such a line (but not any more).


After a lot of googling and digging and frustration, I have learned the following. (This sort of thing happens a lot, when you want to know about anything that has to do with to the running of TeX instead of just typesetting it.) The %& comment, which I propose to call the “peramp,” is a mechanism for feeding a “format” to the tex engine. A format, as one learns from Victor Eijkhout’s book TeX By Topic, is a kind of precompiled bundle of macros that the basic TeX engine can use. (Even “plain” TeX, it turns out, is the TeX engine using a “plain” format). It is possible to make your own formats and feed them to the TeX engine at the command line (cf. the tex manpage) with a command like tex &myformat.fmt. As one might guess LaTeX is implemented as a format. The pdftex engine, furthermore, supports switching among plain TeX, LaTeX (both dvi output), pdfTeX, and pdfLaTeX using formats. So—this is kind of cool—if your source file has a peramp line of the form %&engine, you can process it with any of latex, pdftex, and pdflatex and get consistent results equivalent to processing it with engine at the command line. In fact it seems that for a while all of these engines have secretly been the single pdftex program invoked with the appropriate format.

Apparently some other TeX varieties I don’t use can also be handled this way. Unfortunately, XeTeX, which I do use, is not secretly a TeX format. As the author of XeTeX testily explains in this mailing list post I found, xetex is an independent engine and must be invoked as such on the command line. pdftex will not switch over to xelatex if it finds %&xelatex at the start of the file, and xelatex will not switch over to pdftex in the converse situation. The engine xetex does support TeX formats compiled specifically for it—that is what XeLaTeX is. So if you run xetex on a file that begins %&xelatex it will indeed be processed as XeLaTeX and not as plain XeTeX.

The water is further muddied because I seem not to be the only person to have picked up this idea about peramp-as-shebang, and there are programs on the internet that this method or a variant. In particular the GUI front-end TeXShop does support this kind of engine detection, with its own distinctive first-line syntax: %! TS-program = XeLaTeX (note the caps). But this is specific to TeXShop, not a feature of TeX.

Working with TeX one often feels one has stepped into a kind of Bizarro *nix Land: a lot of things look very similar to, but not quite the same as, things in a Unix-style programming environment. This is, I think, mostly evidence of TeX’s age (older than the GNU project) and devotion to backward compatibility. It’s also evidence of the fact that TeX users have not, by and large, been programmers but scientists, who (in my small experience) seem to specialize in Bizarro Programming.

[Edit, same day: If you use tex at the command line, it will not process a peramp-line for one of the other formats.]