TeXstudio

Scroll a TeXstudio changelog to the very end and you find entries that are not even TeXstudio: they belong to Texmaker. TeXstudio began as a set of extensions to Texmaker under the name “TexMakerX,” was renamed at version 2.2, and still carries its parent's history with it. That ancestry explains the character of the editor rather well: it ships not one executable of its own, yet everything a writer needs sits in a single window — editor, build chain, PDF viewer, spelling and grammar checking, a map of the document. Everything except LaTeX itself. This page covers the build configuration people get stuck on, the completion that .cwl files make possible, the structure view, and SyncTeX.

A LaTeX IDE that ships no LaTeX

TeXstudio is a GPL v2 open-source editor that runs on Windows, macOS, Linux and BSD, and it compiles by launching external commands such as pdflatex or latexmk. That fixes the order of installation: a TeX distribution first — TeX Live or MiKTeX — and TeXstudio second. Do it the other way round and you get the confusing state where the program starts fine but nothing will build. The features the project itself advertises are palettes of “more than 1000 mathematical symbols,” an interactive spell checker and grammar checker, code folding, a structure view, and an integrated PDF viewer with “(almost) word-level syncing” — that last one leading straight to the SyncTeX section below.

The Build tab and the Commands tab: reading txs:///

Everything is under Options → Configure TeXstudio, and two tabs govern building. The Commands tab is where you say what each external command actually is — the path to the executable and its arguments. The Build tab is where you define the “meta commands” that combine them. Until you tick Show Advanced Options in the lower left, most of the latter stays hidden. That is where people get stuck: staring at the Build tab when they want to change an argument to pdflatex, or the other way round.

Day to day you touch only four actions. Build & View (F5) compiles and then opens the PDF; Compile (F6) only produces it; View (F7) opens what is already there; and Clean sweeps away the intermediates — .aux, .toc and their relatives — while leaving the finished PDF alone.

A meta command is just a list of names that begin with txs:///, joined by the pipe |. “Build & View” is, in essence, a two-word expression meaning “the default compiler, then the default viewer.” Every command registered in the Commands tab can be referenced the same way, so you can splice your own conversion step into the chain.

Out of the box the default compiler is pdfLaTeX, but switching it to latexmk is the standard move. latexmk inspects the dependencies and reruns exactly as often as the bibliography, the index and the cross-references demand, so no human has to count passes. Write it in the Commands tab like this. Note that % expands to the absolute path of the root (master) document without its extension — the root, not the file you happen to be editing. That single detail is what makes multi-file projects behave.

latexmk -pdf -synctex=1 -interaction=nonstopmode -file-line-error %.tex

To change engines per document, a magic comment on the first line does it. TeXstudio reads % !TeX program, % !TeX root, % !TeX encoding and % !TeX spellcheck, among others. Put the line below at the top and that document alone compiles with LuaLaTeX, with the settings dialog left untouched. The exact syntax of the % !TEX family is covered in detail on the TeXShop page.

% !TeX program = lualatex
% !TeX root = ../thesis.tex
% !TeX spellcheck = en_GB

Only three settings need freezing first

There are a great many settings, so the realistic approach is to settle just three first: the default compiler, the Build & View chain, and whether SyncTeX is on. Once those are fixed, pressing F5 follows the same path every time, and when something goes wrong the search has only one thread to pull.

• For mostly Western documents, let latexmk produce the PDF directly; for an inherited Japanese template, choose upLaTeX + dvipdfmx.
• Define Build & View as “what the F5 I press all day actually does,” compilation and opening the internal viewer included.
• Always put -synctex=1 and -file-line-error in the command: the first so you can get back from the PDF to the source, the second so errors arrive with a file name and a line number.
• Test the setup on a ten-line .tex before opening the real manuscript, and read both the log and the PDF to confirm the engine you expected is the one that ran.

Configuring builds for Japanese

Two routes are in wide use. One is LuaLaTeX: in the Build tab set Build & View to “Compile & View” and the default compiler to “LuaLaTeX,” and one press of F5 takes you to the PDF. For a fresh start this is the straightforward choice. The other is upLaTeX + dvipdfmx, long the Japanese standard; because it puts a DVI before the PDF, you set Build & View to the “DVI->PDF chain” and the default compiler to “LaTeX.”

The clearest arrangement is to describe the engine combination in a .latexmkrc and let TeXstudio merely call latexmk. Put the following file next to your .tex and latexmk handles the upLaTeX → dvipdfmx flow, the bibliography (upbibtex), the index (upmendex) and the number of reruns. Because $latex carries -synctex=1, SyncTeX keeps working too.

