# LaTeX/Basics

LaTeX

Getting Started

Common Elements

Mechanics

Technical Texts

Special Pages

Special Documents

Creating Graphics

Programming

Miscellaneous

Help and Recommendations

Appendices

edit this boxedit the TOC

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

LaTeX uses a markup language in order to describe document structure and presentation. LaTeX converts your source text, combined with the markup, into a high quality document. For the purpose of analogy, web pages work in a similar way: the HTML is used to describe the document, but it is your browser that presents it in its full glory - with different colours, fonts, sizes, etc.

The input for LaTeX is a plain text file. You can create it with any text editor. It contains the text of the document, as well as the commands that tell LaTeX how to typeset the text.

A minimal example looks something like the following (the commands will be explained later):

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

### Spaces

The LaTeX compiler normalises whitespace so that whitespace characters, such as [space] or [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”. A double line break (an empty line), however, defines the end of a paragraph; multiple empty lines are also treated as 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{} 

The backslash character \ cannot be entered by adding another backslash in front of it (\\); 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 shall be kept local, i.e. limiting its scope. 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:

• 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".
• They consist of a backslash \ and exactly 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}... 

Most standard LaTeX commands have a switch equivalent. Switches have no arguments but apply on the rest of the scope, i.e. the current group or environment. A switch should (almost) never be called outside of any scope, otherwise it will apply on the rest of the document.

Example:

 % \emph is a command with argument, \em is a switch. \emph{emphasized text}, this part is normal % Correct {\em emphasized text}, this part is normal % Correct \em emphasized text, this part is normal % Incorrect \em{emphasized text}, this part is normal % Incorrect 

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, which in this case is a generic article format. The handy thing is that if you want to change the appearance of your document, substitute article for another class file that exists. \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.

## Compilation

### Compilation process

The general concept is to transform a plain text document into a publishable format, mostly a DVI, PS or PDF file. This process is called compilation, which is done by an executable file called a compiler.

There are two main compilers.

• tex compiler reads a TeX .tex file and creates a .dvi.
• pdftex compiler reads a TeX .tex file and creates a .pdf.

These compilers are basically used to compile Plain TeX, not LaTeX. There is no such LaTeX compiler since LaTeX is just a bunch of macros for TeX. However, there are two executables related to the previous compilers:

• latex executable calls tex with LaTeX initialization files, reads a LaTeX .tex file and creates a .dvi
• pdflatex executable calls pdftex with LaTeX initialization files, reads a LaTeX .tex file and creates a .pdf

If you compile a Plain TeX document with a LaTeX compiler (such as pdflatex) it will work while the opposite is not true: if you try to compile a LaTeX source with a TeX compiler you will get many errors.

As a matter of fact, following your operating system latex and pdflatex are simple scripts or symbolic links.

Most of the programs should be already within your LaTeX distribution; the others come with Ghostscript, which is a free and multi-platform software as well. Here are common programs you expect to find in any LaTeX distribution:

• dvi2ps converts the .dvi file to .ps (postscript).
• dvi2pdf converts the .dvi file to .pdf (dvi2pdfm is an improved version).

and with Ghostscript:

• ps2pdf and pdf2ps converts the .ps file to .pdf and vice-versa.

When LaTeX was created, the only format it could create was DVI; later PDF support was added by pdflatex. PDF files can be created with both pdflatex and dvipdfm. The output of pdflatex takes direct advantage of modern features of PDF such as hyperlinks and embedded fonts, which are not part of DVI. Passing through DVI imposes limitations of its older format. On the other hand, some packages, such as PSTricks, exploit the process of conversion to DVI, and therefore will not work with pdflatex. Some of those packages embed information in the DVI that doesn't appear when the DVI is viewed, but reemerges when the DVI is converted to another, newer format.

You would write your document slightly differently depending on the compiler you are using (latex or pdflatex). But as we will see later it is possible to add a sort of abstraction layer to hide the details of which compiler you're using, while the compiler can handle the translation itself.

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 pdflatex for a PDF output, converting to PostScript only when it is necessary to print the document.

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

### Generating the document

It is clearly not going to be the most exciting document you have ever seen, but we want to see it nonetheless. I am assuming that you are at a command prompt, already in the directory where hello.tex is stored. LaTeX itself does not have a GUI (graphical user interface), since it is just a program that crunches away at your input files, and produces either a DVI or PDF file. Some LaTeX installations feature a graphical front-end where you can click LaTeX into compiling your input file. On other systems there might be some typing involved, so here is how to coax LaTeX into compiling your input file on a text based system. Please note: this description assumes that you already have a working LaTeX installation on your computer.

1. Type the command: latex hello (the .tex extension is not required, although you can include it if you wish)
2. 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.dvi (1 page, 232 bytes).
Transcript written on hello.log.


This means that your source file has been processed and the resulting document is called hello.dvi, which takes up 1 page and 232 bytes of space. Now you may view the DVI file. On Unix with X11 you can type xdvi foo.dvi, on Windows you can use a program called yap (yet another previewer). (Now evince and okular, the standard document viewers for many Linux distributions are able to view DVI files.)

This way you created the DVI file, but with the same source file you can create a PDF document. The steps are exactly the same as before, but you have to replace the command latex with pdflatex:

1. Type the command: pdflatex hello (as before, the .tex extension is not required)
2. 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, 5548 bytes).
Transcript written on hello.log.


you can notice that the PDF document is bigger than the DVI, even if it contains exactly the same information. The main differences between the DVI and PDF formats are:

• DVI needs less disk space and it is faster to create. It does not include the fonts within the document, so if you want the document to be viewed properly on another computer, there must be all the necessary fonts installed. It does not support any interactivity such as hyperlinks or animated images. DVI viewers are not very common, so you can consider using it for previewing your document while typesetting.
• PDF needs more disk space and it is slower to create, but it includes all the necessary fonts within the document, so you will not have any problem of portability. It supports internal and external hyperlinks. It also supports advanced typographic features: hanging punctuation, font expansion and margin kerning resulting in more flexibility available to the TeX engine and better looking output. Nowadays it is the de facto standard for sharing and publishing documents, so you can consider using it for the final version of your document.

About now, you saw you can create both DVI and PDF document from the same source. This is true, but it gets a bit more complicated if you want to introduce images or links. This will be explained in detail in the next chapters, but for now assume you can compile in both DVI and PDF without any problem.

Note, 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. But this will be discussed in the future when it comes up.

### Autobuild Systems

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



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

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:

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