3.1 The Document Class Declaration

To tell LATEX what class of document you are going to create, you type a special first line into your file which identifies it.¹ To start a report, for example, you would type the \documentclass command like this as your first line:

\documentclass{report}
      

There are four built-in classes provided, and many others that you can download (some may already be installed for you):

report

for business, technical, legal, academic, or scientific reports;

article

for white papers, magazine or journal articles, reviews, conference papers, or research notes;

book

for books and theses;

letter

for letters.²

The article class in particular can be used (some would say ‘abused’) for almost any short piece of typesetting by simply omitting the titling and layout (see below).

The built-in classes are intended as starting-points, especially for drafts and for compatibility when exchanging documents with other LATEX users, as they come with every copy of LATEX and are therefore guaranteed to format identically everywhere. They are not intended as final-format publication-quality layouts. For most other purposes, especially for publication, you use add-in packages to extend these classes to do what you need:

• The memoir and komascript packages contain more sophisticated replacements for all the built-in classes;

• Many academic and scientific publishers provide their own special class files for articles and books (often on their Web sites for download);

• Conference organisers may also provide class files for authors to write papers for presentation;

• Many universities provide their own thesis document class files in order to ensure exact fulfillment of their formatting requirements;

• Businesses and other organizations can provide their users with corporate classes on a central server and configure LATEX installations to look there first for packages, fonts, etc.

Books and journals are not usually printed on office-size paper. Although LATEX's layouts are designed to fit on standard A4 or Letter stationery for draft purposes, it makes them look odd: the margins are too wide, or the positioning is unusual, or the font size is too small, because the finished job will normally be trimmed to a different size entirely — try trimming the margins of the PDF version of this book to 185mm by 235mm (the same as The LATEX Companion series) and you'll be amazed at how it changes the appearance!

1. Readers familiar with SGML, HTML, or XML will recognize the concept as similar to the Document Type Declaration.

2. The built-in letter class is rather idiosyncratic: there are much better ones you can download, such as the memoir and komascript packages.

3.2 The document environment

After the Document Class Declaration, the text of your document is enclosed between two commands which identify the beginning and end of the actual document:

\documentclass[11pt,a4paper,oneside]{report}

\begin{document}
...
\end{document}
      

