Chapter 6. Mastering Floats

Documents would be easier to read if all the material that belonged together was never split between pages. However, this is often technically impossible and TeX will, by default, split textual material between two pages to avoid partially filled pages. Nevertheless, when this outcome is not desired (as with figures and tables), the material must be “floated” to a convenient place, such as the bottom or the top of the current or next page, to prevent half-empty pages.

This chapter shows how “large chunks” of material can be kept conveniently on the same page by using a float object. We begin by introducing the parameters that define how LaTeX typesets its basic figure and table float environments, and we describe some of the packages that make it easy to control float placement (Section 6.2). We then continue by explaining how you can define and use your own floating environments (Section 6.3.1), or, conversely, how captioning commands can be used to enter information into the list of figures and tables for nonfloating material (Section 6.3.2). Then methods for rotating the content of a float are described (Section 6.3.3).

It is often visually pleasing to include a “picture” inside a paragraph, with the text wrapping around it. Various packages have been written to achieve this goal more or less easily; in Section 6.4 we look at two of them in some detail.

The final section addresses the problem of customizing captions. There is a recognized need to be able to typeset the description of the contents of figures and tables in many different ways. This includes specifying sub-figures and sub-tables, each with its own caption and label, inside a larger float.

Many float-related packages have been developed over the years and we cannot hope to mention them all here. In fact, the packages that we describe often feature quite a few more commands than we are able to illustrate. Our aim is to obtained in a given framework. In each case consulting the original documentation will introduce you to the full possibilities of a given package.

topnumber Counter specifying the maximum number of floats allowed at the top of the page (the default number is 2). This can be changed with the setcounter command.

bottomnumber Counter specifying the maximum number of floats allowed at the bottom of the page (the default number is 1). This can be changed with setcounter.

totalnumber Counter specifying the maximum number of floats allowed on a single page (the default number is 3). This can be changed with setcounter.

opfraction Maximum fraction of the page that can be occupied by floats at the top of the page (e.g., 0.2 means 20% can be floats; the default value is 0.7). This can be changed with enewcommand.

ottomfraction Maximum fraction of the page that can be occupied by floats at the bottom of the page (the default value is 0.3). This can be changed with enewcommand.

extfraction Minimum fraction of a normal page that must be occupied by text (the default value is 0.2). This can be changed with enewcommand.

floatpagefraction Minimum fraction of a float page that must be occupied by floats, thus limiting the amount of blank space allowed on a float page (the default value is 0.5). This can be changed with enewcommand.

dbltopnumber Analog of topnumber for double-column floats in two-column style (the default number is 2). This can be changed with setcounter.

dbltopfraction Analog of opfraction for double-column floats on a two-column page (the default value is 0.7). This can be changed with enewcommand.

dblfloatpagefraction Analog of floatpagefraction for a float page of double-column floats (the default value is 0.5). This can be changed with enewcommand.

floatsep Rubber length specifying the vertical space added between floats appearing at the top or the bottom of a page (the default is 12pt plus 2pt minus 2pt for 10pt and 11pt document sizes, and 14pt plus 2pt minus 4pt for 12pt document size). This can be changed with setlength.

extfloatsep Rubber length specifying the vertical space added between floats, appearing at the top or the bottom of a page, and the text (the default is 20pt plus 2pt minus 4pt). This can be changed with setlength.

intextsep Rubber length specifying the vertical space added below and above a float that is positioned in the middle of text when the h option is given (the default is similar to floatsep). This can be changed with setlength.

dblfloatsep Rubber length that is the analog of floatsep for double-width floats on a two-column page (the default is like floatsep). This can be changed with setlength.

dbltextfloatsep Rubber length that is the analog of extfloatsep for double-width floats on a two-column page (the default is like extfloatsep on a text page, but is 8pt plus 2fil on a page that contains only floats). This can be changed with setlength.

opfigrule Command to produce a separating item (by default, a rule) between floats at the top of the page and the text. It is executed immediately before placing the extfloatsep that separates the floats from the text. Like the footnoterule, it must not occupy any vertical space.

otfigrule Same as opfigrule, but put after the extfloatsep skip separating text from the floats at the bottom of the page.

dblfigrule Similar to opfigrule, but for double-column floats.

Changing the values of these parameters lets you modify the behavior of LaTeX’s algorithm for placing floats. To obtain the optimal results, however, you should be aware of the subtle dependencies that exist between these parameters.

The problem of half-empty float pages

If you use the default values in a document you will observe that, with many floats, the formatted document will contain several float pages—that is, pages containing only floats. Often such pages contain a lot of white space. For example, you may see a page with a single float on it, occupying only half of the possible space, so that it would look better if LaTeX had filled the remaining space with text. The reason for this behavior is that the algorithm is designed to try placing as many dangling floats as possible after the end of every page. The procedure creates as many float pages as it can until there are no more floats left to fill a float page. Float page production is controlled by the parameter floatpagefraction, which specifies the minimum fraction of the page that must be occupied by float(s)—by default, half the page. In the standard settings every float is allowed to go on a float page (the default specifier is tbp), so this setting means that every float that is a tiny bit larger than half the page is allowed to go on a float page by itself. Thus, by enlarging its value, you can prevent half-empty float pages.

However, enlarging the value of floatpagefraction makes it more difficult to produce float pages. As a result, some floats may be deferred, which in turn prevents other floats from being placed. For this reason it is often better to specify explicitly the allowed placements (for example, by saying egin{figure}[tb]) for the float that creates the problem.

Another common reason for ending up with all floats at the end of your chapter is use of the bottom placement specifier, [b]. It indicates that the only acceptable place for a float is at the bottom of a page. If your float happens to be larger than ottomfraction (which is by default quite small), then this float cannot be placed. This will also prevent all floats of the same type from being placed. The same problem arises if only [h] or [t] is specified and the float is too large for the remainder of the page or too large to fit opfraction.

In calculating these fractions, LaTeX will take into account the separation (i.e., extfloatsep) between floats and main text. By enlarging this value, you automatically reduce the maximum size a float is allowed to have to be considered as a candidate for placement at the top or bottom of the page.

In general, whenever a lot of your floats end up at the end of the chapter, look at the first ones to see whether their placement specifiers are preventing them from being properly placed.

The float placement algorithm prefers to put floats at the top of the page, even if it means placing them before the actual reference. This outcome is not always acceptable but there is no easy cure for this problem short of substantially changing LaTeX’s algorithm. The flafter package (by Frank Mittelbach) makes this change, thereby ensuring that floats are never placed before their references.

Sometimes, less drastic solutions might be preferred. For example, if the float belongs to a section that starts in the middle of a page but the float is positioned at the top of the page, the float will appear as if it belongs to the previous section. You might want to forbid this behavior while still allowing floats to be placed on the top of the page in other situations. For this purpose LaTeX offers you the following command.

The optional argument placement can be either t or b. If the command suppressfloats is placed somewhere in the document, then on the current page any following floats for the areas specified by placement are deferred to a later page. If no placement parameter is given, all remaining floats on the current page are deferred. For example, if you want to prevent floats from moving backward over section boundaries, you can redefine your section commands in the following way:

Possible arguments to @startsection are discussed in Section 2.2.2.

