A typesetting engine is an underlying tool or a set of tools that takes as its input a root latex document and produces a PDF. When you use one of the standard typesetters in the Typeset menu, such as Cmd-T, an underlying typesetting engine is used to generate the actual PDF. Composite typesetters such as BibTeX (Cmd-B), also use a typesetting engine to manufacture the PDF while adding references, etc. Texpad supports theoretically infinite number of such engines, but six, listed below, are supported natively.
pdfLaTeX: Used to generate most documents in PDF from LaTeX source.
LaTeX dvi2pdf: Used to generate a DVI and a PDF. Certain LaTeX packages may only work when typeset with this option -- please consult the documentation provided with the package.
LaTeX dvips ps2pdf: Used to generate a DVI, a PS and a PDF. Certain LaTeX packages may only work when typeset with this option -- please consult the documentation provided with the package.
XeLaTeX: Runs XeLaTeX to generate a PDF. XeLaTeX is a modern typesetting engine recommended for most documents.
pLaTeX dvi2pdfmx: Runs pLaTeX to generate a PDF. This option is necessary to typeset documents written in Japanese.
LuaLaTeX: This is a version of pdfTeX with a Lua scripting engine embedded. It is modern and capable of typesetting a large class of LaTeX documents.
A bibliography engine is a tool that manages your reference files. It is entirely optional as LaTeX is perfectly capable of producing citations out of your references with out the use of such an engine. Currently, Texpad supports three bibliography engine, BibTeX, Biber and BibTeX8.
A typesetter in Texpad is a typesetting chain that implements the complete sequence of calls to the underlying tools (typesetting or bibliography engines) such as pdfLaTeX, BibTeX, MakeIndex, etc that are required to typeset a document, compile its references and convert any PS or DVI files to PDF. Based on the choice of the underlying tool in Typesetting Preferences (see below) and a typesetter selected here, Texpad calculates this sequence automatically.
All these options may be accessed either via the Typeset menu or the Typesetter popup menu on the tool bar. Following is an explanation of these typesetters including how and when they may be used.
The default and recommended way to typeset in Texpad is with the `Auto-detect' typeset chain, activated by Cmd-L. When run this will check if the document relies on BibTeX or MakeIndex, and choose the correct typesetting tools as necessary. Additionally this will read the timestamps on any BibTeX files, and after the first run it will only rerun BibTeX if the BibTeX intermediate files are out of date.
If Auto-detect is not working for you, select one of the four hardwired typesetters, and it will force Texpad to run the correct chain. There is an additional option to run a custom typesetting chain via a .tpbuild script. These four chains are assigned to Cmd-T, Cmd-B, Cmd-I, Shift-Cmd-I and Alt-Shift-Cmd-T respectively.
Basic typeset with the underlying tool as set in the Preferences' window. Since tools such as pdfLaTeX need to be run twice when a new reference of any kind is added to the course code, Texpad automatically runs them twice, thus eliminating the need to do so by the user. Chain: pdfLaTeX pdfLaTeX
Typesets and compiles the bibliography file. The underlying bibliography engine is set in the Preferences' window (current options include BibTeX and Biber). Chain: pdfLaTeX BibTeX/Biber pdfLaTeX pdfLaTeX.
Runs MakeIndex tool for compiling the indices in addition to running the usual underlying tool. Chain: pdfLaTeX MakeIndex pdfLaTeX.
Compiling MakeIndex with glossaries and acronyms: Texpad attempts to dynamically determine the options that need to be passed to MakeIndex when glossaries and acronyms are being compiled. These cases result in additional intermediate files such as .acn}, .ist, .glo, etc being generated by the underlying typesetting tool, which helps Texpad add additional MakeIndex calls to the typesetting chain.
Combines the BibTeX and MakeIndex typesetters.
In addition to the built-in typesetters that should serve most typesetting needs, Texpad allows you to use your own scripts to customise and control the typesetting process. When using these, the standard and the auto-detect typesetters are bypassed in favour of these custom build scripts. These scripts must have case-sensitive extensions `.tpbuild' and are currently assumed to be Unix bash scripts* (meaning they are run by Texpad using /bin/bash).
Custom typesetting is designed for those advanced users only who are familiar with writing Unix-based bash scripts. We recommend avoiding these custom scripts unless they are absolutely essential for typesetting a nonstandard LaTeX project. In some cases, it may be difficult to integrate their use with Texpad.
Before running the .tpbuild script, Texpad sets the following two environment variables for you to use in your .tpbuild files:
TEXPAD_ROOTFILE}
TEXPAD_ROOTFILE_NO_EXT
For instance, root.tpbuild may look like as follows
xeLaTeX $TEXPAD_ROOTFILE
with TEXPAD_ROOTFILE
being set to root.tex by Texpad before running the .tpbuild script. The second environment variable TEXPAD_ROOTFILE_NO_EXT
comes handy when you have to, for instance, convert the DVI output of your first step, the $TEXPAD_ROOTFILE_NO_EXT.dvi
file, to a PDF in a follow-up step.
For Texpad to display the PDF output of a custom script in its PDF pane, the file must be placed in the same directory as TEXPAD_ROOTFILE.tex
and must be named TEXPAD_ROOTFILE.pdf
.
These scripts form two classes, local and global .tpbuild scripts.
Texpad is shipped with a number of global build scripts that are installed in the directory
~/Library/Application Support/Texpad/BuildScripts/
This directory may be opened from within Texpad using the menu option
.Shipped scripts: Out-of-the-box, Texpad comes with ConTeXt (for typesetting with ConTeXt engine), ePub (for creating ePub books straight from your LaTeX source), latexmk (for using latexmk build chain for your documents), Plain TeX and Sweave (for compiling and typesetting Sweave/R projects) scripts. These are given Alt-Shift-Cmd-1 to Alt-Shift-Cmd-5 hotkeys. These may be deleted and new scripts may be added to BuildScripts directory as required. These scripts may also serve as templates for creating your own scripts.
Assigning hotkeys: Hotkeys for global scripts are of the form Alt-Shift-Cmd followed by a number N. These numbers are assigned to scripts based on their alphabetical order in BuildScripts directory. Once a script has been assigned a hotkey, the key is reserved for that script regardless of the order in which it appears in the directory. The hotkey is freed up for use by other, new scripts when the script is deleted from the directory.
There may be cases when a document or a project has specific typesetting needs catered for neither by the standard typesetters nor by a global .tpbuild script. Such cases may be dealt with using a local .tpbuild script. These scripts are run using Alt-Shift-Cmd-T or accessed via the typesetting menus. When this option is chosen for a file root.tex8, Texpad first looks for a root.tpbuild file in the same directory as root.tex. If it finds one, it runs it instead of its own typesetting chain. The mechanism is error-proof in that if Texpad fails to find a local .tpbuild script, it simply reverts to the Normal typesetter (equivalent to pressing Cmd-T).
Certain special cases must be kept in mind when working with specialised packages.
-shell-escape
If you wish to use packages such as epstopdf, minted, gnuplot, etc with Texpad, you must first enable the -shell-escape
option of the typesetting pane of the Preferences window, see section on Preferences for more details. This is because these packages launch external binaries via a command
\write18{}
which must be explicitly enabled using -shell-escape
when invoking TeX. By default, Texpad disables \write18{}
since it allows for arbitrary code execution on your machine, which is a serious security hole.