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.

Comments and Escaping

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.

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.

\documentclass{article}
\begin{document}
In \LaTeX, \textbackslashis the escape character.
\end{article}