## LaTeX

LaTeX is a software package which simplifies the typesetting with TeX using macros. The LaTeX Exporter can export Ulysses Projects to LaTeX files, i.e. text files with LaTeX markup, to typeset the Documents with TeX in a subsequent step. To process LaTeX files and convert them to PDF or DVI, a TeX distribution such as MacTeX is required. The LaTeX exporter is quite comprehensive and offers many options to customize the export.

### Export Mode

As already described in the section "Export Mode (Settings Common to all Exporters)", the LaTeX Exporter can export the Project Documents into one single file or in separate files. If the former is used, you can enter a filename in the textfield below (the default name is "Export.tex"). If the latter is used, an additional option, "Create main and include documents", is available. If this option is disabled, the LaTeX exporter will create separate TeX files including a preamble. Each of those files can be processed by TeX and is a product of its own. If the option is enabled, one additional file with a preamble will be created, which will then include each other file (that were created from every Document).

### Templates

The LaTeX document classes can be chosen from the templates. The templates for the following classes are already provided: "Book", "KOMA-Script Book" and "Memoir". Templates can contain secondary class and style files needed for the used document class. If one of these files should be missing in the TeX installation, they can be saved in the target directory using "Save class files, too". Furthermore, these templates also contain default export settings.
However, these settings will not automatically be used as the current settings. To do so, press "Use Settings from Template". It is also possible to create custom templates. This topic is covered in detail in the section "The Template Editor".

### Paper Setup, Type Area, and Text Setup

The settings of the following parameters, which are written in the LaTeX preamble as commands or options, affect the functioning of LaTeX.

Paper Setup: These parameters cover the final paper format (e.g., US Letter, A4, etc.), the binding (whether it should be there or not and how large it should be) and whether the typesetting should be one-sided or two-sided.

Type Area: The print space can either be left to LaTeX ("Automatic") or custom created. Chapters can start either only on the left side, only on the right side, or on both sides.

Text Setup: Depending on the chosen template, different font sizes are available. The selected font size is used for the body text; the sizes for the headings are adjusted proportionately.

The selected language should be the same as the text language of the Ulysses project. If the used language is not on the list, choose the option "Other…" and enter the according language option for the LaTeX package "babel" in the appearing sheet.
The option "Use numerations and prefixes" enables/disables the numbering of headings.
"Use medieval numbers" encloses every number in dollar characters (), thus LaTeX will typeset them as medieval numbers. The last two options enable/disable the optical margin alignment and the use of type1 fonts. ### Paragraph Styles LaTeX offers various commands to format paragraphs, e.g. as headings or as enumerations. The paragraph styles used in the project can be assigned to these commands in the column "Action". LaTeX commands can be added, removed, and edited in the template editor. Besides assigning LaTeX commands, one of the three default actions ("Delete Tags", "Delete Paragraphs" and "Don't touch") can also be assigned. "Delete Tags" will remove all tags from the Documents, "Delete Paragraphs" will delete the paragraphs from the Documents and "Don't touch" will leave the tags and paragraphs untouched. ### Inline Styles Just like the Paragraph Styles, Inline Styles can be assigned actions using the pop up menu in the "Action" column. The items at the top (e.g., "Bold", "Italic") correspond to their LaTeX commands and can be changed in the template editor. Additionally, the default actions "Delete Tags", "Delete Text" and "Don't touch" are also available. "Delete Tags" will remove all tags from the Document, "Delete Text" will remove the tagged passages including the tags from the Document and "Don't touch" will leave the tags and the text in between unchanged. Some of the LaTeX commands in the list can interpret the text in between start and end tags as key to a link to the notes. It is therefore possible to include footnotes and images in LaTeX files. This mechanism is covered in detail in the "Template Editor" section. ### Markers Markers can be assigned to the same text formatting or actions like the Paragraph and Inline Styles, except the action "Delete Tags", since markers can not be tagged. Instead, characters can be inserted at the start and the end of the marked passages by using the Action "Enclose in". The inserted characters are arbitrary, the start and the end characters can differ as well. If one wants to do so, the desired characters have to be entered after each other (start first, end second) and separated by " - " (space, dash, space), e.g. if "S" should be at the start of a marker and "E" at its end, "S - E" would have to be entered. ### Conversions In this section, quotation marks can be converted to different styles, ellipses can be automatically replace with "\ldots", and arbitrary characters can be replaced with other characters in the table "Convert Characters". ### Title Page If the option "Create title page" is enabled, LaTeX commands to insert a title page will be included upon export. The desired title should be entered in the text field of the same name. If this field is left blank, the Document title will be used. The author can also be entered in the field "Author". In the option for the date, the timestamp of the Document can be used as the date for the title page (using the option "Adopt from document"). ### Special Pages The option "Create copyright page" will insert the LaTeX commands for a copyright page, which will be placed after the title page (if the title page is enabled). The text for this page has to be entered in the fields "©" (copyright) and "ACK" (acknowledgements). These texts will be typeset at the bottom of the copyright page with a gap of 1 cm (0.4 in). If a table of contents is needed, the option "Create table of contents" can be enabled. Likewise, the option "Create backmatter" will create such a page at the end of the exported document. The field "Text" can be used for entering a text, which will then be typeset on a new empty page. ### Additional Options In this section settings of general nature can be made. "Document class": The options for the document class are set through the template and the settings in the other areas. In the text field "Document class" additional options can be entered or completely replaced using the options "Only these options". By pressing the button "Current options", the options given from the template and the other settings will be entered in the text field. "Mask characters": Some characters have a controlling function in LaTeX. To disable those functions, these characters have to be masked, i.e. a "\" (backslash) has to be put in front of each of these. Every character to be masked has to be entered in the text field. "Enclose '<' and '>' with ''": In LaTeX, angle brackets ("<" and ">") are considered mathematical symbols and therefore have to be enclosed in the dollar character.
"Insert empty lines between paragraphs": LaTeX distinguishes paragraphs by empty lines. If this option is enabled, empty lines will be inserted between paragraphs in the Ulysses Documents (if they are not already there).
"Add to preamble": Everything entered in this text field will be appended to the preamble, right before the LaTeX command \begin{document}. This way, custom document settings and commands can be supplied.
"Add to document": Likewise, everything entered in this text field will be will be inserted right after the LaTeX command \begin{document}.
"Encoding": The encoding for the exported LaTeX file(s) is set here. Available encodings are "UTF-8", "Applemac" and "ISO Latin 1".

