Download the lesson example and open it up in your development environment. The text here is complementary to the source code, and this lesson will mostly be a description of how the source code works. It's probably worth compiling the source code just to get a notion of what the result of each bit of the source code looks like.

Comments

An important aspect of this self-descriptive code, and possibly of your own source code, is the use of comments. "Comments", both in general programming and in LaTeX, describes things which are included in the source code and have no effect whatsoever on the compiled result. There are a lot of good reasons to use comments: if you want some information relevant to your writing which you don't want your reader to see (like, say, "This should probably be changed in the next draft" or "We can probably improve this argument"), you can add it in comments so that it informs your writing process without being in the way of the reader. You can also use comments to explain some tricky LaTeX (which is mostly how I'm using it, in this file). Also, if there are whole chunks of your writing which you think aren't ready for primetime but you don't want to delete completely, you can "comment them out" so that they're still in your original document for when you want them but aren't in the compiled output.

A "comment" in LaTeX is everything from a percent sign to the end of the line that it's on. Most development environments will color comments in a way which makes them easy to detect. To make your own comment, just put in a percent sign and write whatever you want to after it. To "comment out" text, just add percent signs at the beginnings of lines.

Lines 1–10, 14–22, 24–27, and many others in the source file you downloaded are comments, which are describing what is going on in the text; in this way the LaTeX code is "self-documenting", since the explanation of what I'm doing is right there in the code. This is not remotely necessary for most writing but for this tutorial it's a good way to explain what's going on.

Source file structure

A LaTeX source file consists of two major sections: the preamble, which includes some general document setup and formatting, and the document, which includes the actual text and other content to be rendered. Preambles can get a bit esoteric, so we'll be focusing chiefly on the document section for the time being, but the document always has the following overarching structure:

  \documentclass[⟨options⟩]{⟨class⟩}

  ⟨Preamble⟩

  \begin{document}
    ⟨Document content⟩
  \end{document}

Thus, every source file has the \documentclass directive, as the first non-comment line, the line \begin{document} somewhere to mark the beginning of the document content, and \end{document} as the very last non-comment line of the source. For now we're not going to focus much on the preamble, but note how in the example provided, we have a \documentclass command on line 12, a pretty much empty preamble, and document content from line 31 to the very end.

Document content

Most of the content of the source file should be self-evident: the text in the document source is exactly the text in the output. There are certain restrictions and caveats on this worth mentioning, though.

Paragraph structure

One important aspect of LaTeX's processing is that it treats a single newline as the same thing as a space, and multiple spaces in a row are also treated as a single space; this is so that if you want to write a very long paragraph, you don't have to write it all on a single line (some text editors are very bad about rendering or navigating single lines). I in fact usually don't write paragraphs on a single line, but have my editor automatically wrap my paragraph onto several lines.

Lines 46–54 are written in the source file in a way to accentuate this behavior. The source code has all sorts of bizarre spacing and line-breaking, but the entirety is treated as a single paragraph.

Note specifically that line 49 also has a comment on the end. The compiler will only see the word are on this line and will ignore the comment completely (it also ignores the newline, so if there wasn't a space after the word are, then there wouldn't be a space in the output either; this can sometimes be useful).

Of course, sometimes you want to end a chunk of text; surely your document shouldn't all be a single paragraph! To indicate a paragraph break, put two or more consecutive newlines with no text in between (spaces or comments in between are fine). Lines 45, 55, 57, 69, 79, 94, and 102 are paragraph breaks in the example text provided.

Special symbols

In addition to having to be able to include paragraph breaks, we also want to sometimes use symbols which have special meaning to LaTeX: for instance, we have already seen that the symbol "%" has a special meaning to LaTeX, but sometimes we might want to use a percent-sign in our text! Likewise, the curly braces and backslash have seen extensive usage in the source code, and they mean something special to LaTeX, so we have to be clever if we want to include those symbols in our output text. Several other symbols also have special technical meanings to LaTeX we haven't seen yet: a complete list of special symbols is \, %, #, $, {, }, &, ^, and _. The dollar sign, octothorp, and percent sign are likely to be the ones which you'll find yourself using regularly (as well as the braces, when doing math with sets). The good news is that, with the exception of the backslash and caret, all of these can be included as literal text (rather than as LaTeX-specific symbols) in the same way: precede them with a backslash. Line 90 of the example includes an example of how you might write out text using these symbols to be rendered correctly.

Some other symbols render in ways which are either subtly or radically different from their literal interpretation. A double-quote character will always render as a close-quote, which gives you the flexibility to put a close-quote wherever you want but means that a straightforward enclosure of a phrase in double quotes will look wrong (an example of this wrongness appears on line 62). To put in a proper open-quote, you use the double backtick `` (the "backtick" or "reversed apostrophe" is probably on the upper left of your keyboard). You can also render a close-quote with a double apostrophe rather than a double-quote, so that two characters are used to represent both the opening and closing quotes. Examples of this usage can be seen on lines 66, 90, 98, 99, 107, and 110 of the source code.

If you are using TeXstudio, you can configure the editor to automatically replace your quotes for you, by selecting "Configure TeXstudio" from the "Options" menu, selecting the "Editor" pane, and setting the "Replace Double Quotes" option to "English Quotes". Texmaker may have a similar option somewhere.

