# 1-1: Get Down With the Markup

You have probably already noticed that LaTeX is very different from Microsoft Word and its relatives. Whereas Microsoft Word follows the what you see is what you get (wysiwyg) philosophy, LaTeX is a markup language where you type in commands that will be interpreted and executed in order to create a visual display or pdf. It’s a lot easier to crash LaTeX than it is to crash Word! The flip-side of this is that LaTeX allows infinite customizability and has a rich set of pre-defined plugins and packages which will benefit you a lot.

When we talk about Maple, you’ll see that some of the themes from LaTeX are re-introduced: nailing the exact spelling and punctuation of the input commands matters, or else the program will fail to understand what you are trying to do. These will be common ideas to you if you have ever used a programming language or HTML before.

## Whitespace

Go back to the $$\text{Hello, world!}$$ file that we created in the previous lesson. Now, put a newline in between Hello, and world, like this:

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

Now compile the code again and look at the output. Do you notice anything unexpected? Rather, do you not notice anything expected? Take a good look and once you think you have figured out the “surprise,” continue below.

The “surprise” is that the output still has $$\text{Hello, world!}$$ all on one line, even though the input file (source code) has the words separately on two separate lines. Why does LaTeX behave like this? The motivation is that LaTeX tries to intelligently figure out how your text breaks in to paragraphs, and it is pretty common that you will have a long paragraph that is too long to fit comfortably on a single line of the source code. In order to tell LaTeX that you definitely want to begin a new paragraph, you need to have a completely blank line separating the chunks of text, or in other words you need to press the Return key twice. Here is an example.

\documentclass{article}
\begin{document}
Hello,

world!

We're still in LaTeX and this is a very long paragraph, which we don't want to have to write all on one line of the source code. Instead, we're breaking it up onto different lines. But notice that the line breaks in the source code are not the same locations as the line breaks in the LaTeX output.
\end{document}

When you compile this it looks like:

You can also see that LaTeX, by default, puts an indent at the start of every paragraph.

Another fact about whitespacing is that multiple blank lines behave the same as a single blank line. For example,

\documentclass{article}
\begin{document}
Hello,

world!
\end{document}

and

\documentclass{article}
\begin{document}
Hello,

world!
\end{document}

both give the exact same output. Later on we’ll talk about how to force more space when you want it. But we recommend in general, that you should let LaTeX try by itself to automatically lay things out, before starting to tweak things.

If you have ever done any programming, you know that comments are a way of inserting text into your source code in such a way that it will be ignored by the computer. Common uses for comments include:

• explaining parts of the program, for you or other people to read later;
• leaving “to do” notes, when you write a longer file;
• temporarily disabling (“commenting out“) a line of your source code without totally deleting it, so that it is easier to put back in later.

To be more precise, comments in LaTeX are designated by %, the percent symbol. Whenever a line of input contains a %, that symbol and everything after it will be completely ignored. For example,

\documentclass{article}
\begin{document}
Hello, world! %and perhaps things not of this world

% \end{document} --- this is ignored because of the %

Goodbye, world!
\end{document}

will only result in the two lines of output $$\text{Hello, world!}$$ and $$\text{Goodbye, world!}$$

