# SyncTeX

Open source (see source for details)

SyncTeX is a new method in TeXLive 2008 for enabling synchronization between source TeX files and the resulting dvi or pdf file. Designed as a replacement for srcltx and pdfsync, it is called as an option to TeX using the option -synctex=1. e.g.

`pdflatex -synctex=1 filename.tex`

will generate a file names filename.synctex.gz containing information used by either and editor or viewer to find the corresponding location in the companion source or compiled file and move the cursor or other pointer to that location. This helps to partially compensate for the non-GUI nature of TeX/LaTeX where locating corresponding locations in either source or result documents could otherwise become tedious.

SyncTeX has the advantage of being far more compatible with packages (other style files) by being embedded in the TeX engine, and also is not prone to modification of the layout of the document, an unfortunate unintended result of pdfsync in many cases.

## Current status of support

SyncTeX is being implemented as of the summer of 2008 and will likely be supported by all major editors and viewers eventually.

Below is a list that is confirmed by our readers. Please add to the lists as practical.

Front Ends now supporting SyncTeX include: TeXShop, iTeXMac2, TeXworks, TextMate (version 1459, using any of the drivers pdflatex, xelatex, or latex), and TeXlipse (a plugin to add LaTeX support to Eclipse).

Editors now supporting SyncTeX include: AlphaX (as of version 8.2b1); Emacs (all versions, through AucTeX).

Viewers now supporting SyncTeX include: Skim. But note that in version 1.3.5 of Skim, which is the current at the time of writing, the Command-Shift-click is not linked to the inverse search, i.e. inverse search is not working in that version. The problem is already fixed in SVN and so it should be working again in the next release. So long, compile from sources or stick with 1.3.4

## Using SyncTeX (by application)

### AlphaX/Skim

The preference flag "useSynctex" must be ON (which it is by default if synctex is in your PATH).

You should choose Skim as PDF viewer in the "Helper Applications" prefs pane.

In Skim, go to the sync preferences (Preferences:Sync) and make sure AlphaX is selected.

It is best to turn OFF Skim's "Check for file changes" feature, as Alpha in any case sends the appropriate refresh Apple-event when needed.

### AucTeX/Skim

Official documentation gives you the current way to use forward and backward search from a Gnu-Emacs LaTeX text buffer to the PDF/Skim previewer. After editing a sentence of your LaTeX text, you can enter CTRL_c CTRL_v (View), and Skim will open and highlights the corresponding lines of the formatted PDF text. This is forward search. On the opposite, with a Shift_Command_Click on some part of the PDF file viewed by Skim, your buffer in Emacs will scroll up or down to the right line; this is backward search.

In order to use the forward search, you need to compile with --synctex=1 (for latex, xelatex etc.). This is automatically done by setting TeX-source-correlate-method-active to synctex instead of auto. You can verify, while compiling with CTRL_c-CTRL_c LaTeX that the log which can be accessed by the command CTRL_c_CTR_l includes --synctex=1. You can also verify which command is used from (usually) pdflatex, xelatex or lulatex commands. That command corresponds to a specific TeX engine which is set in the variable TeX-engine, respectively pdftex, xetex, luatex. You can toggle from synctex to nil, with CTRL_c-CTRL_t-CTRL-s: this is mandatory to turn it off for a final version to be sent.

In order to use the backward search, the binary `emacsclient` should be in the Emacs path. Verify by viewing the value of the variable exec-path, CTRL_h-vexec-path<cr>. For example, it could be set as:

```(setq exec-path (append '("/usr/texbin" "/Applications/Emacs.app/Contents/MacOS/libexec" "/Applications/Emacs.app/Contents/MacOS/bin" "/usr/local/bin") exec-path)) ;
```

In order to use emacs on the command line, I created a file:

```\$ cat /usr/local/bin/emacs
#!/bin/bash
/Applications/Emacs.app/Contents/MacOS/Emacs "\$@"
```

You may have different installations of Emacs on your Mac. If you are using the binary of an application like /Applications/Emacs.app/Contents/MacOS/bin you should also set the same path in the Skim preference for emacsclient:

```Command: /Applications/Emacs.app/Contents/MacOS/bin/emacsclient
Arguments: --no-wait +%line "%file"
```

The variable TeX-engine is local and specific to a buffer. In order to use the correct engine and settings for a text, you can add at the very end of the text something like:

```% These lines tells gnu-emacs to typeset with the xetex engine
% which requires Unicode encoding only (utf-8)
% ^c^t^s for toggling synctex (TeX-source-correlate-mode variable).
% ^-Shift-Click to move from pdf to source, Command-Shift-Click on OSX
%%% Local Variables:
%%% TeX-engine: xetex
%%% TeX-source-correlate-method-active: synctex
%%% ispell-local-dictionary: "american"
%%% coding: utf-8
%%% End:
```

### Aquamacs/Skim

Aquamacs supports SyncTeX via AucTeX, but doesn't currently (Joseph Slater 18:58, 11 September 2008 (UTC)) automatically apply the SyncTeX flag in compiling documents.

To get this working, in:

• In the LaTeX menu, select Customize AucTeX:Browse Options
• Click on the TeX Command group
• The LaTeX command should currently read latex. Change this to latex -synctex=1

Similar changes should work for TeX, Context, etc.

Be sure to click Save for Future Sessions

If you want to use XeLaTeX with Aquamacs and SyncTeX follow these directions:

