The caption package^{∗}

Harald Axel Sommerfeldt axel@hp1.ang-physik.uni-kiel.de

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 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 ⟨label⟩: }⟨caption⟩} .

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 environments 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 redefine \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:

∗This package has version number 1.4b, last revised 1995/04/05.

 \renewcommand{\thesubfigure}{\thefigure.\arabic{subfigure}}
 \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 preamble 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 \captionlabelfont \captionmargin  \captionsize is defined for backward compatibility with v1.3 of this package.
 4 \newcommand{\captionsize}{}
 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 L^{A}TEX Companion[3, p155] and modified

10 \newcommand{\as@isucaption}[2]{%
11 \sbox{\as@captionbox}{#1\space}%
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 \@thesubfigure \@thesubtable If the subfigure package is loaded, a little message will be typeout and \as@subcapsize – which sets the size of the subcaptions – will be defined. Also \@thesubfigure 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}}

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 \as@captionwidth \as@makecaption \@makecaption And now . . . it’s . . . the new \@makecaption code!
68 \newsavebox{\as@captionbox}
69 \newlength{\as@captionwidth}
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}%
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 \@makerotcaption If the rotating package is loaded, the command \@makerotcaption (for support 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 \floatc@ruled If the float package is loaded, the command \floatc@plain (and the command \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}}
118 \fi
119 \fi

References

[1] Sebastian Rahtz and Leonor Barroca: A style option for rotated objects in L^{A}TEX, 1994/10/02

[2] Anselm Lingnau: An Improved Environment for Floats, 1995/03/25

[3] Michel Goossens, Frank Mittelbach and Alexander Samarin: The L^{A}TEX Companion, Addison-Wesley, Reading, Massachusetts, 1994.

[4] Anne Brüggemann-Klein: Einführung in die Dokumentverarbeitung, B.G. Teubner, Stuttgart, 1989

[5] Helmut Kopka: L^{A}TEX– Erweiterungsmöglichkeiten, 3. überarbeitete Auflage, Addison-Wesley, Bonn, 1991