Another way to influence the placement of floats in LaTeX is to specify a ! in conjunction with the placement specifiers h, t, and b. The placement of floats on float pages is not affected by this approach. This means that for this float alone, restrictions given by the settings of the parameters described earlier (e.g., extfraction) are ignored. Thus, such a float can be placed in the designated areas as long as neither of the following two restrictions is violated:

• The float fits on the current page; that is, its height plus the material already contributed to the page does not exceed extheight.

• There are no deferred floats of the same type.

All other restrictions normally active (e.g., the number of floats allowed on a page) are ignored. For example, if you specify [!b] this float can be placed on the bottom of the page even if it is larger than the maximum size specified by ottomfraction. Also, any suppressfloats commands are ignored while processing this float.

Algorithm to determine allowed placement

The order of the given specifiers is irrelevant, and all specifiers should be given at most once. For example, [bt] is the same as [tb] and thus does not instruct LaTeX to try to place the float at the bottom and only then try to place it on the top. LaTeX always uses the following order of tests until an allowed placement is found:

1. If ! is specified, ignore most restrictions as described above and continue.

2. If h is specified, try to place the float at the exact position. If this fails and no other position was specified, change the specifier to t (for a possible placement on the next page).

3. If t is specified, try to place it on the top of the current page.

4. If b is specified, try to place it on the bottom of the current page.

5. If p is specified, try to place it on a float page (or float column) when the current page (or column) has ended.

6. Steps 3 and 4 are repeated if necessary at the beginning of each subsequent page, followed by Step 5 at its end.

[h] does not mean “here”

Sometimes you will find that LaTeX’s float placement specifiers are too restrictive. You may want to place a float exactly at the spot where it occurs in the input file—that is, you do not want it to float at all. It is a common misunderstanding that specifying [h] means “here and nowhere else”. Actually, that specifier merely directs LaTeX to do its best to place the float at the current position. If there is not enough room left on the page or if an inline placement is forbidden because of the settings of the style parameters (see Section 6.1), then LaTeX will ignore this request and try to place the float according to any other specifier given. Thus, if [ht] is specified, the float will appear on the top of some later page if it does not fit onto the current one. This situation can happen quite often if the floats you try to place in the middle of your text are moderately large and are thus likely to fall into positions where there is not enough space on the page for them. By ignoring an h and trying other placement specifiers, LaTeX avoids overly empty pages that would otherwise arise in such situations.

In some cases you might prefer to leave large gaps on your pages. For this reason the package float provides you with an [H] specifier that means “put the float here”—period. It is described in Section 6.3.1.

For example, you could redefine the sectioning command and introduce the FloatBarrier command in its definition inside the @startsection command (see Section 2.2.2), as shown here:

The author of placeins anticipated that users might often want to output their floats before a new section starts, so his package provides the package option section, which automatically redefines section to include the FloatBarrier command. However, by itself this option forces all floats to appear before the next section material is typeset, since the FloatBarrier prevents a float from a current section from appearing below the start of the new section, even if some material of the current section is present on the same page.

Turning the barrier into a membrane

If you want to allow floats to pass the FloatBarrier and appear at the bottom of a page (i.e., in a new section), specify the option below. To allow floats to pass it in the opposite direction and appear on the top of the page (i.e., in the previous section), specify the option above.

When using the option verbose the package shows processing information on the terminal and in the transcript file.

Preventing floats at the end of the document

Sometimes LaTeX’s float positioning mechanism gets overloaded, and all floating figures and tables drift to the end of the document. You may flush out all the unprocessed floats by issuing a clearpage command, but this tactic has the effect of making the current page end prematurely. The afterpage package allows you to issue the command afterpage{clearpage}. It will let the current page be filled with text (as usual), but then a clearpage command will flush out all floats before the next text page begins.

Floating multipage tables

With the multipage longtable environment (see Section 5.4.2), you can experience problems when typesetting the text surrounding the long table, and it may be useful to “float” the longtable. However, because such tables can be several pages long, it may prove impossible to hold them in memory and float them in the same way that the table environment is floated. Nevertheless, if the table markup is in a separate file (say ltfile.tex) you can use one of the following commands:

The first form lets text appear on the same page at the end of the longtable. The second ensures that the surrounding text starts again on a new page.

The afterpage command can be combined with the float package and the [H] placement specifier, as explained at the end of Section 6.3.1.

The endfloat package features a series of options to control the list of figures and tables, their section headings, and the markers left in the text. A list of available options follows.

figlist/nofiglist Produce (default) or suppress the list of figures.

tablist/notablist Produce (default) or suppress the list of tables.

lists/nolists Produce or suppress the list of figures and the list of tables (shorthand for the combination of the previous two option sets).

fighead/nofighead Produce or omit (default) a section heading before the collection of figures. The section headings text is given by figuresection and defaults to the string “Figures”.

tabhead/notabhead Produce or omit (default) a section heading before the collection of tables. The section headings text is given by ablesection and defaults to the string “Tables”.

heads/noheads Produce or omit a section heading before the collection of figures and before the collection of tables (shorthand for the combination of the previous two option sets).

markers/nomarkers Place (default) or omit markers in text.

figuresfirst/tablesfirst Put all figures before tables (default), or vice versa.

Hooks

The package offers the hooks AtBeginFigures, AtBeginTables, and AtBeginDelayedFloats to control the processing of the collected floats. For instance, the instruction AtBeginTables{cleardoublepage} ensures that the delayed tables will start on a recto page.

When the floats are finally typeset, the command efloatseparator is executed after each float. By default, it is defined to be clearpage, which forces one float per page. If necessary, it can be redefined with enewcommand.

Float markers in text

By default, the package indicates the original position of a float within the text by adding lines such as “[Figure 4 about here.]” at the approximate place. These notes can be turned off by specifying the nomarkers option when loading the package. The text and the formatting of the notes, which are defined via the commands figureplace and ableplace, can be changed with enewcommand. For example, they might be adapted to a different language (the package does not support babel parameterization). A sample redefinition for French could look as follows:

Within the replacement text hepostfig and heposttbl reference the current figure or table number, respectively. Such redefinitions can, for example, be put in the package configuration file endfloat.cfg that, if present, is loaded automatically by the package (with the usual caveat of nonportability).

Premature output

By default, the delayed floats are processed when the end of the document is reached. However, in some cases one might wish to process them at an earlier point—for example, to display them at the end of each chapter. For this purpose endfloat offers the command processdelayedfloats, which will process all delayed floats up to the current point. The float numbering will continue by default, so to restart numbering one has to reset the corresponding counters (details are given in the package documentation).

Caveats

The endfloat package file creates two extra files with the extensions .fff and .ttt for storing the figure and table floats, respectively. As the environment bodies are written verbatim to these files, it is important that the end command, (e.g., end{figure}), always appears on a line by itself (without any white space) in the source document; otherwise, it will not be recognized. For the same reason the standard environment names (i.e., figure, table, and their starred forms) will be recognized only if they are directly used in the document. If they are hidden inside other environments recognition of the environment end tag will fail.

