# The role of %&latex at the beginning of a source latex file

Could someone please explain what is the role of %&latex which is put in a source LaTeX file before \begin{document} command?

-
@egreg Maybe you could point to some on-line material concerning the issue? –  Mad Hatter Feb 18 '14 at 11:33
–  texenthusiast Feb 18 '14 at 13:42

In olden times, TeX came in two incarnations: initex and virtex. The first binary was used to create formats such as Plain and LaTeX, the second one was used for typesetting documents after loading one of the available formats.

initex lplain


and save the created file lplain.fmt in some suitable directory; from then on, it was possible to typeset a document with

virtex '&lplain' file


Of course many users or system administrators defined aliases, so that one could simply call

latex file


During the years several tricks for easing the choice of formats were devised. For instance, some systems made a memory dump of initex instead of doing \dump, so the dump could be turned into an executable, so speeding up the start of the run.

Another trick was to allow TeX to parse the first line of the first input file, so if the file was

%&latex
\documentclass{article}
\begin{document}
The Mad Hatter and the White Hare.
\end{document}


a simple call

tex file


would have been equivalent to tex '&latex' file. Yes, in more recent times, instead of virtex the executable was being called tex and the format for LaTeX was being created with initex latex.ltx, so the format produced was latex.fmt.

This “first line parsing” is available also with current TeX distributions. I'm not sure what's the status of MiKTeX (what I know is that it allows more options to be specified).

The TeX Live distribution uses a different strategy; when a format is created (using the script mktexfmt-sys), say for pdflatex, a symbolic link

pdftex -> pdflatex


is created in the binary directory; this is what I have on my system:

lrwxr-xr-x  1 root  wheel  6 Apr 20  2013 /usr/texbin/pdflatex@ -> pdftex


This makes pdflatex into an “executable”, but pdftex is actually run; the program has the ability of knowing what name it has been called with, and do the appropriate action when loading the format.

So, what happens if you have the file above and run the command line

pdflatex file


without any other option? The “first line parsing” is active, so this overrides the format choice based on the calling name and the latex format is chosen, which produces its output in DVI format rather than PDF.

So, the best thing is not to use the first line in that format. It's confusing, at the least.

You can look at the documentation of TeX Live, for more information:

http://texdoc.net./texmf/doc/texlive/texlive-en/texlive-en.pdf

discovering that the option is not even described. The man page for pdftex has

-parse-first-line
If the first line of the main input file begins with %& parse it to look for a dump name or a -translate-file option.

-no-parse-first-line
Disable parsing of the first line of the main input file.

[...]

-translate-file tcxname
Use the tcxname translation table to set the mapping of input characters and remapping of output characters. This feature can be useful if you have a personal special format and don't want to bother with creating aliases or symbolic links.

The TeX Live manual talks a bit about TCX files that are, however, a relic of the past, mainly.

The feature can be turned off at run time by calling

pdftex -no-parse-first-line


(any symbolic link pointing to pdftex can be used). Note that the feature is turned off by default when using tex (that is, the original Knuth TeX, not able to produce PDF output). The relevant settings in the standard texmf.cnf file are

% Allow TeX, and MF to parse the first line of an input file for
% the %&format construct.
parse_first_line = t

% But don't parse the first line if invoked as "tex", since we want that
% to remain Knuth-compatible.  The src_specials and
% file_line_error_style settings, as well as the options -enctex,
% -mltex, -8bit, etc., also affect this, but they are all off by default.
parse_first_line.tex = f
parse_first_line.initex = f


parse_first_line = f


to the top level texmf.cnf file, that is

/usr/local/texlive/2013/texmf.cnf


for the 2013 release, you turn off the feature for all binaries.

-
miktex-pdftex has --parse-first-line and --dont-parse-first-line argument to verify or not read %& respectively –  texenthusiast Feb 18 '14 at 13:46
off-topic: surprising why texdoc.net link shows 2012 guide rather than texdoc texlive –  texenthusiast Feb 18 '14 at 13:50
Also running pdftex on a file with pdftex "\input" filename.tex disables first line parsing. AUCTeX does so, it should be remembered when compiling with C-c C-c. –  giordano Feb 18 '14 at 14:06
@giordano Yes; only a letter makes TeX loading a file (and do the parsing of the first line); a command will immediately start TeXing. –  egreg Feb 18 '14 at 14:11

It makes pdflatex compile a DVI output. If you want to produce a PDF, just do one of the following:

• Change it to %&pdflatex
• Run pdflatex -no-parse-first-line
• Remove it.
-
One more question -- the command can take arguments, for example: %&latex --translate-file=cp1250t1. What is their role? –  Mad Hatter Feb 18 '14 at 11:38
I think that argument is used to specify text encoding outside the document. That way, documents self-specify their encoding and do not need to use the inputenc package (which may produce some conflicts). –  Majoko Feb 18 '14 at 11:51