An Improved Environment for Floats^{∗}

Anselm Lingnau

          lingnau@tm.informatik.uni-frankfurt.de

1995/03/29

Abstract

This style option improves the interface for defining floating objects such as figures and tables in L^{A}TEX. It adds the notion of a ‘float style’ that governs appearance of floats. New kinds of floats may be defined using a \newfloat command analogous to \newtheorem. This style option also incorporates the functionality of David Carlisle’s style option here, giving floating environments a [H] option which means ‘PUT IT HERE’ (as opposed to the standard [h] option which means ‘You may put it here if you like’).

1 Introduction

Among the features of L^{A}TEX are ‘floating’ figures and tables that drift from where they appear in the input text to, say, the top of a page. The contents and formatting of floats is pretty much up to the user, except that there is a \caption command that governs formatting of the caption — it is centered if it is short, and formatted as a paragraph if it is longer than a single line of text. Sometimes other types of floating objects, e.g., algorithms or programs, are desirable, but they must be defined by analogy to the existing floats since there is no simple command for doing this. This goes beyond the knowledge or inclination of the average L^{A}TEX user.

In this style option, I present an interface to floating objects that attempts to fix some of these shortcomings. First of all, I introduce the notion of a ‘float style’. A float style governs the appearance of a class of floats like a page style governs the appearance of a page (L^{A}TEX has page styles plain, empty and headings, among others). This style option provides some exemplary float styles:

plain This is the float style that L^{A}TEX normally applies to its floats, i.e., nothing in particular. The only difference is that the caption comes out below the body of the float, regardless of where it is given in the text.

boxed The body of the float is printed inside a box. The caption goes below that box.

ruled This float style is patterned on the table style of Concrete Mathematics. The caption is printed at the top of the float, surrounded by rules; another rule finishes off the float.

Program 1.1 The first program. This hasn’t got anything to do with the style but is included as an example. Note the ruled float style.

 #include <stdio.h>
 int main(int argc, char **argv)
 {
        int i;
        for (i = 0; i < argc; ++i)
                printf("argv[%d] = %s\n", i, argv[i]);
        return 0;
 }

To facilitate the definition of new floating objects, float supports the \newfloat command. This command is comparable to \newtheorem in that it allows the user to add a new class of floats at the document level. No style option hacking is necessary. There’s also a \listof command that prints a listing of all the floats of a given type, like \listoffigures and \listoftables in vanilla L^{A}TEX.

2 The User Interface — New Floats

\newfloat The most important command in float is the \newfloat command. As mentioned above, it is patterned on \newtheorem. The \newfloat command takes three required and one optional argument; it is of the form

\newfloat{⟨type⟩}{⟨placement⟩}{⟨ext⟩}[⟨within⟩] ⟨type⟩ is the ‘type’ of the new class of floats, like program or algorithm. After the

appropriate \newfloat, commands like \begin{program} or \end{algorithm*}

will be available. ⟨placement⟩ gives the default placement parameters for this class of floats. The placement parameters are the same as in standard L^{A}TEX, i.e., t, b, p and h for ‘top’, ‘bottom’, ‘page’ and ‘here’, respectively. When L^{A}TEX writes the captions to an auxiliary file for the list of figures (or whatever), it’ll use the job name followed by ⟨ext⟩ as a file name. Finally, the optional argument ⟨within⟩ determines whether floats of this class will be numbered within some sectional unit of the document. For example, if ⟨within⟩=chapter, the floats will be numbered within chapters. (In standard L^{A}TEX, this happens with figures and tables in the report and book document styles.) As an example, Program 1.1 above was created by a command sequence similar to that shown in the following Example.

∗This file has version number v1.2c. Part of this style option is based on the here option by David P. Carlisle (carlisle@cs.man.ac.uk), who also provided helpful criticism.

\begin{matrix}n & \binom{n}{0} & \binom{n}{1} & \binom{n}{2} & \binom{n}{3} & \binom{n}{4} & \binom{n}{5} & \binom{n}{6} & \binom{n}{7} \\ 0 & 1 \\ 1 & 1 & 1 \\ 2 & 1 & 2 & 1 \\ 3 & 1 & 3 & 3 & 1 \\ 4 & 1 & 4 & 6 & 4 & 1 \\ 5 & 1 & 5 & 10 & 10 & 5 & 1 \\ 6 & 1 & 6 & 15 & 20 & 15 & 6 & 1 \\ 7 & 1 & 7 & 21 & 35 & 35 & 21 & 7 & 1 \end{matrix}

