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. These tabs may have different editor and PDF location, 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.

TypesetPressing 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 ChainA brief description of the current typeset chain along with a dropdown arrow that opens the full typeset configuration.
ShareA dropdown view with options for emailing or exporting your project contents.
OutlineShows/Hides the Outline View to the left of the editor pane.
ViewPressing the view buttons will change the arrangement of the editor between Editor only, Editor and Output, and Output only respectively.
IssuesA dropdown view for outstanding errors in your source code along with the full typeset log.
Search fieldSearch box for finding and replacing text across all the files in the project.
Backward/Forward ArrowsJump 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 egin{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 ef,\cite and egin families of commands, and autocompleting custom commands and environments defined via ewcommand and ewenvironment 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{}, ef{} and egin{}, 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, ibitems and .bib file entries. If you type one of the ef{ family of commands Texpad will offer all known labels as possible completions.

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

Automatching blocks

If you insert a egin{ 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

egin{some environment}

This behaviour can be enabled or disabled with the Automatch egin 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. egin{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. rac{numerator}{denominator}

(c) 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{}, ef{} 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 =
egin{itemize}
  \item <SELECTION>
\end{itemize}

Hotkeys: Key combinations associated with snippets

Keys understood by Texpad are

ctrl keyThe value must be a single character. It is the key that when pressed with the control key is the hotkey for this snippet.
groupThe name of the group that this should be displayed in
insert at cursorThe 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'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 egin{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 ef,\cite and egin families of commands, and autocompleting custom commands and environments defined via ewcommand and ewenvironment 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{}, ef{} and egin{}, 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, ibitems and .bib file entries. If you type one of the ef{ family of commands Texpad will offer all known labels as possible completions.

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

Automatching blocks

If you insert a egin{ 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

egin{some environment}

This behaviour can be enabled or disabled with the Automatch egin 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. egin{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. rac{numerator}{denominator}

(c) 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{}, ef{} 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 =
egin{itemize}
  \item <SELECTION>
\end{itemize}

Hotkeys: Key combinations associated with snippets

Keys understood by Texpad are

ctrl keyThe value must be a single character. It is the key that when pressed with the control key is the hotkey for this snippet.
groupThe 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.||-pdf-sync