Your First Document

This tutorial assumes you already have a LaTeX distribution and a text editor installed. If that is not the case, follow the installation steps on the Downloads page.

The remainder of this tutorial presents examples in Texmaker. If you do not use Texmaker, don’t worry, just a few steps will be different!

As is mentioned on the downloads page, the LaTeX distribution comes with a couple of different TeX engines. To keep things simple, we’ll use pdfLaTeX in this tutorial which Texmaker is configured to use by default.

The Document

A LaTeX document is a plain text file consisting of text and routines as understood by the TeX compiler. This means you can use any plain text editor to write LaTeX documents, e.g. Texmaker, TeXStudio, Notepad, Wordpad, TextEdit, nano, vi, etc. The list is long!

As an example, the following snippet is a minimal LaTeX document that writes “Hello World!” in the top left corner of a paper.

\documentclass{article}
\usepackage[left=1cm,
            top=1cm,
            right=1cm,
            bottom=1cm]{geometry}
\begin{document}
Hello World!

\begin{equation}
  \sum \limits_{i = 0}^{N} a_i
\end{equation}
\end{document}

This snippet, as with all LaTeX documents, consists of two parts: a preamble and a document body. The preamble is the name of the content that is before the \begin{document}-line and is where all document-specific formatting is placed. For example, \documentclass{article}, includes settings from the article document class, e.g., page style, size of margins, font sizes of paragraphs and headings, definitions of useful routines and much more. Following the document class, you can include your own customisations and define your own commands and routines.

Preamble

Usually, someone else has already made the change you desire and instead of spending hours just to change the size of the margins, you can simply include the geometry-package and specify the (left, top, right and bottom) size in the unit you desire:

\usepackage[left=1cm,
            top=1cm,
            right=1cm,
            bottom=1cm]{geometry}

A LaTeX package is a black box of features and customisations that can be included in a LaTeX document. The geometry package is an example of a package that makes it easier to change page dimensions. However, the geometry package has much more under the hood than the snippet above shows.

Your LaTeX distribution comes with many packages by default and they are initially fetched from CTAN - Packages, an archive of thousands of packages that are freely available for anyone to use. On this website, the documentation for a specific package can also be found.

Commonly used packages include: float, biblatex, amsmath and cleveref. If you are interested, you can read about them in their documentation on CTAN.

A preamble can quickly grow with many packages and other customisations, and a cluttered LaTeX document is not what We want! That is where the role of a document class shines, which abstracts all the customisations and reduces them to a single line: \documentclass{article}. With that being said, many classes exist and if you want to make a poster, use the tikzposter class, or maybe you want to write a book, then use the memoir class. All of the different classes serve a specific purpose, but the most general, easiest and most simple class to use, is the article class.

The syntax of LaTeX consists of certain special characters as you might have noticed from the snippet above: \, { and }, [ and ] (sometimes). Apart from these, the following characters are also special: # (argument reference), & (alignment), % (comments), $, ^, and _. The first three are not covered in this tutorial.

  • \ (backslash): The backslash followed by a word is understood by the TeX compiler as a reference to a defined command (or control sequence). Thus, in the document example above, three commands are referenced/invoked: documentclass, usepackage, begin, sum, limits, and, end.
  • { and } (curly brackets): Curly brackets must written in pairs and everything inside this group can be thought of as an argument.
  • [ and ] (square brackets): Usually, when used in combination with a command, the meaning of the square brackets are optional arguments. documentclass accepts optional arguments, e.g., 12pt and a4paper to set the base font size to 12pt (points) and document dimensions for an A4 paper: \documentclass[12pt, a4paper]{article}. Note: the default paper format is configured during the installation of the LaTeX distribution. Optional arguments are also used in the package snippet where the margins are set when invoking the usepackage command for the geometry argument.

Document Body

All the properties included in the preamble, either specifically defined there or included by a package, becomes available in the body of the document. The body of the document is the content inside the document environment, started by the \begin{document} command, and ended by the \end{document} command. Everything within this document environment is output as text in the compiled document, or in the special case of commands, which first gets evaluated and then substituted by their returned value.

Environments isolate their content and may have special commands only available inside them. As an example, a powerful environment that makes LaTeX so great, is the math environment (also referred to as math-mode) which typesets mathematical expressions differently from normal text and enables shorthand versions of sub- and super-script as _ and ^. These two operators only affect the following character, except in the situation where the character is a { which then starts a group of characters that must be ended with a }. The grouped characters inside these brackets will all be affected by the operator. One way to think of it, is to perceive _{input} as a function that takes the argument input.

