diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/captdef/captdef.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/captdef/captdef.tex | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/captdef/captdef.tex b/Master/texmf-dist/doc/latex/captdef/captdef.tex new file mode 100644 index 00000000000..afa928a4b53 --- /dev/null +++ b/Master/texmf-dist/doc/latex/captdef/captdef.tex @@ -0,0 +1,102 @@ +\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} |