Texpad OS X Guide

Texpad is a LaTeX editor designed for fast navigation around projects of all sizes. Given a single LaTeX root file, it will read through the LaTeX source, and that of all included files to present you with an outline of your project. Similarly Texpad reads the LaTeX console output, finding errors, and presenting them in a table you can use to jump straight to the errors in the LaTeX source.


Contents

  1. Quick Start
  2. The Organiser Window
  3. Features
  4. Detailed Reference
  5. Licensing

1. Quick Start

To begin editing a document or project, drag the root LaTeX file to the Texpad icon. The outline view on the left of the editor window that appears will show the document structure similar to LaTeX’s table of contents. Texpad will traverse the root file, hunting for included files and incorporating them in the outline view. Clicking on this outline view table will allow you to navigate your entire project.

When you are finished editing, click the Typeset button on the menu bar and Texpad will pass your source to the LaTeX distribution to typeset. You may choose between pdfLaTeX and LaTeX/dvipdf in the Typesetting Engine Preferences. Please note that Texpad relies on an underlying TeX distribution such as MacTex www.tug.org/mactex, a packaging of TexLive for OS X.

When typesetting is finished a pane will appear to the right of the editor pane. If the typesetting was clean it will show the resulting PDF, if not it will display an error list. Clicking on these errors will jump to and highlighting the offending line in the editor.

Texpad is SyncTeX aware, so if your TeX distribution supports SyncTeX, clicking the pdf will highlight the corresponding LaTeX source. Likewise, clicking on the document structure will jump to the corresponding point in both the LaTeX source and the PDF view.

2. The Organiser Window

The Texpad Organiser is the initial window you see when you launch Texpad, or click on the Texpad icon in your desktop Dock. It is also accessible via Ctrl-Cmd-T. The Organiser provides an easy access basic file & project features in Texpad.

osx-organiser

In the Home view, there’s a quick sanity check of your LaTeX and Texpad installation. You may create new documents and open existing ones right from the Organiser, as well as access three most recent documents you’ve worked on.

The second pane entitled Texpad Connect allows you to sign in to your Texpad Connect account and access all your projects.

osx-organiser-tpc

3. Features

The central premise of handling source code in Texpad is working with a LaTeX root document, that is a a document that contains a typesetable block such as the one below

\documentclass[10pt]{article}
\begin{document}
    Some text...
\end{document}

