Typesetting takes your LaTeX (or markdown) source code and outputs the formatted PDF, highlighting if necessary any errors in your code. In advanced use cases where bibliographies, indices and other types of content is involved, the typeset process can get rather complex, requiring multiple, precise calls to various LaTeX tools.

Texpad makes the process of typesetting as simple as it can be: a single button (or a key combination Cmd-T) triggers the process, compiles and updates the PDF.

## Configuring typesetting

When you open a new file, Texpad’s source code parsers determine a set of traits your document possesses, such as the use of bibliographies, or a specific type of index. These lead to auto-sensing the typeset needs for the document. Texpad combines these auto-sensed typeset requirements with the global settings in the Preferences’s Typesetting section and produces a typeset configuration, captured by the dropdown panel next to the typeset button,

The text on the toolbar outlines the chain of underlying typeset operations, “pdfLaTeX” in this case. The Current Configuration gives you a summary of how the typeset will be typeset. The Auto-Typeset setting is based on your global preferences.

### Auto-sense

If you leave the Auto-sense option on, Texpad adjusts the typeset configuration as you proceed with typing your document. For instance, if you add the line

    \\bibliography{mybibliography}

to your LaTeX source, the configuration is updated to include a call to BibTeX to compile your bibliography file,

Providing feedback: Texpad auto-senses a large class of typesetting traits. More are added as we improve the parsers to inform the typesetting. If you find that your particular typesetting requirements are not auto-sensed, please send us an example file to help improve auto-sense further.

### Manual configuration

Occasionally Texpad might fail to auto-sense correctly precisely the typeset configuration for your document, or you may wish to adjust certain aspects of it. All you need to do is flick the button to Manual and all the options are revealed. The first time you go from auto-sense to manual, the

### Compiling bibliographies

Texpad autosense the bibliography compilation needs of a document automatically and runs an appropriate tool. In the manual configuration, you can customise these options

### Compiling Indicies and Glossaries

Texpad currently only supports makeindex to compile indices and glossaries. When auto-sense is on, it will attempt to compile each of the index type you have used in the document. These can be hand-selected in manual typeset.

In the manual mode, once you’ve selected a list of indices for a document, these are remembered by Texpad for future use for that document as part of the document’s persisted workspace state.

### Compiling Woven R code (RNW files)

R code can be woven with LaTeX in the form of RNW files. These can be processed using two main tools, knitr and sweave. Texpad can handle typeset RNW files out of the box. When using auto-sense, it will automatically pick the correct flavour and typeset the PDF for you. As always, you can customise this in the manual mode of the typeset configuration,

## What happens while the typeset wheel spins?

A typeset operation triggered by the spinning wheel on the toolbar or Cmd-T triggers 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 typeset configuration pane (see above), Texpad calculates this sequence automatically.

The actual process of taking some text files with your LaTeX source and generating a PDF is handled by the underlying typesetting engines. 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. This underlying engine is often auto-sensed for you by Texpad. These include

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 typeset may additionally require compilation of bibliographies, indices, processing of R code (within your RNW files) and other formats within your LaTeX code. 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 without the use of such an engine. Currently, Texpad supports three bibliography engine, BibTeX, Biber and BibTeX8. For compiling indicies, Texpad currently supports makeindex only, with xindy to follow in a future version. For processing RNW files, Texpad uses R with sweave or knitr related packages given as parameters.

## Custom Typesetting using Build Scripts (Advanced)

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.tex` and must be named `TEXPAD_ROOTFILE.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.

###### i. 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.

###### ii. 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).

## Typesetting Caveats

Certain special cases must be kept in mind when working with specialised packages.

## Shell Escape

LaTeX is more than a markup language, it allows great flexibility when compiling your documents. One example is the ability for your code and the packages you include to call other utilities installed on your computer to carry out various tasks. This is achieved by including

    \write18{}

in the LaTeX code that allows the code to launch external binaries. Packages such as epstopdf, minted, gnuplot, etc. use this facility. To provide additional security, LaTeX requires `-shell-escape` be specified on the command line. In Texpad, this amounts to switching the option Shell Escape on in the typeset configuration from the toolbar of an open project.

### Shell escape security warning

Shell escape allows for execution of arbitrary code during typesetting, which is a potential, but serious, security hole. Please use this sparingly and only with packages you trust.

Texpad’s auto-sense typesetting is capable of enabling this feature when necessary. You can however override this by configuring the “Shell Escape security policy for Autosense” in the Typesetting pane of your Preferences.

## Using ‘Hide Intermediate Files’ option

In order to keep the working directory clean Texpad will by default create a hidden .texpadtmp directory in the same path as the root file and use this for all intermediate files created whilst typesetting. It goes to great lengths to ensure that this does not interfere with typesetting your documents. Occasionally you may use packages that conflict with this option. Texpad in such cases auto-corrects itself and switched the option off.

However some packages call external tools which are unaware of LaTeX’s intermediate files setting and hence cannot find these intermediate files. In order to typeset with these packages you must uncheck the “Hide intermediate files” option in Texpad’s preferences.

Known packages with this problem are

- Minted
- Gnu plot
- dot2tex