The caption package^{∗}

Harald Axel Sommerfeldt

axel@hp1.ang-physik.uni-kiel.de Harald Sommerfeldt @ W (MausNet)

1995/10/09

Abstract

The caption package provides many ways to customise the captions in

floating environments such figure, table, sidewaysfigure, and sidewaystable.

The following L^{A}TEX 2ε packages are supported: float, longtable, and subfigure. But it works fine with the following packages as well: floatfig, rotating, supertabular, and wrapfig.

1 Documentation? What documentation?

I’m sorry to say this, but there is no documentation provided with the new version of this package, yet. And it’s still beta. I hope I can eleminate both circumstances in the near future; at the moment my spare time is very very very limited, so I decided to make this beta public. This new version is nearly compatible with the lastest official release (version 1.4b), so you can use the old documentation so far. Here is what differs this version from version 1.4b:

• If the caption package will detect a loaded float package, it will not redefine the boxed style of floats anymore. If you want to have the old behaviour, you have to specify the new option boxed to the caption2 package.

• Anything said about the subfigure package in the old doc isn’t true anymore; the caption package is now adapted to the new version 2.0 of this package. Especially the caption package will not redefine \@thesubfigure and \@thesubtable anymore and it will not set \subcapsize – you have to do this now for yourself if you want to, e.g. with the following code:

    \usepackage[normalsize]{subfigure}
    \usepackage[large]{caption}

So you can load the caption2 package before loading the subfigure package now without problems, in fact this is recommend now. Don’t care about what the old doc or the doc of the subfigure package is telling you!

∗This package has version number 2.0(BETA), last revised 1995/10/09.

As a summary, the new caption package won’t lead into different results of your documents just because of loading it (without options). If you are really interested in the (many!) new features of this totally rewritten package, take a look in the provided test document (test2.tex) to get a idea of the new commands and possibilities. And feel yourself free to write a email to me, if any questions occur.

1.1 Just a few notes…

If you use the new command \setcaptionwidth to set the absolut width of a caption, you are not allowed to change \captionmargin anymore! Instead, use the new command \setcaptionmargin to do this. Longtables will still take care of \LTcapwidth, even if you are setting your own

width via \setcaptionwidth or \setcaptionmargin. To get rid of this, use the

following code just after loading the caption2 package:

     \dummycaptionstyle{longtable}{}

or just specify the new package option longtable. This package was developed and tested with following versions of the other packages:

package version date
float 1.2c 1995/03/29
longtable 3.15  1995/06/15
rotating 2.9  1995/04/07
subfigure 2.0  1995/03/06

Maybe it will work with older versions, maybe not… BTW: If you are interested in rotated versions (like sidewaysfigure or sidewaystable) of new floats (defined with the float package), take a look at the rotfloat package, which comes from a very talented young man with a very german style of writing english docs (if he ever writes any!) and a very big mouth - myself :-)

2 Thanks

I would like to thank David Carlisle for his help writing the longtable support; without the changes in his package this wouldn’t become possible.

