T

E
XShop Tips & Tricks
v0.7.12013/08/18
H. Schulz
[email protected]
Contents
1 Introduction 2
1.1 What Isnt Here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2 What Is Here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2 Editing, Typesetting and Viewing the Work Cycle 2
2.1 Editing the Source File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1.1 L
A
T
E
X & Matrix Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1.2 The Tags Popup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1.3 Find/Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2 Typesetting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.2.1 Removing Aux les . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3 Viewing the Output pdf File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3.1 Synchronizing between pdf and Source . . . . . . . . . . . . . . . . . . . . . . 5
2.4 Working with a Large Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.4.1 Switching between Source Windows . . . . . . . . . . . . . . . . . . . . . . . . 6
2.5 Working with BibDesk and Citations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.6 Getting Help for Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3 Controlling the Keyboard 6
3.1 Menu Shortcuts & System Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2 More Editing Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.3 Key Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4 Macros 7
4.1 Text Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.2 Applescript Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5 Command Completion 10
5.1 Completions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.2 Substitutions or Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.3 Hey, it doesnt work! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
6 Extending Processing via Engines 11
6.1 The pdflatexmk engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1
1 Introduction
T
E
XShop is a Front End for a T
E
X distribution on Mac OS X. As such it allows the user to create
and edit T
E
X source les, interact with the T
E
X distribution (e.g., typeset the source le) and nally
preview the nal pdf le. It also allows the user to go back and forth between preview and source.
Over the years T
E
XShop has added many features. Some of them are obvious and are meant to
help a novice get started. Others are a bit more subtle in their use and the underlying power of
these features needs to be coaxed out.
1.1 What Isnt Here
This article is, rst of all, not about T
E
X or L
A
T
E
X. I dont intend to teach you how to write T
E
X source.
There are many ne books and articles that will teach you how to become a T
E
Xpert or, at least, a
T
E
Xptzer like me.
Although there is some introductory material it is also not meant as a complete manual for
the use of T
E
XShop for the total novice. Over time it might evolve into such a document but Ive
got to start somewhere and this is that start.
1.2 What Is Here
In this article I hope to introduce you to some of the more subtle things you can do to make your
life as a T
E
X source editor easier. These include adding keyboard commands and extending the
editing capabilities of T
E
XShop; helping you make short(er) work of creating documents, etc., with
the use of Macros and Command Completion; and, nally, how one can extend the processing
capabilities of T
E
XShop using Engines.
2 Editing, Typesetting and Viewing the Work Cycle
This is about as close to a beginners section you will get in this document.
2.1 Editing the Source File
The rst thing youve got to do to create that great work is to type it into the source document that
will be typeset and viewed later. This involves both putting L
A
T
E
X markup as well as your wonderful
words into the document.
To get started you can open a new document using FileNew (Cmd-N) and then ll in the
start of a new document by choosing a template from the Templates popup menu in the Source
Window or use the FileNew From Stationery. . . command and picking appropriate Stationery
from the list. Note that the templates and stationery provided are certainly not complete; if you
have some that you think are of general use feel free to submit them for inclusion in T
E
XShop. You
can add personal Templates and Stationery to ~/Library/TeXShop/Templates and ~/Library/
TeXShop/Stationery respectively. Note: ~/Library is the Library folder in your HOME folder.
Note: Under Mac OS X 10.7/10.8 the Library folder is hidden by default; in Finder hold
the Opt key down and click on the Go menu and it will be available.
2.1.1 L
A
T
E
X &Matrix Panels
While I believe that panels with a clickable interface actually hinder learning Ill mention that
T
E
XShop has two panels: one to help with entering L
A
T
E
X code (the L
A
T
E
X Panel) and one for setting
up the basic structure of a matrix or tabular (the Matrix Panel). These are toggled on/off under the
Window Menu or with the keyboard shortcuts
1
Opt-Cmd-- and Opt-Cmd-= respectively. Figure (1)
shows what the panels look like.
1
The given shortcuts are for the English localization and may be different with other localizations.
2
(a) (b)
Figure 1: (a) The L
A
T
E
X Panel; and (b) Matrix Panel.
Figure 2: The Tags Popup Menu.
It is possible to make a fewchanges and additions to the L
A
T
E
X Panel by editing the ~/Library/
TeXShop/LatexPanel/completion.plist le. Note: all plist les must be edited using UTF-8
Unicode encoding.
2.1.2 The Tags Popup
The Tags popup menu on the Source Toolbar will automatically list sectioning commands so you
can quickly jump to a relevant part of your document source. You can add your own tag to the list
at a particular place in the document by placing the line
%:my tag name
at that position and it will then appear in the popup list so you can jump to that location quickly.
See Figure (2). Sorry, tags are not recursively included for les you \include or \input.
2.1.3 Find/Replace
There are three Find/Replace panels available with T
E
XShop 3.xx (two with T
E
XShop 2.xx). Each
is discussed individually below. You choose the Find/Replace Panel you wish to use on the Source
3
(a) (b)
(c)
Figure 3: The Find/Replace panels available in T
E
XShop: (a) the standard Apple Find Panel;
(b) the Ogrekit Find Panel with the More Options panel displayed; and, (c) the Apple Find Bar
available with T
E
XShop 3.xx.
tab under TeXShopPreferences. You must restart T
E
XShop to enable any changes made to the
Find/Replace Panel choice in Preferences.
Apple Find Panel The traditional Apple Fine/Replace panel. A simple to use panel for nding
and replacing text. The Standard Apple Find/Replace Panel is shown in Figure (3a) on
page 4.
OgreKit Find Panel An advanced Find/Replace panel that supports Regular Expressions (regex
for short) of various styles (press the More Options button to select the dialect). Regex is a
very advanced way to nd and replace text and is a good investment of your time to learn.
The OgreKit Find Panel with the More Options panel displayed is shown in Figure (3b) on
Page 4.
Apple Find Bar Only available in OS X 10.7 and later; and therefore only in T
E
XShop 3.xx. It
provides a drop down bar for doing Find with an additional line if you select Replace. See
Figure (3c) on page 4 for an example of the Apple Find Bar; the additional Replace line is
displayed.
2.2 Typesetting
Once you are ready to take a look at how your document will appear you typeset it with the default
engine, pdflatex out of the box, by simply using the Typeset Typeset (Cmd-T) command.
You may wish to use a different engine as your default. You can change the default engine in
TeXShopPreferences Typesetting.
If you are including many eps graphics les in your document you may wish to typeset using
latexdvipsps2pdf since pdf(la)tex does not allow for direct inclusion of eps les
2
. The
easiest way to do this is to include the line
% !TEX TS-program = latex
2
The pdflatex program in MacT
E
X-2010 and later will do on-the-y conversion of eps les.
4
(a) (b)
Figure 4: (a) Source Preview Synchronization; and (b) PreviewSource Synchronization.
at the top of your document. Then T
E
XShop will use the latex+distiller typesetting method
noted above no matter what the default engine setting. Change latex to pdflatex to force use of
pdflatex to typeset your le.
2.2.1 Removing Aux les
The process of typesetting produces several auxiliary les that contain information about cross
references, bibliography, indexes, etc. If an error occurs during typesetting these les can be left
in some unknown state and need to to be removed before attempting to typeset the document
again. The FileTrash Aux Files (Ctl-Cmd-A) command removes most of the les that may create
problems.
With T
E
XShop 3.18 and later there is an additional way to remove those les and then typeset
the document with a single command. If you hold the Opt key down while clicking the Typeset
menu the Typeset Typeset command becomes Typeset Trash Aux & Typeset (Opt-Cmd-T).
Search for trash aux in HelpTeXShop Help Panel. . . for the list of all le extensions removed
by the Trash Aux Files and Trash Aux & Typeset menu commands. The Terminal commands used
to add additional extensions to the trash list and return the list to the default list of extensions is
also given in that section of T
E
XShops Help Panel.
2.3 Viewing the Output pdf File
Assuming the document was successfully typeset the pdf le will automatically open in a separate
preview window.
You can control how its displayed in the PreviewMenu. You can change the default settings
in TeXShopPreferences Preview.
2.3.1 Synchronizing between pdf and Source
With more recent T
E
X distributions you can also skip back and forth between a location in the
Preview Window and the equivalent location in the Source Window by Cmd-Clicking in either one
to go to the (approximate) location in the other. See Figure (4) for an example of Source Preview
and PreviewSource synchronization.
2.4 Working with a Large Document
It is often handy to break a large document into more manageable subordinate parts and then
create a root le which contains the preamble and \include commands to bring all the parts
together for typesetting.
To have T
E
XShop know which le to typeset when working on a subordinate le put the line
5
(a) (b)
Figure 5: BibDesk Plugin: (a) citation insertion; and (b) cross-reference insertion.
% !TEX root = path/to/rootfile.tex
at the top of your subordinate le; path/to/rootfile.tex is the relative or absolute path to the
root le for this document. Once this is done T
E
XShop will typeset the root le if you press Type-
set Typeset (Cmd-T) even though you are editing a subordinate le and properly synchronize
between the Source and pdf. E.g., if the root le is called mygreatbook.tex and the chapter les,
chapter1.tex, etc., are in a chapters sub-folder below the root le then place the line
% !TEX root = ../mygreatbook.tex
at the top of each of the chapter les. The ../ means go up one folder level to nd the root le.
2.4.1 Switching between Source Windows
If you have multiple source les open you can switch between just those windows by using the
WindowNext/Previous Source Window(Cmd-F2/Shft-Cmd-F2) menu commands.
2.5 Working with BibDesk and Citations
T
E
XShop has a built-in plugin that interacts with the BibDesk bibliography application to allow
you to complete citation references in the \cite command. To enable the use of the plugin
make sure that TeXShopPreferences SourceEditor BibDesk Completions is checked.
To use it you must rst open the required bibliography (bib) le(s) in BibDesk. Enter several
characters from the reference label within the \cite command and press F5 to get a list of
matching references from the bib le(s) with a bit of information about each one. Scroll to the
one you want and press Return or Tab. See Figure (5) on page 6 for an example.
The plugin also works for entering cross-references within \ref or \pageref commands
but only for those with labels in the le you are editing.
2.6 Getting Help for Packages
There are many times when having help about a given package can be handy. T
E
XShop has an
interface to texdoc which will bring up that documentation. Execute the HelpShow Help for
Package. . . (Opt-Cmd-I) and enter the name of the package.
You can also easily look at a package directly with the HelpOpen Style File. . . command
and enter the full package le name including the proper extension (e.g., .sty for packages or
.cls for document classes).
3 Controlling the Keyboard
One of the best ways to speed up your entry of text in a source le is to keep your hands on the
keyboard as much as possibleonly one of the reasons I dont like the clicky interface of the
6
L
A
T
E
X and Matrix Panels. There are many shortcuts associated with the T
E
XShop menu system but
this section is about changing and adding others and other keyboard customizations.
3.1 Menu Shortcuts &SystemPreferences
Sometimes youd like to add a shortcut to a menu item that doesnt have one or add one to a
command whose shortcut you dislike. Mac OS X 10.4 (Tiger) and later have a method to add
shortcuts to specic menu items both globally and in specic programs. This feature has become
much more reliable in OS X 10.5 and especially in OS X 10.6 and later.
One example using Mac OS X 10.6 (Snow Leopard) or later: T
E
XShop 2.36 has added a
FileNew from Stationery. . . command, without a shortcut, which can be very helpful once you
set up stationery the way you want. To add Opt-Cmd-N as the shortcut to that menu item: open
up the System Preferences application to KeyboardKeyboard Shortcuts and select Application
Shortcuts; press the +button to add a shortcut; select T
E
XShop as the application; enter the exact
menu title [New from Stationery. . . note you must enter a real ellipsis, . . . , (Opt-; with the
English keyboard layout)]; and press Opt-Cmd-N as the shortcut.
3.2 More Editing Help
T
E
XShop is built using Apples programmers interfaces (called frameworks) and therefore inherits
all the properties and functionality of those interfaces. There are many things available through
the Text framework that arent tied to the keyboard by default, e.g., many emacs-like keyboard
commands, but Apple has made it possible to add those commands to all applications that use
the Text framework; e.g., TextEdit and Mail as well as T
E
XShop.
This is done by creating a special le, DefaultKeyBinding.dict, and placing it in a particular
location, ~/Library/KeyBindings (you may have to create the KeyBindings folder there if it
doesnt already exist).
You can get more information about this, as well as a (useful) sample, by downloading the
KeyBindings.zip le at <https://dl.dropbox.com/u/10932738/index.html>.
3.3 Key Bindings
Besides adding shortcuts to Menu Items you can actually bind keystrokes, within T
E
XShop, to
expand into groups of characters. Checking the TeXShopPreferences SourceEditor Key
Bindings option will enable this feature. You can also toggle it on/off for any particular docu-
ment using SourceKey Bindings Toggle On/Off. This feature was previously called Auto
Completion; not to be confused with Command Completionsee section (5) below.
E.g., pressing Opt-, with a US keyboard layout, usually enters into your document but
with Key Binding enabled \leq will be entered. Similarly, with some text selected pressing " will
surround the selected text with and .
You can add, remove or change the key bindings using the Key Bindings Editor (SourceKey
Bindings Edit Key Bindings File. . . ). Figures (6) and (7) show the Key Bindings Menu and Editor.
Once in the Editor the left hand column displays the input keystroke while the right hand
column shows what will be substituted for that keystroke. To see how you produce some of
those keystrokes enable the Keyboard Viewer in System Preferences KeyboardKeyboard by
checking the Show Keyboard & Character Viewers in menu bar item and then clicking on the
new keyboard icon in your Menu Bar.
4 Macros
Macros can be simple text substitutions or Applescript programs that can do all sorts of processing
on a le. You can also assign a keyboard shortcut to any macro for direct execution. The ones that
are part of T
E
XShop are found under the Macros Menu.
7
Figure 6: The Key Bindings Menu in T
E
XShop.
Figure 7: The Key Bindings Editor in T
E
XShop.
8
Figure 8: The Macro Editor Window.
Figure 9: The extra menu items when the Macro Editor is open.
You can remove or add additional macros to the menu by using the Macro Editor (use the
Macros Open Macro Editor command). The Macro Editor window and extra menu items in the
Macros Menu are shown in Figures (8) and (9) respectively.
Besides writing your own macros you can add macros supplied by others to the Macros menu
one of two ways: copy and paste the text version of the macro into a New Itemin the Macro Editor;
or obtain the macro as a plist le and use the Add macros from le. . . command found in the
Macros Menu when the Macro Editor is open (again, see Figure (9)).
More information on macros can be found by searching for macros in HelpTeXShop Help
Panel. . . .
4.1 Text Macros
Text macros are simple text substitutions. You can also tell T
E
XShop to insert any selected text
using #SEL#, place the cursor using #INS# and even put in multiple lines in the macro itself. Then
you can assign the text macro to a keyboard shortcut.
I like to use Cmd-B and Cmd-I to insert \textbf{...} and \emph{...} into the document
where ... is any possible selected text. Macros to do that are already under the Macros Text
Styles Menu so we need only assignkeyboard shortcuts to them. To assignCmd-I to the emphasize
macro: open the Macro Editor where the form of the Macros menu appears in the left hand pane;
click the emphasize macro found under Text Styles; click the Key insertion box and simply insert
a lower case i (the Cmd key is assumed and additional modier keys can be checked off ).
9
4.2 Applescript Macros
You cannot distinguish Applescript macros in the Macros Menu from text macros but they can do
complicated processing and add/change the source le in T
E
XShop. One example in the default
set is the Programmacro that creates a
% !TEX TS-program = xxxx
line at the top of a le with your choice of engine substituted for xxxx. You can look at the
Applescript code for this macro by clicking on its name in the Macro Editor.
5 Command Completion
L
A
T
E
X markup is rather wordy which is nice because it describes what its supposed to do but a
bit painful to write. Command Completion allows you to insert complete environments and
commands with a few keystrokes and the press of a trigger key (this is Esc by default but can be
changed to Tab in TeXShopPreferences SourceCommand Completion Triggered By:).
Commands that have arguments usually have a Mark () inserted for each argument. You
move to the next argument by using the SourceCommand CompletionMarks Next Mark
command (Ctl-Cmd-F [or Opt-Trigger]). This also selects the Mark so typing automatically removes
the Mark and substitutes the typed information. See the complete documentation, with lists of
commands/abbreviations supplied with T
E
XShop out of the box, in the ~/Library/TeXShop/
CommandCompletion folder for much more information.
5.1 Completions
You can complete many commands by starting to type them and pressing the trigger key. Varia-
tions on the commands with differing numbers of optional arguments are generated by additional
presses of the trigger. One example: typing \sec and then the trigger on a new line produces
\section{}
while a second press of the trigger gives
\section
*
{}
the *-variant of the command and a nal press of the trigger gives
\section[]{}
with the optional argument.
5.2 Substitutions or Abbreviations
Besides completions for partial command insertions there are also many abbreviations. These are
short mnemonics for complete substitutions.
All abbreviations for environments start with a b. To generate a complete itemize environ-
ment place \bite on a line by itself and press the trigger key to get
\begin{itemize}
\item

