LaTeX/Basics

This tutorial is aimed at getting familiar with the bare bones of LaTeX.

Before starting, ensure you have LaTeX installed on your computer (see Installation for instructions of what you will need).

• We will first have a look at the LaTeX syntax.
• We will create our first LaTeX document.
• Then we will take you through how to feed this file through the LaTeX system to produce quality output, such as postscript or PDF.
• Finally we will have a look at the file names and types.

The LaTeX syntax

When using LaTeX, you write a plain text file which describes the document's structure and presentation. LaTeX converts this source text, combined with markup, into a typeset document. For the purpose of analogy, web pages work in a similar way: HTML is used to describe the document, which is then rendered into on-screen output - with different colours, fonts, sizes, etc. - by your browser.

You can create an input file for LaTeX with any text editor. A minimal example looks something like the following (the commands will be explained later):

\documentclass{article} \begin{document} Hello world! \end{document}

Spaces

LaTeX normalises spaces in its input files so that whitespace characters, such as a space or a tab, are treated uniformly as space. Several consecutive spaces are treated as one, space opening a line is generally ignored, and a single line break also yields space. More line breaks (empty lines) define the end of a paragraph. An example of applying these rules is presented below: the left-hand side shows the user's input (.tex), while the right-hand side depicts the rendered output (.dvi, .pdf, .ps).

It does not matter whether you enter one or several spaces after a word. An empty line starts a new paragraph.

It does not matter whether you enter one or several spaces after a word. An empty line starts a new paragraph.

Reserved Characters

The following symbols are reserved characters that either have a special meaning under LaTeX or are unavailable in all the fonts. If you enter them directly in your text, they will normally not print but rather make LaTeX do things you did not intend.

# $ % ^ & _ { } ~ \

As you will see, these characters can be used in your documents all the same by adding a prefix backslash:

\# \$ \% \^{} \& \_ \{ \} \~{} \textbackslash{}

In some circumstances, the square bracket characters [ ] can also be considered as reserved characters, as they are used to give optional parameters to some commands. If you want to print these directly after some command, like in this situation: \command [text] it will fail, as [text] will be considered as an option given to \command. You can achieve the correct output this way: \command {} [text].

The backslash character \ cannot be entered by adding another backslash in front of it, like so \\; this sequence is used for line breaking. For introducing a backslash in math mode, you can use \backslash instead.

The commands \~ and \^ produce respectively a tilde and a hat which is placed over the next letter. For example \~n gives ñ. That's why you need braces to specify there is no letter as argument. You can also use \textasciitilde and \textasciicircum to enter these characters; or other commands .

If you want to insert text that might contain several particular symbols (such as URIs), you can consider using the \verb command, which will be discussed later in the section on formatting. For source code, see Source Code Listings

The less-than < and greater-than > characters are the only visible ASCII characters (not reserved) that will not print correctly. See Special Characters for an explanation and a workaround.

Non-ASCII characters (e.g. accents, diacritics) can be typed in directly for most cases. However you must configure the document appropriately. The other symbols and many more can be printed with special commands as in mathematical formulae or as accents. We will tackle this issue in Special Characters.

LaTeX groups

Sometimes a certain state should be kept local, in other words its scope should be limited. This can be done by enclosing the part to be changed locally in curly braces. In certain occasions, using braces won't be possible. LaTeX provides \bgroup and \egroup to begin and end a group, respectively.

\documentclass{article} \begin{document} normal text {\itshape walzing \bfseries Wombat} more normal text normal text \bgroup\itshape walzing \bfseries Wombat\egroup{} more normal text \end{document}

Environments form an implicit group.

LaTeX environments

Environments in LaTeX have a role that is quite similar to commands, but they usually have effect on a wider part of the document. Their syntax is:

\begin{environmentname} text to be influenced \end{environmentname}

Between the \begin and the \end you can put other commands and nested environments. The internal mechanism of environments defines a group, which makes its usage safe (no influence on the other parts of the document). In general, environments can accept arguments as well, but this feature is not commonly used and so it will be discussed in more advanced parts of the document.

Anything in LaTeX can be expressed in terms of commands and environments.

LaTeX commands

LaTeX commands are case sensitive, and take one of the following two formats:

1. They start with a backslash \ and then have a name consisting of letters only.
   • Command names are terminated by a space, a number or any other non-letter.
2. They consist of a backslash \ and exactly one non-letter.
   • Command names are terminated after that one non-letter.

Some commands need an argument, which has to be given between curly braces { } after the command name. Some commands support optional parameters, which are added after the command name in square brackets [ ]. The general syntax is:

\commandname[option1,option2,...]{argument1}{argument2}...

Many LaTeX formatting commands come in pairs.

1. An argument form command, where one of the arguments is the text to be formatted.
2. A scope form command, where the formatting will be applied to all text after the command until the end of the current scope. That is, until the end of the current group or environment. This form may also be called a switch command. A scope form command might still have arguments, but the text to be formatted is not an argument. This form should almost never be called outside of any scope, otherwise it will apply on the rest of the document.

