Environments

LaTeX has a multitude of logical structures to work with, called 'environments.' Use them.

An environment is established by the pair \begin{}...\end{}

Quotation and verse

For example, a quotation may be typeset using the quote environment (for such a displayed quote we do not use quote marks, quote marks are only used for short quotes typeset inline).

\begin{quote} 
... 
\end{quote}

or a passage of verse may be typeset by the verse environment

\begin{verse} 
... 
\end{verse}

See Src/fractals11.tex and the use of \\ to specify line breaks in the verse environment.

LaTeX knows that it is good style to leave a wider stretchable space after a full-stop at the end of a sentence. However, this means that sometimes you have to tell LaTeX that some full-stop/space combinations are not at the end of a sentence, one example being between a person's initials. As in L.~F. Richardson and A.~J. Roberts, a tilde does two things:

it typesets a standard width space, and
it tells LaTeX never to break a line at that space.

The tilde is used to tie text in other circumstances such as Figure~2, equation~(3), and Section~3.1. You must make it a habit to use such ties. Knuth describes fully where to use such ties.

Abstract

See video discussion 22

The abstract environment does a little more for you in that

\begin{abstract} 
... 
\end{abstract}

also typesets a natty little title. See Src/fractals12.tex.

Ensure your abstract addresses the following. Remember: write to interest a reader, not for yourself.

What was done?
Why do it?
What were the results?
What do the results mean in theory and/or practice?
What is the reader's benefit?
How can readers use this information for them- selves?

Sometimes, conferences ask you to head the Abstract with the word Summary instead. That is not your concern, it is theirs. Their style file should automatically translate your logical "abstract" to their desired appearance of "Summary". However, if necessary, in the preamble redefine the hook with

\renewcommand{\abstractname}{Summary}

Itemize and enumerate

Extremely useful are the list environments of which I describe two. Use them wherever you have a sequence of steps or a list of things. The format for a bulleted list is

\begin{itemize} 
\item ... 
\item ... 
... 
\end{itemize}

The format for a numbered list is

\begin{enumerate} 
\item ... 
\item ... 
... 
\end{enumerate}

See Src/fractals13.tex. Blank lines between items have no effect.

Lists may be embedded within lists to a maximum of four nested levels.

If necessary, one can change the labelling of enumerated list using some LaTeX hooks. For example,

\renewcommand{\labelenumii}
    {\theenumi(\alph{enumii})}

changes the labels of enumeration at the second level.

Tabular and center

See video discussion 23

Often we want to display information in a table; LaTeX has the tabular environment for this (the same as array inside maths).

The tabular environment is a more sophisticated environment in that it has an argument as well as material in the body of the environment. The format of the environment is

\begin{tabular}{argument} 
\hline 
... & ... & ... \\
\hline 
... & ... & ... \\
... & ... & ... \\
... & ... & ... \\
\hline 
\end{tabular}

for a table of four rows and three columns (with horizontal lines around the heading line and also at the end of the table).

The special & character separates the different items in any one row.
The '\\' separates different rows.
The argument of the tabular environment is a string made up of a letter for each column of the table, either c, l or r denoting a centred, left-justified or right-justified column respectively---the letters optionally separated by a '|' if you need vertical lines between columns.
The optional \hline's draw horizontal lines between the rows of the table. Use \hline's and |'s sparingly---let the table structure work for you at the lowest level.

The fractal document does not have a table at present, but we put one in at the end listing seven geometric objects and their fractal dimension, see Src/fractals14.tex. Tables are usually put inside a center environment:

\begin{center} 
... 
\end{center}

which centres the enclosed material across the width of the page (note the American spelling of center).

Multiline cells in tables

Sometimes you need the heading of a column to be a phrase or sentence. Phrases and sentences are usually too wide for a column and so need to be typeset over multiple lines. For such a cell, use

\parbox{width}{\raggedright ...}

