LaTeX/Structured document and document structure
Sommaire
Structured document
A structured document or structured text is a text where its layout is disconnected from its content.
LaTeX is based on the idea that authors should be able to focus on the content of what they are writing without being distracted by its visual presentation. In preparing a LaTeX document, the author specifies the logical structure using familiar concepts such as chapter, section, table, figure, etc., and lets the LaTeX system worry about the presentation of these structures. It therefore encourages the separation of layout from content while still allowing manual typesetting adjustments where needed. The main disadvantage of manual typesetting is that it requires to remember these not always so familiar LaTeX codes! Even with the aid of improved text editors, with help menus and clickable icons, LaTeX will still belong to the "Remember and type" category of software far from the "What you see is what you get" (WYSIWYG) softwares like MS Word.
A structured document helps you to distinguish what belongs to the author from what is publisher's job. But in order to verify the quality of your work, a standard but beautiful layout is applied. The notion of style is currently well known by students; it wasn't in the mid 80's.
An author must decide when a text has to be split into paragraphs or not and if the paragraphs belong to a subsection or a section, and if this section has be in front or after another section, but he hasn't to decide if sections will be numbered A, B, C or 1, 2, 3 or even I, II, III. This decision belongs to the publisher which will decide according to the layout of the series where the text will be published.
The confusion is even more problematic with maths. If you write the following lines with a standard word processor (example from Leslie Lamport):
Such a structure is very ambiguous. Does it mean:
i.e for all x such that... or does it mean that for all x:
The former ambiguous layout is almost impossible to be done with LaTeX (you need special TeX macros). LaTeX prevents authors from such ambiguity.
You are therefore encouraged to use the most basic layout when writing a text. When time to publish has come, you are supposed to use the layout or style provided by your publisher or your university. Then, just a few lines will be changed, depending how far from its final layout the document is required by the publisher.
LaTeX Document structure
Therefore a structured document need a structure and the layout of the structure is easily recognized once you know a little bit of LaTeX codes. If the code is nicely indented, it will help understand your source code and its different parts. A LaTeX document has always the same structure which is presented on this page.
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}
Here are comments
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}
\usepackage[utf8x]{inputenc}
\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, we specified mathptmx which means LaTeX will use the Postscript Times type 1 font instead of the default ComputerModern font.
The code \usepackage[utf8x]{inputenc} means that your input file is using Unicode characters. This is mandatory if your use accented characters or non roman characters and if your TeX engine is pdflatex. If your TeX engine is XeTeX, unicode is used by default \usepackage{xltxtra} and if your Tex engine is LuaTeX \usepackage{fontspec}.
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.
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{article} \usepackage{mathptmx} \usepackage[utf8x]{inputenc} \begin{document} \title{Les populations semi-stables} \author{Jean Bourgeois-Pichat \and Paul Vincent \\ Institut national d'études démographiques\\ Paris,\\ France,\\ \texttt{pichat@ined.fr} } \date{\today} \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).
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{Jane Doe \and John 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.
Many scientific publishers are proposing their own style for a specific review but the AMS article class amsart (AMS art on Springerlink) might be used instead of the old article style:
\documentclass{amsart} \usepackage[utf8x]{inputenc} \begin{document} % Article information \title[Complete-simple distributive lattices] {A construction of complete-simple\\ distributive lattices} % Author information \author{George~A. Menuhin} \address{Computer Science Department\\ University of Winnebago\\ Winnebago, MN 53714} \email{gmen@ccw.uwinnebago.edu} \urladdr{http://math.uwinnebago.edu/homepages/menuhin/} \thanks{The research of the first author was supported by the NSF under grant number 23466.} \author{Ernest~T. Moynahan} \address{Mathematical Research Institute of the Hungarian Academy of Sciences\\ Budapest, P.O.B. 127, H-1364\\ Hungary} \email{h1175moy\%ella@relay.eu.net} \thanks{The research of the second author was supported by the Hungarian National Foundation for Scientific Research, under Grant No. 9901.} \date{\today} \maketitle \end{document}
If you are using another class like beamer, the equivalent presentation will look like:
\documentclass{beamer} % For a Beamer presentation \usepackage[utf8x]{inputenc} \begin{document} % Article information \title[Complete-simple distributive lattices] {A construction of complete-simple\\ distributive lattices} % Author information \author{ George~A. Menuhin \thanks{ \texttt{gmen@ccw.uwinnebago.edu} Computer Science Department, University of Winnebago, Winnebago, MN 53714. The research was supported by the NSF under grant number 23466.} and Ernest~T. Moynahan \thanks{\texttt{h1175moy\%ella@relay.eu.net} Mathematical Research Institute of the Hungarian Academy of Sciences, Budapest, P.O.B. 127, H-1364, Hungary. The research was supported by the Hungarian National Foundation for Scientific Research, under Grant No. 9901.} } \date{\today} \maketitle \end{document}
It means that the \thanks command can be used for many purposes.
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 classes 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}
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...
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:
| Command | Level | Comment |
|---|---|---|
| \part{part} | -1 | not in letters |
| \chapter{chapter} | 0 | only books and reports |
| \section{section} | 1 | not in letters |
| \subsection{subsection} | 2 | not in letters |
| \subsubsection{subsubsection} | 3 | not in letters |
| \paragraph{paragraph} | 4 | not in letters |
| \subparagraph{subparagraph} | 5 | not in letters |
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}
Within the beamer class, the \section and \subsection commands may take optional short arguments. These short arguments are used whenever a short form of the section of subsection name is needed. While this is in keeping with the way beamer treats the optional arguments of things like \title, it is different from the usual way LaTeX treats an optional argument for sections (where the optional argument dictates what is shown in the table of contents and the main argument dictates what is shown everywhere else; in beamer things are exactly the other way round).
Table of contents
If a table of content is an important summary in reports or books, it is not used in a scientific article. But for a presentation, it might be useful for the audience to keep track of your speech. Therefore the command \tableofcontents has to be included where you want it. And thus, you will include it in a frame.
Here is a simple Beamer presentation that you can compile and preview.
\documentclass[table]{beamer}
%\documentclass[notes]{beamer}
% Class options include: notes, handout, trans
% Theme for beamer presentation.
\usepackage{beamerthemesplit}
% Other themes include: beamerthemebars, beamerthemelined,beamerthemetree, beamerthemeplain
\title[Beamer Presentations]{A Sample Presentation using the Beamer Class}
\subtitle{Examples of lists, columns and graphics} % Enter your title between curly braces
\author[L. Numbers]{Lucas Numbers} % Enter your name between curly braces
\institute[Michael Boyd]{Michael Boyd College} % Enter your institute name between curly braces
\date{April 2010} % Enter the date or \today between curly braces
\usepackage{graphicx} % If you want to insert a graphic
\begin{document}
% Creates title page of slide show using above information
\begin{frame}
\titlepage
\end{frame}
\note{Talk for 30 minutes} % Add notes to yourself that will be displayed when typeset with the notes class option.
\section[Outline]{}
% Creates table of contents slide incorporating all \section and \subsection commands.
\begin{frame}
\tableofcontents
\end{frame}
\section[Itemized list $f(x)=x^{-2}$]{Itemized lists rather long section title}
\subsection{Basic list environment}
\begin{frame}
\frametitle{A simple list.} % Insert frame title between curly braces
\begin{itemize}
\item
\begin{example}
Let $f(x)=x^{-2}$.\ Using $k=11$ and no derivatives gives%
\begin{align*}
\sum\limits_{j=1}^{\infty }f(j)& =\sum\limits_{j=1}^{\infty }j^{-2}\approx
\sum\limits_{j=1}^{10}j^{-2}+\int\limits_{11}^{\infty }x^{-2}dx+\frac{1}{2}(11^{-2}) \\
& =1.644\,809\,053\text{.}
\end{align*}
\end{example}
\item
\begin{theorem}
Suppose a function $f$ is ...
\end{theorem}
\end{itemize}
\end{frame}
\note[enumerate] % Add notes to yourself that will be displayed when
{ % typeset with the notes class option
\item The Euler Maclaurin Summation Formula
\item Main Theorem
}
\subsection{Uncovering list items}
\begin{frame}
\frametitle{Sample uncovering technique for lists}
\begin{itemize}
\item<1-> Point 1
\item<2-> Point 2
\item<3-> Point 3
\item<3-> Point 4 is table
\rowcolors[]{1}{blue!20}{blue!10}
\begin{tabular}{l!{\vrule}cccc}
Class & A & B & C & D \\\hline
X & 1 & 2 & 3 & 4 \\
Y & 3 & 4 & 5 & 6 \\
Z &5&6&7&8
\end{tabular}
\item<5-> Point 5
\item<4-> Point 6
\end{itemize}
\end{frame}
\note{Speak clearly} % Add notes to yourself that will be displayed when
% typeset with the notes class option
\section{Slide with two columns}
\begin{frame}
\frametitle{Items and a graphic} % Insert frame title between curly braces
\begin{columns}[c]
\column{2in} % slides are 3in high by 5in wide
\begin{enumerate}
\item<1-> First item
\item<2-> Second item
\item<3-> ...
\end{enumerate}
\column{2in}
\framebox{Insert graphic here}
\end{columns}
\end{frame}
\note{The end} % Add notes to yourself that will be displayed when
% typeset with the notes class option
\end{document}
Section numbering
(see wikibooks:en:LaTeX/Document_Structure#Section_numbering
The value where the section numbering starts from can be set with the following command:
\setcounter{section}{4}
Appendices
The separate numbering of appendices is also supported by LaTeX. The \appendix macro can be used to indicate that following sections or chapters are to be numbered as appendices.
In the report or book classes this gives:
\appendix
\chapter{First Appendix}
For the article class use:
\appendix
\section{First Appendix}
Ordinary paragraphs
Paragraphs of text come after section headings. Simply type the text and leave a blank line between paragraphs. The blank line means "start a new paragraph here": it does not mean you get a blank line in the typeset output. For formatting paragraph indents and spacing between paragraphs, refer to the Formatting section.
Table of contents
(see wikibooks:en:LaTeX/Document_Structure#Table_of_contents
The Bibliography
Any good research paper will have a whole list of references. 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.
To be short, you will add the following commands at the end of your article or report:
\cleardoublepage
%\phantomsection
% \addcontentsline{toc}{chapter}{Bibliography}
\bibliographystyle{apalike}
\bibliography{my_bib_file, fertility}
\end{document}
