Stuart's Soliloquy to the void

Programming LaTeX — writing environments

Saturday, August 4th, 2007 | LaTeX

We have previously seen how to create commands in LaTeX. Today, we will be looking at how we can create environments, that is the things that are typically started with a \begin and ended with an \end command. In the course of writing a document with a barebones LaTeX setup, we may see several of these environments: document, figure, table, itemize and enumerate. Each of these environments dictates some form of structure that helps abstract the actual layout of your document from the contents and structure of your document, an important tenant in the LaTeX world.

We can, for instance, imagine that we are writing a document where all figures are centered before they are drawn. In many cases this is accomplished by people using roughly the following code:

\begin{figure}
  \begin{center}
    % figure code goes here
  \end{center}
  \caption{...}
  \label{...}

\end{figure}

But with this, we have mixed together structure and layout, so let us drag the author out back and shoot him before it is too late. Rather, what we would want to do is somehow create a new environment, say myfigure, that takes care of centering the contents. In order to introduce a new environment, we may use the \newenvironment command, which functions very much like \newcommand except that it takes two arguments: what happens before the content, and what happens after the content. So using this knowledge, we can wrap up the centering code:

\newenvironment{myfigure}{
  \begin{figure}\begin{center}
}{
  \end{center}\end{figure}
}

Do note that the order of appearance of the figure and center environments matter. If you try to end a figure environment with a center environment, LaTeX will throw errors your way. With our brand new environment, we can now write our figure using our own environment:

\begin{myfigure}
  % figure code goes here
  \caption{...}
  \label{...}
\end{myfigure}

Thus, we nicely separate our layout and our structure. Normally it would seem prudent to find a better name than myfigure, one that better describes the purpose of the structural component, but sometimes no nifty names come to mind.

Like with commands, environments can also be given a number of parameters. These parameters are, however, only available in the ‘before content’ code. If we often customise our itemize environments to use different kinds or itemisation symbols, we could create an environment that lets us specify these easily:

\makeatletter
\newenvironment{myitemize}[1]{
  \begin{itemize}
    \expandafter\renewcommand\expandafter{
      \csname labelitem\romannumeral\the\@itemdepth\endcsname}{#1}
}{
  \end{itemize}
}

\makeatother

Now we can use this to change the item symbol like this:

\begin{myitemize}{$\star$}
  \item Test
\end{myitemize}

And there would be a nice little star to the left of ‘Test’.

This is basically what there is to environments at the surface. This leaves the technical details of how they are actually implemented (as they are not a part of plain TeX). In fact, \newenvironment is just a cover around creating two different commands: \environmentname and \endenvironmentname. Here the parameters are passed to the \environmentname exclusively, as that is typically where they are needed. Now, invoking \begin{environmentname} is not entirely the same as invoking \environmentname as \begin also sets up some other variables and starts a new group (scope in regular programming).

The primary goal of using environments, though, is to separate the content from the layout. If you keep this in mind when creating documents it will be extremely easy to tweak the layout without having to go through the entire document every time you wish to change all your figures to be centered, for instance.

Tags: LaTeX, programming

1 Comment to Programming LaTeX — writing environments

Leave a comment