where ... denotes the phrase or sentence, and where width is the desired width of the cell. Prefer to express widths in terms of em, such as {8em}. Since 1em is the width of the letter M, the cell will adapt to whatever font and font size that you and/or publishers may choose for every version of the document. Try it in the example Src/fractals14.tex.

When you need every cell in a whole column to be a phrase or sentence, then in the tabular argument, in place of the column descriptor c, l or r, use p{width}, where again the width of the cells are in units of em.

Try using it for the whole left column in the example Src/fractals14.tex.

Verbatim

See video discussion 24

Computer code, no matter what special characters it has, may be listed with the verbatim environment:

\begin{verbatim} 
... 
\end{verbatim}

All characters and line breaks within the body of this environment are reproduced in the fixed width font. See Src/fractals15.tex where I typeset the LaTeX commands needed to typeset the table of dimensions!

Many people have made more powerful code listing environments. The advantage of these packages is that it empowers you to automatically include the precise code in your document (without having to worry about copying and pasting new versions after the slightest edit). Use whichever of these packages suits you.

For example, to use the fancyvrb package: invoke \usepackage{fancyvrb} in the preamble; then where you want a listing of a code file specify

\VerbatimInput[numbers=left]{filename}

Arguably the most beautiful package for code listing is minted, but I find it too slow.

Beautifully document code

For reproducible research we need to properly document code, which requires typesetting mathematics properly, and sectioning, and so on. The document needs to be typeset in LaTeX. For example, in using Matlab we insert LaTeX code within Matlab block comment environments and so both execute in Matlab, and typeset in LaTeX. Base on the example in the two files Src/simple.tex and Src/simple.m, or upon the following templates: store the first template as say filename.tex

\documentclass{article}
...
\usepackage{fancyvrb}
\newenvironment{matlab}%
    {\Verbatim[numbers=left
    ,firstnumber=\the\inputlineno]}%
    {\endVerbatim}
...
\begin{document}
... 
\input{filename.m}
...
\end{document}

Store the second template in filename.m for both execution and typesetting.

%a short description, printed by 'help'
%!TEX root = filename.tex
%{
... LaTeX explanation ...
\begin{matlab}
%}
function xk=newtonSearch(fun,xk,eps)
%{
\end{matlab}
... more LaTeX explanation ...
\begin{matlab}
%}
more Matlab code
%{
\end{matlab}
... LaTeX ...
%}

Include the typesetting of results and generated graphics. Other techniques work for other languages, such as knitr for R.

Simple Mathematics

See video discussion 25

Mathematics is treated by LaTeX in a fashion completely different from ordinary text. The mathematics mode is invoked by specific environments.

math

Mathematics to be typeset inline with the text should be contained in the environment

\( ... \)

A universal bad habit is to use matching dollar signs

$...$

to invoke the math environment for inline mathematics; warning: an unmatched $-sign causes incomprehensible error messages.

See Src/fractals16.tex and observe the mathematics in section 2 when typeset. A different font is always used for mathematical letters (usually math italic); all mathematics is typeset in a math environment (even if it is just a single letter), and not in the roman font that is the default for text, nor in the italic font for text.

In any mathematics environment, blank characters are totally ignored.

scripts and symbols

Subscripts and superscripts are typeset in a mathematics environment using the underscore and the caret character respectively. For example, d^{-1} and d^2 will typeset '-1' and '2' as superscripts to $d$, as in $d^{-1}$ and $d^2$, see Src/fractals17.tex. Similarly for subscripts indicted by the underscore "_". Single character scripts need no enclosing braces.

LaTeX has an enormously wide variety of symbols to help typeset mathematics. For example, in fractals17.tex I used:

\times to get a times sign, $\times$;
\propto to get a proportional to symbol, $\propto$;
\pi to get the greek letter pi, $\pi$.

See the menus in Alpha, or the Essential Mathematics document, for an idea of the wide range of symbols available; in particular, the whole of the greek alphabet. The names of these symbols have to be followed by a non-alphabetic character, often a blank.

