Are you loading incompatible packages with a template?

Posted on by Lian Tze Lim

(Reader, this is going to be a long, ranty, rambling piece; I apologise beforehand.)

There are LaTeX packages for typesetting all kinds of things. And sometimes, there are more than one LaTeX  packages that can do (almost) the same thing — but are not compatible with each other so you often cannot load them at the same time.

If you had been given a template e.g. for typesetting your report, thesis, conference or journal manuscript, be sure to read through the instructions and example code provided in the .tex file. There may be important information re the specific packages that had already been loaded by the template or class to help you typeset certain elements (e.g. algorithms; code listings; sub-figures or sub-tables) — you should then use the commands and environments provided by these packages (i.e. the packages that the template intend you to use), and avoid loading other packages that provide similar functions.

It would also be good to add \listfiles to the top of the .tex file, and then compile the .tex file. The generated .log file will then contain a list of packages used (and their version numbers), similar to the following:

 *File List*
    book.cls    2023/05/17 v1.4n Standard LaTeX document class
    bk10.clo    2023/05/17 v1.4n Standard LaTeX file (size option)
titlesec.sty    2021/07/05 v2.14 Sectioning titles
 tocloft.sty    2017/08/31 v2.3i parameterised ToC, etc., typesetting
   alltt.sty    2021/01/29 v2.0g defines alltt environment
   ...

Keep a copy of this initial .log file, so that you can refer back to it later, to check which packages are loaded by the template.

For example, you may have heard (or seen a code snippet) that, to typeset subfigures side-by-side, you can load the subfigure package and then use \subfigure commands like this:

\begin{figure}\centering
\subfigure[first caption.]{%
  \includegraphics[width=0.4\textwidth]{example-image}%
  \label{fig:1a}%
}
%
\subfigure[second caption.]{%
  \includegraphics[width=0.4\textwidth]{example-image}%
  \label{fig:1b}%
}
\caption{Main caption}
\end{figure}

…so you happily copy-and-paste this code snippet into your thesis .tex file, and even made sure that you have added \usepackage{subfigure} in your preamble, too. But then you promptly got some glaring compile error messages, when you compile your .tex file. For example (but not limited to):

! LaTeX Error: Command \c@subfigure already defined.
               Or name \end... illegal, see p.192 of the manual.
 
See the LaTeX manual or LaTeX Companion for explanation.
Type H return  for immediate help.
 ...                                              
 
l.113 \newcounter{subfigure}
                            [figure]
! LaTeX Error: Command \l@subfigure already defined.
               Or name \end... illegal, see p.192 of the manual.
 
See the LaTeX manual or LaTeX Companion for explanation.
Type H return  for immediate help.
 ...                                              
 
l.123 ...xxxline{\ext@subfigure}{2}{3.8em}{2.5em}}
! Missing number, treated as zero.
 
                   \unhbox 
l.9 }
! Extra }, or forgotten \endgroup.
\@endfloatbox ...pagefalse \outer@nobreak \egroup 
                                                  \color@endbox 
l.15 \end{figure}
! LaTeX Error: Command \c@lofdepth already defined.
               Or name \end... illegal, see p.192 of the manual.
 
See the LaTeX manual or LaTeX Companion for explanation.
Type H return  for immediate help.
 ...                                              
 
l.124 \newcounter{lofdepth}

In the worst cases your document might not even be able to generate a PDF at all — your compile .log file ends with a disheartened

*** (job aborted, no legal end found)
 
!  ==> Fatal error occurred, no output PDF file produced!

Now if you had that \listfiles added to your .tex file, look at your .log file again for the list of package files used. You now notice that subcaption.sty or subfig.sty was already loaded by your thesis template, by the .cls, .sty or other preamble in your .tex file — and subfigure is not compatible with these packages.

Therefore it is important to be aware of packages that perform similar functions, but that are incompatible with each other, and check which package has been loaded by the class, style file or template you’re using.

…yes I know, this is why LaTeX is hard . You can’t just copy-paste-duct-tape solutions from the internet or ChatGPT and chuck them together — some of them just won’t work together…

The rest of this post will (non-exhaustively) list some common scenarios and packages. Note that I don’t personally recommend any particular package over others (except packages that are marked obsolete on CTAN or have been unmaintained for a very long time). IMHO it’s important to first check if a particular package for a particular function has been loaded by the template/class/style provided to you; and then use only the commands/environments provided by that package. If you disagree with a package choice or think another package should be used instead, I’d recommend contacting the template author/maintainer to discuss further.

Algorithms, pseudocode

To typeset algorithms or pseudocode in LaTeX you can use one of the following options:

Note that you should choose only one of the above groups of packages, and use only the commands and syntax provided by the package you choose. These packages cannot be loaded simultaneously; otherwise you will get lots of errors. This Overleaf help page provides a nice overview about these packages, so we won’t delve further about them here.

Subfigures, subtables (subfloats)