Other symbols present a moderate and occasionally unpleasant surprise. For historical reasons, < and > will typically render as the symbols ¡ and ¿, as you can see on lines 98 and 99 of the example. You shouldn't actually be using these symbols at all outside of mathematics, which is done separately, so if you do accidentally produce these symbols, the odds are good that you mean to be producing mathematics and are not. Finally, dashes are used to render three different symbols: a sigle dash is a hyphen, as used in hyphenated words; two dashes are an en dash, used for specifying ranges, and three dashes are an em dash, used in some specific rhetorical contexts. You can see all three used and rendered in lines 107–113 of the example code. To learn more about their appropriate uses, consult a stylistic source, like the the Chicago Manual of Style.

Troubleshooting

LaTeX is basically a programming language, and unlike in a word processor, where it's pretty much impossible for you to do anything the system doesn't expect, in LaTeX you can create input files which the compiler can't actually make any sense of. It does its best to recover, but if the input looks wrong, it would rather tell you "this doesn't look like it works" than try to guess what you mean. At the moment, there isn't much you can do wrong, but using a special symbol without escaping it, or leaving out some of the necessary elements of document structure, will still cause errors. When you do get an error in your compilation, go ahead and look at the text of the error and the line number it's associated with; sometimes this information wont be quite what you need, because the error will be the result of some cascade of misinterpretation from an earlier line, but it's a good place to start. Here are a few of the errors you might encounter:

• The font size command \normalsize is not defined: there is probably something wrong with the class file.: This might seem a pretty strange error (what's this \normalsize business?) but the key clue is in the mention of "class file". Unless you're doing something really strange, this is a symptom that you haven't defined any class file for your document. You normally do this in the very first line of your document, with the \documentclass command which is a pretty much compulsory part of your file structure. To fix it, put \documentclass{article} in as the first line of your source code.
• Missing \begin{document}: This one's pretty self-explanatory. The \begin{document} command is a necessary part of the document structure, and if it's not there, then LaTeX can't compile. It's easy to fix: just add the line \begin{document} before the text you want typeset, and if it's not already there, also an \end{document} at the end.
• Emergency stop: This means LaTeX ran out of input before it expected to. The most likely cause is that you never formally end your document, which is to say, there's no \end{document} at the bottom of your file. Add one and this error should go away.
• Undefined control sequence: A control sequence is anything starting with a backslash, and LaTeX won't correct misspellings. So if you've misspelled \documentclass, \begin, or \end, then instead of trying to guess what you might mean, LaTeX will just tell you it couldn't figure it out.
• Environment ⟨clue⟩ undefined: If you misspell "document" in your \begin{document} command, LaTeX will assume you're trying to start some other sort of environment (not a "document") and get confused because it's never heard of that thing you're making. This error message will explicitly tell you how you mispelled it, where I've included the phrase ⟨clue⟩.
• \begin{document} ended by \end{⟨clue⟩}: Every \begin statement needs an identical \end statement to close it. If you misspell "document" in your \end{document} command, LaTeX will see that your \begin{document} statement has a mismatched ending. This error message will explicitly tell you how you misspelled it, where I've included the phrase ⟨clue⟩.
• File ⟨clue⟩.cls not found: When you use a document class (like "article"), LaTeX actually looks up a file that tells it how to render that type of document; for instance, your documents all make use of the file article.cls that's included in the core LaTeX system. If you misspell article in your \documentclass statement, then LaTeX will go off looking for a file whose name is identical to your misspelling, and probably won't find it.
• Missing $ added: LaTeX uses dollar signs to toggle in and out of equation-writing mode, so probably the reason it wants to add a new dollar sign is because you already used one, and it expects you to eventually toggle out of math-mode. While in some later sections of this tutorial, once you start writing equations, this might be the case, with what you're writing at this point the odds are much higher that what you've done is included a dollar sign meant to be typeset as a dollar sign, and didn't put a backslash before it.
• You can't use `macro parameter character #' in horizontal mode.: The clue here is the reference to the character #, which is a special character to LaTeX and it gets really unhappy seeing it except where it has a special purpose for it. Replace your # with the escaped character \# to fix this error.
• Misplaced alignment tab character &.: The clue here is the reference to the character &, which is a special character to LaTeX and it gets really unhappy seeing it except where it has a special purpose for it. Replace your & with the escaped character \& to fix this error.

• Missing text where a percent sign should be: LaTeX will treat a percent-sign as a comment and ignore the rest of the line it's on, so instead of including the "%" character in your write-up, it'll actually annihilate everything after it on the line! LaTeX won't flag this as an error because it assumes you have a perfectly good reason to comment out the end of a line and will take it at face value. If you want a literal percent-sign in your text, escape it with \%.
• Missing braces: Braces are also special to LaTeX for grouping purposes, but it'll let you group anything anywhere, and not consider it an error. The grouping, however, is invisible (it's useful for a lot of commands, so it's important "under the hood"), so the apparent effect is that your braces have just vanished. To include literal braces in your text, you need to use the character combinations \{ and \}.
• Missing dollar signs, possibly with weird italicized text: LaTeX uses dollar signs to toggle in and out of equation-writing mode, and if you have an even number of dollar signs in a paragraph, it'll interpret that as a paragraph containing a bunch of equations, and it'll typeset every letter in the "equations" the way it ordinarily typesets variables. This is probably not what you want to do if you're trying to print literal dollar signs, and you'll want to replace every $ with \$.
• Backwards open-quotes: The character " is interpreted by LaTeX as a close-quote and will look wrong if you use it as an opening quote. Use `` instead.

Exercise

Download this source file. It won't compile, and has some problems other than just compilation. Fix it so that it compiles to make a PDF looking like this.