The caption package∗

Harald Axel Sommerfeldt

[email protected]

1995/04/05

Abstract
The caption package provides many ways to customise the captions in
floating environments such figure and table. The \rotcaption command
and the sidewaysfigure and sidewaystable environments provided by the
rotating package from S. Rahtz and L. Barroca are also supported. The
caption package also cooperates with the float package written by A. Lingnau
and the subfigure package written by S.D. Cochran.

1 The user interface

To use this package just type

\usepackage[options]{caption}

in the preamble of your document, where the following options are supported:

normal provides ‘normal’ captions, this is the de-

fault
hang or isu provides captions with hanging indention
center provides captions where each line is centered
centerlast provides captions where the last line of the
paragraph is centered
nooneline if a caption fits on one line on the page,
it will be centered. If you don’t like this
behaviour, just select this option.
scriptsize, . . . , Large sets the font size of the captions
up, it, sl, sc,
md, bf, rm, sf, or tt sets the font attribute of the caption labels.
ruled supports ruled floats of the float package, see
section 1.1 for details

\captionfont To setup the font size and attributes of the captions, this package also provides
\captionlabelfont ∗ This package has version number 1.4b, last revised 1995/04/05.

1
 the commands \captionfont and \captionlabelfont to allow a more flexible
way to customize the captions than the above options could do. \captionfont is
called before each caption, \captionlabelfont is called just before the label of
the caption, so the whole caption will be created as

{\captionfont{\captionlabelfont hlabel i: }hcaptioni} .

Note that these commands are used by the options, e.g. the options small and sf
are identical to

\renewcommand{\captionfont}{\small} and
\renewcommand{\captionlabelfont}{\sffamily} .

\captionmargin Furthermore there is a new length \captionmargin to setup an extra left and
right margin for the captions, e.g. the command

\setlength{\captionmargin}{10pt}

sets this margin to 10pt.

\abovecaptionskip The lengths \abovecaptionskip and \belowcaptionskip contain the amount of
\belowcaptionskip white space to leave above and below the caption. \abovecaptionskip is preset
(in the article, report and book document class) to 10pt, \belowcaptionskip to
0pt.

1.1 The rotating, float and subfigure package

If you want to use this package together with the rotating[1], float[2] and/or the
subfigure package, you have to input this package after the other ones, like

\usepackage{float,rotating,subfigure}
\usepackage[centerlast,small,sc]{caption}

The caption package now redefines the sidewaysfigure and sidewaystable envi-
ronments and the \rotcaption command provided by the rotating package from
S. Rahtz and L. Barroca. Note that the \captionmargin does not affect the
\rotcaption command.
It also redefines the captions of the plain and boxed styled floats provided by the
float package from A. Lingnau. ruled floats are not supported by default, but you
can change this via setting the option ruled. Note that the \captionmargin is
not supported in ruled floats.
If the subfigure package from S.D. Cochran is detected, the options scriptsize,
. . . , large will redefine \subcapsize in an adequate way. If you redefine
\captionfont by yourself and use the subfigure package, you also have to re-
define \subcapsize by yourself. Also the commands \@thesubfigure and
\@thesubtable will be redefined to use the \captionlabelfont command, please
take this into consideration if you redefine \@thesubfigure or \@thesubtable by
yourself. E.g. a adequate version of the second example in subfigure.sty will
be:

\renewcommand{\thesubfigure}{\thefigure.\arabic{subfigure}}

2
 \makeatletter
\renewcommand{\@thesubfigure}{{\captionlabelfont\thesubfigure:}\space}
\renewcommand{\p@subfigure}{}
\makeatother
...

This package cooperates with the version 2.8 (1995/04/02) of the rotating package,
version 1.2c (1995/03/29) of the float package and version 1.6 (1993/05/13) of the
subfigure package, but will hopefully work with future versions, too.

2 Example
Here’s an example figure which was produced with the following code in the pream-
ble of this document:

\usepackage[hang,small,bf]{caption}
\setlength{\captionmargin}{20pt}

EXAMPLE FIGURE

Figure 1: This is an example caption with a small font and a sans serif label.
The hang option was used. There is a left and right margin of 20pt.

3 The code
3.1 Identification
1 \NeedsTeXFormat{LaTeX2e}[1994/06/01]
2 \ProvidesPackage{caption}[1995/04/05 v1.4b caption package (HS)]
3 \typeout{Package: caption v1.4b <1995/04/05> (Harald Sommerfeldt)}

3.2 Initial code

