LaTeX/Document Structure

From Wikibooks, the open-content textbooks collection

The main point of writing a text is to convey ideas, information, or knowledge to the reader. The reader will understand the text better if these ideas are well-structured, and will see and feel this structure much better if the typographical form reflects the logical and semantical structure of the content.

LaTeX is different from other typesetting systems in that you just have to tell it the logical and semantical structure of a text. It then derives the typographical form of the text according to the “rules” given in the document class file and in various style files. LaTeX allows users to structure their documents with a variety of hierarchal constructs, including chapters, sections, subsections and paragraphs.

[edit] 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!

[edit] Preamble

The preamble is everything from the start of the Latex source file until the \begin{document} command. It normally contains commands that affect the entire document.

% simple.tex - A simple article to illustrate document structure.
 
\documentclass{article}
\usepackage{mathptmx}
 
\begin{document}

The first line is a comment (as denoted by the % sign). The \documentclass command takes an argument, which in this case is article, because that's the type of document we want to produce. It is also possible to create your own, as is often done by journal publishers, who simply provide you with their own class file, which tells Latex how to format your content. But we'll be happy with the standard article class for now! \usepackage is an important command that tells Latex to utilize some external macros. In this instance, I specified mathptmx which means Latex will use the Postscript Times type 1 font instead of the default ComputerModern font. And finally, the \begin{document}. This strictly isn't part of the preamble, but I'll put it here anyway, as it implies the end of the preamble by nature of stating that the document is now starting.

[edit] Top Matter

At the beginning of most documents there will be information about the document itself, such as the title and date, and also information about the authors, such as name, address, email etc. All of this type of information within Latex is collectively referred to as top matter. Although never explicitly specified (there is no \topmatter command) you are likely to encounter the term within Latex documentation.

A simple example:

\documentclass[11pt,a4paper,oneside]{report}
 
\begin{document}
\title{How to Structure a LaTeX Document}
\author{Andrew Roberts}
\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 (at least if you want LaTeX to write the title automatically); if you omit the \date command, LaTeX uses today's date by default. You always finish the top matter with the \maketitle command, which tells LATEX that it's complete and it can typeset the title according to the information you have provided and the class (style) you are using. If you omit \maketitle, the titling will never be typeset (unless you write your own).

Here is a more complicated example:

\title{How to Structure a \LaTeX{} Document}
\author{Andrew Roberts\\
  School of Computing,\\
  University of Leeds,\\
  Leeds,\\
  United Kingdom,\\
  LS2 1HE\\
  \texttt{andyr@comp.leeds.ac.uk}}
\date{\today}
\maketitle

as you can see, you can use commands as arguments of \title and the others. 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.

If there are two authors separate them with the \and command.

\title{Our Fun Document}
\author{John Doe \and Jane Doe} 
\date{\today}
\maketitle

If you are provided with a class file from a publisher, or if you use the AMS article class (amsart), then you can use several different commands to enter author information. The email address is at the end, and the \texttt commands formats the email address using a mono-spaced font. The built-in command called \today will be replaced with the current date when processed by LaTeX. But you are free to put whatever you want as a date, in no set order. If braces are left empty, then the date is omitted.

Using this approach, you can create only basic output whose layout is very hard to change. If you want to create your title freely, see the Title Creation section.

[edit] Abstract

As most research papers have an abstract, there are predefined commands for telling LaTeX which part of the content makes up the abstract. This should appear in its logical order, therefore, after the top matter, but before the main sections of the body. This command is available for the document class article and report, but not book.

\documentclass{article}
 
\begin{document}
 
\begin{abstract}
Your abstract goes here...
...
\end{abstract}
...
\end{document}

By default, LaTeX will use the word "Abstract" as a title for your abstract, if you want to change it into anything else, e.g. "Executive Summary", add the following line in the preamble:

\renewcommand{\abstractname}{Executive Summary}

[edit] Sectioning Commands

The commands for inserting sections are fairly intuitive. Of course, certain commands are appropriate to different document classes. For example, a book has chapters but an article doesn't. Here is an edited version of some of the structure commands in use from simple.tex.

\section{Introduction}
This section's content...
 
\section{Structure}
This section's content...
 
\subsection{Top Matter}
This subsection's content...
 
\subsubsection{Article Information}
This subsubsection's content...

As you can see, the commands are fairly intuitive. Notice that you do not need to specify section numbers. LaTeX will sort that out for you! Also, for sections, you do not need to markup which content belongs to a given block, using \begin and \end commands, for example. LaTeX provides 7 levels of depth for defining sections:

All the titles of the sections are added automatically to the table of contents (if you decide to insert one). 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}

[edit] Section numbering

Numbering of the sections is performed automatically by LaTeX, so don't bother adding them explicitly, just insert the heading you want between the curly braces. Parts get roman numerals (Part I, Part II, etc.); chapters and sections get decimal numbering like this document, and appendices (which are just a special case of chapters, and share the same structure) are lettered (A, B, C, etc.). You can change the depth to which section numbering occurs, so you can turn it off selectively. By default it is set to 2. If you only want parts, chapters, and sections numbered, not subsections or subsubsections etc., you can change the value of the secnumdepth counter using the \setcounter command, giving the depth level from the previous table. For example, if you want to change it to "1":

\setcounter{secnumdepth}{1}

A related counter is tocdepth, which specifies what depth to take the Table of Contents to. It can be reset in exactly the same way as secnumdepth. For example:

\setcounter{tocdepth}{3}

To get an unnumbered section heading which does not go into the Table of Contents, follow the command name with an asterisk before the opening curly brace:

\subsection*{Introduction}

All the divisional commands from \part* to \subparagraph* have this "starred" version which can be used on special occasions for an unnumbered heading when the setting of secnumdepth would normally mean it would be numbered.

If you want the unnumbered section to be in the table of contents anyway, use the \addcontentsline command like this:

\section*{Introduction}
\addcontentsline{toc}{section}{Introduction}

[edit] 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 mean you get a blank line in the typeset output. 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. 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.

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).

[edit] 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 pagenumber references are correctly calculated. We've already seen 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.

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, 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.

[edit] Depth

The default ToC will list headings of level 3 and above. To change how deep the table of contents displays automatically the following command can be used in the preamble:

\setcounter{tocdepth}{4}

This will make the table of contents include everything down to paragraphs. The levels are defined above on this page.

[edit] The Bibliography

Any good research paper will have a whole list of references. Fortunately, LaTeX has a slightly more intelligent approach to managing your references than the average word processor where everything has to be input manually (unless you purchase a 3rd party add-on). There are two ways to insert your references into LaTeX:

• you can embed them within the document itself. It's simpler, but it can be time-consuming if you are writing several papers about similar subjects so that you often have to cite the same books.
• you can store them in an external BibTeX file and then link them via a command to your current document and use a Bibtex style to define how they appear. This way you can create a small database of the references you might use and simply link them, letting LaTeX work for you.

In order to know how to add the bibliography to your document, see the Bibliography Management section.