An argument form command will have one argument more than its corresponding scope form command, the extra argument being the text the command affects.

Examples:

Emphasing text: \emph is an argument form command with one argument, the text to be emphasised. \em is the corresponding scope form command with no arguments.

\emph{emphasized text}, this part is normal % Correct. {\em emphasized text}, this part is normal % Correct. \emph emphasized text, this part is normal % Incorrect: command without argument. \em{emphasized text}, this part is normal % Incorrect: switch with argument. \em emphasized text, this part is normal % Dangerous: switch outside of any environment.

Coloring text: This example requires you to \usepackage{xcolor}. \textcolor is an argument form command with two arguments, the color and the text to be colored. \color is the corresponding scope form command with only one argument, the color.

By default, this text is black. \textcolor{red}{This is red text.} Back to black. By default, this text is black. {\color{red}This is red text.} Back to black.

Comments

When LaTeX encounters a % character while processing an input file, it ignores the rest of the current line, the line break, and all whitespace at the beginning of the next line.

This can be used to write notes into the input file, which will not show up in the printed version.

This is an % stupid % Better: instructive <---- example: Supercal% ifragilist% icexpialidocious

This is an example: Supercalifragilisticexpialidocious

Note that the % character can be used to split long input lines that do not allow whitespace or line breaks, as with Supercalifragilisticexpialidocious above.

The core LaTeX language does not have a predefined syntax for commenting out regions spanning multiple lines. Refer to multiline comments for simple workarounds.

Our first document

Now we can create our first document. We will produce the absolute bare minimum that is needed in order to get some output; the well known Hello World! approach will be suitable here.

• Open your favorite text-editor. vim, emacs, Notepad++, and other text editors will have syntax highlighting that will help to write your files.
• Reproduce the following text in your editor. This is the LaTeX source.

% hello.tex - Our first LaTeX example! \documentclass{article} \begin{document} Hello World! \end{document}

• Save your file as hello.tex.

When picking a name for your file, make sure it bears a .tex extension.

What does it all mean?

% hello.tex - Our first LaTeX example!	The first line is a comment. This is because it begins with the percent symbol (%); when LaTeX sees this, it simply ignores the rest of the line. Comments are useful for people to annotate parts of the source file. For example, you could put information about the author and the date, or whatever you wish.
\documentclass{article}	This line is a command and tells LaTeX to use the article document class. A document class file defines the formatting standard to follow, which in this case is the generic article format. Journals, university departments, etc. can provide these files to ensure publication standards are met. In many instances, the same document content can be reformatted for submission to a different publisher simply by substituting the required document class file. There are numerous generic document classes available to choose from if one is not provided.
\begin{document}	This line is the beginning of the environment called document; it alerts LaTeX that content of the document is about to commence. Anything above this command is known generally to belong in the preamble.
Hello World!	This was the only actual line containing real content - the text that we wanted displayed on the page.
\end{document}	The document environment ends here. It tells LaTeX that the document source is complete, anything after this line will be ignored.

As we have said before, each of the LaTeX commands begins with a backslash (\). This is LaTeX's way of knowing that whenever it sees a backslash, to expect some commands. Comments are not classed as a command, since all they tell LaTeX is to ignore the line. Comments never affect the output of the document, provided there is no white space before the percent sign.

Building a document

We then feed our input file into a LaTeX engine, a program which generates our final document.

There are several LaTeX engines in modern use: lualatex, xelatex, and pdflatex. There are important differences between the three, but we'll discuss those elsewhere - any of them will work for building our first document.

Generating the document

LaTeX itself does not have a GUI, though some LaTeX installations feature a graphical front-end where you can click LaTeX into compiling your input file. Assuming you're not using one of those:

1. Open a terminal and navigate to the directory containing your .tex file.
2. Type the command: xelatex hello.tex (The .tex extension is not required, although you can include it if you wish.)
3. Various bits of info about LaTeX and its progress will be displayed. If all went well, the last two lines displayed in the console will be:

Output written on hello.pdf (1 page).
Transcript written on hello.log.

This means that your source file has been processed and the resulting document is called hello.pdf. You can view it with any PDF viewer installed on your system.

In this instance, due to the simplicity of the file, you only need to run the LaTeX command once. However, if you begin to create complex documents, including bibliographies and cross-references, etc., LaTeX needs to be executed multiple times to resolve the references. This will be discussed in the future when it comes up.

Autobuild Systems

Compiling can be quite tricky as soon as you start working on more complex documents. A number of programs exist to automatically read in a LaTeX document and run the appropriate compilers the appropriate number of times. For example, latexmk can generate a PDF from most LaTeX files simply:

$ latexmk -pdf file.tex

Note that most editors will take care of it for you.

Historical versions of LaTeX

Both LaTeX and TeX were created many years before the Portable Document Format (PDF) existed, so the plain LaTeX engine, latex, emits DVI, a format designed by Donald Knuth for device-independent TeX output. This format has fallen out of general use, but can be converted into more common output formats using programs from your LaTeX distribution:

• dvips converts .dvi files to .ps (PostScript).
• dvipdf converts .dvi files to .pdf (dvipdfm is an improved version).