By default, nonstandard float environments, such as the sidewaysfigure and sidewaystable environments of the rotating package, are not supported. It is possible, however, to extend the endfloat package to recognize such environments as well. As an example the distribution contains the file efxmpl.cfg, which extends endfloat to cover the environments of the rotating package. To become operational it should be included (copied) into endfloat.cfg so that its code is automatically loaded.

The float package offers ways to define new float types and also provides one way to prevent individual floats from floating at all. A different approach to the latter problem is given by the caption package.

The last two packages described in this section, rotating and rotfloat, allow the rotation of the float content, something that might be necessary for unusually large float objects.

The ewfloat command takes four arguments, three mandatory and one optional, with the following meanings:

type “Type” of the new class of floats, such as program. Issuing a ewfloat declaration will make the environments type and type* available.

placement Default placement parameters for the given class of floats (combination of LaTeX’s t, b, p, and h specifiers or, alternatively, the H specifier).

ext File name extension of an auxiliary file to collect the captions for the new float class being defined.

within Optional argument specifying whether floats of this class will be numbered within some sectional unit of the document. For example, if the value of within is equal to chapter, the floats will be numbered within chapters (in standard LaTeX, this is the case for figures and tables in the report and book document classes).

The style of the float class

The floatstyle declaration sets a default float style that will be used for all float types that are subsequently defined using ewfloat, until another floatstyle command is specified. Its argument is the name of a float style, and should be one of the following predefined styles:

plain The float style LaTeX usually applies to its floats—that is, nothing in particular. The only difference is that the caption is typeset below the body of the float, regardless of where it is given in the input markup.

plaintop Same style as the plain float style except that the caption is placed at the top of the float.

boxed The float body is surrounded by a box with the caption printed below.

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

Only one caption supported

The float styles define the general layout of the floats, including the formatting of the caption. For example, the ruled style sets the caption flush left without a colon, while other styles center the caption and add a colon after the number. Because the float styles define the placement of the caption, floats can contain only a single caption command which is a restriction compared to standard LaTeX’s behavior. One also has to be careful when mixing different float styles in one document so as not to produce typographic monsters.

Even though the package does not offer a user-level interface for defining new float styles, it is fairly easy to add new named styles. For details refer to the package documentation in float.dtx.

The next example shows the declarations for two “nonstandard” new float types, Series and XMLexa. The former are numbered inside sections and use a “boxed” style, and the latter are numbered independently and use a “ruled” style (typographically this combination is more than questionable).

Naming the float class

The introductory string used by LaTeX in the captions of floats for a given type can by customized using the declaration floatname{type}{floatname}. “XML Listing” is used for XMLexa floats in the example below. By default, a ewfloat command sets this string to its type argument if no other name is specified afterwards (shown with the Series float environment in the example).

Listing the captions of a float class

The command listof{type}{title} produces a list of all floats of a given class. It is the equivalent of LaTeX’s built-in commands listoffigures and listoftables. The argument type specifies the type of the float as given in the ewfloat command. The argument title defines the text of the title to be used to head the list of the information associated with the float elements, as specified by the caption commands.

The following example is a repetition of Example 6-3-1 on the preceding page (source only partially shown) with two listof commands added.

Customizing LaTeX’s standard float types

LaTeX’s two standard float types figure and table cannot be given a float style using ewfloat, as they already exist when the float package is loaded. To solve this problem the package offers the declaration estylefloat{type}, which selects the current float style (specified previously with a floatstyle declaration) for floats of this type.

For the same reason there exists the floatplacement{type}{placement} declaration, which can be used to change the default placement specifier for a given float type (e.g., floatplacement{table}{tp}). In the following example, both figure and table have been customized (not necessarily for the better) to exhibit the usage of these declarations.

Place a float “here”

Modeled after David Carlisle’s here package, the float package adds the [H] placement specifier which means “place the float Here regardless of any surrounding conditions”. It is available for all float types, including LaTeX’s standard figure and table environments. The [H] qualifier must always be used on a stand-alone basis; e.g., [Hbpt] is illegal.

If there is not enough space left on the current page, the float will be printed at the top of the next page together with whatever follows, even if there is still room left on the current page. It is the authors’ responsibility to place their H floats in such a way that no large patches of white space remain at the bottom of a page. Moreover, one must carefully check the order of floats when mixing standard and [H] placement parameters. Indeed, a float with a [t] specifier, for example, appearing before one with an [H] specifier in the input file might be incorrectly positioned after the latter in the typeset output, so that, for instance, Figure 4 would precede Figure 3.

In combination with the placeins and afterpage packages described in Sections 6.2.1 and 6.2.2, respectively, an even finer control on the placement of floats is possible. Indeed, in some cases, although you specify the placement parameter as [H], you do not really mean “at this point”, but rather “somewhere close”. This effect is achieved by using the afterpage command:

The FloatBarrier command ensures that all dangling floats are placed first at a suitable point (due to afterpage without producing a huge gap in the text), thereby solving the sequencing problem, described above. The [H] float is then immediately placed afterwards. If you use clearpage instead of FloatBarrier, it would come out on top of the next page instead.

This command works analogously to LaTeX’s caption command, but takes an additional mandatory argument to denote the float type it should mimic. It can be used for any nonfloating material that should get a (numbered) caption whose text will also be added into the list of figures or list of tables. The starred form suppresses both the number and the “List of...” entry.

Watch out for incorrect numbering

The following example shows a normal figure and its nonfloating variant used together. In such a case there is always the danger that a floating figure will travel past its nonfloating counterparts. In the example we force this situation by pushing the floating figure to the bottom of the page. As a result, the numbering gets out of sync. One has to watch out for this problem when mixing floating and nonfloating objects.

¹ In fact, its original release predates the development of the graphics interface. It was later reimplemented as an extension of this interface.

The rotating package implements two environments, sidewaysfigure and sidewaystable, for turning whole floats sideways. These environments automatically produce page-sized floats, or more exactly column-sized floats (if used in twocolumn mode). Starred forms of these environments, which span both columns in twocolumn mode, exist as well.

By default, the floats are turned in such a way that they can be read from the outside margin, as you can see in the next example. If you prefer your floats to be always turned in the same way, you can specify one of the package options figuresright or figuresleft.

The package also defines a number of environments for rotating arbitrary objects, such as turn or rotate (to rotate material with or without leaving space for it); see Section 10.3.4. Directly relevant to floats is the sideways environment, which enables you to turn the float body while leaving the caption untouched. It is used in the following example, which also exhibits the result of the figuresright option (which, despite its name, acts on sidewaysfigure and sidewaystable).

Instead of turning the whole float or the float body, it is sometimes more appropriate to turn only the caption. This ability is supported by the rotating package through the otcaption command. Unfortunately, the layout produced by this command is hard-wired but can be customized through the caption package whose features are discussed in Section 6.5.1.

The rotfloat package offers identical options to the rotating package. Internally, for every float type, rotfloat defines an additional environment with the name sidewaystype and its corresponding starred form. For instance, when you write

four environments become available: XMLexa, XMLexa*, sidewaysXMLexa, and sidewaysXMLexa*. Similarly, the commands for redefining the table or figure environments, for example,

will restyle not only the table and table* environments, but also the environments sidewaystable and sidewaystable*.