Check the .log file of the template to see if one of memoir.cls, subfigure.sty, subfig.sty, or subcaption.sty has been loaded. If yes: you do not need to load another package for typesetting “subfigures” and “subtables”, but you do need to make sure that the commands you’re using adheres to the command argument syntax provided by the package already loaded. Refer to each relevant section below for example code for each package.

If none of these class or packages had been loaded, you can choose one from them, but I would recommend using the subcaption package, because the subfigure and subfig packages aren’t maintained, and hadn’t been updated in a very long time.

Is memoir.cls loaded?

If so, this class already provides the \subcaption{...caption...}, \subbottom[...caption...]{...body...} and \subtop[...caption...]{...body...} command, after declaring the type of subfloat you need with \newsubfloat{figure} or \newsubfloat{table}. (See section 10.9 of the memoir documentation). You don’t need to load any other packages.

\documentclass{memoir}
\newsubfloat{figure}
...
\begin{document}
\begin{figure}[hbt!]
\centering
\begin{minipage}{.3\textwidth}
  \includegraphics[\width=hsize]{example-image}
  \subcaption{First subfigure\label{subfig:11}}
\end{minipage}
%
\begin{minipage}{.3\textwidth}
  \includegraphics[width=\hsize]{example-image-1x1}
  \subcaption{Second subfigure\label{subfig:12}}
\end{minipage}
 
\caption{Main caption}\label{fig:main1}
\end{figure}
 
\begin{figure}[hbt!]
\centering
  \subbottom[First subfigure\label{subfig:21}]
    {\includegraphics[width=0.3\textwidth]{example-image}}
%
  \subbottom[Second subfigure\label{subfig:22}]
    {\includegraphics[width=0.3\textwidth]{example-image-1x1}}
\caption{Main caption}\label{fig:main2}
\end{figure}
 
Figures \ref{subfig:11} and \ref{subfig:12} ...
figures \ref{subfig:21} and \ref{subfig:22} ...

Using subcaption and subbottom commands from the memoir document class

Note that \subcaption must be used within \minipages or \parbox or similar.

Is subfigure.sty loaded?

If so, use \subfigure[...caption...]{...body...} within the figure environment, or  \subtable[...caption...]{...body...} within your table environment. (subfigure package documentation here)

\begin{figure}[hbt!]
\centering
\subfigure[First subfigure\label{subfig:11}]{%
\includegraphics[width=.3\textwidth]{example-image}
}
%
\subfigure[Second subfigure\label{subfig:12}]{%
\includegraphics[width=.3\textwidth]{example-image-1x1}
}
 
\caption{Main caption}\label{fig:main1}
\end{figure}
 
Figures \ref{subfig:11} and \ref{subfig:12} ...

Using subfigure command from the subfigure package

Is subfig.sty loaded?

If so, use \subfloat[...caption...]{...body...} within your float environment. (subfig package documentation here)

\begin{figure}[hbt!]
\centering
\subfloat[First subfigure\label{subfig:11}]{%
  \includegraphics[width=.3\textwidth]{example-image}
}
%
\subfloat[Second subfigure\label{subfig:12}]{%
  \includegraphics[width=.3\textwidth]{example-image-1x1}
}
 
\caption{Main caption}\label{fig:main1}
\end{figure}
 
Figures \ref{subfig:11} and \ref{subfig:12} ...

Using subfloat from the subfig package

Is subcaption.sty loaded?

If so, use \subfloat[...caption...]{...body...} or \subcaptionbox{...caption...}{...body...} within your environment. Note carefully that the subcaption text is given as an optional argument in square brackets [...] for \subfloat, but as a mandatory argument in curly braces {...} for \subcaptionbox! (subcaption package documentation here)

\begin{figure}[hbt!]
\centering
\subcaptionbox{First subfigure\label{subfig:11}}{%
  \includegraphics[width=.3\textwidth]{example-image}
}
%
\subcaptionbox{Second subfigure...\label{subfig:12}}{%
  \includegraphics[width=.3\textwidth]{example-image-1x1}
}
\caption{Main caption}\label{fig:main1}
\end{figure}
 
\begin{figure}[hbt!]
\centering
\subfloat[First subfigure\label{subfig:21}]{%
  \includegraphics[width=.3\textwidth]{example-image}
}
%
\subfloat[Second subfigure...\label{subfig:22}]{%
  \includegraphics[width=.3\textwidth]{example-image-1x1}
}
\caption{Main caption}\label{fig:main2}
\end{figure}

Using the subfloat and subcaptionbox commands from the subcaption package

Very similar commands, be careful!

By now you have probably noticed that some of these commands share very similar argument syntax:

  • \subbottom[...caption...]{...body...} and \subtop[...caption...]{...body...} from the memoir class;
  • \subfigure[...caption...]{...body...} and \subtable[...caption...]{...body...} from the subfigure package;
  • \subfloat[...caption...]{...body...} from the subfig package;
  • \subfloat[...caption...]{...body...} from the subcaption package.
  • \subcaptionbox{...caption...}{...body...} from the subcaption package. Note curly braces around the caption instead of square brackets, unlike other commands from other packages!!!