\captionfont \captionsize is defined for backward compatibility with v1.3 of this package.
\captionlabelfont 4 \newcommand{\captionsize}{}
\captionmargin 5 \newcommand{\captionfont}{\captionsize}
6 \newcommand{\captionlabelfont}{}
7 \newlength{\captionmargin}

Here are the different basic types of captions implemented:

\as@normalcaption The ‘normal’ caption
8 \newcommand{\as@normalcaption}[2]{%
9 #1 #2\par}

\as@isucaption The ‘iso’ or ‘hang’ caption; this code was taken from The LATEX Companion[3,
p155] and modified
10 \newcommand{\as@isucaption}[2]{%
11 \sbox{\as@captionbox}{#1\space}%

3
 12 \addtolength{\as@captionwidth}{-\wd\as@captionbox}%
13 \usebox{\as@captionbox}\parbox[t]{\as@captionwidth}{\leavevmode#2}}

\as@centercaption The ‘center’ caption

14 \newcommand{\as@centercaption}[2]{%
15 \parbox[t]{\as@captionwidth}{{\centering#1 #2\par}}}

\as@annecaption The ‘centerlast’ caption; the idea how to do this was taken from Brüggemann-
Klein[4], it is also mentioned in Kopka[5, p227]
16 \newcommand{\as@annecaption}[2]{%
17 \addtolength{\leftskip}{0pt plus 1fil}%
18 \addtolength{\rightskip}{0pt plus -1fil}%
19 \setlength{\parfillskip}{0pt plus 2fil}%
20 #1 #2\par}

\as@shortcaption Short captions are centered by default

21 \let\as@shortcaption\as@centercaption

3.3 Detection of the subfigure package

\as@subcapsize If the subfigure package is loaded, a little message will be typeout and \as@subcapsize
\@thesubfigure – which sets the size of the subcaptions – will be defined. Also \@thesubfigure
\@thesubtable and \@thesubtable will be redefined here to support the \captionlabelfont
in subcaptions, too (thanks to Kevin Ruland for this idea!). If you don’t like
this behaviour, just load the caption package after the subfigure package (and
eventually redefine the \subcapsize by yourself) or redefine \@thesubfigure and
\@thesubtable after loading the caption package as shown in the documentation
of the subfigure package.
22 \ifx\thesubfigure\undefined
23 \newcommand{\as@subcapsize}[1]{}
24 \else%
25 \typeout{\space\space\space\space\space\space\space\space\space
26 ‘subfigure’ package detected}
27 \let\as@subcapsize\subcapsize
28 \renewcommand{\@thesubfigure}{{\captionlabelfont\thesubfigure}\space}
29 \renewcommand{\@thesubtable}{{\captionlabelfont\thesubtable}\space}
30 \fi

3.4 Declaration of options

There are four different types of captions supported: normal, isu, center and
centerlast. hang is exactly the same as isu.
31 \DeclareOption{normal}{\let\as@caption\as@normalcaption}
32 \DeclareOption{isu}{\let\as@caption\as@isucaption}
33 \DeclareOption{hang}{\ExecuteOptions{isu}}
34 \DeclareOption{center}{\let\as@caption\as@centercaption}
35 \DeclareOption{anne}{\let\as@caption\as@annecaption}
36 \DeclareOption{centerlast}{\ExecuteOptions{anne}}

If option nooneline is set, only-one-line captions will behave like normal ones.
37 \DeclareOption{nooneline}{\AtBeginDocument{\let\as@shortcaption\as@caption}}

4
 There are options for six different font sizes available, they also redefine the
\subcapsize provided by the subfigure package (if detected).
38 \DeclareOption{scriptsize}{%
39 \renewcommand{\captionsize}{\scriptsize}
40 \as@subcapsize{\scriptsize}}
41 \DeclareOption{footnotesize}{%
42 \renewcommand{\captionsize}{\footnotesize}
43 \as@subcapsize{\scriptsize}}
44 \DeclareOption{small}{%
45 \renewcommand{\captionsize}{\small}
46 \as@subcapsize{\footnotesize}}
47 \DeclareOption{normalsize}{%
48 \renewcommand{\captionsize}{\normalsize}
49 \as@subcapsize{\footnotesize}}
50 \DeclareOption{large}{%
51 \renewcommand{\captionsize}{\large}
52 \as@subcapsize{\normalsize}}
53 \DeclareOption{Large}{%
54 \renewcommand{\captionsize}{\Large}
55 \as@subcapsize{\large}}
There are nine options available to set the font attributes of the caption labels.
56 \DeclareOption{up}{\renewcommand{\captionlabelfont}{\upshape}}
57 \DeclareOption{it}{\renewcommand{\captionlabelfont}{\itshape}}
58 \DeclareOption{sl}{\renewcommand{\captionlabelfont}{\slshape}}
59 \DeclareOption{sc}{\renewcommand{\captionlabelfont}{\scshape}}
60 \DeclareOption{md}{\renewcommand{\captionlabelfont}{\mdseries}}
61 \DeclareOption{bf}{\renewcommand{\captionlabelfont}{\bfseries}}
62 \DeclareOption{rm}{\renewcommand{\captionlabelfont}{\rmfamily}}
63 \DeclareOption{sf}{\renewcommand{\captionlabelfont}{\sffamily}}
64 \DeclareOption{tt}{\renewcommand{\captionlabelfont}{\ttfamily}}

If the option ruled is set, the captions of ruled floats provided by the float package
will also be supported.
65 \DeclareOption{ruled}{\newcommand\as@ruled{}}

3.5 Execution of options

The ‘normal’ type of caption is preselected.
66 \ExecuteOptions{normal}
67 \ProcessOptions

3.6 Main code

\as@captionbox And now . . . it’s . . . the new \@makecaption code!
\as@captionwidth 68 \newsavebox{\as@captionbox}
\as@makecaption 69 \newlength{\as@captionwidth}
\@makecaption 70 \newcommand{\as@makecaption}[2]{%
71 \setlength{\leftskip}{\captionmargin}%
72 \setlength{\rightskip}{\captionmargin}%
73 \addtolength{\as@captionwidth}{-2\captionmargin}%
74 \captionfont%
75 \sbox{\as@captionbox}{{\captionlabelfont #1:} #2}%

5
 76 \ifdim \wd\as@captionbox >\as@captionwidth
77 \as@caption{{\captionlabelfont #1:}}{#2}%
78 \else%
79 \as@shortcaption{{\captionlabelfont #1:}}{#2}%
80 \fi}
81 \renewcommand{\@makecaption}[2]{%
82 \vskip\abovecaptionskip%
83 \setlength{\as@captionwidth}{\linewidth}%
84 \as@makecaption{#1}{#2}%
85 \vskip\belowcaptionskip}

3.7 Support of the rotating package

\@makercaption If the rotating package is loaded, the command \@makerotcaption (for support
\@makerotcaption of \rotcaption) will be redefined here. The code was taken from the rotating
package [1] itself and adapted.
86 \ifx\@makerotcaption\undefined
87 \else
88 \typeout{\space\space\space\space\space\space\space\space\space
89 ‘rotating’ package detected}
90 % \let\@makercaption\undefined
91 \renewcommand{\@makerotcaption}[2]{%
92 \captionfont%
93 \sbox{\as@captionbox}{{\captionlabelfont #1:} #2}%
94 \ifdim \wd\as@captionbox > .8\vsize
95 \rotatebox{90}{%
96 \setlength{\as@captionwidth}{.8\textheight}%
97 \begin{minipage}{\as@captionwidth}%
98 \as@caption{{\captionlabelfont #1:}}{#2}%
99 \end{minipage}}\par
100 \else%
101 \rotatebox{90}{\usebox{\as@captionbox}}%
102 \fi
103 \hspace{12pt}}
104 \fi

3.8 Support of the float package

\floatc@plain If the float package is loaded, the command \floatc@plain (and the command
\floatc@ruled \floatc@ruled if the option ruled is given) will be redefined here.
105 \ifx\floatc@plain\undefined
106 \else
107 \typeout{\space\space\space\space\space\space\space\space\space
108 ‘float’ package detected}
109 \renewcommand\floatc@plain[2]{%
110 \setlength{\as@captionwidth}{\linewidth}%
111 \as@makecaption{#1}{#2}}
112 \ifx\as@ruled\undefined
113 \else
114 \renewcommand\floatc@ruled[2]{%
115 \setlength{\as@captionwidth}{\linewidth}%
116 \captionfont%
117 \as@caption{{\captionlabelfont #1:}}{#2}}

6
118 \fi
119 \fi

References
[1] Sebastian Rahtz and Leonor Barroca: A style option for rotated objects in
LATEX, 1994/10/02
[2] Anselm Lingnau: An Improved Environment for Floats, 1995/03/25
[3] Michel Goossens, Frank Mittelbach and Alexander Samarin: The LATEX Com-
panion, Addison-Wesley, Reading, Massachusetts, 1994.
[4] Anne Brüggemann-Klein: Einführung in die Dokumentverarbeitung, B.G.
Teubner, Stuttgart, 1989
[5] Helmut Kopka: LATEX– Erweiterungsmöglichkeiten, 3. überarbeitete Auflage,
Addison-Wesley, Bonn, 1991