\end{itemize}
with an extra Mark at the end so you can easily jump to the end of the environment. Additional
items can be generated by typing \it and the trigger to get
10
\item

ready for entry of text.

In addition to the \section command lower level sectioning commands have abbreviations.
Sub-sections can be generated by typing \ssec and the trigger to get
\subsection{}
with subsequent presses of the trigger key giving the *-variant and nally the variant with the
optional argument.
As a nal example \tt and the trigger gives the \texttt{} command and a second press of
the trigger gives the declaration \ttfamily with similar results for other font changing commands.
5.3 Hey, it doesnt work!
If these examples dont work you probably need to let T
E
XShop update the ~/Library/TeXShop/
CommandCompletion folder; simply delete that folder from ~/Library/TeXShop and restart
T
E
XShop.
6 Extending Processing via Engines
T
E
XShop offers several default engines (also referred to as scripts which is left over from earlier
times) in its Typeset Menu. These include running Plain TeX or LaTeX (either using pdftex or
TeX+DVI), BibTeX, MakeIndex, MetaPost or ConTeXt. But there are many things you may wish to
do that fall outside of this limited set so T
E
XShop also allows you to create new engines that are
stored in ~/Library/TeXShop/Engines. These additional engines do not show up in the Typeset
menu but only in the popup list on the Source and Preview Toolbar (see Figure (10)).
You can use these engines by choosing from that popup list and then pressing the Typeset
button or, a better choice if you use different engines for different documents, by putting a line
like
% !TEX TS-program = xelatex
at the top of your source le; the example given will run the xelatex engine on this le indepen-
dent of other choices.
T
E
XShop is shipped with a few engines activated (i.e., directly in the ~/Library/TeXShop/
Engines folder) but also includes several additional ones in ~/Library/TeXShop/Engines/
Inactive. As an example lets activate and use the pdatexmk engine found in ~/Library/
TeXShop/Engines/Inactive/Latexmk.
6.1 The pdflatexmk engine
If your document had cross-references, bibliographies and/or indexes it takes multiple pdflatex
runs with intermediate runs of bibtex and/or makeindex to create the bibliographies, indexes
and resolve all cross-references. The pdflatexmk engine automates this whole process.
T
E
XShop 3.07 or 2.46 and later activate the pdatexmk engine by default in a fresh installa-
tion. If you are using an earlier version of T
E
XShop, or even updated to the latest version from
an earlier version, you need to activate the engine. To activate the engine simply move the
pdflatexmk.engine le from ~/Library/TeXShop/Engines/Inactive/Latexmk two folders
up, to ~/Library/TeXShop/Engines. When you restart T
E
XShop you can check that pdatexmk
in now in the popup menu.
Then place the line
11
Figure 10: The Engines Popup Menu on the Source Toolbar.
% !TEX TS-program = pdflatexmk
at the top of your source le. From then on when you simply typeset the le (Typeset Typeset
or Cmd-T) T
E
XShop will use this engine and the complete process for typesetting the document to
its nal form will be carried out.
12