3 The (not well documented) code

 1 \NeedsTeXFormat{LaTeX2e}[1994/12/01]
 2 \ProvidesPackage{caption2}[1995/10/09 v2.0 caption package (AS)]
 3 \typeout{Package: caption v2.0(BETA) <1995/10/09> (Harald Sommerfeldt)}
 4 %
 5 % package detection message
 6 \let\caption@message\undefined
 7 \newcommand*\caption@package[1]{%
 8 \ifx\caption@message\undefined
 9  \message{\space\space\space\space\space\space\space\space\space
10  packages detected:}
11  \let\caption@message\empty
12 \fi
13 \message{#1}}

14 %

15 % `internal' stuff
16 \newlength\realcaptionwidth
17 \newsavebox\captionbox

18 %

19 % Code initialisation, `normal' stuff
20 \newcommand*\captionsize{}
21 \newcommand*\captionfont{\captionsize}
22 \newcommand*\captionlabelfont{}
23 \newcommand*\captionlabeldelim{:}
24 \newdimen\captionlabelsep
25 \sbox\captionbox{ }
26 \setlength\captionlabelsep{\wd\captionbox}
27 \newdimen\captionmargin
28 \newdimen\captionwidth
29 % only used by captionstyle `indent', but can be used in user-defines styles
30 \newdimen\captionindent
31 \newif\ifonelinecaptions
32 \newif\iftakecaptionwidth

33 %

34 %\newcommand*\setcaptionfont[1]{%
35 %  \def\captionfont{#1}}
36 %\newcommand*\setcaptionlabelfont[1]{%
37 %  \def\captionlabelfont{#1}}
38 \newcommand*\setcaptionmargin[1]{%
39 \setlength\captionmargin{#1}%
40 \takecaptionwidthfalse}
41 \newcommand*\setcaptionwidth[1]{%
42 \setlength\captionwidth{#1}%
43 \takecaptionwidthtrue}

44 %

45 % \newcaptionstyle, \renewcaptionstyle & \defcaptionstyle
46 \newcommand\newcaptionstyle[2]{%
47 \expandafter\ifx\csname caption@@#1\endcsname\relax
48  \defcaptionstyle{#1}{#2}%
49 \else
50  \PackageError{caption}{Caption style `#1' already defined}{}%
51 \fi}
52 \newcommand\renewcaptionstyle[2]{%

53 \expandafter\ifx\csname caption@@#1\endcsname\relax
54  \PackageError{caption}{Caption style `#1' undefined}{}%
55 \else
56  \defcaptionstyle{#1}{#2}%
57 \fi}
58 \newcommand\defcaptionstyle[2]{%
59 \@namedef{caption@@#1}{#2}}
60 \newcommand*\dummycaptionstyle[2]{%
61 \defcaptionstyle{#1}{%
62  \expandafter\ifx\csname caption@@\caption@style\expandafter\endcsname%
63  \csname caption@@#1\endcsname
64  \PackageError{caption}{You can't use the caption style `#1' directy}{%
65  The caption style `#1' is only a dummy and does not really exists.%
66  \MessageBreak You have to redefine it (with \protect\renewcaptionstyle)
67  before you can select\MessageBreak it with \protect\captionstyle.}%
68  \else
69  #2\usecaptionstyle{\caption@style}%
70  \fi}}

71 %

72 % preimplemented types of captions, all with a label and text,
73 % separated by \captionlabeldelim
74 \newcaptionstyle{normal}{\caption@make{normal}}
75 \newcaptionstyle{center}{\caption@make{center}}
76 \newcaptionstyle{flushleft}{\caption@make{flushleft}}
77 \newcaptionstyle{flushright}{\caption@make{flushright}}
78 \newcaptionstyle{centerlast}{\caption@make{centerlast}}
79 \newcaptionstyle{hang}{\caption@make{hang}}
80 \newcaptionstyle{indent}{\caption@make{indent}}

81 %

82 % \captionstyle
83 \newcommand*\captionstyle[1]{%
84 \expandafter\ifx\csname caption@@#1\endcsname\relax
85  \PackageError{caption}{Undefined caption style `#1'}{}%
86 \else
87  \def\caption@style{#1}%
88 \fi}

89 %

90 % Options
91 \DeclareOption{normal}{\captionstyle{normal}}
92 \DeclareOption{center}{\captionstyle{center}}
93 \DeclareOption{flushleft}{\captionstyle{flushleft}}
94 \DeclareOption{flushright}{\captionstyle{flushright}}
95 \DeclareOption{centerlast}{\captionstyle{centerlast}}
96 \DeclareOption{anne}{\ExecuteOptions{centerlast}}
97 \DeclareOption{hang}{\captionstyle{hang}}
98 \DeclareOption{isu}{\ExecuteOptions{hang}}
99 \DeclareOption{indent}{\captionstyle{indent}}

100 %

101 \DeclareOption{oneline}{\onelinecaptionstrue}
102 \DeclareOption{nooneline}{\onelinecaptionsfalse}

103 %

104 \DeclareOption{scriptsize}{\renewcommand*\captionsize{\scriptsize}}
105 \DeclareOption{footnotesize}{\renewcommand*\captionsize{\footnotesize}}
106 \DeclareOption{small}{\renewcommand*\captionsize{\small}}

107 \DeclareOption{normalsize}{\renewcommand*\captionsize{\normalsize}}
108 \DeclareOption{large}{\renewcommand*\captionsize{\large}}
109 \DeclareOption{Large}{\renewcommand*\captionsize{\Large}}

110 %

111 \DeclareOption{up}{\renewcommand*\captionlabelfont{\upshape}}
112 \DeclareOption{it}{\renewcommand*\captionlabelfont{\itshape}}
113 \DeclareOption{sl}{\renewcommand*\captionlabelfont{\slshape}}
114 \DeclareOption{sc}{\renewcommand*\captionlabelfont{\scshape}}
115 \DeclareOption{md}{\renewcommand*\captionlabelfont{\mdseries}}
116 \DeclareOption{bf}{\renewcommand*\captionlabelfont{\bfseries}}
117 \DeclareOption{rm}{\renewcommand*\captionlabelfont{\rmfamily}}
118 \DeclareOption{sf}{\renewcommand*\captionlabelfont{\sffamily}}
119 \DeclareOption{tt}{\renewcommand*\captionlabelfont{\ttfamily}}

120 %

121 \DeclareOption{boxed}{\AtEndOfPackage{%
122 \ifx\caption@@ruled\undefined
123  \PackageWarningNoLine{caption}{%
124  Option `boxed' is set but there is no `float' package\MessageBreak
125  around here, so this option will be totally ignored}
126 \else
127  \dummycaptionstyle{boxed}{}%
128 \fi}}
129 \DeclareOption{ruled}{\AtEndOfPackage{%
130 \ifx\caption@@ruled\undefined
131  \PackageWarningNoLine{caption}{%
132  Option `ruled' is set but there is no `float' package\MessageBreak
133  around here, so this option will be totally ignored}
134 \else
135  \dummycaptionstyle{ruled}{\onelinecaptionsfalse\setcaptionmargin{0pt}}%
136 \fi}}

137 %

138 \DeclareOption{longtable}{\AtEndOfPackage{%
139 \ifx\caption@@longtable\undefined
140  \PackageWarningNoLine{caption}{%
141  Option `longtable' is set but there is no `longtable' package\MessageBreak
142  around here, so this option will be totally ignored}
143 \else
144  \dummycaptionstyle{longtable}{}%
145 \fi}}

146 %

147 \DeclareOption*{\AtEndOfPackage{%
148 \InputIfFileExists{\CurrentOption.caption}{}{%
149  \PackageError{caption}{File `\CurrentOption.caption' not found}{%
150  You selected the unknown package option `\CurrentOption', so I
151  thought you want to\MessageBreak
152  input the definition file `\CurrentOption.caption' here
153  -- but there is no one!}}}}

154 %

155 \ExecuteOptions{normal,oneline}
156 \ProcessOptions

157 %

158 % \@makecaption
159 \renewcommand\@makecaption[2]{%
160 \vskip\abovecaptionskip

161 \realcaptionwidth\linewidth
162 \def\captionlabel{#1}%
163 \def\captiontext{#2}%
164 \usecaptionstyle{\caption@style}%
165 \vskip\belowcaptionskip}

166 %

167 % Helpers for caption style authors
168 \newcommand*\caption@canterr[1]{%
169 \PackageError{caption}{You can't use \protect#1
170  in normal text}{The usage of \protect#1 is only
171  allowed inside code declared with\MessageBreak \protect\defcaptionstyle,
172  \protect\newcaptionstyle \space or \protect\renewcaptionstyle.}}
173 \newcommand\onelinecaption[2]{%
174 \ifx\captiontext\undefined
175  \caption@canterr{\onelinecaption}%
176 \else
177  \def\caption@temp{#2}%
178  \ifonelinecaptions
179  \sbox\captionbox{#1}%
180  \ifdim\wd\captionbox >\realcaptionwidth
181  \caption@temp
182  \else
183  {\centering\usebox{\captionbox}\par}%
184  \fi
185  \else
186  \caption@temp
187  \fi
188  \let\caption@temp\undefined
189 \fi}
190 \newcommand*\usecaptionmargin{%
191 \ifx\captiontext\undefined
192  \caption@canterr{\usecaptionmargin}%
193 \else
194  \iftakecaptionwidth
195  \leftskip\realcaptionwidth
196  \advance\leftskip by -\captionwidth
197  \divide\leftskip by 2
198  \rightskip\leftskip
199  \realcaptionwidth\captionwidth
200  \else
201  \leftskip\captionmargin
202  \rightskip\captionmargin
203  \advance\realcaptionwidth by -2\captionmargin
204  \fi
205 \fi}
206 \newcommand*\usecaptionstyle[1]{%
207 \ifx\captiontext\undefined
208  \caption@canterr{\usecaptionstyle}%
209 \else
210  \@ifundefined{caption@@#1}%
211  {\PackageError{caption}{Caption style `#1' undefined}{}}%
212  {\@nameuse{caption@@#1}}
213 \fi}

214 %

215 % equal code for normal, center, centerlast, hang, and indent
216 \newcommand*\caption@make[1]{%
217 \usecaptionmargin\captionfont
218 \def\caption@label{%
219  {\captionlabelfont\captionlabel\captionlabeldelim}%
220  \hskip\captionlabelsep}%
221 \onelinecaption{\caption@label\captiontext}%
222  {\@nameuse{caption@@@#1}}}

223 %

224 % the preimplemented caption styles
225 \newcommand*\caption@@@normal{%
226 \caption@label\captiontext\par}
227 \newcommand*\caption@@@center{%
228 \parbox[t]{\realcaptionwidth}{\centering
229 \caption@label\captiontext\par}}%
230 \newcommand*\caption@@@flushleft{%
231 \parbox[t]{\realcaptionwidth}{\raggedright
232 \caption@label\captiontext\par}}%
233 \newcommand*\caption@@@flushright{%
234 \parbox[t]{\realcaptionwidth}{\raggedleft
235 \caption@label\captiontext\par}}%
236 \newcommand*\caption@@@centerlast{%
237 \advance\leftskip by 0pt plus 1fil%
238 \advance\rightskip by 0pt plus -1fil%
239 \parfillskip0pt plus 2fil%
240 \caption@label\captiontext\par}
241 \newcommand*\caption@@@hang{%
242 \sbox\captionbox{\caption@label}%
243 \hangindent\wd\captionbox\noindent
244 \usebox\captionbox\captiontext\par}
245 \newcommand*\caption@@@indent{%
246 \hangindent\captionindent\noindent
247 \caption@label\captiontext\par}

Support of the float package

248 \ifx\floatc@plain\undefined
249 \else
250 \caption@package{float}

251 %

252 % interface float package -> caption package
253 \newcommand\caption@floatc[3]{%
254  \realcaptionwidth\linewidth
255  \def\captionlabel{#2}%
256  \def\captiontext{#3}%
257  \usecaptionstyle{#1}}

258 %

259 % floatstyle plain verwendet jetzt den gesetzten captionstyle
260 \renewcommand\floatc@plain{\caption@floatc{\caption@style}}

261 %

262 % floatstyle boxed auch (kann aber mit \renewcaptionstyle geaendert werden)
263 \dummycaptionstyle{boxed}{\def\captionlabelfont{\bfseries}}
264 \newcommand\floatc@boxed{\caption@floatc{boxed}}
265 % jetzt muessen wir nur noch dafuer sorgen, dass es auch (statt floatc@plain)
266 % in \fs@boxed verwendet wird...

267 \let\caption@boxed\fs@boxed
268 \renewcommand\fs@boxed{\let\floatc@plain\floatc@boxed\caption@boxed}

269 %

270 % floatstyle ruled, dies geht zum Glueck wieder geradeaus
271 \newcaptionstyle{ruled}{{\bfseries\captionlabel} \captiontext\par}
272 \renewcommand*\floatc@ruled{\caption@floatc{ruled}}

273 %

274 \fi

Support of the longtable package

275 \ifx\LT@makecaption\undefined
276 \else
277 \caption@package{longtable}
278 \dummycaptionstyle{longtable}{\setcaptionwidth\LTcapwidth}
279 \renewcommand\LT@makecaption[3]{%
280  \LT@mcol\LT@cols c{\hbox to\z@{\hss\parbox[t]\linewidth{%
281  \realcaptionwidth\linewidth
282  \ifx#1\@gobble
283  \def\captionlabel{}%
284  \def\captionlabeldelim{}%
285  \captionlabelsep\z@
286  \else
287  \def\captionlabel{#2}%
288  \fi
289  \def\captiontext{#3}%
290  \usecaptionstyle{longtable}%
291  \endgraf\vskip\baselineskip}%
292  \hss}}}
293 \fi

Support of the subfigure package

294 \newcommand*\addtosubcaption[1]{}
295 \@ifundefined{@makesubfigurecaption}{}{%
296 \caption@package{subfigure}
\subcapsize
297 \newcommand*\subcapstyle[1]{%
298  \expandafter\ifx\csname caption@@#1\endcsname\relax
299  \PackageError{caption}{Undefined caption style `#1'}{}%
300  \else
301  \def\caption@substyle{#1}%
302  \fi}
 Detection of \caption@substyle.
303 \subcapstyle{normal}
304 \ifsubcaphang
305  \subcapstyle{hang}
306 \fi
307 \ifsubcapcenter
308  \subcapstyle{center}
309 \fi
310 \ifsubcapcenterlast
311  \subcapstyle{centerlast}
312 \fi

NOTE: \subfigcapmargin is not a length, it’s a command. So we make

 \subfigcapwidth also a command!
313 \newif\iftakesubfigcapwidth
314 \newcommand*\subfigcapwidth{0pt}
315 % only used by captionstyle `indent', but can be used in user-defines styles
316 \newlength\subcapindent
\setsubcapmargin
\setsubcapwidth
317 \newcommand*\setsubcapmargin[1]{%
318  \renewcommand*\subcapfigmargin{#1}%
319  \takesubfigcapwidthfalse}
320 \newcommand*\setsubcapwidth[1]{%
321  \renewcommand*\subcapfigwidth{#1}%
322  \takesubfigcapwidthtrue}
323 \renewcommand\@makesubfigurecaption[2]{%
324  \realcaptionwidth\@tempdima
325  \def\captionlabel{#1}%
326  \def\captiontext{#2}%
327  \let\captionfont\subcapsize
328  \let\captionlabelfont\relax
329  \let\captionlabeldelim\empty
330  \captionlabelsep0pt
331  \ifsubcapnooneline\onelinecaptionsfalse\else\onelinecaptionstrue\fi
332  \iftakesubfigcapwidth\takecaptionwidthtrue\else\takecaptionwidthfalse\fi
333  \setlength\captionmargin{\subfigcapmargin}%
334  \setlength\captionwidth{\subfigcapwidth}%
335  \captionindent\subcapindent
336  \hbox{\parbox[t]\@tempdima{\strut\usecaptionstyle{\caption@substyle}}}}
337 \renewcommand*\addtosubcaption[1]{%
338  \let\caption@makesubfigurecaption\@makesubfigurecaption
339  \renewcommand\@makesubfigurecaption[2]{%
340  #1\caption@makesubfigurecaption}
341  \let\@makesubtablecaption\@makesubfigurecaption}}

Cleaning up

342 \ifx\caption@message\undefined
343 \else\message{^^J}\let\caption@message\undefined\fi
344 \let\caption@package\undefined
345 \let\caption@subcapsize\undefined

References

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

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

[3] Harald Axel Sommerfeldt: The rotfloat package, 1995/03/30

[4] Steven Douglas Cochran: The subfigure package, 1995/03/06

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

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

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