A flip side of this is that if you ever want to actually output a percent symbol in LaTeX, you need to write \%. This is called escaping the percent symbol, or an escape sequence. There are numerous escape sequences in LaTeX: any character with a special meaning must be preceded by \ if you want it to be interpreted literally. For example, to write an open brace { you must write \{ in your source code. To write a backslash \ you need the special command \textbackslash, since \\ has another meaning. We will later explain that the verb and verbatim commands can be used to make escaping easier when there is a ton of text to be escaped.

Exercise (nickname: milk)

Create the following sentence of LaTeX output exactly:

Use the $$\text{Hello, world!}$$ file as a template to get started; you’ll need to leave the documentclass and begin/end commands as they are. Note that the colon symbol : and question mark ? must not be escaped, or else they vanish mysteriously.

Optional challenge version (will not be graded). Create the following sentence of LaTeX output exactly:

$$\text{The output % is produced by the input \%, but \ is not produced by \\.}$$

Hint: you are likely to get the output $$\text{\is}$$ on your first attempt, where the space before “is” is missing. In order to fix this, you can change \textbackslash to \textbackslash{}. The \textbackslash command ate the space as its input, and adding {} allows you to specify it should consume no input.

Make sure you don’t lose the solutions to the exercises that you complete! You’ll need to combine them all at the end of Lesson 1-3 in order to hand in Assignment 1. One convenient option is to comment out the old exercises when starting the new one, using just one file the whole time.

## Structures in Source Code

We haven’t yet discussed three lines of the Hello, world! document: the first one, and the ones with begin and end. It is required that every LaTeX document starts with

\documentclass{«name of some valid document class»}

We’re going to keep on using article for a while, but a few other sample document classes are  report, letter, book and beamer. They affect how things look, how citations and bibliographies are presented, whether the document should be broken into sections or chapters, and lots more.

Notice that the command \documentclass is followed by some stuff contained in braces {}. The contents of the braces are called arguments to the command, and they act like its inputs. We’ll see that in other situations, you’ll also need to use [] for optional arguments.

Furthermore, we’ll see that {} without any preceding command can also be used as a generic container for content, which will be especially useful for text formatting.

Just like each { must have a matching }, the \begin{document} must have a matching \end{document}. The main text of the document must go between these delimiters (anything afterwards is ignored). We’ll see begin/end commands for other environments as we go along.

## Debugging

If you have forgotten a } to match with a {, then LaTeX will complain when you try to compile. There are many, many other so-called syntax errors that you will encounter as you work with LaTeX. The process of writing a LaTeX document, like computer programming, is an iterative process.

Debugging, or fixing syntax errors to get your LaTeX source code to compile, is a skill that improves with practice. LaTeX will always provide some sort of an error message when it can’t compile. Often these are straightforward and not hard to diagnose. Sometimes they can be very tricky — the error messages can sometimes be hard to understand, or refer to a part of the code that is different from what is the true cause.

Here are some recommendations on how to make debugging as painless as possible.

• Deal with the first error first. Even if you compile your document and it produces a hundred errors, you only need to fix one at a time, and the first error is most often the clearest to understand. Try to understand and fix it first, then recompile to see if that error goes away.
• Compile early, compile often. Avoid working for hours on the source code and then compiling it; you may end up with lots of errors, or learn that parts of your document need to be restructured. Instead, get in the habit of compiling after every few sentences. The source of any new errors will be obvious.
• Isolate the error. You can try copying a small section of the problem area to a new empty file to see if you can isolate the source of the error. Or, you can move the \end{document} up earlier.
• Don’t hesitate to ask for help. That’s what the course staff is here for. You can either message the course staff privately or make a public forum post. Be careful not to copy all of your source code to a public forum post (you don’t want other students to have to worry about plagiarism), but if you can remove the exercise-specific parts, the public posts may help other students and give you a faster response.

Exercise (nickname: debug)

Non-graded exercise — mandatory, but not to be handed in. Depending on your LaTeX editor and operating system, your error messages may show up in different places. It is a good idea to figure this out and get used to the flow of debugging.

Create a new document and erase its contents, pasting this instead:

\documentclass{article}
\begin{document}
In \LaTeX, \textbackslashis the escape character.
\end{article}
• When you try to compile it, in what part of your editor does it indicate there was an error?
• What is the text of the first error? (It should refer to part of the input.)
• Try fixing that error. (If you’re stuck, review the part of this lesson about backslashes.)
• Recompile. If the same error occurs, repeat the previous steps.
• There should now be a second, different, error. What is the error message? Debug it.
• After fixing those two issues, the document should compile correctly.

Since this exercise is non-graded, you can ask any questions about it that you like in the forums.

These are course notes for the University of Waterloo's course Math 600: Mathematical Software.
© 2012—. Written and developed by David Pritchard and Stephen Tosh. Contact (goes to the CEMC)