You might also find Ghostscript, a set of free and open-source tools for working with PostScript, useful. Its ps2pdf converts .ps files to .pdf, and pdf2ps does the reverse.

The following diagram shows the relationships between the LaTeX source code and the formats you can create from it:

The boxed red text represents the file formats, the blue text on the arrows represents the commands you have to use, the small dark green text under the boxes represents the image formats that are supported. Any time you pass through an arrow you lose some information, which might decrease the features of your document. Therefore, you should choose the shortest route to reach your target format. This is probably the most convenient way to obtain an output in your desired format anyway. Starting from a LaTeX source, the best way is to use only latex for a DVI output, or only pdflatex for a PDF output, converting to PostScript only when it is necessary to print the document.

Note that using latex to generate DVI output keeps you from using PDF-only features, such as hyperlinks and embedded fonts.

Chapter Export To Other Formats discusses more about exporting LaTeX source to other file formats.

Files

Picking suitable filenames

Never, ever use directories (folders) or file names that contain spaces. Although your operating system probably supports them, some don't, and they will only cause grief and tears with TeX. Make filenames as short or as long as you wish, but strictly avoid spaces. Stick to lower-case letters without accents a-z, the digits 0-9, the hyphen (-), and only one full point or period (.) to separate the file extension (somewhat similar to the conventions for a good Web URL): it will let you refer to TeX files over the Web more easily and make your files more portable. Some operating systems do not distinguish between upper-case and lower-case letters, others do. Therefore it's best not to mix them.

Ancillary files

The TeX compilers are single-pass processes. It means that there is no way for a compiler to jump around the document, which would be useful for the table of contents and references. Indeed the compiler cannot guess at which page a specific section is going to be printed, so when the table of contents is printed before the upcoming sections, it cannot set the page numbers.

To circumvent this issue, many LaTeX commands which need to jump use ancillary files which usually have the same file name as the current document but a different extension. It stores temporary data into these files and use them for the next compilation. So to have an up-to-date table of contents, you need to compile the document twice. There is no need to re-compile if no section moved.

For example, the temporary file for the table of contents data is filename.toc.

None of these files contains unrecoverable information. It means you can delete them safely, compiling will regenerate them automatically.

When you work with various capabilities of LaTeX (index, glossaries, bibliographies, etc.) you will soon find yourself in a maze of files with various extensions and probably no clue. The following list explains the most common file types you might encounter when working with TeX:

Common file extensions in LaTeX

.aux	A file that transports information from one compiler run to the next. Among other things, the .aux file is used to store information associated with cross-references.
.bbl	Bibliography file output by BiBTeX and used by LaTeX
.bib	Bibliography database file. (where you can store a list of full bibliographic citations)
.blg	BiBTeX log file. (errors are logged here)
.bst	BiBTeX style file.
.cls	Class files define what your document looks like. They are selected with the \documentclass command.
.dtx	Documented TeX. This is the main distribution format for LaTeX style files. If you process a .dtx file you get documented macro code of the LaTeX package contained in the .dtx file.
.ins	The installer for the files contained in the matching .dtx file. If you download a LaTeX package from the net, you will normally get a .dtx and a .ins file. Run LaTeX on the .ins file to unpack the .dtx file.
.fd	Font description file telling LaTeX about new fonts.
.dvi	Device Independent File. This is the main result of a LaTeX compile run with latex. You can look at its content with a DVI previewer program or you can send it to a printer with dvips or a similar application.
.pdf	Portable Document Format. This is the main result of a LaTeX compile run with pdflatex. You can look at its content or print it with any PDF viewer.
.log	Gives a detailed account of what happened during the last compiler run.
.toc	Stores all your section headers. It gets read in for the next compiler run and is used to produce the table of contents.
.lof	This is like .toc but for the list of figures.
.lot	And again the same for the list of tables.
.idx	If your document contains an index. LaTeX stores all the words that go into the index in this file. Process this file with makeindex.
.ind	The processed .idx file, ready for inclusion into your document on the next compile cycle.
.ilg	Logfile telling what makeindex did.
.sty	LaTeX Macro package. This is a file you can load into your LaTeX document using the \usepackage command.
.tex	LaTeX or TeX input file. It can be compiled with latex.
.out	hyperref package file, just one for the master file.

And what now?

Common Elements

See Document Structure and the Common Elements part for all the common features that belong to every type of document.

Non-English documents and special characters

LaTeX has some nice features for most languages in the world. You can tell LaTeX to follow typography rules of the target language, ease special characters input, and so on. See Special Characters and Internationalization.

Modular document

See Modular Documents for good recommendations about the way to organize big projects into multiple files.

Questions and Issues

We highly urge you to read the FAQ if you have issues about basic features, or if you want to read essential recommendations. For the more specific questions and issues, refer to the Tips and Tricks page.

Macros for the utmost efficiency

The full power of LaTeX resides in macros. They make your documents very dynamic and flexible. See the dedicated part.

Working in a team

See chapter Collaborative Writing of LaTeX Documents.