Any subfiles included in the root document via LaTeX tags, such as \input{subfile1.tex} or \include{subfile2.tex} are loaded into the editor automatically by Texpad. All typesetting operations are carried out on the root file, but you may edit any of the included subfiles, including bibliography files ({.bib), user stylesheets (.sty), LaTeX classes (.cls), etc.

The Workspace

When a file is opened with Texpad, a workspace is created for it. This is a persistent state of the entire project for that file, including the typeset configuration, the states editor tabs are in as well as various other pieces of information that help Texpad to restore the project to its current state when you close it and reopen it.

Tabs

Texpad allows you to open files in your projects in multiple tabs. Note that the tabs are designed to open different files of the same project, but not different projects. A project here refers to an input file or a set of input files containing LaTeX source that compile into a single output PDF.

Tabs in a window may have different editor and PDF locations, allowing you to work on different parts of the project simultaneously and easily switch between them. You can create as many tabs as you want.

osx-tabs

Creating a new tab (Cmd-Shift-T) duplicates the state of the current tab and makes the new tab current. Cmd-Shift-[ and Cmd-Shift-] allow you to quickly move to the next and previous tabs.

The toolbar

The toolbar is designed minimally to aid your workflow without cluttering the screen. It is your quick access to many of the common functions. The typeset may be triggered and configured right from here. The outline, the editor and the PDF panes may be shown and hidden from here. You can search the whole project as well as view any outstanding typeset issues. The share button allows you to email or export the LaTeX source or the PDF with ease.

osx-toolbar

The buttons and controls on this toolbar are described below.

Control Function
Typeset Pressing this will button will set in motion the typesetting process. A spinning wheel in this button indicates that a typeset operation is in progress. A second-click on the spinning wheel will abort the typesetting. This button may be indirectly pressed by selecting a typesetter from the Typeset menu or an associated hotkey.
Typeset Chain A brief description of the current typeset chain along with a dropdown arrow that opens the full typeset configuration.
Share A dropdown view with options for emailing or exporting your project contents.
Outline Shows/Hides the Outline View to the left of the editor pane.
View Pressing the view buttons will change the arrangement of the editor between Editor only, Editor and Output, and Output only respectively.
Issues A dropdown view for outstanding errors in your source code along with the full typeset log.
Search field Search box for finding and replacing text across all the files in the project.
Backward/Forward Arrows Jump to previous and next locations during the navigation of your document. These apply to the current tab.

The project outline

The pane to the left of the editor pane shows the structural outline of your LaTeX project, updated every time you save or typeset the file.

osx-project-outline-cropped

Clicking on these tags will jump to the corresponding position in the source code, and if your distribution supports SyncTeX, the PDF output.

The menu bar in the Outline View contains a ‘Settings’ button on the left. The menu attached to that button may be used to customise the level detail you wish to see in the Outline as shown below.

osx-project-outline-toc-filter-menu

The menu bar in the Outline View contains a Settings button on the left which may be used to customise the level detail you wish to see in the Outline. The arrows on the right help move back and forth between different points in the code that you’ve visited. It is particularly useful when moving around between different files, to edit them or to jump from the Error Log.

The Editor

Texpad’s custom built editor is designed to facilitate writing LaTeX code with ease. It provides highlighting of LaTeX syntax, completion of LaTeX commands while you are typing and many others utilities to help you along while writing your documents.

Syntax Highlighting

It can be difficult to read the syntax of LaTeX source. Like many editors Texpad colours your text according to its role, command, maths, comment, etc.

Embedded Code

Sometimes source for a different language can be embedded in LaTeX documents, for example lua code in LuaTeX, Haskell in Literate Haskell, or even code listings using minted.

Texpad is sensitive to these cases, and it will not colour code following e.g. $ symbols as mathematics so that it does not spoil the highlighting for the remainder of your document. In some cases - for example embedded luacode within a \begin{luacode} environment - Texpad will also highlight the embedded code.

Editor Aids

Autocompleting commands while typing

Texpad has an advanced and configurable autocomplete system capable of autocompleting straightforward commands, autofilling the \\ref,\cite and \\begin families of commands, and autocompleting custom commands and environments defined via \newcommand and \newenvironment macros.

Command autocompletion

Type a standard LaTeX command and a small window will appear next to the cursor with a list of possible completions, and information about the highlighted entry at the bottom of the autocomplete list. You can accept an autocomplete with the Tab key, and dismiss the autocomplete window with the Escape key. Up and down keys will change the selected autocomplete. You can disable autocomplete entirely with the Auto Completion option in the preferences window.

osx-autocomplete-menu

Autofill command parameters

When typing commands with parameters such as \cite{}, \ref{} and \begin{}, Texpad will not only help complete the command itself, it will also fill the argument, known as autofill.

Texpad will parse any BibTeX or LaTeX files in your project, looking for \labels, \bibitems and .bib file entries. If you type one of the \ref{ family of commands Texpad will offer all known labels as possible completions.

Texpad knows many other autofills beside these, for example, it will autofill \bibliographystyle{ commands, \usepackage{ and \begin{ commands, amongst many others.

Automatching blocks

If you insert a \begin{ command from autocomplete and there is no matching \end{ command, Texpad will insert one. Texpad will also generate a matching

\end{some environment}

every time you press return on a line with

\begin{some environment}

This behaviour can be enabled or disabled with the Automatch \begin with \end option in the Preferences window.

Auto Indent

When you press return, Texpad will insert an equivalent amount of whitespace as there is at the beginning of the current line. This behaviour can be enabled or disabled with the Auto Indent option in the preferences window.

Auto itemise

In certain types of environment, e.g. the itemize and enumerate environments, texpad will insert an \item command every time you press return on a line containing an \item command

Configuring Autocomplete

Custom Autocomplete commands are stored in the autocompleted_commands.txt file inside Texpad’s Application Support directory. You can open this file in Texpad by clicking the Add/Edit autocompleted commands… menu item in the Texpad menu. Once you have changed this file you must reboot Texpad for the changes to take effect.

This file consists of lines that are either a comment, and autocomplete command or an autofill identity. Their syntax is explained below.

(a) Comment

The first non-whitespace character in the line should be a % symbol. E.g.

% This is a comment line

(b) Autocomplete

A line that describes a custom autocomplete. This consists of four parts, the first mandatory, the second, third and fourth optional.

1. Key

The first entry should be the autocomplete key. For a regular command this should simply be the command without the preceding slash, e.g. for \documentclass write documentclass.

For an autofill autocomplete (e.g. \\begin{someenvironment} or \documentclass{article}), write the first stage, followed by a colon, followed by the autocomplete. e.g. begin:someenvironment or documentclass:article.

Autocompletes will always be sorted alphabetically, but some autocompletes are more commonly used than others and there may be one you wish to prioritise over others. To prioritise an autocomplete, prepend a stars to the key, the more stars, the higher the priority. For example to prioritise \documentstyle so that it is selected by default instead of \documentclass, add an entry beginning ***documentstyle. In the case of an autofill complete, place the stars after the colon.

2. Description

To add a description, append a | character followed by the description. This description is presented to you in the autocomplete menu when typing the command in the editor.

3. Files it is defined in

To note the file the command has been defined in, write an @ character followed by a comma separated list of files.

4. Files it is redefined in

To note the files the command has been redefined in, write an @@ followed by a comma separated list of files.

An example of a simple \documentclass command with no description is

documentclass

An example of an environment with a full description is

begin:*fake | description here @ a.tex @@ b.cls, c.sty

An example with multiple placeholders would follow the following syntax

frac | Fraction in math mode E.g. \frac{numerator}{denominator}

© Autofill identity

In many cases different commands are autofilled in the same way. For example, begin and end are autofilled identically. To save you entering the options all again, you can add an autofill identity between, for this example begin and end. This should begin with an =, followed by the new autofilled command, followed by a colon, followed by a fully defined autofilled command (not another identity). There should be no whitespace at all on the line. To return to the begin and end example, where the autofills have been defined for begin, you would write.

=end:begin

This is useful if you have defined a custom referencing command. You could write

=customref:ref

Texpad would autofill when you type \customref{.

Comment/Uncomment

To comment an entire block of text, that is to say stop it appearing in the final document, then select the block and press Cmd-/ to comment it. Pressing Cmd-/ with the same block selected will uncomment.

Indent/Unindent

If you have a block of text you wish to indent, then rather than pressing tab at the beginning of each individual line, select the entire block of text and press Cmd-] to indent it.

The indented string will be the same as your Tab key would indent. This can be configured in the preferences pane.

You can unindent in the same way with Cmd-[

The indent size may be customised using the Editor tab indent size option in the Editing Aids pane of the Preferences window. You can choose a tab or number of spaces in {1,2,4}.

Info boxes

Many LaTeX commands are used to create references to other parts of the document, for example \cite{}, \ref{} and \includegraphics{}, which reference bibliography entries, labels and image files respectively.

In these cases Texpad is capable of creating a short summary of the referenced entity, which is displayed in the Autocomplete window. It is also displayed over the editor if you place the cursor in the command and wait. For BibTeX entries, Texpad will display as many BibTeX keys as is practically possible, for Labels Texpad will attempt to display the context of the label (section title, etc.), and for images it will show a preview of the included image.

osx-editor-popover-info-box

Snippets

Since version 1.5, Texpad has supported Snippets functionality to make it easy to insert regularly used blocks of text into your document. Texpad is distributed with a small number of helpful Snippets, but the system is fully configurable. You may edit them and/or add your own.

osx-snippets-menu

Usage

To use a Snippet, either choose the Snippet from the dropdown menu, or press the associated hotkey – all hotkeys are activated with a control key.

Configuring

All snippets are stored as text files in the Snippets subdirectory of Texpad’s Application Support directory. To open this directory, click the Add/Edit Snippets… option from the top of the Snippets menu.

To delete a snippet delete the file and it will be removed when Texpad is rebooted.

To rename a snippet, rename the file containing the snippet. The file extension is ignored, and will not form part of the snippet name.

To add a snippet, either copy the snippet file into the directory, or create a new file in that directory, with the name you want the snippet to carry.

Syntax

Snippet files are flat text files with a straightforward key = value syntax. Lines beginning with a % sign are interpreted as comments and ignored. All other lines have a key = value syntax.

The key is flattened. That is to say all whitespace, dashes and underscores are stripped and the entire key is rendered into lower case. For example Ctrl-Key, Ctrl key and ctrlkey are all equivalent keys.

If there is no right hand side to the line, then starting with the next line, all lines until the end of the file are used as the value.

An example file follows.

% A snippet to insert an itemize environment
ctrl key = z
group = Environment
insert at cursor =
\\begin{itemize}
  \item <SELECTION>
\end{itemize}

Hotkeys: Key combinations associated with snippets

Keys understood by Texpad are

Key Explanation
ctrl key The value must be a single character. It is the key that when pressed with the control key is the hotkey for this snippet.
group The name of the group that this should be displayed in.
insert at cursor The text that should be inserted at the current cursor position. Any currently selected text will be substituted for <SELECTION> and the new selection will be placed around that text.

The PDF view

The in-built PDF viewer allows you to see your LaTeX document and the output PDF side by side. With auto-typeset on (see the section on Typesetting), the PDF is updated live to reflect the changes you make to the source code.

The small toolbar at the bottom of the PDF provides convenient standard functions to alter the appearance of the displayed PDF. The Editor-PDF scroll lock allows you to navigate the document with the input (the LaTeX source code) and the output (the PDF) scrolling in sync with each other.

osx-pdf-minibar-with-pdfview

You can also zoom in and out, set a particular zoom level and send the PDF to an external display.

Syncing between PDF and LaTeX source

Texpad allows you to synchronise your LaTeX source with the output PDF. There are two ways you may choose to do so, a continuous scroll lock or a one-off sync.

One off syncing

To sync in a one off manner, then please hold the Cmd button on your keyboard and click in the editor or the pdf.

  • PDF to LaTeX source: Cmd-clicking on the pdf will jump to that line in the editor pane. You can alos use the right-click context menu at any point in the cursor and select the option “Synchronise PDF”.
  • LaTeX source to PDF: Either clicking on the outline view, or Cmd-clicking on the text will jump to that point in the pdf.

Note that in versions older than 1.5, a simple click was the default behaviour to go from PDF to editor. If you prefer that option, please use the Single-click PDF sync with editor option in the PDF Viewer pane of your Preferences.

In either case the other pane will be synchronised as precisely as possible. When syncing from editor to PDF, a light blue box will flash over the matching text, and when syncing PDF to editor, the cursor position will be set as closely as possible, often to the character.

Scroll lock

It can be useful when editing a document to keep the PDF and editor panes permanently in sync. You can do this by turning the scroll lock on from the right of the popup PDF toolbar. This will scroll the top of the two panes to match each other as you scroll.

osx-pdf-minibar-scroll-lock-on

Texpad uses SyncTeX

Please note that you will need a modern TeX distribution for this to work. As always, we suggest you download the latest version of MacTeX. If your distribution supports SyncTeX, Texpad will typeset the project with SyncTeX information automatically to enable the sync. SyncTeX is a technology built into recent TeX typesetters that generates a file with the information necessary to convert a position in the typeset PDF with a position in the editor source. As long as your TeX distribution creates the SyncTeX database then Texpad will use it. MacTeX has had SyncTeX built in since 2008 so it is overwhelmingly likely that your distribution supports SyncTeX. SyncTeX is not compatible with all LaTeX document classes; Beamer, for example, often causes trouble.

Typesetting

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.

osx-typeset-icon

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,

osx-typeset-configuration-pane-autosense-on-pdflatex

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,

osx-typeset-configuration-pane-autosense-on-pdflatex-bibtex

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

osx-typeset-configuration-pane-manual

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

osx-typeset-configuration-pane-manual-bibtex

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.

osx-typeset-configuration-pane-manual-indices

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,

osx-typeset-configuration-pane-manual-woven-r

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.

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,

osx-typeset-configuration-pane-build-scripts

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

Navigating and fixing LaTeX errors

The Error List

Instead of exposing LaTeX’s sometimes cryptic console output, Texpad reads this for you and delivers it to the log portion of the output pane. Each error displayed in the Error List table is categorised by their severity levels as shown below.

Icon Explanation
osx-red-bug The red triangles indicate the issues that are essential for obtaining a full PDF out of your LaTeX source code.
osx-amber-bug Yellow triangles indicate LaTeX warnings, such as those concerning missing packages.
osx-green-bug Green errors are the very low level errors to do with layout perfections. Most users would choose not to pay attention to these.

The level of detail you wish to see may be set in the Typesetting pane of the Preferences window.

The Error Log

As Texpad recognises that some LaTeX errors are better understood by reading the full log printed by the underlying TeX tools to the console, it displays this raw output beneath the error list.

Jumping to Errors in the Editor

Clicking on an error will jump to the corresponding line in the editor as well as to the detailed log as shown in the figure below.

osx-error-view

Locations in the code the error view jumps to are added to the forward/backward stacks, which means you can move back to the text you were editing by clicking on the Backward button.

Please note that for location jumping, Texpad relies on the raw error log of LaTeX tools, parsing whom is prone to inaccuracies. Please report any issues you encounter to the Texpad team so they can be fixed in a future version.

Searching your LaTeX Documents

Global search allows you search all documents in a workspace simultaneously.

osx-global-search-field

Getting started

Press Cmd-Shift-F or click in the search box on the toolbar to start a search. Once you have typed more than 2 characters of your search term, the search will start and a popover will appear with results as they are found. For a large document, this may take some time, especially when performing regex searches, and the results will be added as they are found.

osx-global-search

Regex Search

Some users may be familiar with Regular Expressions, often referred to as regexes. This is a special syntax for constructing complex text searches. This is not an introduction to Regular expressions, the Wikipedia page is a good place to start.

If you want to search by Regular Expression in Texpad, for example, the regular expression string\s+theory, type it into the search box enclosed in forward slashes, ie /string\s+theory/. Please note that applying complex regular expressions to a large document can take some time to return all results.

NB Texpad’s Regular Expression engine is based on icucore, so it uses classical Unix syntax for Regular Expressions.

Replacement

Once your results are displayed, you may want to replace some of them. To do this, type some replacement text in the box at the bottom of the search popover.

Select a result and press the Replace button to replace just that search result.

Press Replace All to replace all search results.

Please note that before any result is replaced, it will be compared to the original search term. It will only be replaced if it matches the original search term.

Regex Replace

A useful feature of regular expressions is to capture groups. For example the regular expression /how (\w+) you/ applied to how are you would capture are as group 1.

When replacing regex searches, you can insert group 1,2,3, etc. into the replacement string with $1, $2, $3, etc. So if you were to search for /how (\w+) you/ and replace with where $1 you?, then how are you would become where are you?, how were you would become where were you? and so on.

Keyboard Navigation

The search window is designed to be fully navigable via the keyboard.

  • Cmd-Shift-F: open the global search window
  • Esc: close the global search popover without clearing it, this allows you to press Cmd-Shift-F to return to where you started.
  • &#8593, &#8595: The up and down arrows let you navigate the global search results.
  • Enter: Press enter on a global search result to close the window and jump to that result in the text.

4. Detailed Reference

The Toolbar

The toolbar is designed minimally to aid your workflow without cluttering the screen. It is your quick access to many of the common functions. The typeset may be triggered and configured right from here. The outline, the editor and the PDF panes may be shown and hidden from here. You can search the whole project as well as view any outstanding typeset issues. The share button allows you to email or export the LaTeX source or the PDF with ease.

osx-toolbar

The buttons and controls on this toolbar are described below.

Control Function
Typeset Pressing this will button will set in motion the typesetting process. A spinning wheel in this button indicates that a typeset operation is in progress. A second-click on the spinning wheel will abort the typesetting. This button may be indirectly pressed by selecting a typesetter from the Typeset menu or an associated hotkey.
Typeset Chain A brief description of the current typeset chain along with a dropdown arrow that opens the full typeset configuration.
Share A dropdown view with options for emailing or exporting your project contents.
Outline Shows/Hides the Outline View to the left of the editor pane.
View Pressing the view buttons will change the arrangement of the editor between Editor only, Editor and Output, and Output only respectively.
Issues A dropdown view for outstanding errors in your source code along with the full typeset log.
Search field Search box for finding and replacing text across all the files in the project.
Backward/Forward Arrows Jump to previous and next locations during the navigation of your document. These apply to the current tab.

Menu Items

Note that this section only covers Texpad-specific menu items that have not been covered above. The usual Mac OS menu items behave as expected.

The Texpad Menu

Menu Option Explanation
Texpad About Texpad Information, legal statement and credits.
Texpad Texpad for iPad/iPod/iPhone A link to the iOS version of Texpad.
Texpad Preferences (Cmd-,) Settings and preferences window.
Texpad Add/Edit Autocompleted Commands… Opens the directory where auto-complete commands can be customised.

The File Menu

Menu Option Explanation
File New From Template Create a new .tex document from a template.
File Add/Edit templates… View the directory where the templates are stored ~/Library/Application Support/Texpad/Templates/. Any files added to this directory are automatically listed in the File New From Template menu by Texpad.
File Reveal PDF in Finder (Cmd-R) Opens the Mac OS Finder where the output PDF file is stored.
File Email PDF (Cmd-E) Open a new email message with the current PDF file as an attachment.
File File Encoding Choose the file encoding Texpad should use for loading and saving files. If you alter the file encoding with open documents, Texpad will migrate all files in the project, and save to disc. We strongly recommend that you use UTF-8 file encoding for your work; it supports all languages, and as such it is becoming a de facto standard for plain text files.

osx-encodings-menu
File Reload with File Encoding If you see strange characters, there is a good chance you have opened a file with the incorrect encoding; this option will discard all changes and reload all open files using the specified character encoding.
File Print LaTeX Source… (Alt-Cmd-P) Prints the source code.
File Print PDF… (Cmd-P) Prints the PDF.

The Edit Menu

Menu Option Explanation
Edit Comment Block (Cmd-]) and Edit Uncomment Block (Cmd-[) These menu options will comment or uncomment an entire block of text in one go.
Edit Indent Block (Shift-Cmd-]) and Edit Unindent Block (Shift-Cmd-[) These menu options will indent or unindent an entire block of text.
Edit Autocomplete Force-opens the auto-complete window in the editor for the currently typed word. It is a menu alternative for the simple Esc key.
Edit Global Search (Shift-Cmd-F) Brings into focus the global search field on the top of the window.

The Snippets Menu

The menu lists all the currently deployed snippets in the snippets’ directory that may be opened by selecting Add/Edit Snippets….

osx-snippets-menu

The Typeset Menu

See the help article on the Texpad Toolbar for details on various typesetters and their use.

Menu Option Explanation
Typeset Normal (Cmd-T) Normal typeset.
Typeset BibTeX (Cmd-B) Typeset and compile the bibliography file.
Typeset Add/Edit Global .tpbuild Scripts</span Opens directory BuildScripts containing all currently installed global .tpbuild scripts.
Typeset Toggle Auto-typeset (Shift-Cmd-L) Switches on and off the auto-typeset for the current project.
Typeset Remove Intermediate Files (Cmd-K) If the Hide intermediate files option is selected, Texpad keeps your home file uncluttered by hiding the intermediate files such as .aux, .log, etc. in a hidden directory called .texpadtmp. Selecting this menu option deletes this hidden directory. Note that this is safe operation and is sometimes necessary to remove possibly corrupted .aux files.
Typeset Abort Typesetting (Cmd-.) This will abort typesetting if in progress.

The Window Menu

Menu Option Explanation
Window Zoom In (Cmd-+) & Zoom Out (Cmd–) Zoom in/out for the PDF pane.
Window Show Welcome Window (Ctrl-Cmd-T) Displays the Texpad welcome window.
Window Toggle Outline (Cmd-1) Shows/hide the Outline View.
Window Hiding/showing View Panes (Cmd-2 to Cmd-4) Menu items to change arrangement of the editor between Editor only, Editor and Output, and Output only respectively.
Window Switch between PDF and Log Output (Cmd-8 & Cmd-9) Allows you to switch the output pane between the PDF view and the Error log.

Customising Texpad

Preferences window enables you to customise the operation of Texpad. It may be reached via the Texpad Preferences menu or Cmd-,. Each setting is accompanied by a short description that serves as a quick guide to its intended use.

General Preferences

osx-prefs-general

Notifications

These are preferences related to the notification system in Texpad.

Setting Explanation
Show Soft Notifications Soft notifications are Growl-like notification messages, designed to be minimally disruptive to the writing flow.
Animate Button for Auto-Typesetting You can choose to not have the typeset button spinning when the typeset operation is kicked off in the background as a result of auto-typeset being on.

View Options

These are preferences related to what panes should show and stay in focus as you work on your projects in Texpad.

Setting Explanation
Keep editor in focus Keep cursor focused in editor after a typeset.
Hide Outline on open Automatically hide the Outline View when opening documents
Single-click PDF sync with editor Check this option if you want a single click on the PDF pane to change focus to the editor.

Troubleshooting

To help when things go wrong.

Setting Explanation
Restore Default Options User preferences may be reset to their factory defaults using this button. Any user customisations will be lost and will need to be re-applied.

Automations

osx-prefs-editor-aids

Miscellaneous

Various automations settings across Texpad.

Setting Explanation
Auto Completion If checked Texpad will attempt to guess the command as you are typing it.
Auto Indent If checked each line will be indented to match the previous line.
Automatch \\begin with \end If checked Texpad will supply a matching \end{...} command for every \\begin{...} command you type.
Autosave on Typeset Check this to silently save before typesetting.

Snippets

Snippets are seen as automating entering of frequently-used blocks of LaTeX source code.

Setting Explanation
The base hotkey Snippets may be inserted using the Snippets menu or a hotkey such as Ctrl or Ctrl-Shift associated with the snippet. The default is Ctrl-Shift.

File Loading

Settings for automatically loaded files through LaTeX tags such as \include or \input.

Setting Explanation
Suppress .def files Stop Texpad from automatically chain loading .def files and displaying them in the Outline View.

Editor Preferences

osx-prefs-editor

Miscellaneous

General settings for the editor.

Setting Explanation
Show Line Numbers Check this to display line numbers along the left hand edge of the editor pane.
Continuous Spell-Checking Turn on/off inline spell checking.

Editor Themes

Themes allow customising background and syntax colours of the editors. There is a list of five themes on offer.

Setting Explanation
The list of themes Standard themes based on various colour schemes to suit your editor preferences. The preview box below demonstrates how the theme may look in the editor.
Editor font The font used to display your LaTeX source. This has no effect on the PDF output.
Editor text size The size of the font used to display your LaTeX source. This has no effect on the PDF output.
Use default font for theme Each theme comes with a default font. Clicking this button would restore that.

Typesetting Preferences

osx-prefs-typeset

General Typesetting Options

These are general Texpad-wide typesetting option applicable to all projects.

Setting Explanation
Auto-typeset by default Whether to set auto-typeset for projects when they are opened. This option may then be changed for an open window via the on/off button on the toolbar.
Default typesetter<>/span Whether to use auto-detect as default typesetter for projects. This may also be changed after the project is opened.
-shell-escape Run LaTeX with the -shell-escape option. This is necessary for packages such as gnuplot and minted, but it introduces a potential security hole, so it is turned off by default in Texpad.
Hide intermediate files (Use of .texpadtmp directory.) In an effort to keep your working directories clean and free of LaTeX’s intermediate files, Texpad stores these files inside a hidden .texpadtmp directory created in the same directory as the LaTeX root file. The Typeset Remove Intermediate Files menu item will delete this directory, and the intermediate files it contains. Please note that certain external tools you may be using, such as gnuplot, rely on the intermediate files to be present in the same directory as the root .tex file in order to work properly.
Level of details in LaTeX error log Level of detail to be reported in the Error Log.
osx-prefs-error-log-level
In addition to the minimal TeX Errors Only reporting, you may choose to see detailed LaTeX warnings as well as TeX’s hair-splitting layout alerts such as overfull or underfull hboxes.

Underlying Typesetting Engine(s)

Texpad comes with five standard options for the underlying typesetting tool, which may be set here.

Choose between typesetting directly to a PDF with pdfTeX, or typesetting to DVI with tex, and then converting to PDF. The latter option is appropriate if you intend to embed EPS figures, or you want DVI output. To embed EPS in pdfTeX, you must convert them to PDF first with the eps2pdf tool in your LaTeX distribution.

Bibliography Compilation

Texpad currently supports BibTeX and Biber bibliography engines. In addition, when using BibTeX, further environment variables BIBINPUTS and BSTINPUTS may be set to handle non-standard locations of bibliography (.bib) and style (.bst) files respectively. Note that most users will not need to fill these fields.

Managing LaTeX Distribution

osx-prefs-distributions

LaTeX Installations

Texpad does its best to ensure you are guided through to a installing a working LaTeX distribution, if you do not already have one on your system.

Setting Explanation
Installed LaTeX distributions Texpad finds and lists all available distributions. This list provides a means to switch between them, but most users are urged to choose the standard distribution, generally installed in /usr/texbin by installation tools of MacTex.
osx-prefs-distributions
Set Custom Distribution Most users will find their standard LaTeX installation has already been detected and set for use by Texpad. If you’ve installed LaTeX in a non-standard location, you may have to manually set it (only if it’s not listed in the auto-searched list) by clicking on Set Custom Distribution button and selecting the directory where LaTeX binaries may be found.
Health Check of the Selected Distribution Texpad checks that binaries it needs for typesetting your LaTeX documents are indeed present in the distribution it has been told to use. It shows you the results of its findings in this section.
Download MacTex A link to the download page of latest version of LaTeX from the Mac-specific distribution called MacTex.

Ghostscript Installation

A working ghostscript installation is needed for tools such as ps2pdf that are used to convert Postscript files to PDF. You may not needs this if you do not use the chain that requires ps2pdf.

Command Cheatsheet

Key combination Explanation
Cmd-L Automatically typeset using the correct engine.
Cmd-T Typeset using just LaTeX.
Cmd-B Typeset and run BibTeX.
Cmd-I Typeset and run MakeIndex.
Shift-Cmd-I Typeset and run BibTeX followed by MakeIndex.
Cmd-K Delete the temporary directory with intermediate files produced during a typeset.
Cmd-. Abort a typeset operation.
Cmd-/ Comment the selected block of LaTeX source.
Cmd-/ Un-comment the selected block of LaTeX source.
Cmd-1 Toggle the outline view.
Cmd-2 Show only the editor and not the output.
Cmd-3 Show both the editor and the output side-by-side.
Cmd-4 Show the output (PDF) only.
Cmd-J Switch the focus between the editor and the output pane.
Cmd-8 Show the PDF in the output pane, when available.
Cmd-9 Show the error log in the output pane, when there are errors or warnings.
Shift-Cmd-= PDF zoom in. (Also works with Cmd-=.)
Shift-Cmd– PDF zoom out.
Cmd-R Reveal PDF in Finder.
Cmd-E Email PDF.
Shift-Cmd-F Global Search.

Note that in the above, Cmd-X means simultaneously pressing the command key and the key X.

5. Licensing

When you first download Texpad it will start in a two week trial period during which it will be fully functional. If you wish to continue using Texpad, please buy a license from our website.

Purchase certificate

When you buy a license for Texpad you will be presented with a purchase certificate. To attach this license to Texpad double click it, or drag it to the dock icon.

When Texpad first sees a purchase certificate, it will verify that license with our server. You will need to be online for this operation, but from then on Texpad will run offline.

Switching from Mac App Store Texpad

If you have already purchased Mac App Store Texpad, you can swap to the Texpad distributed through texpad.com for free at any point. The direct version of Texpad automatically supports App Store licences. Please follow the following steps,

  • Ensure you have a copy of Texpad version 1.4.7 freshly downloaded from the app store. Move this copy out of the Applications folder, for instance, to your Desktop.
  • Download the latest version of Texpad from www.texpad.com/osx.
  • Install this version in your Applications folder and launch it.
  • On the welcome screen (the Organiser), you’ll see a button to locate the App Store copy for validation.
  • Simply click the button, navigate to the Texpad 1.4.7 (the app store version of Texpad) and select open.
  • The new version of Texpad will recognise that you own an app store purchase and respect that.
  • We advise that you make a backup of the app store copy in case it is needed in future.

If you see a “Validation Failed” error during this process , it usually means that you’ve changed computers since downloading the original App Store copy of Texpad. In such cases, please ensure that you re-download a fresh copy of the app from the App Store before repeating the above process as this associates the receipt with the current machine. Also note that the App Store downloads frequently break and is therefore advisable to make a backup of the app before deleting it in order to re-download.

News  ·   Blog  ·   About us  ·   Contact us
  Follow  ·     Tweet  ·     Like  ·     Tell a Friend
Valletta Ventures
Company  ·   Terms & Conditions  ·   Privacy & Security
© 2011-2017 Valletta Ventures (UK) Ltd. All rights reserved.