Magic Comments

This page defines "magic" comments that are ignored by TeX but provide TeXworks with valuable information about the source file.

Defining a root file

If you have your LaTeX code for one document distributed over several files this is for you. The problem is that only one document (the 'root document') contains all the commands necessary to be typeset (like \documentclass or \begin{document}). LaTeX will fail when run on any of the other files. To let TeXworks know that it should run LaTeX on that root file instead of the current one put the following line in the beginning of the file:

% !TEX root = path/to/root_file.tex

Setting the (La)TeX engine per file

If you have a file that has to be compiled with another than the standard (La)TeX program and you don't want to have to set the program by hand every time you open the file put the following line in the beginning of the file:

% !TEX program = your_program

Note that /your_program/ is the name you chose for the program in the settings, not the actual name of the executable.

Setting the file encoding per file

If you put the following line in the beginning of a file, TeXworks will deal with special characters accordingly:

% !TEX encoding = your_encoding

For a complete list of supported encodings, please see the TeXworks settings.

Setting the spell checking language per file

If you put the following line in the beginning of a file, TeXworks will set configure the spell checker for the corresponding language:

% !TEX spellcheck = language_tag

The language tag is typically a IETF language tag, but may depend on your spell checking software and your installed dictionaries. For a complete list of supported tags on your system, please refer to the TeXworks "Edit -> Spelling" menu.

Using the outline and bookmarks in source files

If you activate the menu item Windows -> Show -> Tags, you will get a sidebar that displays the outline of the current source document by automatically locating the \part, \section, ... commands. By clicking on any of the items in the tag tree, the cursor will be positioned at the corresponding code in the editor.

Note: This currently only works for LaTeX commands by default.

Note: To customize the recognized patterns, edit the file tag-patterns.txt in your TeXworks resource directory

In addition to the automatically detected commands, you can add a custom bookmark by inserting the line

%: My bookmark label

into the source code at the appropriate location.

Using the "Insert Citations" feature

To use the "Insert Citations..." dialog (from the Edit menu), you need to tell TeXworks which BiBTeX files to parse and display in the dialog. For now, they are not taken automatically from a \bibliography statement to allow splitting a document across many source files, using packages that redefine/rename that command, etc.

To specify the BiBTeX files TeXworks should display in the "Insert Citations" dialog, add the following line at the beginning of the TeX file:

% !TEX bibfile = file.bib

Instead of a single file, you can also specify a comma-separated list of several files, e.g. file1.bib, file2.bib.