The floatlib package^{∗}

Andrew D. Lewis

1998/03/05

1 How do I use the floatlib macros?

As the name suggests, floatlib contains some macros for handling floats. The basic functionality is broken into two parts: inputing figures, and making special captions. The captioning is handled by a “style” file. The style mytools is provided with floatlib. You may design your own style mystyle by making a file

\captionstyle capmystyle.sty and loading it with the command \captionstyle{mystyle}. You

can use capmytools.sty as a model. Also, before loading the caption style file,

\newcaptionstyle you should “declare” it with \newcaptionstyle{mystyle}.

1.1 Options and packages required

floatlib can handle two options.

epsfiles If specified this means that the PostScript files will be loaded with the macros provided for this purpose with floatlib.

noepsfiles If you give this option, then the floatlib macros will load none of the corresponding PostScript files. Instead a box with the figure name will be printed in their place. Note, however, that the PostScript file will be loaded by those commands not defined by floatlib!

The default is epsfiles.

1.2 Features for including PostScript files

\cfigure Basically, when you load in a figure, you want to just centre it on the page and be done with it. To do this, use the \cfigure macro. In case you need to do some customisation, you can. The full usage is

     \cfigure[width]{figure}

∗This file has version number v1.0a, last revised 1998/03/05.

Of course width must be a legal TEX dimension, and figure should be a specification of where the PostScript file is located. This file will be loaded with \includegraphics. In case you are not familiar with the full capabilities of \includegraphics, you do not have to specify any kind of an extension to the filename. It will figure it out, and that includes those cases when you have compressed the PostScript file with a .Z or a .gz extension. A handy feature. And, as mentioned above, if you specify the noepsfiles option, the PostScript file will not be loaded by \cfigure.

\ctwofigure Another common request for including PostScript files is to have two figures side-by-side. To facilitate this, I use the macro \ctwofigure. The basic usage is

     \ctwofigure*[space]{figure}

There are now two optional arguments as the * is optional. If the * is specified,

\dblcapwidth the figures are both scaled to the TEX dimension \dblcapwidth. We will see this dimension in Section 1.3 when we discuss captioning. The default value for \dblcapwidth is 0.42\hsize. Feel free to change it as you need. If you give the optional space argument for \ctwofigure then the TEX dimension space will

\capskip separate the two figures. Otherwise they will be separated by \capskip whose default value is 0.04\hsize. Again, change this as you see fit.

1.3 Captioning features

\caption First of all, I changed the basic L^{A}TEX \caption command, although its usage

remains the same. Now the captions will not be full width, but will have width

\capwidth \capwidth whose default value is 0.8\hsize. A long caption will also receive a \capindent hanging indentation of \capindent whose default value is 0.05\hsize. I always

thought the standard L^{A}TEX captions look nasty with long captions. The font for float captions will match that of theorem headers unless you specify otherwise

\captionfont with \captionfont{font} where font specifies the font you want. If you use the procdefs package, an attempt will be made to make the caption font match the theorem header font. So if you set either of these by hand (see the procdefs documentation for how to do this there) you might see some warning messages indicating font mismatches. If you see more than one such message, heed only the last one which might say everything is OK. If you want a different font for theorem headers and captions, ignore all such messages.

dblcaption If one is going to have side-by-side figures, it makes sense to allow side-by-side captions. This is facilitated by the dblcaption environment. Here’s the basic usage.

     \begin{dblcaption}
     \caption{Left caption}\label{left label}\\

\caption{Right caption}\label{right label}

     \end{dblcaption}

\dblcapwidth The captions will each have a width of \dblcapwidth and will be separated by

\capskip \capskip whose default values are given above. The caption headers are given a hanging indent of 0.5\capindent.

2 Implementation

1 ⟨∗package⟩

Options and commands for the options.

2

 3 \newif\if@ADL@epsfiles\@ADL@epsfilestrue
 4 \newcommand\@ADL@epsfiles{\@ADL@epsfilestrue
 5 \PackageWarning{floatlib}{I am compiling optional figures}}
 6 \newcommand\@ADL@noepsfiles{\@ADL@epsfilesfalse
 7 \PackageWarning{floatlib}{I am not compiling optional figures}}
 8 \DeclareOption{epsfiles}{\@ADL@epsfiles}
 9 \DeclareOption{noepsfiles}{\@ADL@noepsfiles}
10 \ProcessOptions

We need graphicx. Also load smallcap if available.

11

12 \RequirePackage{graphicx}
13 \IfFileExists{smallcap.sty}{\RequirePackage{smallcap}}{}

Do some gyrations to see that the the theorem header and float caption fonts agree. Use a bold default header font if possible.

14

