TeXworks ‘magic comments’

The new TeXworks release adds a new ‘magic comment’ to the set that the program knows. So I thought it might be useful to have a list of those that currently work, and a typical setting for each one.

% !TeX program = LuaLaTeX

The name of the typesetting engine to use for the current file, which should be one of the engines that is set up for use with TeXworks. This is useful if you normally use one engine (for example pdfLaTeX), but have a few files that need an alternative engine. In my example, the file would automatically use LuaLaTeX as the engine.

% !TeX encoding = UTF-8

Sets the file encoding for the current file. The usual default is UTF-8, but this setting is handy if you need to collaborate with other people using non-UTF-8 editors.

% !TeX root = somefile.tex

Indicates that the current file is not the main file for typesetting: when you choose to typeset, TeXworks will save the current file then typeset the master file. Using this setting, you need the full name of the master file including the extension. This is clearly a handy setting for larger projects, where you might have a lot of files which are to be included in one master document.

% !TeX spellcheck = de_DE

Specify the spell check language for the current file. This is a new setting in v0.4.0 (it was not present in the 0.2 stable release). The language of course needs to be one you have installed! One point to notice with the

root setting is how it interacts with program. Let’s imagine that the master file needs to be typeset using LuaLaTeX, and that your default engine is pdfLaTeX. You then need to include the program in each subsidiary file to get everything to work properly:

% !TeX root    = master.tex
% !TeX program = LuaLaTeX

If you don’t do that, when you try to typeset from one of the subfiles then TeXworks will use the currently-selected engine (probably pdfLaTeX) and

not LuaLaTeX for the typesetting. Once you know, this is not so surprising, but at first it caught me out!

15 thoughts on “TeXworks ‘magic comments’

  1. Curmudgeon that I am, I feel compelled to point out that this is not an innovative feature: AucTeX has been using emacs local variables to do this sort of thing for a good while now.

    That said, it is a great feature, so I’m glad TeXworks is borrowing it.

  2. The magic comments used by TeXworks are derived from those used by TeXshop: I think spellcheck is new, but the others certainly are not. I did not intend to imply this was unique to TeXworks!

  3. I’m not sure I see that: if TeXworks used the AucTeX comments you’d have the same argument the other way around (‘Why not use TeXshop comments …’). I’d also point out that TeXshop and TeXworks have similar target audiences: not many AucTeX users are likely to want to switch to TeXworks, I think.

  4. Clearly no, if one has gotten used to emacs + auctex + reftex, then one will never leave.

    I’d like other editors to steal the feature behind C-c C-e and C-u C-c C-e, this is such a nice feature when editing existing code, that I really miss it if I’m forced to work within other editors.

    Any idea if TL will push the new version to users? They did with biber.

  5. You might need to explain what C-C C-e and C-u C-c C-e do, for the benefit of those of us who do not use Emacs!

    On the TL question, I’ve not heard anything. I know that TeXworks in MiKTeX has already been updated, so hopefully the process itself is not so bad. (For TL, the issue would probably be the Mac version, given the awkwardness of producing universal binaries.)

  6. C-c C-e prompts for the name of an environment to insert (with tab-completion to the environment names auctex knows about), and then inserts “begin{foo}n _nend{foo}n” (the underscore indicates where the cursor ends up). C-u C-c C-e similarly prompts for an environment name, and then changes the “current” environment to that (i.e. the begin{foo} and end{foo} are changed simultaneously). Very useful if one decides to change from equation to align or similar.

    Also, if one inserts e.g. itemize using this, a first “item” is also automatically inserted (and Alt+Enter inserts subsequent “item”s).

  7. Exactly, many editors have fixed lists of environment, but with this you can type whatever. AucTeX the may include extra features for certain environments, e.g. equation will automatically include a label (if reftex is enabled), equation* does not. The table environment will ask for placement, whether to center, caption text, label text, and then go on to start tabular and ask for options for this.

    There are many more features. Then one has learned these, one really miss them when working with other editors.

    The C-c C-e and C-u C-c C-e (control + c and then control + e, etc.) are the features I use the most.

  8. Oh wow! I’ve been using autex for a couple of years now, and I didn’t know about C-u C-c C-e. That is so cool! I normally do it “by hand”.

    Also, C-c . to mark the current environment and C-c * to mark current section are nifty features…

  9. I suspect that the AUCTeX-like idea is one that belongs as a script in TeXworks, not in the core. It’s after all a LaTeX feature, whereas TeXworks is a general TeX editor.

  10. What made Emacs (AUCTeX) more precise than TeXShop was the distinction between the TeX engine and the TeX format (or TeX dialect like LaTeX or CONText).
    In my view TeXWorks should avoid this confusion.

    There are currently three competing TeX engines, pdftex, xetex and luatex. And if LaTeX is the most popular dialect, it is only a format (a set of macros dumped into a .fmt file) and pdflatex is not a engine but simply a command similar to ‘pdftex –fmt=latex.fmt’. Same for xelatex and lualatex.

    In GNU/Emacs, if the source code as well as the extension (.tex) can’t give a unique information on how to compile, one can use header variables in the “Local Variables: -> End:” top matter of the file:

    %%% Local Variables:
    %%% mode: LaTeX
    %%% TeX-engine: luatex
    %%% coding: utf-8
    %%% LaTeX-command: “latex -shell-escape”
    %%% TeX-command-default: “LaTeX”
    %%% End:

    The most important variables are TEX-engine and TeX-command-default. In the above example, the luatex engine will be used, and the source code of the text is supposed to be written in LaTeX. AUCTeX knows how to manage that and will use lualatex to compile. In this example, it will also add the -shell-escape option to the command line (used for an Inkscape sub-shell for example). The corresponding command line will be (similar to):

    lualatex -shell-escape –synctex=1 –jobname=exemple -interaction=nonstopmode “input” exemple.tex

    For concrete examples, it is not necessary to specify all these header variables because most of them are guessed when the file is open: coding, end of line (CR or CRLF), latex mode etc. ; except the TeX-engine variable.

    Thus the “top matter” of a LaTeX file can be as simple as:

    %%% Local Variables:
    %%% TeX-engine: xetex
    %%% End:

    Emacs will detect that it is a LaTeX file from its content and compile it with xelatex because the TeX-engine is specified as xetex.

    If you wrote TeX-engine: xelatex, Emacs would have complained by a warning when opening the file: xelatex it is not a TeX engine even if the command xelatex exists and is a binary named “xelatex.exe” on Windows.

  11. I can’t say I agree, because if I set up a file for (say) LuaLaTeX then it needs both the LuaTeX engine and LaTeX format. (The two are not independent of one another). For ConTeXt, there is even more care needed: Mark IV has to be run using `context` and always uses LuaTeX, whereas Mark II can be run with pdfTeX or XeTeX but _not_ LuaTeX. So the two things are not ‘independent axes’.

    At a much more practical level, it’s in my opinion better to have what you write as the engine equivalent to what you type at the command line.

    (I’d also note that TeXworks takes a pretty simple approach to the entire engine business. There is no hard-coded idea of what is and is not an engine – there is just a match between the text you write in the ‘magic comment’ and the label for the Typesetting menu. In general, I like simple.)

  12. Why is it
    % !TeX spellcheck = de-DE
    and not
    % !TeX spellcheck = de_DE

    TexStudio for example uses the form with the underscore instead of the dash. Does TexWorks also understand the underscore?

Leave a Reply