As a consequence of this processing model, it is relatively easy to implement a float mechanism in which floats span the full width of the page or at least the full width of individual columns. Unfortunately, it is nearly impossible to have floats that occupy only parts of a text column and have the text flow around them. The reason being that when the paragraphs are broken into lines, their final positions are not yet known. It is therefore impossible to direct the paragraph builder to leave holes for the float objects if a later part of the process will decide on their final placement. In contrast, placing floats at the top or the bottom of a page (or column) only directs the output routine to chop off less material from the assembled galley without otherwise manipulating the galley content.

Because of this processing model, the production of inline floats with text flowing around the float object has to take place during the paragraph-generating phase. The best outcome that packages can currently achieve is to ensure that the inline floats do not fall off the page (by measuring the amount of material already assembled on the galley to decide whether there is enough space to fit in the inline float with its surrounding paragraph(s)).

Such an algorithm is, for example, implemented by the wrapfig package. Because the package’s inline floats only “float” very little in comparison to standard floats, mixing both types can result in the float numbering getting out of sequence.¹ Most relevant packages leave the placement decisions completely to the user because the automatic solution comes out wrong in many cases, so that it is not worth supplying it in the first place.

¹ In theory, one could do better and properly synchronize both types, although the coding would probably be quite difficult.

For this book we have chosen a total of three packages that are representative of what is available in this area. We have already discussed one such package (picinpar) in Section 3.1.14; two more are introduced here. The wrapfig package supports figures and tables and offers some support for automatic placement. The picins package allows precise control over the placement of inline figures and for this particular task can be quite interesting. Unlike other packages in this area, it does not support inline tables.

All packages have some problems so that it might be worthwhile to explore other possibilities such as floatflt by Mats Dahlgren (an extension of the floatfig package by Thomas Kneser), which works together with the multicol package. A good starting point to look for other packages is Graham Williams’ TeX online catalogue [169].

The wrapfigure and wraptable environments have two mandatory and two optional arguments with the following meanings:

nlines (optional) The number of narrow lines needed for the float (normally calculated automatically). Each display equation counts as three lines.

placement Horizontal placement of the float, specified as one of the following letters: r or R (right side of the text), and l or L (left side of the text). There is no option for centering the float. For a two-sided document, the placement can alternatively be specified via i or I (inside edge) and o or O (outside edge). This refers to the inside and outside of the whole page, not to individual columns. In each case the uppercase variant allows the figure or table to float, while the lowercase variant puts it “exactly here”.

overhang (optional) Overhang of the float into the margin (default 0pt).

width Width of the figure or table. Specifying 0pt has a special meaning, such that the “natural width” will be used as the wrapping width. The caption is then typeset to the wrapping width. If the figure is wider than the space allotted, an “overfull box” will be generated and the figure or table contents can overwrite the wrapping text.

LaTeX will wrap surrounding text around the figure or table, leaving a gap of intextsep at the top and bottom and columnsep at the side, thereby producing a series of shortened text lines beside the figure. The size of the hole made in the text is the float width plus columnsep minus the overhang value.

LaTeX calculates the number of short lines needed based on the height of the figure and the length intextsep. This guess may be overridden by specifying the first optional argument (nlines), which is the desired number of shortened lines. It can be useful when the surrounding text contains extra vertical spacing that is not accounted for automatically.

Our first example shows a wrapped table, 4 cm wide and placed at the left side of the paragraph. The package calculated a wrapping of 5 lines, which would have left a lot of empty space below the caption, so we explicitly selected 4 lines of wrapping instead. The figure is referenced using LaTeX’s standard label and ef commands.

The wrapfigure and wraptable environments should not be used inside another environment (e.g., list). They do work in twocolumn page layout (provided the column width is wide enough to allow inline floats).

Generally LaTeX will not be able to move wrapfigure and wraptable environments to their optimal places, so it is up to you to position them in the best fashion. It is best to wait to do so until just before printing your final copy, because any changes to the document can ruin their careful positioning. Information about float processing by wrapfig is written to the log file if you specify the verbose option. Here are some rules for good placement:

• The environments should be placed so as to not run over a page boundary and must not be placed in special places like lists.

• Only ordinary text should have to flow past the figure but not a section title or large equations. Small equations are acceptable if they fit.

• It is convenient to place egin{wrapfigure} or egin{wraptable} just after a paragraph has ended. If you want to start in the middle of a paragraph, the environment must be placed between two words where there is a natural line break.

Our second example displays a figure that is set to its natural width (last argument 0pt), but extends 20% into the left margin (specified by the optional argument). Instead of using the special unit width, denoting the natural float width in this case, one can, of course, use some explicit dimension such as 30pt. The effect of this choice can be clearly seen by looking at the way the paragraph text is typeset below the picture when the text wrapping ends. As the example also shows, wrapping continues even across paragraph boundaries if necessary.

The formatting of the caption can be influenced by combining wrapfig with packages like caption, although an option like centerlast may not be the appropriate choice in narrow measures.

In the preceding example we specified an overhang length explicitly. The overhang width can also be specified globally for all wrapfig environments by setting the wrapoverhang length with LaTeX’s setlength command to a non-zero value. For example, to have all wrap figures and tables use the space reserved for marginal notes, you could write

New “wrapping” environments for additional float types (as defined via the float package) with the same interface and behavior as wrapfigure or wraptable may be easily added, or directly invoked, using the wrapfloat environment:

You can find other ways to fine-tune the behavior of wrapfig by reading the implementation notes at the end of the wrapfig.sty package file.

w,h (optional) Width and height of the picture. The text lines that flow around the picture are set in a paragraph whose lines are shorter than the text width by an amount w. The height h is used to calculate the number of lines of text that will flow in this manner.

If the argument is not specified, the actual picture size (“bounding box”) is used, if it can be calculated by LaTeX. Otherwise, an error results.

x-o,y-o (optional) The x and y offsets of the picture with respect to the upper-left corner of its bounding box (positive x-o yields a displacement to the right; positive y-o moves the picture downward). If the argument is absent, the picture is positioned using the pos specification.

opt (optional) Placement and box characteristics of picture, given as a pair of one positional and one frame specifier.

The positional specifiers are l (left) picture at left of paragraph and r (right) picture at right of paragraph.

The frame specifiers are d (dash) picture surrounded by dashed lines; f (frame) picture surrounded by full lines; o (oval) picture frame with rounded corners; s (shadow) picture surrounded by shadow box; and x (box) picture surrounded by “three-dimensional” box. When no option is specified, the picture is placed at the left of the paragraph.

pos (optional) Position of the picture inside its frame, given as one horizontal specifier, one vertical specifier, or a pair of horizontal and vertical specifiers. Possible horizontal specifiers are l (left) picture at left of frame and r (right) picture at right of frame. If no horizontal specifier is given, the picture is centered horizontally in its frame.

Possible vertical specifiers are t (top) picture at top of frame and b (bottom) picture at bottom of frame. If no vertical specifier is given, the picture is centered vertically in its frame.

If the offset argument x-o,y-o is present, the pos argument is ignored.

pict The source of the picture. It can be any LaTeX construct.

The following examples show various ways to place a picture inside a paragraph. We also introduce some other commands provided by the picins package to fine-tune the visual presentation of the typeset result.

