captdef.tex

\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}
<earlier text>
\begin{figure}
  <figure stuff>
  \caption{...}
\end{figure}
...
<intervening text>
...
<inline figure stuff>
\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}