(You would put your text where the dots are.) The reason for marking off the beginning of your text is that LATEX allows you to insert extra setup specifications before it (where the blank line is in the example above: we'll be using this soon). The reason for marking off the end of your text is to provide a place for LATEX to be programmed to do extra stuff automatically at the end of the document, like making an index.

A useful side-effect of marking the end of the document text is that you can store comments or temporary text underneath the \end{document} in the knowledge that LATEX will never try to typeset them.

...
\end{document}
Don't forget to get the extra chapter from Jim!
      

This \begin ...\end pair of commands is an example of a common LATEX structure called an environment. Environments enclose text which is to be handled in a particular way. All environments start with \begin{...} and end with \end{...} (putting the name of the environment in the curly braces).

---

  Exercise 2. Adding the document environment

1. Add the document environment to your file.

2. Leave a blank line between the Document Class Declaration and the \begin{document} (you'll see why later).

3. Save the file.

---

3.3 Titling

The first thing you put in the document environment is almost always the document title, the author's name, and the date (except in letters, which have a special set of commands for addressing which we'll look at later). The title, author, and date are all examples of metadata or metainformation (information about information).

\documentclass[11pt,a4paper,oneside]{report}

\begin{document}

\title{Practical Typesetting}
\author{Peter Flynn\\Silmaril Consultants}
\date{December 2004}
\maketitle

\end{document}
      

The \title, \author, and \date commands are self-explanatory. You put the title, author name, and date in curly braces after the relevant command. The title and author are usually compulsory; if you omit the \date command, LATEX uses today's date by default.

You always finish the metadata with the \maketitle command, which tells LATEX that it's complete and it can typeset the titling information at this point. If you omit \maketitle, the titling will never be typeset. This command is reprogrammable so you can alter the appearance of titles (like I did for the printed version of this document).

The double backslash (\\) is the LATEX command for forced linebreak. LATEX normally decides by itself where to break lines, and it's usually right, but sometimes you need to cut a line short, like here, and start a new one. I could have left it out and just used a comma, so my name and my company would all appear on the one line, but I just decided that I wanted my company name on a separate line. In some publishers' document classes, they provide a special \affiliation command to put your company or institution name in instead.

When this file is typeset, you get something like this (I've cheated and done it in colour for fun — yours will be in black and white for the moment):

---

  Exercise 3. Adding the metadata

1. Add the \title, \author, \date, and \maketitle commands to your file.

2. Use your own name, make up a title, and give a date.

The order of the first three commands is not important, but the \maketitle command must come last.

---

The document isn't really ready for printing like this, but if you're really impatient, look at Chapter 4 to see how to typeset and display it.

3.4 Abstracts and summaries

In reports and articles it is normal for the author to provide an Summary or Abstract, in which you describe briefly what you have written about and explain its importance. Abstracts in articles are usually only a few paragraphs long. Summaries in reports can run to several pages, depending on the length and complexity of the report and the readership it's aimed at.

In both cases (reports and articles) the Abstract or Summary is optional (that is, LATEX doesn't force you to have one), but it's rare to omit it because readers want and expect it. In practice, of course, you go back and type the Abstract or Summary after having written the rest of the document, but for the sake of the example we'll jump the gun and type it now.

\documentclass[11pt,a4paper,oneside]{report}
\usepackage[latin1]{inputenc}
\renewcommand{\abstractname}{Summary}
\begin{document}

\title{Practical Typesetting}
\author{Peter Flynn\\Silmaril Consultants}
\date{December 2004}
\maketitle

\begin{abstract}
This document presents the basic concepts of 
typesetting in a form usable by non-specialists. It 
is aimed at those who find themselves (willingly or 
unwillingly) asked to undertake work previously sent 
out to a professional printer, and who are concerned 
that the quality of work (and thus their corporate 
æsthetic) does not suffer unduly.
\end{abstract}

\end{document}
      

After the \maketitle you use the abstract environment, in which you simply type your Abstract or Summary, leaving a blank line between paragraphs if there's more than one (see section 3.6 for this convention).

In business and technical documents, the Abstract is often called a Management Summary, or Executive Summary, or Business Preview, or some similar phrase. LATEX lets you change the name associated with the abstract environment to any kind of title you want, using the \renewcommand command to give the command \abstractname a new value:

\renewcommand{\abstractname}{Executive Summary}
      

---

  Exercise 4. Using an Abstract or Summary

1. Add the \renewcommand as shown above to your Preamble.

   The Preamble is at the start of the document, in that gap after the \documentclass line but before the \begin{document} (remember I said we'd see what we left it blank for: see the panel ‘The Preamble’ in section 3.4).

2. Add an abstract environment after the \maketitle and type in a paragraph or two of text.

3. Save the file (no, I'm not paranoid, just careful).

---

Notice how the name of the command you are renewing (here, \abstractname) goes in the first set of curly braces, and the new value you want it to have goes in the second set of curly braces (this is an example of a command with two arguments). The environment you use is still called abstract (that is, you still type \begin{abstract}...\end{abstract}). What the \abstractname does is change the name that gets displayed and printed, not the name of the environment you store the text in.

If you look carefully at the example document, you'll see I sneakily added an extra command to the Preamble. We'll see later what this means (Brownie points for guessing it, though, if you read section 2.7).

3.5 Sections

In the body of your document, LATEX provides seven levels of division or sectioning for you to use in structuring your text. They are all optional: it is perfectly possible to write a document consisting solely of paragraphs of unstructured text. But even novels are normally divided into chapters, although short stories are often made up solely of paragraphs.

Chapters are only available in the book and report document classes, because they don't have any meaning in articles and letters. Parts are also undefined in letters.⁴

In each case the title of the part, chapter, section, etc. goes in curly braces after the command. LATEX automatically calculates the correct numbering and prints the title in bold. You can turn section numbering off at a specific depth: details in section 3.5.1.

\section{New recruitment policies}
...
\subsection{Effect on staff turnover}
...
\chapter{Business plan 2005--2007}
      

There are packages⁵ to let you control the typeface, style, spacing, and appearance of section headings: it's much easier to use them than to try and reprogram the headings manually. Two of the most popular are the ssection and sectsty packages.

Headings also get put automatically into the Table of Contents, if you specify one (it's optional). But if you make manual styling changes to your heading, for example a very long title, or some special line-breaks or unusual font-play, this would appear in the Table of Contents as well, which you almost certainly don't want. LATEX allows you to give an optional extra version of the heading text which only gets used in the Table of Contents and any running heads, if they are in effect . This optional alternative heading goes in [square brackets] before the curly braces:

\section[Effect on staff turnover]{An analysis of the 
effect of the revised recruitment policies on staff 
turnover at divisional headquarters}
      

---

  Exercise 5. Start your document text

1. Add a \chapter command after your Abstract or Summary, giving the title of your first chapter.

2. If you're planning ahead, add a few more \chapter commands for subsequent chapters. Leave a few blank lines between them to make it easier to add paragraphs of text later.

3. By now I shouldn't need to tell you what to do after making significant changes to your document file.

---

4. It is arguable that chapters also have no place in reports, either, as these are conventionally divided into sections as the top-level division. LATEX, however, assumes your reports have chapters, but this is only the default, and can be changed very simply (see section 9.6).

5. Details of how to use LATEX packages are in section 5.1.

3.6 Ordinary paragraphs

After section headings comes your text. Just type it and leave a blank line between paragraphs. That's all LATEX needs.

The blank line means ‘start a new paragraph here’: it does not (repeat: not) mean you get a blank line in the typeset output. Now read this paragraph again and again until that sinks in.

The spacing between paragraphs is a separately definable quantity, a dimension or length called \parskip. This is normally zero (no space between paragraphs, because that's how books are normally typeset), but you can easily set it to any size you want with the \setlength command in the Preamble:

\setlength{\parskip}{1cm}
      

This will set the space between paragraphs to 1cm. See section 2.8.1 for details of the various size units LATEX can use. Leaving multiple blank lines between paragraphs in your source document achieves nothing: all extra blank lines get ignored by LATEX because the space between paragraphs is controlled only by the value of \parskip.

White-space in LATEX can also be made flexible (what Lamport calls ‘rubber’ lengths). This means that values such as \parskip can have a default dimension plus an amount of expansion minus an amount of contraction. This is useful on pages in complex documents where not every page may be an exact number of fixed-height lines long, so some give-and-take in vertical space is useful. You specify this in a \setlength command like this:

\setlength{\parskip}{1cm plus4mm minus3mm}
      

Paragraph indentation can also be set with the \setlength command, although you would always make it a fixed size, never a flexible one, otherwise you would have very ragged-looking paragraphs.

\setlength{\parindent}{6mm}
      

By default, the first paragraph after a heading follows the standard Anglo-American publishers' practice of no indentation. Subsequent paragraphs are indented by the value of \parindent (default 18pt).⁶ You can change this in the same way as any other length.

In the printed copy of this document, the paragraph indentation is set to 12pt and the space between paragraphs is set to 0pt. These values do not apply in the Web (HTML) version because not all browsers are capable of that fine a level of control, and because users can apply their own stylesheets regardless of what this document proposes.

---

  Exercise 6. Start typing!

1. Type some paragraphs of text. Leave a blank line between each. Don't bother about line-wrapping or formatting — LATEX will take care of all that.

2. If you're feeling adventurous, add a \section command with the title of a section within your first chapter, and continue typing paragraphs of text below that.

3. Add one or more \setlength commands to your Preamble if you want to experiment with changing paragraph spacing and indentation.

---

To turn off indentation completely, set it to zero (but you still have to provide units: it's still a measure!).

\setlength{\parindent}{0in}
      

If you do this, though, and leave \parskip set to zero, your readers won't be able to tell easily where each paragraph begins! If you want to use the style of having no indentation with a space between paragraphs, use the parskip package, which does it for you (and makes adjustments to the spacing of lists and other structures which use paragraph spacing, so they don't get too far apart).

6. Paragraph spacing and indentation are cultural settings. If you are typesetting in a language other than English, you should use the babel package, which alters many things, including the spacing and the naming of sections, to conform with the standards of different countries and languages.

3.7 Table of contents

All auto-numbered headings get entered in the Table of Contents (ToC) automatically. You don't have to print a ToC, but if you want to, just add the command \tableofcontents at the point where you want it printed (usually after the Abstract or Summary).

Entries for the ToC are recorded each time you process your document, and reproduced the next time you process it, so you need to re-run LATEX one extra time to ensure that all ToC page-number references are correctly calculated.

We've already seen in section 3.5 how to use the optional argument to the sectioning commands to add text to the ToC which is slightly different from the one printed in the body of the document. It is also possible to add extra lines to the ToC, to force extra or unnumbered section headings to be included.

---

  Exercise 7. Inserting the table of contents

1. Go back and add a \tableofcontents command after the \end{abstract} command in your document.

2. You guessed.

---

The commands \listoffigures and \listoftables work in exactly the same way as \tableofcontents to automatically list all your tables and figures. If you use them, they normally go after the \tableofcontents command.

The \tableofcontents command normally shows only numbered section headings, and only down to the level defined by the tocdepth counter (see section 3.5.1), but you can add extra entries with the \addcontentsline command. For example if you use an unnumbered section heading command to start a preliminary piece of text like a Foreword or Preface, you can write:

\subsection*{Preface}
\addcontentsline{toc}{subsection}{Preface}
      

This will format an unnumbered ToC entry for ‘Preface’ in the ‘subsection’ style. You can use the same mechanism to add lines to the List of Figures or List of Tables by substituting lof or lot for toc.