# Theorem packages: which to use, which conflict?

As far as I know, one can create theorem environments using any of amsthm, ntheorem, thmtools and probably more.

How should I define my theorem environments? Is one package clearly superior? Which packages conflict? Is there one package that does everything? (For some reason I am using ntheorem but I cannot remember why).

For example, thmtools looks like it has some nice features, but I'm afraid of breaking my ntheorem-defined custom environments...

-
thmtools is not the package to do everything because it explicitly won't attempt something similar to ntheorems [thmmarks] option. (I don' think it can be done reliably without special cases to avoid conflict with other packages of hyperrefian dimensions.) –  Ulrich Schwarz Nov 18 '10 at 18:40
+1 for "hyperrefian". –  lockstep Nov 18 '10 at 20:03

To answer your question of whether ntheorem is clearly superior to amsthm (or the other way round), the answer is unfortunately no as both have advantages and shortcomings.

Feature-wise, ntheorem is clearly ahead of amsthm, but amsthm is more robustly designed, and has, as such, less bugs (of course, depending on how you use the ntheorem package, you may never encounter these bugs, but it's better to be aware of them).

Comparison of features of ntheorem and amsthm

The following table is inspired from the one given in the French FAQ entry about theorem and shows a list of features of each packages, clearly showing that ntheorem can do more things than amsthm.

Examples of ntheorem bugs

Here are a few chosen bugs which can occur in ntheorem and of which you should be aware before deciding whether to use ntheorem or amsthm. All these bugs are specific to ntheorem and do not occur in amsthm.

Break style clash with high material

When using the break style, if you put something a little too high at the start of the theorem, it will overlap with the theorem title:

\documentclass{article}
\usepackage{ntheorem}
\theoremstyle{break}
\newtheorem{theorem}{Theorem}
\begin{document}
\begin{theorem}
$\displaystyle \sum_{n=1}^{+\infty}{\frac{1}{n^2}} = \frac{\pi^2}{6}$
\end{theorem}
\end{document}


Footnote in theorem note

While it may not be a very good pratice to put footnotes in theorem optional arguments, it can be needed some times, but doesn't work with ntheorem (the footnote text will be lost; you must use the \footnotemark/\footnotetext trick):

\begin{theorem}[Fermat's little theorem\footnote{First stated in a letter dated October 18, 1640.}]
...
\end{theorem}


Long theorem note

If the theorem's optional argument is too long (either because the document is in two column mode or because the note is indeed very long), it will hang out of the margin. Here's an example in two column mode:

\documentclass[twocolumn]{article}
\usepackage{lipsum}
\usepackage{ntheorem}
\newtheorem{theorem}{Theorem}
\begin{document}
\lipsum[1]
\begin{theorem}[A very very very very long optional argument]
\lipsum[2]
\end{theorem}
\lipsum[3-5]
\end{document}


Examples of amsthm bugs

Although it has less bugs, amsthm is not completely bug-free. Here's a variant of the "too long theorem optional argument" ntheorem bug, but which only occurs with amsthm if a list is immediately following the theorem head:

\documentclass[twocolumn]{article}
\usepackage{lipsum}
\usepackage{amsthm}
\newtheorem{theorem}{Theorem}
\begin{document}
\lipsum[1]
\begin{theorem}[A very very very very long optional argument]
\begin{enumerate}
\item Bla bla bla.
\item Bla bla bla.
\item Bla bla bla.
\end{enumerate}
\end{theorem}
\lipsum[3-6]
\end{document}

-
Thank you, that is a very interesting list to look at for, ahem, interested third parties. –  Ulrich Schwarz Nov 19 '10 at 14:20
there is another bug (maybe) that is not mentioned: the indentation of the text following a ntheorem environment. The only way to get it not indented is to manually use a \noindent after each environment, which is very annoying. I do not know how to handle this. Otherwise, it is very convenient. –  pluton Nov 21 '10 at 16:24
With ntheorem, if there isn't a blank line after \end{theorem}, the following paragraph will not be indented. On the other hand, amsthm will always indent the following paragraph, regardless of whether it is followed by a blank line or not (this is done by \@endparenv trickery). But this is a feature, not a bug: amsthm considers that a theorem is always a paragraph of its own, so the next one needs to be indented. –  Philippe Goutet Nov 21 '10 at 19:59
It might be worth also making the point the ntheorem conflicts with the AMS document classes was well... –  Seamus Apr 7 '11 at 12:09

ntheorem interferes with amsthm but it provides some compatibility if you specify amsthm as option to ntheorem.

ntheorem is better in handling endmarks like \qed boxes or symbols, especially if an environment ends with a displayed formula and the endmark should be placed in line.

thmtools can be used additionally, it should work with either of the other theorem packages.

To sum up, using thmtools together with ntheorem could be the best choice especially if you need endmarks. Though I prefer amsthm, maybe because I'm used to its \newtheoremstyle macro.

-
Addendum: thmtools offers a key-value-syntax for the declaration of new theorem styles. It also allows for customized lists of theorems. –  lockstep Nov 18 '10 at 18:32
"Used to" is the most polite description I've ever heard with regards to the beast with 9 parameters. :) –  Ulrich Schwarz Nov 18 '10 at 18:42
I am in the middle of the job. Changing to \usepackage[amsmath]{ntheorem} creates 914 errors and stops. It is difficult to resolve conflicts. It should be considered, if it must, at the beginning of the work. –  Peter Jones Sep 24 '11 at 9:52

I like ntheorem together with amsmath a lot. There are some wrinkles, however, which as far as I know have never been addressed. One example that I run into frequently and have learned to just work around: If (like me) you like to put your equation numbers on the left (i.e., using leqno), then you have to put the contents of an equation environment in a split, like this:

$$\begin{split} %% ntheorem kludge 2 + 3 = 5 \end{split}$$


and you have to do the same thing if an equation is the last line of a proof. But other than a few irritations like that, I think ntheorem works very nicely.

-