AdaLovelaceDay/2012/LaTeX with Kile

My name is Melissa and I'm a mathematics professor at the Federal University of Santa Catarina in Florianópolis, southern Brazil. As a mathematician, I deal with LaTeX on a daily basis (all my course notes are written in LaTeX, as well as all of my articles, exercises for my students and well, shopping lists! :)

In this tutorial, it would be impossible to talk about all that LaTeX has to offer, as it is an extremely powerful and complete text processing tool, with capabilities including vector graphics generation, music sheet writing, generation of braille texts, crossword puzzle formatting, etc. We will focus instead on how to use LaTeX with Kile, which is a great LaTeX editor.

If you want to follow this tutorial "interactively", I would like to start by asking you all to install Kile, if you don't have it already installed. Installing Kile should also install texlive-core and texlive-bin (maybe that's called different in a different distro, I'm using chakra) but that should be all we need for basic LaTeX document generation.

While you are setting up your environments, I'll briefly explain what LaTeX is, and why it is useful.

An Introduction to LaTeX

LaTeX is not a text editor. It was developed in the 80's by Leslie Lamport to be a set of macros for TeX, a typography system developed in the 70's by Donald Knuth. The basic idead of TeX was to popularize good typography (mainly in academia), and to provide a text processing system that would always generate the same result in any computer. However, TeX turns out to be fairly complicated, and Leslie Lamport began an effort in the 80's to generate some high-level macros in order to make it simpler to use. You can think of LaTeX as a markup language (something like HTML), although it is much more than that. The basic idea of TeX and LaTeX is to separate the form and the contents of a document. The resulting document file is usually a PDF file.

In order to write a document with LaTeX, you usually need to follow a workflow such as: - Write your contents and formatting commands in a text file, using the editor of your choice, and saving this file using the ".tex" file extension; - Compile your document, using one of the available commands (in our case, "pdflatex"); - View the result in a document viewer (in our case, okular). This means you don't see the actual result of the document you're creating as you type; first, you type in the commands, and then you see the result after you run pdflatex on your source .tex file.

Fortunately for us, Kile greatly simplifies this process. So in order to show you a simple example, I would like you all to point your browsers at http://www.mtm.ufsc.br/~melissa/files.html and download firstexample.tex

Save it, and open it in Kile. For this, you should launch Kile, and then go to File -> Open, select firstexample.tex, and click OK.

firstexample.tex

If you see a message saying "The standard tool list need to be reloaded because of the switch from KDE3 to KDE4. (...)", don't worry. It is safe to click "Yes" and ignore that message. You will also see the "Did you know...?" dialog, which can be dismissed if you click on "Close".

Now you should see a text file, with a bunch of "\command{argument}" statements. Those are all LaTeX commands, and we will see what each of them means in a moment. For now, let's see what this generates after we compile it.

To compile a .tex file into a PDF, we will use the PDFLaTeX command. In the Kile menu, you can see some standard toolbar buttons ("New", "Open", "Close", "Save", "Save As", "Undo" and "Redo"), and the next options are probably unfamiliar. Check the next option right after Redo. It should read PDFLaTeX. If it doesn't, click on the down-arrow to the right of it and select this PDFLaTeX option. Then click on it.

Compiling with PDFLaTeX

You can now see some action has taken place at the bottom panel. It says something like "[PDFLaTeX] firstexample.tex => firstexample.pdf (pdflatex)", and it should say also that we have no errors or warnings.

Compilation result.

Now we have compiled our LaTeX file. All we need to do to check how this pdf looks like is to click the "ViewPDF" option on the menu right next to the PDFLaTeX button. Right now you are probably seeing "ViewHTML"; don't worry. Just click on the down-arrow to the right of this option and select "ViewPDF".

Viewing the resulting PDF file.

Now, you should see an okular (or your default PDF viewer) window with our compiled file. Congratulations! That is your first (probably) LaTeX document :)

Now might be a good time to take a look at the source document (the .tex file in Kile) and the PDF output to see how this works. You can see that I have included no commands for indenting, fonts, nothing. These are all the standard LaTeX options and are chosen automatically.

If you want, you can also play around a little with the left panel on Kile and see that it has some shortcuts to LaTeX commands, but we'll check that later.

First Simple Document

What you can see in this document is the basic LaTeX structure. First, you have a \documentclass{article} line; this will always be the first line in any of your LaTeX documents. It tells the LaTeX compiler that we have a document which will look like an article.

The \documentclass command.

Let's try and change that "article" to "report" and compile it again, to see what happens. Just change \documentclass{article} to \documentclass{report}, save it, click on PDFLaTeX, and check your okular window (it should refresh automatically everytime you compile your document inside kile).