15 \def\captionfont#1{\def\@ADLfloat@captionfont{#1}%
16 \@ifundefined{theorem@headerfont}{\relax}
17 {\ifx\theorem@headerfont\@ADLfloat@captionfont%
18 \PackageWarning{floatlib}{Theorem header and caption fonts OK}\else
19 \PackageWarning{floatlib}{Font mismatch in theorem headers and captions}
20 \fi}}
21 \IfFileExists{smallcap.sty}%
22 {\def\@ADLfloat@captionfont{\normalfont\scfamily\bfseries}}
23 {\def\@ADLfloat@captionfont{\normalfont\scshape}}

Here’s the dimensions and their default values.

24

25 \newlength\capwidth\setlength{\capwidth}{0.8\hsize}
26 \newlength\capindent\setlength{\capindent}{0.05\capwidth}
27 \newlength\dblcapwidth\setlength{\dblcapwidth}{0.42\hsize}
28 \newlength\capskip\setlength{\capskip}{0.04\hsize}

Here’s \cfigure with it’s optional width specification. Note that we also handle the case when the noepsfiles option is specified.

29

30 \newcommand\cfigure{\if@ADL@epsfiles\let\@ADL@cfigure\@ADL@@cfigure
31 \else\let\@ADL@cfigure\@ADL@dummycfig\fi\@ADL@cfigure}
32 \def\@ADL@@cfigure{\@ifnextchar[{\@ADL@cfigurewid}{\@ADL@cfigureplain}}
33 \def\@ADL@cfigurewid[#1]#2{%
34 \begin{center}\includegraphics[width=#1]{#2}\end{center}}
35 \newcommand\@ADL@cfigureplain[1]{%
36 \begin{center}\includegraphics{#1}\end{center}}
37 \newcommand\@ADL@dummycfig{\@ifnextchar[{\@ADL@@dummycfig}
38 {\@ADL@@dummycfig[0.4\textwidth]}}

39 \def\@ADL@@dummycfig[#1]{\begin{center}\unitlength=#1
40 \begingroup\@ADL@filereader \@ADL@@@dummycfig}
41 \newcommand\@ADL@@@dummycfig[1]{\xdef\@ADL@filename{#1}\endgroup
42 \begin{picture}(1,1)(0,0)
43 \put(0,0){\framebox(1,1){\normalfont\texttt{\@ADL@filename}}}
44 \end{picture}\end{center}}

Now \ctwofigure with the optional star and the optional separation specification. Again, we need to handle the case when \noepsfiles has been selected.

45

46 \newcommand\ctwofigure{\@ifstar{\@ADL@ctwofigurestar}{\@ADL@ctwofigurenostar}}
47 \newcommand\@ADL@ctwofigurenostar{\if@ADL@epsfiles\let\@ADL@ctwofigure
48 \@ADL@@ctwofigurenostar\else\let\@ADL@ctwofigure\@ADL@dummyctwofig\fi
49 \@ADL@ctwofigure}
50 \newcommand\@ADL@@ctwofigurenostar{\@ifnextchar[{\@ADL@ctwofigurewidnostar}
51 {\@ADL@ctwofigurewidnostar[\capskip]}}
52 \def\@ADL@ctwofigurewidnostar[#1]#2#3{%
53 \begin{center}\includegraphics{#2}\hspace{#1}
54 \includegraphics{#3}\end{center}}
55 \newcommand\@ADL@ctwofigurestar{\if@ADL@epsfiles\let\@ADL@ctwofigure
56 \@ADL@@ctwofigurestar\else\let\@ADL@ctwofigure\@ADL@dummyctwofig\fi
57 \@ADL@ctwofigure}
58 \newcommand\@ADL@@ctwofigurestar{\@ifnextchar[{\@ADL@ctwofigurewidstar}
59 {\@ADL@ctwofigurewidstar[\capskip]}}
60 \def\@ADL@ctwofigurewidstar[#1]#2#3{%
61 \begin{center}\includegraphics[width=\dblcapwidth]{#2}\hspace{#1}
62 \includegraphics[width=\dblcapwidth]{#3}\end{center}}
63 \newcommand\@ADL@dummyctwofig{\@ifnextchar[{\@ADL@@dummyctwofig}
64 {\@ADL@@dummyctwofig[\capskip]}}
65 \def\@ADL@@dummyctwofig[#1]{\begin{center}\unitlength=\dblcapwidth
66 \begingroup\@ADL@filereader \@ADL@@@dummyctwofig{#1}}
67 \newcommand\@ADL@@@dummyctwofig[3]{\xdef\@ADL@fileone{#2}
68 \xdef\@ADL@filetwo{#3}\endgroup
69 \begin{picture}(1,1)(0,0)
70 \put(0,0){\framebox(1,1){\normalfont\texttt{\@ADL@fileone}}}
71 \end{picture}\hspace{#1}
72 \begin{picture}(1,1)(0,0)
73 \put(0,0){\framebox(1,1){\normalfont\texttt{\@ADL@filetwo}}}
74 \end{picture}\end{center}}

This little segment I use for handling filenames with characters which make L^{A}TEX choke. Right now it only handles filenames which have a _. But if you have other characters you need to include, add them to the list in the definition of \@ADL@filereader. For example, if you’d like files with @ in their names go

     \gdef\@ADL@filereader{\@ADL@makeletter\_\@ADL@makeletter\@}

This was the only hard part of this macro package…

75

76 \def\@ADL@makeletter#1{\catcode`#111\relax}
77 \begingroup
78 \catcode`\_11

79 \gdef\@ADL@filereader{\@ADL@makeletter\_}
80 \endgroup

Now the \captionstyle commands. This is modelled on \theoremstyle.

81 \def\captionstyle#1{%
82 \@ifundefined{@ADLcap@#1}{\@warning
83  {Unknown captionstyle `#1'.  Using `mytools'}%
84  \@ADLcaption@style{mytools}}%
85  {\@ADLcaption@style{#1}}%
86  \begingroup
87  \csname @ADLcap@\the\@ADLcaption@style \endcsname
88  \endgroup\csname @ADLcap@\the\@ADLcaption@style \endcsname}

89

90 \newtoks\@ADLcaption@style
91 \@ADLcaption@style{mytools}
92 \def\newcaptionstyle#1{\@namedef{@ADLcap@#1}{\@input@{cap#1.sty}}}
93 \newcaptionstyle{mytools}
94 \captionstyle{mytools}

These commands should be used in the preamble only.

95

96 \@onlypreamble\newcaptionstyle
97 \@onlypreamble\captionstyle

98

Change the parameters for positioning of floats.

99

100 \setcounter{topnumber}{5}
101 \renewcommand\topfraction{0.9}
102 \setcounter{bottomnumber}{1}
103 \renewcommand\bottomfraction{0.3}
104 \setcounter{totalnumber}{10}
105 \renewcommand\textfraction{0.1}
106 \renewcommand\floatpagefraction{0.9}

107 ⟨/package⟩

Now the capmystyle captioning style.

108 ⟨∗capmytools⟩

109

110 \begingroup \makeatletter
111 \@ifundefined{@ADLcaption@style}{\input{floatlib.sty}}{}
112 \ProvidesFile{capmytools.sty}
113  [\ADLfltinfo]

114

115 \gdef\@ADLcap@mytools{%

Here’s where the appearance of the standard captions gets changed (see discussion in Section 1.3.

116

117 \long\def\@makecaption##1##2{
118 \vskip 10pt \small

119 \setbox\@tempboxa\hbox{{\@ADLfloat@captionfont##1.} ##2}
120 \ifdim\wd\@tempboxa>\capwidth
121 \setbox1=\hbox{\hskip\capindent}
122 \begin{center}
123  \parbox[t]{\capwidth}{\noindent\hangindent\wd1\normalfont
124  \hbox{{\@ADLfloat@captionfont##1.}\ } ##2}
125 \end{center}
126 \else
127 \begin{center}
128  {\normalfont{{\@ADLfloat@captionfont##1.}\ } ##2}
129 \end{center}
130 \fi}

Now the side-by-side captioning. This is pretty straightforward, just a bit tedious to get the labelling straight and all that. \@ADL@dblcaptioncr is the action taken when you type \\ inside the dblcaption environment.

131

132 \def\@ADL@dblcaptioncr{\hskip\capskip}

133

134 \def\dblcaption{\trivlist \let\\=\@ADL@dblcaptioncr
135 \let\caption=\@ADL@dblcaption
136 \rightskip\@flushglue\leftskip\@flushglue\parindent\z@\parfillskip\z@\item[]}

137

138 \let\enddblcaption=\endtrivlist

139

140 \def\@ADL@dblcaption{\refstepcounter\@captype
141 \@dblarg{\@ADL@@dblcaption\@captype}}

142

143 \long\def\@ADL@@dblcaption##1[##2]##3{\addcontentsline{\csname
144 ext@##1\endcsname}{##1}{\protect\numberline{\csname
145 the##1\endcsname}{\ignorespaces ##2}}\setbox1=\hbox{\hskip0.5\capindent}
146 \parbox[t]{\dblcapwidth}{\small\noindent\hangindent\wd1\normalfont
147 \hbox{\@ADLfloat@captionfont\csname fnum@\@captype\endcsname.\ }\ignorespaces
148 ##3}}

149 }

150 \endgroup

151

152 ⟨/capmytools⟩