• open Aquamacs
• type: M-x latex mode
• go to the LaTeX menu, select Customize AucTeX:Browse Options
• go to TeX command group
• go to TeX command list
• insert a new item:
• Name: XeLaTeX_SyncteX
• Command: %`xelatex --synctex=1%(mode)%' %t
• check boxes for LaTeX and whatever else you want to use with this command
• save for future sessions

In Skim, go to the sync preferences (Preferences:Sync) and make sure Aquamacs Emacs is selected. You will probably also want the Check for file changes box checked.

### Carbon Emacs/Skim

Carbon Emacs supports SyncTeX for synchronized preview (with Skim) of the pdf files, which are the output of the command PDFLaTeX, via AucTeX. In Emacs, AucTeX can be customized in the following way (as in Aquamacs/Skim):

• Load a LaTeX file in Emacs.
• From the Emacs' menu bar, pull down the LaTeX menu and select "Customize AucTeX: Browse Options".
• Go to "TeX Command group" and click on "go to group".
• The LaTeX command, initially, by default, is: "latex". Change it to: "latex -synctex=1".
• If you want synchronization with SyncTeX to be the permanent setting of your Emacs, click the button Save for Future Sessions on the top of the customization buffer for group Tex Command.

In Skim, go to Preferences: Sync. Check up the box in front of "Check for file changes"; select: "PDF-TeX Sync support: Preset: Emacs".

### Vim LaTeX/Skim

To activate Forward search with Skim and the vim-latex plugin, add the following content to ~/.vim/ftplugin/tex.vim

```let g:Tex_DefaultTargetFormat = 'pdf'

let g:Tex_CompileRule_dvi = 'latex --interaction=nonstopmode \$*'
let g:Tex_CompileRule_ps = 'dvips -Pwww -o \$*.ps \$*.dvi'
let g:Tex_CompileRule_pspdf = 'ps2pdf \$*.ps'
let g:Tex_CompileRule_dvipdf = 'dvipdfm \$*.dvi'
let g:Tex_CompileRule_pdf = 'pdflatex -synctex=1 --interaction=nonstopmode \$*'

let g:Tex_ViewRule_dvi = 'texniscope'
let g:Tex_ViewRule_ps = 'Preview'
let g:Tex_ViewRule_pdf = 'Skim'

let g:Tex_FormatDependency_ps  = 'dvi,ps'
let g:Tex_FormatDependency_pspdf = 'dvi,ps,pspdf'
let g:Tex_FormatDependency_dvipdf = 'dvi,dvipdf'

" let g:Tex_IgnoredWarnings ='
"       \"Underfull\n".
"       \"Overfull\n".
"       \"specifier changed to\n".
"       \"You have requested\n".
"       \"Missing number, treated as zero.\n".
"       \"There were undefined references\n".
"       \"Citation %.%# undefined\n".
"       \"\oval, \circle, or \line size unavailable\n"' ```

If you never use another format than pdf you can of course omit the lines that deal with dvi or ps. Now typing \ls in vim it opens Skim and jumps to the position in the pdf file where your cursor has been in the source file.

If you're using MacVim, to setup inverse search, firstly move the helper application mvim from the MacVim download to a sensible place like /usr/local/bin/. Then go to the Sync preferences in Skim, select Custom from the drop-down, as command choose /usr/local/bin/mvim or wherever your mvim lies and as arguments choose

`--remote-silent +":%line;foldo!" "%file" `

```\synctex=1
```

in the preamble of a tex file triggers the synchronization with SyncTeX, not only with pdflatex, but with other TeX commands too.

### iTeXMac2

If you don't want to use SyncTeX in one document, for example a beamer presentation, just go to the Presentation->Options panel, choose the Synchronization tab and check the "Without SyncTeX" box. If you do not want SyncTeX at all, check the same box in the PDF viewer preferences.

### TeXShop

New users need do nothing - TeXShop will use SyncTeX by default.

Existing users may need to change the engine call for pdfTeX for LaTeX from

`pdflatex --shell-escape`

to

`pdflatex --shell-escape --synctex=1`

or similar, or enter

`\synctex=1`

in the preamble of their TeX file and change the preferences in Misc to Sync Method:SyncTeX.

Please see the page on TeXShop Synchronization.

### BBEdit/Skim

For backward search (from preview to source) to work, choose BBEdit in Skim's Sync preferences.

The forward search is detailed on the Skim wiki. I prefer the direct AppleScript method, as it doesn't require you to know where Skim is installed, making the whole setup a bit more robust. A forward search script is included in the BBedit+TextWrangler TeX integration scripts

### TeXlipse/Skim

TeXlipse is a LaTeX plugin for Eclipse. The installation of both is assumed here.

To activate forward and inverse search on the Eclipse/TeXlipse side, in "Preferences/Texlipse/Viewer Settings", add a new Viewer configuration in top priority, with the following viewer configuration:

• Viewer name: skim
• Viewer command: /Applications/Skim.app/Contents/SharedSupport/displayline
• Viewer arguments: -r %line "%file" "%texfile"
• Viewer input file format: pdf
• Inverse search support: Viewer runs external command
• Viewer supports forward search: selected

Also make sure that the "-syntex=1" argument is added to the PdfLatex program in "Preferences/Texlipse/Builder Settings".

On the Skim side, "Prefrences/Sync/PDF-Tex sync support" should be configured as follows:

• Preset: Custom
• Command: java
• Arguments: -classpath /Applications/Eclipse-3.6/plugins/net.sourceforge.texlipse_1.4.1/texlipse.jar net.sourceforge.texlipse.viewer.util.FileLocationClient -f %file -l %line