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.

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 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 "Description". The available LaTeX commands are defined in the templates.
Besides assigning LaTeX commands, one of the three default actions ("Delete Tags", "Delete Paragraphs" and "Don't touch") can also be assigned. "Delete Markers" will remove all markers from the documents, "Delete Paragraphs" will delete the marked paragraphs from the documents and "Don't touch" will leave the markers and paragraphs untouched.

Inline styles

The used text styles can be assigned one of the three actions "Delete Tags", "Delete Text" and "Don't touch" in the "Action" column. "Delete Tags" will remove all tags from the document, "Delete Text" will remove the marked passages including the markers from the document and "Don't touch" will leave the markers 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.

Marker styles

Markers can be assigned to the same text formattings or actions like the text 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.

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 empty, 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 "©" and "ACK". 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 use this option". 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".

Template Editor

The Template Editor can be used to create and to edit custom templates. To create a new template, click on "New...", to edit a template, click on "Edit...".
The 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 spaceholders will be filled with LaTeX commands upon export depending on the settings made. To make the settings work even with custom templates, the spaceholders should not be changed. If you do not care about the export options, you can remove the spaceholders safely.

Previews

In this section, preview images can be created. A description on how to create 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.

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

Inline and marker styles

In this last section, text formats are assigned to inline or marker styles. Similar to the paragraph styles, the name for the text format 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 or marked text style. The entry in the column "End" works in the same manner except that the text is inserted at the end of a tagged or marked text 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.
"Key to String in notes": This type uses the text, which is enclosed in the markers of the text 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 marker of the text style (to which the text format 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 marker of the text style. An example: the Ulysses document contains the text style ::key::, therefore the notes must contain ::key-text to be exported:: . Text formats of this kind can only be assigned text styles.
"Key to Graphic in notes": This type also uses the text, which is enclosed in the markers of the text style, as key for a link. The functionality is the same as in "Key for character in the notes", except that after the dash a image has to be inserted in the notes. Images, which are not in the PNG format will be converted to this format and saved in the target directory by the exporter. Again, only text styles can be assigned to this type.