Synchronization is an important feature of Textures, a commercial implementation of TeX for the Macintosh by Blue Sky TeX Systems. Using this feature, an author can click in the preview window and immediately be taken to the corresponding spot in the source window, or click in the source window and be taken to the preview window. The implementation of synchronization in Textures is widely admired for its ability to precisely locate the corresponding spot in the source code.

Since this implementation, a number of TeX systems have provided a roughly similar feature using a mechanism which causes TeX to write extra synchronization information during typesetting. None of these approximations is as accurate as Textures.

TeXShop provides synchronization using new SyncTeX technology introduced by Jérôme Laurens; when this technology is not available, TeXShop falls back on older Search synchronization introduced in TeXShop 2.0. To use synchronization in TeXShop, click on a word or phrase in the source window while holding down the Apple control key; the preview window will scroll to the appropriate spot and the corresponding typeset phrase will be circled in red. Similarly, click on a word or phrase in the preview window. The appropriate source file will open (if necessary) and scroll to the corresponding source phrase, which will be highlighted in yellow.

If you are a new TeXShop user, the SyncTeX method is active by default. Users who installed an older version of TeXShop and upgraded to this version need to change three preference items to make SyncTeX work. In TeXShop Preferences under the Misc tab, change the Sync Method to SyncTeX. In TeXShop Preferences under the Engine tab, change the two pdfTeX items to

  pdftex --synctex=1
  pdflatex --synctex=1

SyncTeX was introduced by Jérôme Laurens in 2008. It causes TeX to output an additional file with extension ".synctex" containing information needed to correlate the output pdf and input source files. The additional file is written directly by the TeX engine. Typesetting is not modified in any way by SyncTeX; in particular, line and page breaks are not changed, as happened with the older pdfsync technology. SyncTeX should allow very accurate synchronization as developers master its features.

SyncTeX requires the versions of pdftex, pdfetex, and xetex introduced in TeX Live 2008 and made available in MacTeX-2008. For users with older TeX distributions, a second synchronization method named Search is also provided in TeXShop. This method works with all TeX engines; no special changes to the source file are needed to use it. The Search method uses features of OS X introduced by Apple in System 10.4. These features allow developers toeasily search pdf files for text strings; the search method finds strings in the source file and corresponding strings in the output pdf file. This method does not require an additional style file, so theoretically it works for all typesetting methods. But it fails when the pdf strings is different than the input strings and thus fails for mathematical expressions.

By default, TeXShop first tries SyncTeX. But if SyncTeX fails or the ".synctex" file does not exist, TeXShop falls back on the Search synchronization method.

TeXShop can provide synchronization in three ways: SyncTeX, Search, and PdfSync. The method used is controlled by the "Sync Method" preference. The SyncTeX option select synchronization with SyncTeX, but falls back on the Search method if SyncTeX fails. The Search and PdfSync options call the Search and PdfSync methods respectively, while the "Both" option calls Search but falls back on PdfSync if Search fails. This complexity is due to the history of these features on OS X. Pdfsync is older technology replaced with SyncTeX, and will not be discussed here.

To use SyncTeX, the typesetting engine needs to be called with a special flag instructing it to output the ".synctex" file. This is done by adding the following option when calling the engine:

  --synctex=1

For example, to use SyncTeX with pdftex and pdflatex, we modified the two entries on the left side of the Preferences Dialog under the Engine flag to

  pdftex --synctex=1
  pdflatex --synctex=1

Incidentally, if TeXShop is used with an older engine which does not support this flag, typesetting will still occur. The engine will report in console that it does not recognize the "synctex" flag and proceed.

Similar changes must be made in the call to simpdftex, and in engines files, including any engine files you have created. None of these changes have yet been made, so you will need to make the changes yourself if you use one of these engines and want to use SyncTeX. In modern TeX distributions, most typesetting is done by pdfetex or xetex, both of which support this flag. The original TeX program by Knuth does not support the flag.

SyncTeX is very new, and supported for it was first added to TeXShop in August of 2008. As the developers understand more clearly the information provided by Jérôme Laurens' synctex utility, the accuracy of TeXShop synchronization with SyncTeX will improve.

From now on, we discuss the older Search method; most of these comments do not apply to SyncTeX.

When using Search synchronization, it helps to know the underlying mechanism. Suppose you click on a spot in the source file. TeXShop obtains the string 20 characters wide centered about the click, and searches for the corresponding string in the pdf file. If it finds this string exactly once, it circles the pdf string in red and declares success. But often, source strings contain formatting commands and do not match output strings; this is certainly true when typesetting mathematics. So if the search fails, TeXShop backs up 5 characters, obtains a new string 20 characters wide, and tries again. It repeats this operation 20 times if necessary, and if none of the tries succeeds it repeats the operation 20 more times looking forward past the original string rather than backward. If none of these search operations succeeds, TeXShop gives up.

Obviously, then, it is best to click on sentences rather than formulas. Paragraphs with heavy markup may not synchronize well. Experiments show, however, that searches usually succeed and clicking can be done without really thinking about selecting an appropriate spot.

Synchronizing from the preview window to the source window works the same way, but there is an additional complication. Projects may contain several source files, inserted using the \include or \input methods. TeXShop handles this complication by assuming that all \include and \input statements occur in the root file, using one of the commands \include{this file}, \input{this file}, or \import{this file}. In the initial implementation, it makes a list of the first sixty such files and searches all of them, declaring success if a string occurs exactly once in exactly one of the files. If the string is found in a file which is not yet open, TeXShop opens the file. Then it scrolls to the appropriate spot and highlights the resulting phrase in yellow. (In future implementations, the number sixty may be raised; write if you need more files searched.)

ConTeXt uses a different method of inputting files, so a search for \include and \input statements will not find related ConTeXt files. There is a manual method to indicate files to be searched for synchronization; this method works with any typesetting method and is required in ConTeXt. At the top of the root file, list files to be searched via

  % !TEX projectfile =

Here are examples:

  % !TEX projectfile = /Users/koch/MyDoc/chapter1.tex
  % !TEX projectfile = chapter2.tex
  % !TEX projectfile = ../chapter3.tex

Advanced Help
Pdfsync