We start by using picins’s default setting, where the width and height of the contents are automatically calculated. In that case the “picture” is placed at the left of the paragraph. This paragraph has a normal indentation: if this effect is not desired, one has to start it with oindent. The second part of the example pulls in an Encapsulated PostScript (EPS) picture and lets text flow around it. In this case the natural dimensions of the picture are read from the BoundingBox comment in the EPS source file. We added a dashed frame for more clarity.

We can specify the dimensions of the picture ourselves, so that LaTeX will use these parameters in its typesetting calculations, and will not try to use the intrinsic information associated with the source. If no offsets or position parameters are given, the content is centered (first picture). On the second picture we shift the content 2mm to the right and 14mm down. There the “dr” argument produces a dashed frame and places the picture to the right.

Controlling the hole

A picskip{nlines} command instructs LaTeX to continue to typeset the paragraph for nlines lines at the given indentation (as though the picture extended downward for that many lines). A zero value for nlines means that the following lines no longer need to be indented and that a new paragraph must start. The horizontal space between the paragraph text and the picture can be controlled through the pichskip command.

Perhaps the results produced by the offset in the previous example were somewhat surprising. For this reason the next example studies its effects in some detail. If we specify an offset of 0mm,0mm the “picture” is placed with its reference point at the top-left corner of the area reserved for the picture. As most LaTeX constructs produce a box with the reference point at the left of the bottom baseline, the “picture” is effectively placed outside the intended area—that is, in a completely different place than it would be without any offset at all.

You can use the parpic inside list environments at any depth. This is in contrast to other packages in this area, which often restrict the placement of pictures within lists. The following example features an itemize list with embedded parpic commands. It also shows how line thickness (linethickness), length of the dashes (dashlength), and depth of the shade (shadowthickness) and the 3-D effect (oxlength) can all be controlled separately.

One can generate numbered captions for the pictures that will appear in LaTeX’s “List of Figures”. As the pictures do not float, one has to be careful when mixing them with ordinary floats to avoid out-of-sequence numbering. To specify a caption text you use the command piccaption, which takes the same arguments as the standard caption command but only stores them for use with the next parpic.

For our first example we typeset the contents of a picture inside a framed shadow box, with the caption appearing outside the frame and below the picture. This corresponds to the default positioning for caption material. There is a space of 6mm between picture and text as specified with the pichskip command.

The default caption placement can be explicitly requested with the declaration piccaptionoutside. The package offers three other placement options that can be selected piccaptioninside, piccaptionside, and piccaptiontopside. Their effects are shown in the next example. Even though picins uses its own command to specify the caption text, it is possible to influence the caption formatting by loading a package such as caption. We prove this by setting the caption label in bold sans serif font.

We then examine the subfig and subfloat packages, which introduce substructures for float objects. The section concludes with a discussion of the sidecap package (placing captions beside the float body) and the fltpage package (for generating full-page floats whose captions are placed on the opposite page).

This standard LaTeX command is only defined inside a float environment. It increments the counter associated with the float in question. If present, the optional argument short-text goes into the list of figures or tables. If only the mandatory argument text is specified, then it is used in those lists. If the caption is longer than one line, you are strongly advised to use the optional argument to provide a short and informative description of your float. Otherwise, the list of figures and tables may become unreadable and it may be difficult to locate the necessary information. In fact, LaTeX allows multi-paragraph captions only if the short-text argument is present. Otherwise, you will get a “Runaway argument?” error.

The following example shows how standard LaTeX typesets captions. Compare this layout to the customization provided by the various packages discussed in the next sections. Note how the optional argument of the second caption command defines what text appears for that figure in the “List of Figures”.

Internally, caption invokes the command @makecaption{label}{text}. The label argument is the sequence number of the caption and some text like “Figure”; it is generated internally depending on the type of float. The text argument is passed on from the mandatory caption argument; it is the text to be typeset. The default definition for the part responsible for the typesetting of a caption looks something like this:

After an initial vertical space of size abovecaptionskip (default often 10pt), the material is typeset in a temporary box @tempboxa, and its width is compared to the line width. If the material fits on one line, the text is centered; if the material does not fit on a single line, it will be typeset as a paragraph with a width equal to the line width. Thereafter, a final vertical space of elowcaptionskip (default typically 0pt) is added, finishing the typesetting. The actual implementation that you find in the standard classes uses lower-level commands to speed up the processing so it looks somewhat different.

You can, of course, define other ways of formatting your captions. You can even supply different commands for making captions for each of the different types of floats. For example, the command @makefigcaption can be used instead of @makecaption to format the captions for a figure environment.

This approach requires fairly low-level programming and is not very flexible, so it is normally better to use a package like caption (described below) to do this work for you.

Rather than force you to write your own code for customizing captions, we invite you to read the following pages, which describe a few packages that offer various styles to typeset captions.

¹ The caption package is, in fact, a completely rewritten version of Axel’s caption2 package and makes the latter obsolete. Axel advises all users of caption2 to upgrade to caption as soon as possible and, if needed, to modify their LaTeX sources accordingly.

Like the geometry package, the caption package uses the extended option concept (based on the keyval package), in which options can take values separated from the option name by an equals sign. In most cases there exists a default value for an option; thus, you can specify the option without a value to produce this default behavior.

The customization possibilities of the caption package cover (nearly) all aspects of formatting and placing captions, and we will introduce them below. For those users who need even more customization, the package offers an interface to add additional option values (representing special formattings). One can even add additional options, a functionality used, for example, by the subfig package described in Section 6.5.2.

Customizing the general shape

The first set of options we examine here are those that influence the overall shape of the caption:

singlelinecheck If the whole caption (including the label) fits on a single line, center¹ it (keyword true). With the keyword false, such captions are formatted identically to multiple-line captions.

¹ Or do something else with it.

format This option defines the overall shape of the caption (except when overwritten by the previous option). With the keyword default, you will get a typical “standard LaTeX” format, that is, the label and the caption text are set as a single block. Absent any further customization by other options, the label and the text are separated by a colon and space, and the caption is set justified to full width.

As an alternative, the keyword hang specifies that the caption should be set with the label (and separation) to the left of the caption text. In other words, continuation lines are indented by the width of the label.

margin, width By default, the caption occupies the whole width of the column (or page). By specifying either a specific width or a margin, you can reduce the measure used for the caption. In either case the caption is centered in the remaining space. Thus, with the current implementation, it is not possible to specify different values for left and right (or inner and outer) margins.

indention If set to a given dimension, this option specifies an additional indention for continuation lines (e.g., on top of any indention already produced by the hang keyword).

Customizing the fonts

If you look at the previous example, you will notice that with this particular layout the space between box and caption appears very tight. Options for adjusting² such spaces are discussed on page 312. First, however, we look at options for adjusting the fonts used within the caption, which are always working.

² However, in some float styles, such as “boxed”, they are hard-wired and cannot be changed.

font This option defines the font characteristics for the whole caption (label and text) unless overwritten. This option can take a comma-separated list of keyword values to specify the font family (rm, sf, or tt), font series (md or bf), font shape (up, it, sl, or sc), or font size (scriptsize, footnotesize, small, normalsize, large, or Large). If more than one keyword is used, then the list must be surrounded by braces to hide the inner comma from being misinterpreted as separating one option from the next (see the example below). Keywords for the same font attribute (e.g., the font shape) overwrite each other, but those for different attributes have the expected combined effect. To set the font attributes to their default settings use the keyword default.