### LaTeX Processing

This section enables automated post-processing. Whenever the export finishes successfully, LaTeX can be run (up to three times). You can set up some additional preferences like the command (such as pdflatex), and some command-line options.

### Template Editor

The Template Editor can be used to create and edit custom templates. To create a new template, click on "New…", to edit a template, click on "Edit…". Additionally, you can also create a copy of an existing template using "Duplicate…". Only custom templates can be edited and deleted. Whenever a new template is created, the default settings are already set so they only need to be adjusted to the personal preferences.
The Template Editor is divided in six sections, which are described below.

#### Preamble

A basic framework is provided for the text field of the preamble. Any LaTeX command that is syntactically correct for the preamble can be added to this framework. The placeholders will be filled with LaTeX commands upon export depending on the settings made. To make the settings work even with custom templates, the placeholders should not be changed. If you do not care about the export options, you can remove the placeholders safely. A full list of placeholders can be found in the appendix for this help page.

#### Previews

In this section, preview images can be inserted. A description on how to create and insert such images is shown on the left side. A text field is shown below the preview images. The text entered in this field will be displayed under the preview images for the double page. The name of the template creator can also be displayed by enclosing his or her name in "@". This name will then be used for displaying the standard text.

#### Class Files

In the section "Class files", LaTeX files like class definition files (.cls) or style files (.sty) can be added to the template. You can also simply drag & drop them into the table.

#### Possible Font Sizes

All available font sizes for the document class, which is based on the template, should be entered here. The font sizes have to be entered as they are stated as option of the document class.

#### Paragraph Style

The paragraph format can be defined here, which will then be assigned to the Paragraph Styles in the export settings. The name of the Paragraph Style action has to be entered in the column "Name". This name will then appear in the context menu. In the column "Start" the first part of the LaTeX command, which will be inserted at the start of a paragraph, should be entered. The same is also applicable for the "End" column, in which the LaTeX command, which will be inserted at the end of a paragraph, should be entered. To realize LaTeX environments, which span over multiply paragraphs (e.g., enumerations), the column "Before every" can be used. If the suitable LaTeX command is entered in this column, consecutive paragraphs with the same paragraph style will be combined. The text from the "Start" column will only be inserted before the first paragraph; the text from the "End" column will only be inserted after the last paragraph. However, the text in the column "Before every" will be still inserted before every paragraph. For instance, if a style for (unordered) enumerations is created, then \begin{itemize} should be at the start of each enumeration and is thus entered in the "Start" column. The "End" column should contain \end{itemize}. Finally, \item  should be inserted before every paragraph, thus it needs to be entered in the last column.

