Making a new environment combining equation and split

Question

I'm trying to define a new environment that consists of a split environment inside an equation environment. But I'm getting an error. Here's what I'm doing:

\documentclass[a4paper,12pt]{article}
\usepackage[brazil]{babel}
\usepackage[utf8]{inputenc}
\usepackage{amsmath}
\newenvironment{example}{\begin{equation}\begin{split}}{\end{split}\end{equation}}

\begin{document}
\begin{example}oi\end{example}
\end{document}

And the error message I'm getting is:

ERROR: LaTeX Error: \begin{split} on input line 8 ended by \end{example}.

I then tried a few other cases. If I remove the splits and define example to be just equation, it runs fine. If I remove the equations and define example to be just split, I get the exact same error message.

In other words: I only get this error when split is involved. Is there a way to make this work?

EDIT: The reason I'm doing this, is because I want a convenient way to create split-equations. I know it's similar to align. I prefer split-equations because the entire line of equations gets a single number for referencing (it's even placed in the middle line). align, however, will force me to \notag each line, otherwise I get a number for each line in the equation (which tends to get messy when equations are long and numerous). It's not the end of the world, but the split-equation combination is just quicker and easier (if I can manage to define a command for it).

Alternatively, the multline environment is not appropriate either, because it doesn't let you manually align each line (like aligning the equal signs). Instead it only lets you push everything left or right.

EDIT2: I just tried this:

\newenvironment{example}{ \begin{equation}\split}{\endsplit \end{equation}}

and got this error

ERROR: LaTeX Error: \begin{equation} on input line 8 ended by \end{example}.

Which is weird, because removing \split and \endsplit entirely doesn't return any errors (so it's not equation's fault).

Answer 1

I wouldn't have expected this, but there's an easy answer; thanks to Stefan Kottwitz! (And thanks to Will Robertson for writing the package environ that I had never heard of before. He should have given this answer; with his package it works like a charm.)

\documentclass{article}
\usepackage{amsmath,environ}
\NewEnviron{example}{%
\begin{equation}\begin{split}
  \BODY
\end{split}\end{equation}
}
\begin{document}
\begin{example}
a &= b + c \\
  &= d + e
\end{example}
\end{document}

Some explanations can be found in Stefan's post behind the above link.

Answer 2

The reason that \begin{split} ... \end{split} doesn't work when the \begin ... \end are invoked within the begin and end parts of another environment is related to the reason given in the "technical notes on the amsmath package" (texdoc technote) -- the parsing requires an exact match of the environment specified by \begin{...}.

this isn't really obvious from the current documentation in technote, but it would be a good idea to add it, and I'll try to arrange for that to happen.

Answer 3

The split environment has to be used within a math displaying environment. I guess that what you are trying to do is to create a shortcut so that you don't have to write

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

every time.

Perhaps an alternative to split would be the aligned environment which also allows you align a sequence of formulas on the equal sign and, placing it inside an equation environment, you also get a single equation number for the whole expression. Also luckily, aligned doesn't have the parsing problems of split and plays well with new environment definitions.

\usepackage{amsmath}
\newenvironment{equations}{\equation\aligned}{\endaligned\endequation}

\begin{equations}
a &= b + c \\
  &= d + e
\end{equations}

Of course, you can always read the documentation from amsmath by typing

texdoc amsldoc

on a command line to find inspiration and browse for alternatives.

Answer 4

In regards to Juan's answer: declaring a new environment using equation and aligned does work, but it introduces some added wrinkles with spacing. It seems to include a single space (smaller than an indent) in the text which follows the equation. I'll quote the relevant wikibooks page:

When creating a new environment you may easily get bitten by extra spaces creeping in, which can potentially have fatal effects. For example when you want to create a title environment which suppresses its own indentation as well as the one on the following paragraph. The \ignorespaces command in the begin block of the environment will make it ignore any space after executing the begin block. The end block is a bit more tricky as special processing occurs at the end of an environment. With the \ignorespacesafterend LaTeX will issue an \ignorespaces after the special ‘end’ processing has occurred

Including ignorespaces in the new environment definition seems to be weirdly behaved. Dealing with this subtle spacing issue seems like too much trouble for just a shortcut. I recommend writing out the full

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

using auto-completion, like with TexWorks or TeXShop. (\begin{align}\begin{split} seems to be just as good in this context where we aren't defining new environments.) This has the added benefit of being easier to read for anyone else (e.g., a journal) looking at your LaTeX.