Table 1: Pascal’s triangle. This is a re-styled L^{A}TEX table.

     \floatstyle{ruled}
     \newfloat{Program}{tbp}{lop}[section]

… loads o’ stuff …

     \begin{Program}
     \begin{verbatim}

… program text …

     \end{verbatim}

\caption{… caption … }

     \end{Program}

Example 2.1: This is another silly floating Example. Except that this one doesn’t actually float because it uses the [H] optional parameter to appear Here. (Gotcha.)

\floatstyle The \floatstyle command sets a default float style. This float style will be used for all the floats that are subsequently defined using \newfloat, until another \floatstyle command appears. The \floatstyle command takes one argument, the name of a float style. For instance, \floatstyle{ruled}. Specifying a string that does not name a valid float style is an error.

\floatname The \floatname command lets you define the float name that L^{A}TEX uses in the caption of a float, i.e., ‘Figure’ for a figure and so on. For example,

\floatname{program}{Program}. The \newfloat command sets the float name

to its argument ⟨type⟩ if no other name has been specified before.

\floatplacement The \floatplacement command resets the default placement specifier of a

class of floats. E.g., \floatplacement{figure}{tp}.

\restylefloat The \restylefloat command is necessary to change styles for the standard float types figure and table. Since these aren’t usually defined via \newfloat, they don’t have a style associated with them. Thus you have to say, for example,

  \floatstyle{ruled}
  \restylefloat{table}

to have tables come out ruled. The command also lets you change style for floats that you define via \newfloat, although this is, typographically speaking, not a good idea. See table 1 for an example.

\listof The \listof command produces a list of all the floats of a given class. Its syntax is

\listof{⟨type⟩}{⟨title⟩} ⟨type⟩ is the float type given in the \newfloat command. ⟨title⟩ is used for the title of the list as well as the headings if the current page style includes them. Otherwise, the \listof command is analogous to the built-in L^{A}TEX commands

\listoffigures and \listoftables.

3 The User Interface — [H] Placement Specifier

Many people find L^{A}TEX’s float placement specifiers too restrictive. A Commonly Uttered Complaint (CUC) calls for a way to place a float exactly at the spot where it occurs in the input file, i.e., to not have it float at all. It seems that the [h] specifier should do that, but in fact it only suggests to L^{A}TEX something along the lines of “put the float here if it’s OK with you”. As it turns out, L^{A}TEX hardly ever feels inclined to actually do that. This situation can be improved by judicious manipulation of float style parameters.

The same effect can be achieved by changing the actual method of placing floats. David Carlisle’s here option introduces a new float placement specifier, namely [H], which, when added to a float, tells L^{A}TEX to “put it HERE, period”. If there isn’t enough space left on the page, the float is carried over to the next page together with whatever follows, even though there might still be room left for some of that. This style option provides the [H] specifier for newly defined classes of floats as well as the predefined figures and tables, thereby superseding here. David suggests that the here option be withdrawn from the archives in due course.

The [H] specifier may simply be added to the float as an optional argument, like all the other specifiers. It may not be used in conjunction with any other placement specifiers, so [Hhtbp] is illegal. Neither may it be used as the default placement specifier for a whole class of floats. The following table is defined like this:

     \begin{table}[H]
     \begin{tabular}{cl}
     \tt t & Top of the page\\

… more stuff …

(It seems that I have to add some extraneous chatter here just so that the float actually comes out right in the middle of a printed page. When I L^{A}TEXed the documentation just now it turned out that there was a page break that fell exactly between the “So now” line and the float. This wouldn’t Prove Anything. Bother.) So now we have the following float placement specifiers:

t Top of the page
b Bottom of the page
p Page of floats
h Here, if possible
H Here, definitely

Index

The italic numbers denote the pages where the corresponding entry is described, numbers underlined point to the definition, all others indicate the places where it is used.

F

\floatname . . . . . . . . 3
\floatplacement . . . . 3
\floatstyle . . . . . . . . 3

L \listof . . . . . . . . . . . 3

N \newfloat . . . . . . . . . 2

R

                                                   \restylefloat . . . . . . 3