labelfont While the option font defines the overall font characteristics, this option specifies the (additional) attribute values to use for the caption label.

textfont This option is like labelfont but is used for the caption text. In the next example we use it to reset the font series from boldface to medium.

Customizing the label further

Another frequent requirement is the customization of the layout for the caption label, such as by replacing the default colon after the label by something else, or omitting it altogether. Also, the separation between label and text may require adjustments. Both can be achieved with the following options and their keywords.

labelformat With this option a format for the label can be selected. Out of the box the following keywords can be used: simple (label string, e.g., “Figure” and the number following each other and separated by a nonbreakable space), parens (number in parentheses), and empty (omit the label including the number altogether). The results of these keywords are shown in several examples in this chapter. Additional keywords for alternative formattings can be defined using the DeclareCaptionLabelFormat declaration, as explained on page 313.

labelsep This option specifies the separation between the label and the text. Available keywords are colon, period, space, and newline, which have the expected meanings. New keywords producing other kinds of separations can be defined using the declaration DeclareCaptionLabelSeparator; see the package documentation for more details.

Paragraph-related customizations

The actual formatting of the caption text within the general shape, such as the justification, can be customized using the following two options:

justification This option specifies how the paragraph should be justified. The default is full justification (keyword justified). Using the keyword centering results in all lines being centered. The raggedleft and raggedright keywords produce unjustified settings with ragged margins at the indicated side.

If the ragged2e package is additionally loaded, you can use the keywords Centering, RaggedLeft, and RaggedRight, thereby employing the commands from that package that are described in Section 3.1.12. Two other special justifications are available: centerfirst centers the first line and fully justifies the rest (with parfillskip set to zero), whereas centerlast works the opposite way, centering the last line. Both shapes are sometimes requested for captions, but in most circumstances they produce questionable results.

Further specialized justification set-ups can be defined using the declaration DeclareCaptionJustification as described in the documentation.

parskip This option controls the separation between paragraphs in multiparagraph captions. It expects a dimension as its value. Recall that captions with several paragraphs are possible only if the optional caption argument is present!

Customizing the spacing around the caption

The final set of options deal with the position of the caption with respect to the float body. Note that none of these settings actually moves the caption in the particular place (you have to do that manually, or use a float style from the float package to do it for you). They only affect the space being inserted.

aboveskip Space between the caption and float body—for example, “above” the caption if caption is the placed at the bottom. It typically defaults to 10pt.

belowskip Space on the opposite side of the caption—that is, away from the float body. It is 0pt in most standard classes.

position Specifies that the caption is placed above the float body (keyword top) or below the float body (keyword bottom; the default). It does not place the caption there. That is still your task (or that of a package such as float).

Be careful with the meanings of the options

Note that the names aboveskip and belowskip give the wrong implications: they do not describe physical places, but rather are swapped if the caption is marked (using position) as being placed on the top. This is quite different from the parameters abovecaptionskip and elowcaptionskip in LaTeX’s default implementation of the caption command (see page 307) which do describe their physical place in relation to the caption! For some float package styles setting these options may have no effect.

An option list as specified in the previous example may not be to everyone’s liking. In addition, it only allows us to customize the captions of all floats in the document regardless of their type. Sometimes, however, the captions for tables may need a different treatment than those for figures, for instance. In such a case the captionsetup declaration will help.

The captionsetup declaration allows you to specify an option-value-list like the one possible when loading the package itself. The difference is that, if used with the optional type argument, this declaration specifies caption formatting for only this particular float type (e.g., figure) or any float type that has been set up with a ewfloat declaration from the float package.

Further assistance is available in the form of the DeclareCaptionStyle declaration. It associates an option/value list with a name that can later be referred to as the value of a style option. The mandatory long-style argument is a list of option/value pairs that describe the formatting of a caption if the style name is selected. The optional short-style argument lists option/value pairs that are also executed whenever the caption is determined to be “short” (i.e., if it would fit on a single line).

It is possible to combine the style option with other options inside the argument of captionsetup, as shown in the next example. There we select the style default (predefined) for all floats except figures but overwrite its setting for labelfont. Note that the example is intended to show possibilities of the package—not good taste.

This declaration defines or redefines a labelformat keyword name to generate code to format the label, where code takes two arguments: #1 (a string like “Figure”) and #2 (the float number). Thus, to produce parentheses around the whole label, you can define your own parens keyword as follows:

While this approach would work well in all examples seen so far, the above definition nevertheless contains a potential pitfall: if #1 is empty for some reason (e.g., if you changed figurename to produce nothing), the above definition would put a space in front of the number. To account for situations like this the caption package offers the othIfFirst command.

The othIfFirst command tests whether first is non-empty and, if so, typesets both first and second. Otherwise, it typesets nothing. With its help the above declaration can be improved as follows:

As a second example, suppose you want your caption labels to look like this: “(4) Figure”. You could set up a new format, named parensfirst, and later assign it to the labelformat:

In a similar fashion you can add new keywords for use with the labelsep using the DeclareCaptionLabelSeparator declaration.

After a DeclareCaptionLabelSeparator the keyword name refers to code and can be used as the value to the labelsep option. For example, if you want to have a separation of one quad between the label and the text that should be allowed to stretch slightly, you can define

and then use it as labelsep=widespace in the argument of captionsetup or DeclareCaptionStyle.

Providing new caption shapes and justifications

In addition to customizing the label format, you can define your own general caption shapes using DeclareCaptionFormat, or specialized justification settings using DeclareCaptionJustification. These are more specialized extensions and their internal coding is a bit more difficult, so we will not show an example here. If necessary, consult the package documentation.

External configuration files

Such declarations can be made in the preamble of your documents. Alternatively, if you are using the same settings over and over again, you can place them in a configuration file (e.g., mycaption.cfg) and then load this configuration as follows:

While it is possible to combine the config option with other options, it is probably clearer to specify additional modifications through a captionsetup declaration in the preamble.

Continuing captions across floats

Sometimes figures or tables are so large that they will not fit on a single page. For such tables, the longtable or supertabular package may provide a solution. For multipage figures, however, no packages for automated splitting are available.

In the past a general solution to this problem was provided through the captcont package written by Steven Cochran, which supports the retention of a caption number across several float environments. Nowadays this functionality is readily available with the caption package. It provides the command ContinuedFloat, to be used before issuing the caption command if the current caption number should be retained.

If you prefer that the continued caption not to appear in the “List of...” list, use caption with an empty optional argument (see Example 6-5-13 on page 321), or caption*, which suppresses LOF entry and caption number.

The caption package collaborates smoothly with the other packages described in this chapter, as can be observed in the various examples. Note that in some cases this package has to be loaded after the packages whose captioning style one wants to modify.

The package is based on the caption package, discussed in the previous section, and makes use of all its features for customizing the layout of captions.¹ The main user command to identify a sub-float object within a float is subfloat.

