It is common to split large input files into several smaller files controlled by a root file. For instance, the root file of a book project might have the form

  `\documentclass[11pt]{book}`
  `\includeonly{Chapter2/two}`
  `\textwidth = 6.5 in`
  `\textheight = 9 in`
  `\begin{document}`
  `\include{Chapter1/one}`
  `\include{Chapter2/two}`
  `\include{Chapter3/three}`
  `\end{document}`

This root file contains formatting commands for the entire project, but the subject matter is contained in files one.tex, two.tex, and three.tex. The second line above tells TeX to typeset chapter two only, speeding up typesetting while chapter two is being written. When the book is complete, this line can be commented out and the entire book can be typeset a final time.

While chapter two is being written, it would be natural to open the file two.tex in TeXShop. But after changes are made to this input file, TeXShop should not typeset two.tex; instead it should typeset the root file. TeXShop can be told to do so as follows. Indicate the root file in one of the first twenty lines of each chapter file by writing

  % !TEX root = ../Main.tex

Note that only the included chapter files need this command; the Root file itself requires no modification.

If the root file is in the same folder as the input file, it is enough to give its name, including the ".tex" extension. For instance, if the root file is named Main, you can enter Main.tex in the first source line or the dialog window.

If the root file is in a different directory, its name can be given relative to the location of the input file. In the above example, the various chapters are contained in subfolders within the folder containing the root file. In that case, you could enter ../Main.tex in the first source line or dialog window, showing the location of the root file relative to the chapter input file.

Finally, the name of the root can be given with an absolute name, as in /Users/me/Main.tex.

If the entire TeX source is contained in a single file, it is not necessary to set the root project name.

TeXShop has a Macro in the Macros menu which makes setting this "root line" almost automatic.

Setting a project root is also important for synchronization. If input lines have a "% !TEX root = ..." line, then synchronizing from the Preview window to the Source window will open the appropriate source chapter file and bring make that source window active.

If a root file is active, typing command-1 when a given source window is at the front will activate the corresponding preview window. Typing command-1 again will activate the source window. Since a preview window may correspond to several source windows, command-1 will activate the source window which previously activated the preview window, or the root source if no previous command-1 was entered.

TeXShop has an alternate method of setting the root file, activated by the menu command "Set Project Root..." This method will continue to be supported in the future, but should not be used because the "% !TEX root = ..." method is more robust. When the "Set Project Root.." command is used to indicate a root file, TeXShop remembers the name of the root file by writing the information to a file with the same name as the input file and the extension ".texshop". For instance, if the input for chapter two is in two.tex, TeXShop writes the name of the root in two.texshop in the same directory as two.tex. If the file two.texshop is later thrown away, TeXShop will revert to typesetting two.tex rather than Main.tex.

Advanced Help
Setting a Project Root File