The sidecap package

Rolf Niepraschk (niepraschk@ptb.de)  Hubert Gäßlein

v1.5d – 2000/02/04

Abstract This package defines the new environments SCfigure and SCtable, analogous to figure and table, which make it easy to typeset captions sideways. Additionally, a wide environment is defined; it allows to use the margin

area, e. g., for figures wider than \textwidth.

1 Introduction

In some cases it may be useful to typeset the caption aside the figure or the table. For this purpose the package sidecap defines the new environments SCfigure and SCtable. The figure or the table and the caption are put into two minipages that are positioned side by side and centered as a whole. The space between the minipages is \columnsep. The correct positioning with respect to left and right pages requires at least two compilation runs.

2 Usage

\usepackage[⟨option⟩]{sidecap}
\begin{SCtable}  [⟨relwidth⟩][⟨float⟩] ...  \end{SCtable}
\begin{SCfigure} [⟨relwidth⟩][⟨float⟩] ...  \end{SCfigure}
\begin{SCtable*} [⟨relwidth⟩][⟨float⟩] ...  \end{SCtable*}
\begin{SCfigure*}[⟨relwidth⟩][⟨float⟩] ...  \end{SCfigure*}

⟨option⟩ – outercaption (default): Caption appears left on left pages and right on right pages. innercaption: Caption appears right on left pages and left on right pages. leftcaption, rightcaption: Caption is always on the left or right, respectively. wide: The floating objects may extend into the margin area. raggedright: Better justification for small captions. The ragged2e package is used if available.

⟨relwidth⟩ – optional; caption width relative to the width of the figure or table. A large value (e.g., 50) reserves the maximum width that is possible. Default is 1.0 .

⟨float⟩ – optional; like the floating position parameter of the original table/figure environments. Default is tbp.

3 REQUIRED PACKAGES 2

\begin{wide} ... \end{wide}

The wide environment may be used inside figure and table environments as well as in the normal text.

3 Required packages

This package requires the standard L^{A}TEX package ifthen.

4 Supported packages

This package is compatible L^{A}TEX package hyperref (tested with version 6.69c as of 2000/01/22). If the raggedright package option has been given, then captions will be set with ragged right margin. The ragged2e package will be used if it can be found.

5 The implementation

5.1 Register allocation and auxiliary macros

1 ⟨∗package⟩

2

 3 \RequirePackage{ifthen}

4

 5 \newlength{\SC@BOXWD} \newlength{\SC@CAPWD} \newlength{\SC@tempdim}
 6 \newcounter{SC@C} \newsavebox{\SC@BOX} \newcommand*{\SC@FLOAT}{}
 7 \newcommand*{\SC@IDENT}{SC@\number\value{SC@C}}