$latex = 'uplatex %O -synctex=1 -interaction=nonstopmode %S';
$bibtex = 'upbibtex %O %B';
$makeindex = 'upmendex %O -o %D %S';
$dvipdf = 'dvipdfmx %O -o %D %S';
$pdf_mode = 3;

$pdf_mode = 3 selects the mode “make a DVI, then turn it into a PDF with $dvipdf.” The tokens %O (extra options), %S (the source file), %B (the base name without extension) and %D (the output target) are latexmk's placeholders, and are not the same thing as TeXstudio's %. Set up this way, you get the same result whether the build is started from TeXstudio, from the command line, or from another editor entirely — because the configuration lives in one place.

Read the log from the first error

Before changing settings at random, look at two things: which command was launched, and what the first error in the log is. LaTeX errors cascade, so the first red line has usually produced all the ones after it. TeXstudio's log panel is built for exactly this reading order: you can switch between the raw log and a table that sorts the messages into errors (red), warnings (yellow) and overfull boxes (blue). Move between errors with Ctrl+Shift+↑ and Ctrl+Shift+↓, and between warnings and boxes with Alt+Shift+↑ and Alt+Shift+↓.

• If you see Could not start the command, the suspect is PATH and the state of your TeX Live / MiKTeX installation, not TeXstudio. Check the executable path in the Commands tab.
• File not found means one of three things: the root file, a relative path, or a figure filename — and check whether the extension is written out.
• When a package is missing, install it with tlmgr install on TeX Live or MiKTeX Console on MiKTeX. The editor cannot fix this one.
• Click the line number in the log, fix only the first error, rebuild, and then read on. Reading the far end of a cascade first is usually wasted time.

Why completion knows your \labels: the .cwl files

TeXstudio is not interpreting LaTeX. It is reading .cwl files — completion word lists. The format came originally from another LaTeX editor, Kile, and TeXstudio extended it with semantic information: this argument is a label, that spot is where the cursor should land. That is why typing \ref{ offers the labels in your document and \cite{ offers the bibliography keys (bibIDs). When you \usepackage something, the matching cwl is loaded if one exists; if not, TeXstudio generates one from the .sty automatically — which yields command names but no sense of what the arguments mean. For a package of your own, writing \usepackage{./myPackage} with a relative path makes TeXstudio look for ./myPackage.cwl.

Three more keystroke-savers are worth learning. When the candidates share a leading string, pressing Tab fills in that common part at once. Begin an environment — type \begin{itemize} — and the matching \end{itemize} is inserted for you. And resting the cursor on an environment name for a moment brings up a mirror cursor, letting you rewrite the names in \begin and \end simultaneously — turning itemize into enumerate in one move. To close whatever environment or brace is still open, press Alt+Return. Forgetting to close something is among the commonest LaTeX accidents, so that one is worth committing to memory.

The structure view, and checking spelling and grammar as you type

The Structure view on the left becomes a map of the document. It lists headings (\section and its family), labels (\label), the files pulled in by \input and \include, beamer blocks, and TODOs — both the \todo{} command and % TODO / %todo comments are picked up. Click an entry and you land there. In a long manuscript or a multi-file project, this list is what keeps you from losing track of where you are.

Spell checking runs while you type, and right-clicking a suspect word offers corrections. The dictionaries are in hunspell format — the same machinery LibreOffice and Firefox use, so extra dictionaries can be borrowed from there. To pin the language to a file, write % !TeX spellcheck = de_DE on the first line and that file switches language automatically every time it is opened. It earns its keep when you are editing a multilingual volume.

Grammar checking, on the other hand, is not TeXstudio's own judgement. The open-source proofreading engine LanguageTool runs locally as a server, TeXstudio connects to it at startup, and each finished paragraph is sent over and the findings come back (you point it at the server URL and the jar under Options → Configure TeXstudio → Language Checking). Because of that arrangement your prose never leaves the machine — a comfort when the manuscript is not yet published.

SyncTeX: ctrl-click, forwards and backwards

There are only two conditions. First, pass -synctex=1 to the compile command. SyncTeX is a feature of the TeX engine rather than of the editor, and this switch is what makes it write the synchronisation file .synctex.gz (the latexmk line and the .latexmkrc above already carry it; if you forget, TeXstudio offers to correct the command for you). Second, open the PDF in the internal viewer. It is that viewer's SyncTeX support that makes the two-way jumps possible.

The gestures are easy to remember, because both directions are Ctrl + left-click. Do it in the source and you land at the matching place in the PDF (forward search); do it in the PDF and you land on the matching source line (inverse search). The right-click menu offers the same under “Go To PDF” and “jump to source.” Forward search also runs automatically to your current cursor position each time the viewer opens. Enable “scrolling follows cursor” and “cursor follows scrolling” and the two stay linked continuously as you write, which makes the proofreading question “which line produced this paragraph?” simply disappear.