Custom Typesetting in Texifier macOS using Build Scripts
This article concerns the
macOS
app.
See other variants:
Windows

Texifier 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 Texifier out of the box, you can write to us to improve Texifier by catering for them as there will be others who could also benefit from them. In the meantime however, you can script Texifier’s typesetting’ to suit your needs using a custom build scripts.

Texifier 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 Texifier 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 Texifier.

How does a .tpbuild script work?

Before running the .tpbuild script, Texifier 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 Texifier 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 Texifier 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,

docs/apps/workspace/typesetting/config/build-scripts_macos.png

and select a build script.

Local and Global Scripts

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

Global .tpbuild Scripts

Texifier is shipped with a number of global build scripts that are installed in the directory

~/Library/Application Support/Texifier/BuildScripts/

This directory may be opened from within Texifier using the menu option Typeset Add/Edit Global .tpbuild Scripts…. Out-of-the-box, Texifier 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, Texifier 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 Texifier 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, Texifier 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 Texifier users. If you don’t find a script you’re looking for here, please be in touch with us at support@vallettaventures.com.