CaseLeaf

Handbook / Going back to the source

Going back to the source

A PDF built by LaTeX can be asked which line of which file drew any point on it, and the answer opened in your editor. You are reading a proof, you see a word that is wrong, and the question is always the same: where is that in the source?

What has to be there

The typesetting run has to have been given -synctex=1. That makes it leave a map beside the PDF — draft.synctex.gz, or draft.synctex where the run was told not to compress it — listing every box it put on a page and which file and line asked for it.

The map has to be beside the PDF, under the PDF's own name. A build that keeps its map somewhere else can still be asked from the command line, which takes a --map, but not from the window.

⌘⇧-click on the page

Hold command and shift and click a word. The line that set that word opens in your editor.

It is the chord Skim uses, and it works with any tool in hand: the press is taken before the tool sees it, so the highlighter does not have to be put down first. The one thing that outranks it is a command that has already asked you to drag a box — Notes ▸ Take Snapshot, capturing a signature — because you are in the middle of answering that.

The answer is the line the words are on, not the line the paragraph ended at. A box in the map is tagged with the line the typesetter had reached when it packed the box away, which for a paragraph is the line after the text; the places recorded inside the box carry the line being set, and those are what answer.

Clicking the white between two paragraphs says nothing was typeset there rather than guessing. Every sheet carries one box covering the whole page, tagged with whatever line the run happened to be on when it sent the sheet out, and answering with that would send you to the end of the document from anywhere on the page.

Go to Source (⇧⌘J)

The same thing without the pointer, under Research.

With words selected it asks about the first character of the selection. With nothing selected it asks about the last place you clicked on the page, so clicking a line and then reaching for the menu means that line.

It is grey while the document in front has no map beside it. Typeset again with -synctex=1 and it lights up; nothing has to be closed and reopened.

Which editor

Settings ▸ LaTeX holds two controls.

Editor is a list of the editors this is known to work with. Until you pick one, the first of them that is actually installed on this Mac is used, so it works before you have opened Settings at all. Editors that are not installed are still listed and say so, because a list that changes length between two Macs is harder to talk about than one that says why.

Editor What it is sent
TeXShop An AppleScript, because it takes a line only by Apple event. It opens the file and goes to the line.
Visual Studio Code code --goto with the file and line
Cursor cursor --goto with the file and line
TextMate mate -l with the line and the file
BBEdit bbedit with the line as +n
Sublime Text subl with the file and line joined by a colon
Emacs emacsclient -n with the line as +n
Custom… Whatever you write

Vim and Neovim are not on the list. Which terminal, in which window, running which shell, has no answer that is right for two people — write yours under Custom….

Command is what is really run. Picking an editor fills it in; you can edit it, and picking Custom… leaves whatever is in it alone. %file becomes the file the map named and %line becomes the line.

There is no shell between this and the command, so a file name is a file name however it is punctuated and a path with spaces in it arrives in one piece. TeXShop's entry reads as a sentence rather than as a command because it is a script; change any entry and it becomes an ordinary command line again, split at the spaces.

When it does not work

Everything is said in one line at the foot of the window.

  • No SyncTeX map beside … — the run was not given -synctex=1, or the map is not beside the PDF. It names the document it looked beside.
  • Nothing was typeset at that point — you are on paper rather than on something that was set. Try the words themselves.
  • The command itself, quoted, when the editor could not be run: either the tool is not on this machine or it refused to start. The line names the command, so you can see which.

Nothing here changes the document, and nothing is written.

Typesetting from TeXShop into CaseLeaf

TeXShop shows every typeset in a preview window of its own and has no setting for another viewer. What it does have is engines — scripts it runs to typeset — and one ships inside CaseLeaf that typesets with latexmk, with the map, and then hands the PDF to CaseLeaf, which reloads it and comes to the front. From then on TeXShop is the editor and CaseLeaf is the page, in both directions: ⌘⇧-click on the page opens the line, and typesetting brings the page back.

Install it once, from any terminal — the one under the document will do:

cp /Applications/CaseLeaf.app/Contents/Resources/TeXShop/pdflatexmk-caseleaf.engine ~/Library/TeXShop/Engines/ && chmod +x ~/Library/TeXShop/Engines/pdflatexmk-caseleaf.engine && defaults write TeXShop BringFrontOnTypeset -bool NO && defaults write TeXShop BringPdfFrontOnTypeset -bool NO && defaults write TeXShop BringPdfFrontOnAutomaticUpdate -bool NO

Then quit and reopen TeXShop, and choose pdflatexmk-caseleaf in the toolbar's engine list, or put this line at the top of the source so the document remembers:

% !TEX program = pdflatexmk-caseleaf

The three defaults lines ask TeXShop not to bring its own preview forward. It may still show it briefly when it notices the new PDF; CaseLeaf comes forward once, a few seconds after the PDF is written, and stays. The pause is the number at the top of the engine file, four seconds as shipped, if your machine wants a different one.

See also

  • The source command: the same question asked without the window, and what --map is for
  • Settings: where the editor is chosen
  • Marking text: the selection Go to Source asks about when there is one

Watch: a short video for this page is still to come.


Contents