Since the math environment is used often, shorthand versions of \begin{math} and \end{math} are defined as a pair of the special character, $: $\pi = 3.14$. This simple way of writing mathematical expressions should be used for inline math. That is, when you want to introduce math inside a paragraph.

By using double dollar signs, $$\pi = 3.14$$, the expression is centered on its own line.

The above usage of the shorthand versions of the math environment are specific to TeX syntax. While they work for LaTeX, the revised LaTeX way of doing it, is by using \( and \) for inline math, and \[ and \] for display math. The use of brackets are much more convenient and errors are much easier to spot.

The following snippet covers these shorthand operators. It compiles into a discrete sum (\sum \limits) of length N (^{N}) with i initialised to 0 (_{i = 0}) and it is centered on the page (\[ and \]). The \limits command simply moves the sub- and superscript to below and above the summation symbol. Leaving it out will preserve the normal behaviour which is rarely desired for sums (e.g. in-line sums).

\[
  \sum \limits_{i = 0}^{N} a_i
\]

Often you want to reference an equation in your text. While the display math usage (as the snippet above) doesn’t tie a number to the math expression, the equation environment does! The snippet can be rewritten as the following which will label the equation as (1).

\begin{equation}
  \sum \limits_{i = 0}^{N} a_i
\end{equation}

This is just a brief sneak-peak to references and labels in LaTeX! To keep this tutorial at the basics, let’s skip ahead and compile the document.

Compiling The Document

In Texmaker, go to File -> New and paste the example from the beginning of this tutorial into the text field. Save the file somewhere, perhaps your desktop. In the top toolbar of Texmaker there are two arrows as illustrated on the following image.

Texmaker's compile toolbar Texmaker’s compile toolbar

These are buttons which will perform the action that is selected in the dropdown menu. By default, the left one performs a Quick Build and the right one updates the PDF viewer. Texmaker has a built-in PDF viewer which you can have side-by-side with your LaTeX document so you don’t have to switch forth and back between windows to see your changes. The other options in the right dropdown are not important since you will only compile your document into a PDF (that is, by using pdfLaTeX).

“What does Quick Build do?” you might wonder. It’s a combination of programs that are executed in sequence when you click the arrow. If you browse the configuration in Texmaker (Options -> Configure Texmaker), you can find the following under the Quick Build-pane.

Texmaker's Quick Build options Texmaker’s Quick Build options

Texmaker is simply a text editor that interfaces with the LaTeX distribution on your system. Thus, Texmaker executes the programs as specified by the selected Quick Build option that are provided by the LaTeX distribution. Texmaker cannot execute these programs if they aren’t installed, meaning you must have a LaTeX distribution available on your system.

The default Quick Build setup is sufficient for regular documents, but once you start to include bibliography, label references, nomenclature, etc., multiple files have to be processed over several steps. By using Quick Build, you don’t have to think about doing these steps manually and, instead, you just click the arrow-button and wait for the program sequence to terminate.

With the default Quick Build setting, Texmaker will run pdfLaTeX followed by updating the PDF viewer on the right hand side.

If you now click the left arrow in the compile toolbar, you shall see your first LaTeX compiled PDF document in the PDF viewer, which will look like the following (cropped to fit here):

Compiled PDF document Compiled PDF document

Murphy’s Law

Murphy’s Law also applies for LaTeX, unfortunately. While you won’t expect it, errors will happen often and they will, as a whole, be your new worst enemy which you will have to learn to beat. The LaTeX syntax is very strict and the smallest mistake can make your document uncompilable – which is horrible because you have to turn in your report in less than an hour!

We have collected and documented several errors that occur frequently in the Troubleshooting Warnings and Errors tutorial, which you might find useful to avoid said situation.

Next Steps

This tutorial walked through the process of creating a simple LaTeX document and compiling it to a PDF document with the pdfLaTeX compiler. The LaTeX distribution that you use comes with other compilers than just pdfLaTeX. If you are interested in learning more about these other compilers, you can read more about them in the TeX Compilers tutorial.

Apart from mathematical equations and expressions, figures and tables are often necessities to make a report complete. These, along with the so-called float behaviour of LaTeX, are covered in the Figures, Tables and Floats tutorial.