Choosing the report document class.

So now you should see a document with a cover page, and the contents on the second page are numbered differently from before! What happened? First, you had "1. Algorithms and Convergence". Now you have "01. Algorithms and Convergence", right?

LaTeX does automatic numbering of sections, chapters, subsections, equations, etc... The document classes each have a different definition: Articles don't have chapters, only sections, subsections, subsubsections and paragraphs. But reports do have chapters: that's why we had a section numbered 0.1 in our pdf file. We never defined a chapter, so this is chapter 0.

Try changing the line \section{Algorithms and Convergence} to \chapter{Algorithms and Convergence}. Save your file, click on PDFLaTex, and check the result in okular.

Automatic numbering of chapters/sections.

Pretty cool, huh? :) This is what I meant earlier when I said LaTeX separates form and content: the author doesn't have to worry about alignments, margins, font sizes and numbering. LaTeX does it all for you, automatically. Of course, if you are a "power user" and like to customize things, there is always a way, but we will focus on the default parameters for now.

Next in this document is a \usepackage{amsmath} line. This is how we include new sets of macros into a LaTeX document. Not every document is a mathematical document of course, and so this is not included in the article or report document class. The package I'm adding gives me new mathematical equation options.

There are literally hundreds (if not thousands) of LaTeX packages, each dedicated to a special document type. (If you are used to programming in python, for example, these are your modules)

Since this source file is just like a programming source file, we should be able to comment it. So just put a % symbol before the \usepackage{amsmath} line. Save your document, click on PDFLaTeX, and check the bottom panel on kile.

Commenting out a line.

Now you can see a lot of errors! The LaTeX compiler is telling us we did something wrong.

\usepackage error

Of course, I'm using the amsmath macros (commands) without telling the compiler beforehand. In this case, I'm using the \begin{equation} - \end{equation} commands. Let's fix it by removing the comment symbol % from the \usepackage line and compiling it again (don't forget to save your document).

Next, you can see the \title and \author commands (which are pretty self explanatory). Change that to your preference if you want, add your name, save your file, recompile it and see what happens. (just avoid using special characters for now!)

If you do want to include special characters, you should add a package to allow you to do that without much effort. So if you want, you can add a line that says \usepackage[utf8]{inputenc} right after the \usepackage{amsmath} line. Now, you have something like:

 \documentclass{report}
 \usepackage{amsmath}
 \usepackage[utf8]{inputenc}

This new command is a little different because is has 2 arguments: First, you have a [utf8] argument, with square brackets. Then you have the {inputenc} argument, with curly braces.

What this means is that inputenc is the package you are adding (this is the mandatory argument of the \usepackage command) and utf8 is just an option for that package ([utf8] is the optional argument for the \usepackage command). Optional arguments are always surrounded by square brackets, and mandatory arguments are always surrounded by curly braces.

This part of the file, from the \documentclass to just before the \begin{document} commands is called a preamble. This is usually where you keep your macro definitions, just like we have just done.

You can then see the \begin{document} command, which should always be paired with a \end{document} command at the end of the file. This just informs the compiler that you have now started the main part of your document.

The \maketitle command just adds the title and author commands to your document. If you remove the \maketitle line, your document has no title or author anymore! In the case of the report document class, you don't get the cover page either.

You might notice that I always break 2 lines of text between paragraphs. This is because LaTeX does not create new paragraphs if you just break the line; you must either break 2 lines or use the end-line symbol \\.

So this is a basic tour of the beginning of our file. Now we have to try and understand the main body of this file.

Basic LaTeX Structures

Since LaTeX was first built to typeset mathematics, it is strongly geared towards making it easy to include mathematical symbols and formulas into your document. You can see already that there are some $ (dolar) symbols on our file. These serve to mark the beginning and the end of a mathematical formula.

Math symbols.

You can already see some of the other LaTeX structures on this file. For example, there is a \begin{equation} - \end{equation} environment. All LaTeX commands of the type "\begin{} - \end{}" are called environments. Inside this \begin{equation}-\end{equation} environment are some mathematical commands but there are no dollar symbols. What happens is that when we use this "equation" environment we already know that all content is meant to be mathematical.

So what's the difference between this and the dollar signs?

If you use \begin{equation} - \end{equation} you get a centered, numbered equation; if you use just the simple dollar signs you get a regular equation, in the middle of the text; and if you look further down, there are some equations with two dollar signs $$ - $$: this gets you a centered equation, without numbering.

Let's do a test and check that the automatic numbering of the equations works: where you see the line

 $$\alpha_n = \alpha + O(\beta_n).$$

change it to

 \begin{equation} \alpha_n = \alpha + O(\beta_n). \end{equation}