#### Inline Styles and Markers

In this last section, text formats are assigned to Inline Styles or Markers. Similar to the Paragraph Styles, the name for the style action has to be entered in the column "Name". The column "Start" has to contain the first part of the LaTeX command, which will inserted at the start of a tagged Inline Style. The entry in the column "End" works in the same manner except that the text is inserted at the end of a tagged Inline Style. The column "Type" contains the type for respective text format is defined in the column "Type", for which three types are available: "LaTeX command", "Key to String in Notes" and "Key to Graphic in Notes".
"LaTeX Command": This is the standard type and should be used for most of the LaTeX commands (such as \textbf, textit).
"Key to String in Notes": This type uses the text inside the Inline Style as key for a link to the Notes. Using this key, the exporter will look up the actual text, which will then be inserted between the text from the "Start" column and the text from the "End" column. The start tag of the Inline Style (to which the Style Action was assigned) has to stand in front of the key in the Notes. The end of the key is labeled with a dash ("-"). Following the dash comes the actual text, terminated by the end tag of the Inline Style. An example: the Ulysses Document contains the Inline Style ::key::, therefore the notes must contain ::key-text to be exported:: . Text formats of this kind can only be assigned Inline Styles.
"Key to Graphic in Notes": This type also uses the text inside the Inline Style as key for a link. The functionality is the same as in "Key to String in Notes", except that after the dash a image has to be inserted in the Notes. Images, which are not in the PNG format are converted to this format and saved in the target directory by the Exporter (except PDF files, which are written as PDF files to the target directory). Again, only Inline Styles can be assigned to this type. In contrast to "Key to String in Notes", you can also add a caption and the width for the image in the Notes. Add a dash after the image, then enter the width of the image, then another dash and then the caption. Thus, the format for Notes containing images is key-image-width-caption. Please note that the width parameter is optional. If you simply enter key-image-caption, the width will be set to 1\textwidth. In your custom Inline Styles, you can now use the following placeholders to insert these parameters: @label@, @size@, and @caption@ for the key, the width, and the caption, respectively.

#### Appendix: Preamble placeholders

A number of placeholders can be entered in the preamble of the Template Editor, which are replaced by their respective contents during export. Most of the placeholders always correspond to the individual settings of the Exporter, such as paper size.

Exporter SettingPlaceholderComment
General Placeholders
Document contents@document@
Current date@date@Shortcut for \date{…}
Page Setup
Paper size@paperSize@
Number of sides@xSided@
Binding@binding@
Type area
Required type area package@typearea@Shortcut for \usepackage[@binding@@ownFactor@]{typearea}
Own splitting factor@ownFactor@
Keep page margins@pageMargins@
Chapters begin@openChapter@
Text setup
Font size@fontSize@
Language@ownFactor@
Use numerations and prefixes@numbering@Shortcut for \setcounter{secnumdepth}{-1}
Use medieval numbers@maediaval@Shortcut for \everymath{\fam 1 }
Optical margin alignment (input)*@opticalAlignment1@Shortcut for \input protcode.tex
Optical margin alignemnt (configuration)*@opticalAlignment2@Shortcut for
 \setprotcode\font {\it \setprotcode\font} {\bf \setprotcode\font} {\bf\it \setprotcode\font}
Use type1 fonts@type1Fonts@Shortcut for \usepackage[T1]{fontenc}
Title page
Create title page@titlePage@Shortcut for
\title{@title@}\author{@author@}@date@\maketitle
Title@title@
Author@author@
Date@date@
Special pages
Acknowledgements (ACK)@ack@
Create table of contents@toc@Shortcut for \tableofcontents
Create backmatter@backmatter@
* Optical Margin Alignment is based on the work on Margin Kerning by Hàn Thé Thành. @opticalAlignment1@ needs to be inserted before \begin{document}, whereas @opticalAlignment2@ needs to be inserted right after \begin{document}. See this article for more information.