¹ An earlier version of this package was known as subfigure. It had a number of customization possibilities in common with the caption2 package by Axel Sommerfeldt, but differed in some important details. When caption2 was upgraded, the author of this book persuaded Steven to base a new version of his code on the emerging caption package. The results are described in this section.

The mandatory object argument specifies the sub-float content, the optional caption argument denotes the caption text for this object, and, if necessary, the optional list-entry argument specifies an alternate form to be used in the list of figures (or tables). If no optional argument is provided, no caption (and no caption label) is produced. If you wish to get only an (alpha)numeric label, use an empty caption argument.

An empty list-entry signifies that for this instance the caption text should not be inserted in the “List of...”. This special feature is relevant only if the sub-float captions should be listed there in the first place: see page 320 for information on creating this set-up.

Our first example shows a figure that features two subfloat components. To reference them, you must associate labels with each of these subfloat commands (be careful to put the label commands inside the braces enclosing the contents of the subfloat). We also place a label following the caption command to identify the enclosing figure environment, so that outside the environment we can refer to each of the components separately.

Because the subfig package is based on caption, it is possible to influence the caption layouts for sub-floats using the options offered by the latter package. If it is not already loaded, subfig loads the caption package without any options. This means you have to either load caption first (as we did in the example below) or customize it after loading subfig by using a captionsetup declaration.

The default setting of the subfig package

As you can see, options for customizing the caption layouts can be set on various levels. Some default settings are already in place when the subfig package is loaded. Most noticeably, a setting of font=footnotesize for all sub-float captions accounts for the fact that our setting of sf when loading the caption package has no effect on the sub-captions. Another default that can be deduced is the use of parens with the labelformat option. But most other changes to the main caption layout are inherited by the sub-floats.

Customizing all sub-captions

To overwrite such defaults, you can use any of the caption options when loading the subfig package, or you can specify them with a captionsetup declaration using the type “subfloat” (as shown in the example). This will change all subsequent sub-float captions uniformly until they are overwritten by a further declaration.

Customizing sub-captions by type

Finally, if you want to customize sub-float captions just for a particular 〈type〉 of float (e.g., for all figures) you can do so by using sub 〈type〉 instead of subfloat in the captionsetup declaration.

Spacing around sub-floats

The subfig package offers a number of customization possibilities through a set of additional options (not available with the caption package) that expect a dimension as their value. They define the space produced around a sub-float. Assuming the default caption position below the object (i.e., position=bottom), we get a layout like that shown in Figure 6.1.

farskip Specifies the space left on the side of the sub-float that is opposite the main float caption (e.g., on top if the main caption is at the bottom of the float). This space is ignored if it is the first object in the float body. The default value if not modified is 10pt.

nearskip Specifies the space left on the side of the sub-float nearer the main caption to separate the sub-float object and its caption from surrounding material. It defaults to 0pt.

captionskip Specifies the vertical space that separates the sub-float object and its caption (default 4pt). If there is no caption, this space is not added.

topadjust Not applicable with position=bottom on the sub-float level. If the sub-caption is placed above the sub-float object (i.e., Figure 6.1 flipped upside down using position=top) this space is added to the captionskip used to separate caption and sub-float body.

The caption is set to the width of the sub-float object reduced on both sides by the value specified with the margin option already provided by caption package.

If the caption is placed above the sub-float object (i.e., using position=top for the sub-float), then captionskip is increased by topadjust to allow for adjusting the separation between the caption and the object in this case. Also, note that the position of farskip and nearskip depends on the placement of the main caption. When it comes first (i.e., position=top at the float-level) farskip and nearskip swap places.

Labeling the sub-captions

Internally, subfloat uses a counter to keep track of the sub-floats within the current float and to produce a label for the caption from it. The counter name is sub type, where type is the current float type (e.g., the counter used for labeling sub-figures is called subfigure). Its representation is defined by hesub type and defaults to alph{sub type}. These counters are incremented for each subfloat regardless of whether a caption was printed.

A somewhat more complex layout applying several of the above options has been used in the following example. It introduces three sub-tables, two on top of a third. Due to the option settings the table captions appear above the tables in small slanted type. Single-line captions are set flush left; multiple-line captions are set ragged right with hanging indentation. To show further customization possibilities, the hesubtable command (which generates the “number” for a sub-float of type table) is redefined to produce two-level caption numbers on the sub-tables. Each of the subfloat commands, as well as the enclosing table environment, is identified by a strategically positioned label command. They allow us to address the components individually.

The references to the individual sub-tables in the previous example were created using the subref command, which returns the reference formatted according to the listofformat (see page 320). This avoids any problem created by our redefinition of the hetable, which would cause the ef command to produce numbers like “11.3”, because it combines the table number “1” with the sub-table number (e.g., “1.3”).

The starred version of this command, subref*, returns only the plain subfloat number (e.g., the value of hesubtable), if needed to construct more complex references, such as “Figure 1(a-c)”.

Captionless sub-floats

Sometimes one wants to label sub-floats but omit textual captions. This is, for example, common practice when showing a set of pictures or photographs: the main caption explains the significance of individual sub-floats. It can easily be achieved by using an empty optional argument on the subfloat command, which results in a labeled sub-float. The next example shows this type of layout.

Manual fine-tuning

It is also possible to fine-tune individual floats, if their sub-floats have unusual forms or excess white space. In Example 6-5-8 on page 316, we could, for example, move the main caption closer to the sub-captions by adding the line

at the top of the float body. This command would apply to the current float only and cancel part of the aboveskip added above the main caption.

So far, we have discussed only sub-floats in figure or table environments. If you have added additional float types, you may want to be able to substructure them as well. This can be achieved with the ewsubfloat declaration.

A prerequisite for using ewsubfloat is that there must already exist the environments to produce the given float-type—for example, environments declared with ewfloat from the float package. In that case ewsubfloat will set up subfloat to be usable within their float bodies (e.g., by declaring the counter sub 〈float-type〉 to produce their labels). In the optional option-value-list argument, you can specify layout options that should apply only to this particular type of sub-float.

Producing list of ... entries

The sub-float captions are automatically entered into the external file holding the data for the corresponding “List of...” list. Such files have the extension .lof (a list of figures), .lot (list of tables), or the extension specified as the third argument to ewfloat.

The sub-float captions will not show up in these lists because only top-level float captions are typeset by default. To change this behavior, you have to set the counter’s extdepth to 2 (where ext is the extension of the corresponding “List of...” file). For example, to make sub-figures captions appear you would use setcounter{lofdepth}{2}, and for sub-tables you would change the value of lotdepth.

As explained in Section 2.3.2 the layout of such entries can be customized by redefining l@subfigure, l@subtable, and similar commands; the command name consists of float type prefixed by l@sub. However, subfig already offers three options that influence the entries in this list and they probably provide enough flexibility in most circumstances.

listofindent The indentation for the sub-float caption inside the contents list. Its default value is 3.8em.

listofnumwidth The width reserved for the label in the contents list. Its default is 2.5em.

listofformat The format used for the label of the sub-float entry when displayed in the contents list. Possible keywords are empty, simple, parens, subsimple, and subparens (default). Additional formattings can be declared using the DeclareCaptionListOfFormat command; for details, see the package documentation. The typeset result is also used by the subref command, so changing the value of this option will affect references created by this command.