So if you ever need to copy existing code from one journal paper/report to another, keep an eye out for the packages that had been loaded in the original LaTeX document, and compare with the packages that are loaded in the new template/skeletal file that you’re copying your code to.

The \subcaptionbox from the subcaption package also has optional arguments for specifying a width for the subcaption, and also for the inner alignment of this box: \subcaptionbox{...caption...}[box width][inner pos]{...body...}

\begin{figure}[hbt!]
\centering
\subcaption{...}{...}
%
\subcaptionbox{Second subfigure...\label{subfig:32}}[.3\textwidth][c]{%
  \includegraphics[width=2cm]{example-image-1x1}
}
\caption{Main caption}\label{fig:main3}
\end{figure}

Or you can use a subcaptionblock environment instead, if that makes things a bit easier to read:

\begin{figure}[hbt!]
\centering
\begin{subcaptionblock}[t]{.3\textwidth}
  \includegraphics[width=\hsize]{example-image}
  \caption{First subfigure}\label{subfig:41}
\end{subcaptionblock}
%
\begin{subcaptionblock}[t]{.3\textwidth}
  \centering
  \includegraphics[width=2cm]{example-image-1x1}
  \caption{Second subfigure...}\label{subfig:42}
\end{subcaptionblock}
 
\caption{Main caption}\label{fig:main4}
\end{figure}

Using extended optional argument for subcaptionbox, and also the subcaptionblock environment

Note that we also used [t] for the subcaptionblocks in Figure 4, to align the subcaptions at the top. The environment name subcaptionblock can also be replaced with subfigure or subtable, depending on whether we’re in a figure or table environment.

Following that last point — since the existence of an environment Env means the commands Env and Endenv are defined, This means you should never copy \subfigure[...caption...]{...body...} or \subtable[...caption...]{...body...} from another LaTeX document that uses the subfigure package, into a document that uses the subcaption package, because the argument syntax for \subfigure and \subtable are different for both packages!

Packages for citations

(Note that “Harvard style” is just a very broad term for author-date styles; it is not really any specific bibliography style. By harvard here I am specifically referring to the harvard.sty LaTeX package.)

The packages cite, natbib, harvard, biblatex are mutually exclusive. Whenever one of them has been loaded, you should not load any of these other packages. Remember also that the BibTeX way (i.e. if using cite or natbib packages) is \bibliographystyle{...}bibliography{...}; but the biblatex way is \usepackage[style=...]{biblatex}\addbibresource{xxx.bib}...\printbibliography.

cite.sty is exclusively used for numerical bibliography styles and citations. If you’re using a journal, conference or thesis template that uses an author-year bibliography style and has loaded natbib.sty, you should not load \usepackage{cite} at all!

Having said that, if natbib has been loaded and a numerical style is in use (with natbib‘s [numbers] option , and you had wanted to load cite so that consecutive numerical citations are compressed: use natbib‘s sort&compress package option instead to enable this behavior. If natbib has been loaded by the .cls or .sty, then write \PassOptionsToPackage{sort&compress}{natbib} before the \documentclass declaration. As for biblatex — check if a -comp version is available for the style that is already in use; e.g. style=numeric-comp.

Do not load harvard and natbib together. The harvard package is compatible only with some author-year bibliography styles; but these styles are all compatible with natbib — so my personal recommendation is to always choose natbib over harvard.

apacite: this package provides the APA6 style for BibTeX, only load it if you need specifically APA6. Do not load cite nor biblatex! You can load natbib package after apacite. But if apacite has already been loaded by the .cls and you prefer to use natbib-style commands \citep and \citet, then use \PassOptionsToPackage{natbibapa}{apacite} before the \documentclass declaration. (If you need APA7, currently the only offering is via biblatex i.e. \usepackage[style=apa]{biblatex}).

By default, biblatex provides the \parencite and \textcite commands, for parenthetical and text citations respectively. If you would like to use the \citep and \citet commands instead, pass the natbib option (not load the natbib package!) to the biblatex package.

Packages for multiple reference lists

Usually there can only be one reference list or bibliography in a LaTeX document. But sometimes you may need more than one — e.g. per-chapter reference lists, or bibliographies by different topics or categories, etc. For BibTeX, chapterbib, bibunits, multibib offer some possibilities, while biblatex‘s refsection or filter mechanisms can achieve similar tasks. These are all covered in this Overleaf help page, so we won’t delve further about them here.

Packages for customising lists

Do not load enumerate and enumitem together. If enumitem has already been loaded by the .cls, but you’d really like to use enumerate‘s shortcut way of saying \begin{enumerate}[a)], you can write  \PassOptionsToPackage{shortlabels}{enumitem} before \begin{document} to enable this syntax with enumitem.

Right! I think that’s gotten most things off my chest now; but the above is by no means exhaustive. I’ll add to this post if some other commonly confused packages comes to mind!

Leave a Reply

Your email address will not be published. Required fields are marked *