[Tex/LaTex] The role of %&latex at the beginning of a source latex file

format-filestex-core

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

Best Answer

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.

So one had to do

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

If you add

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.

Related Question