displayed math and frac

Many mathematical equations and expressions are so complicated or so important that they should not be typeset inline with the text, but they should be displayed on a line all by themselves. Achieve this with the environments:

\[ ... \]

\begin{equation} ... \end{equation}

The difference being that the last also typesets an equation number to the right of the mathematics. See Src/fractals18.tex.

Observe the use of the \frac command, with two arguments enclosed in braces, for producing fractions within mathematics.

mathjax

MathJax analogously empowers web pages to also use LaTeX in the math environments

\(...\)  and  \[...\]

For example, within this web page the code

\[ e^{i\pi/2}=\cos\frac\pi2
+i\sin\frac\pi2=i \]

here displays the following mathematics \[ e^{i\pi/2}=\cos\frac\pi2+i\sin\frac\pi2=i \] Invoke Mathjax for a web page with the following in the web page header (and without the line breaks in the http):

< script type="text/javascript"
src="http://cdn.mathjax.org/
mathjax/latest/MathJax.js?
config=TeX-AMS-MML_HTMLorMML">
< /script>

Theorems et al.

LaTeX does not by default provide an environment for theorems. Instead LaTeX provides an environment for you to create theorem-like environments (extended by the American Mathematical Society). I recommend you include the following in your preambles:

\usepackage{amsthm} % optional
\newtheorem{theorem}{Theorem}
\newtheorem{corollary}[theorem]{Corollary}
\newtheorem{lemma}[theorem]{Lemma}
\newtheorem{definition}[theorem]{Definition}

Thereafter, as seen in Section 8 of Src/maths.tex, you use the following environments as appropriate:

\begin{theorem}...\end{theorem}
\begin{corollary}...\end{corollary}
\begin{lemma}...\end{lemma}
\begin{definition}...\end{definition}
\begin{proof}...\end{proof}

The last proof environment is from the amsthm package.

Label and cross-reference these as described in the next section.

Such environments obtained from \newtheorem can also have an optional argument to provide a name to the 'theorem'. For example,

\begin{definition}[right-angled triangles]
...\end{definition}

Disappearing environments

See video discussion 26

The versions package empowers us to selectively include or exclude environments. For example, one might typeset an assignment, with solutions, and want the solutions to appear for teachers and disappear for students. Invoke in the LaTeX preamble

\usepackage{versions}
\excludeversion{solution}

and in your document surround solutions with

\begin{solution} ... \end{solution}

With the excludeversion invoked as shown, then all the material within all the solution environments will not be typeset.
But with \includeversion{solution} invoked instead, then the material within all the solution environments will be typeset.

Another use of versions is to include or exclude commentary when developing a collaborative document (especially over long time spans).

Summary

The environments described are among the most common ones needed for all sorts of documents. Based upon hundreds of years of printers experience distilled by Knuth and Lamport, LaTeX knows the generic best way to typeset the different sorts of information.

For example, the LaTeX document-class refart typesets articles according to Wendy Priestly's best practice for instruction. After downloading Others/refart.cls, if necessary, simply change the document-class of Src/fractals18.tex from article to refart to see the style (use Others/refrep.cls for long reports).

Before looking at more environments and commands, the next step is to use LaTeX to automatically provide us with cross-references such as a table of contents, citations, equation referencing.

Appendix for the purists

For the purist who prefers environments to commands, there are sectioning environments corresponding of the sectioning commands from section to subparagraph. For example, invoke the section environment with

\begin{section}{Some section title} 
... 
\end{section}

which is equivalent to the section command

\section{Some section title}

but 'better' in that the environment also delineates the end of the section.

One useful exercise when finalising a dissertation is to \excludeversion{section} so that you just typeset and proofread all the chapter introductions: do they make reasonable sense as coherent introductions and overviews of the chapters? If not rewrite.

LaTeX: Environments

by Emeritus Prof A. J. Roberts