(It makes no difference if you put that all in one line or if you break lines; the formatting in the pdf file will be the same)

Numbered equations.

Save your file, compile it and check the PDF output. Hopefully, while you were typing, kile already tried to help you by showing you some standard environments.

You can now check that Kile actually makes this even easier: click on the LaTeX tab on the left hand Kile panel and you will see a list of many predefined LaTeX environments, commands and symbols. If you forget the exact command name of what you want to do, most standard commands are there.

If you want to include mathematical or other symbols, there is also a Symbols tab. You can find there special characters, different alphabets, math symbols etc. You can play with that later if you want :)

Kile is very helpful :)

Since math is not the only thing you can do on LaTeX, let's look at simple tables next.

If you look to the end of our .tex file, there are two simple (and totally made up!!!) tables. If you look into your pdf document, they are slightly different: one has a border for each cell, and the other does not.

The first table is a basic tabular environment. The arguments next to the \begin{tabular} command simply tell the compiler that we have 3 columns, the first one has centered text, the second one has right-aligned text and the last one has left-aligned text.

Basic table.

Next, you have the data for the table. Each cell in a row is separated by the & symbol, while rows are separated by an end line symbol "\\". You can see that in the .tex file they are not aligned at all. The compiler does all the formatting later.

Basic table: rows and cells.

In the last line, I didn't need the end line symbol \\ because I'm ending the tabular environment there (the \begin{center}-\end{center} environment does just that, by the way - centers text).

For the second table, you have exactly the same formatting, except that we have included vertical lines separating the columns (these are indicated along with the alignment options at the \begin{document}{|c|r|l|} command).

Basic table with borders.

We have also horizontal lines surrounding each row; these are indicated by the \hline commands. If you want, you can erase one of the \hlines and recompile your document to see that the border around that row is gone.

Horizontal lines.

Kile menu and other options

As you can see there are many other options for predefined environments in kile and obviously we can't look at them all. But I'd like to show you how to include figures in your document.

For this, put your cursor on any empty line in your .tex document, and on the Kile menu, click on LaTeX -> Image Insertion \includegraphics.

Image insertion dialog.

On the dialog box, just choose whatever image file you wish to include in your document, choose all options accordingly (but don't worry, for now all you need is the picture file and you can leave all other options unchanged).

Including an image.

This should include a bunch of code in your file, and all it does is include a centralized picture in your final document.

\includegraphics command.

If you try to compile this file, you'll get an error, as you haven't loaded the right package to include graphics in your document.

Oops! What went wrong?

So go to the first few lines of your .tex file, right after you used the \usepackage{amsmath} and include the line \usepackage{graphicx}. So now you have something like

 \documentclass{article}
 \usepackage{amsmath}
 \usepackage{graphicx}

or maybe you have the \usepackage[utf8]{inputenc} there as well, it doesn't matter. Just put those in any order before your \begin{document} command.

graphicx package.

Compile your file now and you should have a picture on your pdf document. :) (if you see warnings, don't worry about them)

Now if you go to that same LaTeX menu in Kile, you can see there are predefined environments and commands to help you include them in your document. You can try them out later :)

I'd like to point out just another very useful trick: In the toolbar, you can see a QuickBuild button. If you click on it, you will quickly compile your document and open the resulting pdf file. Not useful right now since we already have compiled and opened it.

Now, if you click the arrow to the right of the QuickBuild button, you can see some options: Selection, Environment, Subdocument and Mathgroup.

QuickBuild Menu.

Each of these options will compile only a part of your document, for previewing. So to try it, just select all the code between (including) \begin{center}-\end{center} on one of the tabular environments; next, go to the little arrow to the right of QuickBuild, and click Selection.

QuickBuild -> Selection

You should see now a preview.dvi file that shows you only the result of the selected region after compilation. Don't worry about the dvi extension; this is just lighter than a pdf and is meant only for viewing in the computer, not printing. This is useful if you have a big file and don't want to compile it all at once. But sometimes you want to check if you made a tiny mistake in one small piece of the text :)

Now, for the other options, it goes something like this:

 - Environment: preview environment around cursor
 - Selection: preview selected code
 - Subdocument: only current file instead of whole multifile document (you can have multifile documents!)
 - Math group: preview math group around cursor

Before we finish, I'd like to point out that there is a Wizard option in the Kile menu which is also pretty useful, specially if you're not sure how to format or how to tell LaTeX to format tables and other math environments.

If you want to know more about LaTeX, there are some documents and links at http://www.mtm.ufsc.br/~melissa/links_english.html :)

I'm always reachable by email (my nickname @gmail.com) or by twitter @melissawm

Hope you enjoyed it! Thanks again for participating!