\documentclass[a4paper]{article} \usepackage[a4paper]{geometry} \usepackage{miscdoc} \usepackage[scaled=0.85]{luximono} \begin{document} \title{The \Package{captdef} package} \author{Robin Fairbairns\thanks{Email: \emph{rf10@cam.ac.uk}}} \maketitle \section{Why this package?} \LaTeX{} provides a command (\cs{caption}) for adding a caption to a float environment (that is to say, a \texttt{figure} or a \texttt{table}, ``out of the box''). The command is a good one, and many users want to use it. Often, they end up using a float environment, in a case where it's not strictly necessary, and get entangled in the positioning problems that floats pose for the innocent user. Using this package, the user can have standard-looking captions without the need of a float environment. This package defines a means of defining caption commands, which creates things that look as if they were created by \cs{caption}, and which work outside of a float. The \textsf{float} package provides an alternative to \cs{captdef}-defined commands, in the float \texttt{[H]} option (``place the environment \emph{here} without doing any of this floating stuff''). So why use \Package{captdef}?\,---\,its great advantage is simplicity; you load it, and it defines just \emph{three} macros, while \textsf{float} defines lots and lots. (Of course, if you need others of \textsf{float}'s capabilities, \textsf{captdef} loses its advantage\dots). \section{How the package works} The package defines a command \begin{quote} \cmdinvoke*{DeclareCaption}{command}{counter} \end{quote} which creates a `caption'-like command, which uses \texttt{counter} for its numbering. The package then goes on to declare the commonly-needed caption commands \cs{figcaption} and \cs{tabcaption}: \begin{quote} \cmdinvoke{captdef}{\cs{figcaption}}{figure}\\ \cmdinvoke{captdef}{\cs{tabcaption}}{table} \end{quote} \section{The potential problem} Commands defined by \cs{captdef} place a caption in text, and also step the \environment{figure} (or \environment{table} or whatever) counter. The float environments do the same. Now, consider the sequence: \begin{quote} \begin{verbatim} \begin{figure}
\caption{...} \end{figure} ... ... \figcaption{...} \end{verbatim} \end{quote} and suppose the \environment{figure} environment doesn't fit anywhere between where it's specified and the inline figure (so that it will float to somewhere later). We will then see a document with \begin{quote} \meta{earlier text}\\ \dots\\ \meta{intervening text}\\ \dots\\ \meta{inline figure stuff}\\ Figure \meta{n+1}: \dots\\ \dots\\ \meta{yet more text}\\ \dots\\ \meta{figure stuff}\\ Figure \meta{n}: \dots \end{quote} That is, the figure numbers have got out of order, because the floating figure was specified before the inline figure. \LaTeX{} won't do this when everything is specified as a float: it keeps floats of the same type in order (which is why floats stack up if a single one won't fit). The moral of that little tale is to say: don't use \cs{captdef}-defined commands with floats of the same type in the same document. (Or be extra-specially careful about what's happening if you must.) \end{document}