Texpad on macOS is scriptable.

LaTeX is a powerful typesetting language and it is impossible to anticipate all its use cases in the field. If your typesetting needs are not being met by Texpad out of the box, you can write to us to improve Texpad by catering for them as there will be others who could also benefit from them. In the meantime however, you can script Texpad’s typesetting’ to suit your needs using a custom build scripts.

Texpad allows you to use your own scripts to customise and control the typesetting process. When using these, the standard typeset is bypassed in favour of these 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).

Who should attempt to write a custom .tpbuild script?

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.

How does a .tpbuild script work?

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 and must be named $TEXPAD_ROOTFILE_NO_EXT.pdf.

For selecting a .tpbuild script in your typeset configuration, switch to the “Manual” option,

and select a build script.

Local and Global Scripts

These scripts form two classes, local and global .tpbuild scripts.

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 Typeset Add/Edit Global .tpbuild Scripts…. Out-of-the-box, Texpad comes with a script for typesetting your LaTeX documents into ePub for creating ePub books straight from your LaTeX source. This 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.

Local .tpbuild Script

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. When this option is chosen for a file root.tex, 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 typeset (equivalent to pressing Cmd- T).

Downloading and sharing Build Scripts

Out-of-the-box, Texpad comes with a number of these scripts. More of these scripts can be downloaded from our TexpadKB repository:

https://github.com/vallettaventures/TexpadKB/tree/master/tpbuild-scripts

Some of these scripts were suggested and written by users to share with other Texpad users. If you don’t find a script you’re looking for here, please be in touch with us at support@vallettaventures.com.