The next example shows how the sub-floats appear in the contents listings. We set lofdepth to make them appear and extend listofindent to 5em so that they are slightly indented. We also use a continuation float to prove that sub-float numbering continues as well. To suppress the “List of...” entry for the continuation float we use an empty optional argument on the caption command—the special feature provided by the caption package for such situations. Alternatively, we could have used caption* to suppress both the caption number and the entry in the list of figures.

External configuration files

Like the caption package, subfig supports the use of external configuration files that contain your favorite settings using the option config. For example,

loads the file xcaption.cfg.

While it is possible to combine the config option with other options, a clearer approach is to specify additional modifications through a captionsetup declaration in the preamble.

Figures (tables) for which sub-numbers are to be generated should be included inside a subfigures (subtables) environment. Alternatively, they can be placed between the commands subfiguresbegin and subfiguresend (subtablesbegin and subtablesend). While the environments must obey the basic nesting rules with respect to other environments, the commands can be placed anywhere. This flexibility can be helpful in unusual circumstances—for example, when sub-figures and sub-tables are intermixed.

The example that follows shows three figures. The first two are inside a subfigures environment, so they use sub-numbering (“1a” and “1b”). Both these labels are correctly handled by LaTeX’s listoffigures and ef commands.

As in the previous example, the default caption label combines an Arabic numeral for the main figure with a lowercase letter to differentiate between the individual sub-figures. This label can be customized by redefining the command hesubfloatfigure. Within its definition the command hemainfigure can be used to produce the main figure number¹ and the counter subfloatfigure to refer to the number of the sub-figure. Thus, to number sub-figures as “2.1”, “2.2”, and so on, one can define

¹ For technical reasons the command hefigure is not usable within sub-figures. The “alias” hemainfigure is provided for this purpose.

The same possibilities can be realized for tables by using the macros hesubfloattable and hemaintable, and the counter subfloattable.

To enable users to automatically refer to the total number of sub-figures with the same main figure number, the package offers the option countmax. When it is used, the floats within a subfigures (subtables) environment are counted and the number is made available in the counter subfloatfiguremax (subfloattablemax). One could, for example, define

to produce caption labels such as “2(1/3)”, “2(2/3)”, and “2(3/3)” when the second set of figures consists of three sub-figures. This counting is implemented as a two-pass system that uses the label and ef mechanism internally—which means that it is expensive in terms of resources and time. For this reason the default is not to count.

The package supports a number of options to influence the caption placement and formatting.

outercaption/innercaption The caption is typeset on the outer (default) or inner side of the page, respectively, i.e., varying between verso and recto pages.

leftcaption/rightcaption The caption is always typeset on the left or right side of the page, respectively.

wide The caption or float may extend into the margin if necessary.

margincaption The caption is set in the margin, with the float body appearing above the text. If this option is selected, the positioning of the float body with respect to the galley margins can be defined by using innerbody, outerbody, centerbody, leftbody, or rightbody.

raggedright/raggedleft/ragged The caption text is not justified. With small measures, this option often leads to better results. With ragged the unjustified margin varies between verso and recto pages, so this is best used with innercaption, outercaption, or margincaption. Martin Schröder’s ragged2e package is used, when available on the system.

If the sidecap package is combined with the caption package, you have the choice of specifying the justification with the above options or through the justification option of the caption package. Only ragged is unique, as caption offers no way to vary the justification between pages.

The environments SCfigure and SCtable (and their starred versions for spanning two columns) take two optional arguments. The rel-width argument defines the width of the caption relative to the width of the table or figure body (default 1.0). A large value (e.g., 20) reserves the maximal width available on the page. The second argument, float-spec, is LaTeX’s standard float positional argument (e.g., [htb]). In contrast to standard LaTeX floats, the float body is assumed to be horizontal material (necessary to be able to measure it). If you require vertical material at this point, use a minipage environment inside the body.

The first example shows a table and a figure with their captions set beside them. For the table the defaults have been used, resulting in a caption that occupies the same amount of space as the table. The figure is set with the caption twice as wide as the figure body. With the defaults the caption would have been typeset on two lines even though ample space is available. Except for the justification, the actual caption layout has been customized using the caption package.

Changing the default settings

In addition to its options, the sidecap package offers some parameters to influence the formatting. The size of the separation between the body and the caption can be changed by redefining sidecaptionsep (using enewcommand). The default is to use the value of the parameter marginparsep. Instead of repeatedly specifying an optional argument to the environments, you can set the (default) relation between the float body and the caption size by redefining sidecaptionrelwidth. For tables, the caption is aligned at the top; for figures, it is aligned at the bottom. This default can be changed by using a declaration like sidecaptionvpos{table}{b}, where the second argument should be any one of: t, c, or b.

The next example uses all three customization possibilities, and the floats are allowed to extend into the margin (option wide). In fact, because of the chosen value for sidecaptionrelwidth, they are forced to use all space available.

The package tries hard to produce a reasonable alignment between the float body and the caption text. In most cases, such as when the body consists of a tabular environment, it will produce satisfactory results. However, if the body contains straight text, perhaps as part of a minipage environment, you may have to help the alignment along by specifying a strut, as shown in the next example. The second strut on the last line is actually not necessary for a top-aligned caption but would be needed if the caption is bottom-aligned.

The example demonstrates the ragged option showing that it results in a ragged left setting if the caption appears in the left margin.

The package behavior is controlled by a number of options that specify the placement of the caption in relation to the float body (options in parentheses are alias option names):

closeFloats The full-page floats are placed on the next possible page. In twoside mode the caption is placed on the bottom of the opposite page; in oneside mode it is always placed on the page before the float body.

rightFloats (CaptionBefore) The float body always appears on a recto page and the caption on the previous page.

leftFloats (CaptionAfterwards) The float body always appears on a verso page and the caption on the following page.

The “isolated” caption that refers to a full-page float is separated from the remaining text on the page by a horizontal rule. This rule can be suppressed by specifying the noSeparatorLine option. Moreover, to make the connection between the caption and the float, you can let the package add hints like “Table xx. (on the facing page)” by specifying the option varioref. In that case the varioref package is used to produce such texts in the document language.¹

¹ This feature may not work if the layout of the caption is customized by the caption package.

We next construct a simple example demonstrating the principles underlying the fltpage package. In the example we construct an artificial full-page table by putting a frame containing an invisible rule (of zero width) inside a box with dimensions that are a small fraction smaller than the page dimensions.² The figure caption is typeset at the bottom of the page opposite the float material. Because we load the varioref package and specify the varioref option, the text “(on the next page)” is inserted automatically by the fltpage package.

² This step is needed to avoid generating overfull boxes due to the width of the framebox rules. The separation fboxsep between the frame and the inner material is also set to zero points.

Caveats

Unfortunately this package is no longer being developed. Thus, it is, for example, impossible to use it for float types other than figure and table (e.g., those that can be defined with the float package). Furthermore, problems may potentially arise if floats appear too close to each other in the source (the content of the second might overwrite the first). Nevertheless, if used with care, it provides a solution to the difficult problem of handling large floats that currently has no counterpart in any other package available.