The <float> command

A TopLeaf float is a typesetting object containing paragraphs, graphics, table rows or boxes. A float is positioned at the bottom or top of a column or page by “floating” it forward through the surrounding content in which it is declared.

The point at which a float is declared in the main data stream is called the float reference point. A float is always positioned in the document after its reference point.

[Note] Note

The maximum height of a float is determined by the current page type at the time it is declared, not the page type in effect when it is placed (see below). This can cause an unexpected result when the page type has a “followed by” page type defined. If you are using floats, consider designing your layout so that all page types have the same data block depth to avoid this problem.

[Warning] Warning

The context in which a float is processed can be different to the one in which it appears in the data. Make sure your stylesheet saves critical parts of the context at the point the float is declared so that this information can be used at processing time.

For example, if the location of an image is referenced relative to the {document-folder} you cannot assume that the current document will be the same when the image is placed on the page. To avoid problems, add a wrapper around the image that sets a variable that can be used to locate the image.

Column floats

A column float is a TopLeaf float type that is positioned at the bottom or top of a data column. The column in which the float is declared is called the float reference column. If there is sufficient room, TopLeaf will position a column float at the bottom of the float reference column. If this is not possible, then TopLeaf will position the column float at the top or bottom of a subsequent data column.

The following command declares a column float object:

<float type="column">CONTENT</float>

Example

A simple way to declare a column float is to scan the content of a element and enclose the scanned content within the float directive. The following example shows how to assign a caption and the scanned content of a tag to a column float:

<float type="column" ><Caption>Figure {Num}</Caption><content/></float>

Positioning column floats

TopLeaf uses the settings declared in the <float-properties/> directive to determine if there is sufficient room to place a float within the float reference column, or if it must be floated to the top or bottom of a subsequent column. Column floats that fit within the same data column as their float reference point are always floated at the bottom of that column. Column floats that cannot fit within their float reference column will be positioned in a subsequent column.

Float objects cannot be floated past a forced end of page or a page type change. When either of these events occurs, any floats that have not been positioned will effectively cease to float and be rendered as part of the data column region before the forced end of page or a page type change.

Styling column floats

Column floats are processed within the context of a $column-float system mapping. You can use this mapping to declare a set of custom actions and default styling rules for a float object. You can also specify a $float page context to declare tag or custom marker mappings applied specifically within the context of a float.

Processing of large float objects

If the depth of a column float exceeds the maximum float depth, the composition engine attempts to fit the float by automatically scaling the size of all block images within it. A warning will be generated if the amount of additional scaling exceeds 40%. You can use the <image-properties/> command to adjust this threshold.

If after scaling all images within a float, the depth of the float still exceeds the maximum float depth, TopLeaf will attempt to split the float into two or more separate floats. The split float will then continue over as many columns as needed to hold the material, after which the normal text will resume. If this attempt is unsuccessful, TopLeaf will generate a non-fatal error.