8

 9 \newcommand*{\isSC@WIDEi}[2]{#2}  %default: false
10 \newcommand*{\isSC@WIDEii}[2]{#2} %default: false

11

12 \let\SC@caption=\caption \let\SC@label=\label%

13

14 \let\SC@justify=\relax

5.2 Package hyperref compatibility

The following work-around for hyperref is due to Heiko Oberdiek.

15 %% From Heiko Oberdiek, 2000/01/24
16 \newcommand*\@getsecondarg{}% LaTeX-check if already defined
17 \long\def\@getsecondarg#1#2#3\@nil{#2}

18

19 \providecommand*{\getpagenumber}[1]{%
20 \expandafter\@getpagenumber\csname r@#1\endcsname{#1}%

21 }

22

23 \newcommand*{\@getpagenumber}[2]{%
24 \ifx#1\relax
25  \protect\G@refundefinedtrue % LaTeX: rerun warning
26  \@latex@warning{Reference `#2' on page \thepage\space
27  undefined}%
28  0%

5 THE IMPLEMENTATION 3

29 \else
30  \expandafter\@getsecondarg#1\@nil
31 \fi

32 }

33 %%---------------------------------------

Note: The \pageref doesn’t work with hyperref …:-(

34 \newcommand*{\isSC@ODD}[2]{%
35 %  \ifthenelse{\isodd{\pageref{\SC@IDENT}}}{#1}{#2}}
36 \ifthenelse{\isodd{\getpagenumber{\SC@IDENT}}}{#1}{#2}}

5.3 Option processing

37 \DeclareOption{innercaption}{\renewcommand*{\SC@FLOAT}[2]{%
38 \isSC@ODD{{#1}\hspace{\columnsep}{#2}} {{#2}\hspace{\columnsep}{#1}}}}

39

40 \DeclareOption{outercaption}{%
41 \renewcommand*{\SC@FLOAT}[2]{%
42 \isSC@ODD{{#2}\hspace{\columnsep}{#1}} {{#1}\hspace{\columnsep}{#2}}}}

43

44 \DeclareOption{rightcaption}{%
45 \renewcommand*{\SC@FLOAT}[2]{{#2}\hspace{\columnsep}{#1}}}

46

47 \DeclareOption{leftcaption}{%
48 \renewcommand*{\SC@FLOAT}[2]{{#1}\hspace{\columnsep}{#2}}}

49

50 \DeclareOption{wide}{%
51 \renewcommand*{\isSC@WIDEi}[2]{\if@twocolumn #2\else #1\fi}
52 \renewcommand*{\isSC@WIDEii}[2]{#1}}

53

54 \DeclareOption{raggedright}{%
55 \let\SC@justify=\raggedright}

56

57 \ExecuteOptions{outercaption}

58

59 \ProcessOptions

60

61 \ifx\SC@justify\raggedright
62 \IfFileExists{ragged2e.sty}{%
63  \RequirePackage[OriginalCommands]{ragged2e}%
64  \let\SC@justify=\RaggedRight
65  }{}
66 \fi

67

5.4 User-level macros (environments)

SCfigure Simply passes the first (optional) parameter and the required one, in this case ‘figure’, to SC@float . The figure caption should be bottom aligned.

68

69 \newenvironment{SCfigure}{\SC@float[b]{figure}}{\endSC@float}
70 \newenvironment{SCfigure*}{\SC@dblfloat[b]{figure}}{\endSC@dblfloat}

SCtable Simply passes the first (optional) parameter and the required one, in this case ‘table’, to SC@float . The table caption should be top aligned.

72

73 \newenvironment{SCtable}{\SC@float[t]{table}}{\endSC@float}
74 \newenvironment{SCtable*}{\SC@dblfloat[t]{table}}{\endSC@dblfloat}

75

wide This is an environment that allows to extend the width of the text body (or of a floating environment) by using the margin space. It shouldn’t be used in twocolumn text.

76

77 \newenvironment{wide}%
78 {%
79 \setlength{\@tempdima}{\linewidth}
80 \addtolength{\@tempdima}{\marginparwidth}%
81 \addtolength{\@tempdima}{\marginparsep}%
82 \begin{lrbox}{\SC@BOX}% ???
83  \begin{minipage}{\@tempdima}% ???
84 }%
85 {%
86  \end{minipage}% ???
87 \end{lrbox}% ???
88 \stepcounter{SC@C}\SC@label{\SC@IDENT}%
89 \isSC@ODD{\def\SC@hpos{l}}{\def\SC@hpos{r}}%
90 \noindent\makebox[\linewidth][\SC@hpos]{\usebox{\SC@BOX}}%

91 }

92

5.5 Internal macros

5.5.1 Collecting arguments

The new internal float environment, similar/analogous to L^{A}TEX’s @float environment. Syntax: \SC@float[⟨vpos⟩]{⟨name⟩}[⟨relwd⟩][⟨fps⟩]

• Parameter ⟨vpos⟩ (optional) is the vertical positioning of the caption.

• Parameter ⟨name⟩ (required) is the name of the ‘original’ L^{A}TEX floating environment (e.g., ‘figure’ or ‘table’).

• Parameter ⟨relwd⟩ (optional) is the desired relative width of the caption.

• Parameter ⟨fps⟩ (optional) is the usual L^{A}TEX float positioning specifier.

The usual ‘cascading’ programming style is applied (cf. L^{A}TEX’s \@float).

\SC@float Initially, the first optional parameter is checked for.

93 \def\SC@float{\@ifnextchar[\SC@xfloat{\SC@xfloat[c]}}

\SC@xfloat Then the first and second parameters are consumed and the third one is checked for.

94 \def\SC@xfloat[#1]#2{\@ifnextchar[%
95 {\SC@yfloat{#1}{#2}}%
96 {\SC@zfloat{#1}{#2}{1.0}[\@nameuse{fps@#2}]}}

\SC@yfloat Again, the fourth (and last) parameter is checked for.

 97 \def\SC@yfloat#1#2[#3]{\@ifnextchar[%
 98 {\SC@zfloat{#1}{#2}{#3}}%
 99 {\SC@zfloat{#1}{#2}{#3}[\@nameuse{fps@#2}]}}

5.5.2 Capturing the float’s contents

\SC@zfloat Finally, here is the macro that does all the work.

100 \def\SC@zfloat#1#2#3[#4]{%
101 \def\SC@vpos{#1}%
102 \expandafter\edef\csname fps@#2\endcsname{#4}%
103 \def\SC@captype{#2}%
104 \ifx#3\@empty\def\SC@fraction{1}\else\def\SC@fraction{#3}\fi%

The \caption and \label commands must be redefined.

105 \let\SC@CAPtext\@empty \let\SC@OPTCAPtext\@empty \let\SC@LABtext\@empty%
106 \renewcommand\caption[2][]{\gdef\SC@OPTCAPtext{##1}%
107 \gdef\SC@CAPtext{\SC@justify##2}}%
108 \renewcommand\label[1]{\gdef\SC@LABtext{##1}}%
109 \@namedef{fnum@#2}{\mbox{\@nameuse{#2name}~\@nameuse{the#2}}}%

Save the figure or table (or whatever) in a box.

110 \begin{lrbox}{\SC@BOX}%

111 }%

112

\SC@dblfloat Analogous to L^{A}TEX’s \@dblfloat.
113 \def\SC@dblfloat{%
114 \if@twocolumn\let\reserved@a\SC@dbflt\else\let\reserved@a\SC@float\fi
115 \reserved@a}
116 \def\SC@dbflt{\SC@float}

5.5.3 Output the float’s contents

\endSC@float Outputs the figure or table (or whatever) and the caption.

117 \def\endSC@float{%
118 \end{lrbox}%
119 ⟨+debug⟩ \typeout{onecolumn}%
120 \let\isSC@WIDE\isSC@WIDEi%
121 \def\@FLOAT{\@float}\def\end@FLOAT{\end@float}%
122 \isSC@WIDE%
123  {\setlength{\@tempdima}{\textwidth}%
124  \addtolength{\@tempdima}{\marginparwidth}%
125  \addtolength{\@tempdima}{\marginparsep}}%
126  {\setlength{\@tempdima}{\columnwidth}}
127 \endSC@FLOAT{\@tempdima}}%

\endSC@dblfloat Ditto for *-forms of floats.

128 \def\endSC@dblfloat{%
129 \end{lrbox}%
130 ⟨+debug⟩ \typeout{twocolumn}%
131 \let\isSC@WIDE\isSC@WIDEii%
132 \def\@FLOAT{\@dblfloat}\def\end@FLOAT{\end@dblfloat}%
133 \isSC@WIDE%

134  {\setlength{\@tempdima}{\textwidth}%
135  \addtolength{\@tempdima}{\marginparwidth}%
136  \addtolength{\@tempdima}{\marginparsep}}%
137  {\setlength{\@tempdima}{\textwidth}}
138 \endSC@FLOAT{\@tempdima}}%

\endSC@FLOAT Sets the caption width. If caption width plus figure/table width (plus separation space) is too large then the caption width is set equal to the remaining width.

139 \def\endSC@FLOAT#1{%
140 \setlength\SC@tempdim{#1}%
141 % Kann man auf dieses Laengenregister verzichten? (RN) <****>
142 \settowidth\SC@BOXWD{\usebox\SC@BOX}%
143 \setlength\SC@CAPWD{\SC@fraction\SC@BOXWD}%
144 \setlength\@tempdima{\SC@BOXWD}%
145 \addtolength\@tempdima{\SC@CAPWD}%
146 \addtolength\@tempdima{\columnsep}%
147 \ifthenelse{\lengthtest{\@tempdima>\SC@tempdim}}%
148  {\addtolength\SC@CAPWD{-\@tempdima}\addtolength\SC@CAPWD{\SC@tempdim}}{}%

\@FLOAT Calls the L^{A}TEX float command with the two minipages inside a main minipage.

149 \@FLOAT{\SC@captype}%
150  \abovecaptionskip\z@skip
151  \belowcaptionskip\z@skip

Creates a label for each figure or table (etc.) for later determination if the page is odd or even. The counter SC@C must be incremented before.

152  \stepcounter{SC@C}\SC@label{\SC@IDENT}%
\isSC@WIDE
153  \isSC@WIDE%
154  {\ifthenelse{\lengthtest{\@tempdima>\textwidth}}%
155  {\isSC@ODD{\def\SC@hpos{l}}{\def\SC@hpos{r}}}%
156  {\def\SC@hpos{c}}%
157  \setlength{\@tempdimc}{\textwidth}}%
158  {\setlength{\@tempdimc}{\SC@tempdim}\def\SC@hpos{c}}%
159  \makebox[\@tempdimc][\SC@hpos]{%

\SC@FLOAT Has two parameters. The first parameter is the minipage with the caption text inside and the last parameter is the minipage with the body of the figure or table inside.

160  \SC@FLOAT%
161  {\begin{minipage}[\SC@vpos]{\SC@CAPWD}%
162  \ifthenelse{\equal{\SC@OPTCAPtext}{\@empty}}%
163  {\SC@caption{\expandafter\protect\SC@CAPtext}}%
164  {\SC@caption[\expandafter\protect\SC@OPTCAPtext]%
165  {\expandafter\protect\SC@CAPtext}}%
166  \unskip%
167  \ifthenelse{\equal{\SC@LABtext}{\@empty}}%
168  {}{\SC@label{\expandafter\protect\SC@LABtext}}%
169  \end{minipage}}%
170  {\begin{minipage}[\SC@vpos]{\SC@BOXWD}%

171  \offinterlineskip%
172  \kern0pt\relax
173  \usebox{\SC@BOX}%
174  \end{minipage}}%

175 }%

176 \end@FLOAT%

177 } 178 ⟨/package⟩