Float Extension

By implementing the advanced float features, AH Formatter V6.5 is capable of arranging the float content in an arbitrary place of the page, arranging the float content in multi-column layout with column spanning of the float. As a result, AH Formatter V6.5 can meet various demands of the arrangement while formatting documents with illustrations, etc.

Using with XSL-FO, the float extension properties (axf:float-*) are applied to the fo:float objects.

Using with CSS, the float extension properties (-ah-float-*) are applied to elements that will become floated elements.

CAUTION: float="left" is interpreted as float="start" and float="right" is interpreted as float="end" by the XSL specification. But with this specification, it isn't possible to put the float to the physical left/right positions regardless of writing-mode. In AH Formatter V6.5 left/right are interpreted so that they indicate the physical direction. The same behavior also applies to clear.

In AH Formatter V6.5, a float with axf:float-y="none" may be split when the page (column) breaks. Please specify keep-together="always" to avoid splitting the float.

Float Extension Properties

axf:float / CSS (-ah-)float

This is a shorthand property for setting float related extension properties. [CSS3-GCPM] Page floats

Value: <float-x> || <float-y> || <float-wrap> || <float-reference> || <float-move> (XSL)
[<float-x> || <float-y> || <float-wrap> || <float-reference> || <float-move>] | footnote | sidenote (CSS)
Initial: none
Applies to: fo:float / floated elements
Inherited: no
Percentages: N/A

Values have the following meanings.

<float-x> = none | start | end | left | right | top | bottom | center | inside | outside | alternate

Specifies horizontal (or vertical if writing-mode is vertical) float alignment.

<float-y> = none | before | after | top | bottom | left | right | center | inside | outside

Specifies vertical (or horizontal if writing-mode is vertical) float alignment.

<float-wrap> = wrap | skip

Specifies whether the text wraps around the float.

<float-reference> = auto | normal | page | multicol | column

Specifies reference area where the float is positioned.

<float-move> = next | auto-next | auto-move | keep | keep-float

Specifies whether the float moves to the next page (or column).

footnote

Generates footnotes in CSS. Footnotes/Sidenotes by CSS

sidenote

Generates sidenotes in CSS. Footnotes/Sidenotes by CSS

This extension property is treated as a shorthand and maps to individual extension properties. For example,

<!-- XSL-FO example -->
<fo:float axf:float="before column auto-move">
  ...
</fo:float>
<!-- XHTML+CSS example -->
<div style="-ah-float: before column auto-move">
  ...
</div>

is equivalent to the following:

<!-- XSL-FO example -->
<fo:float axf:float-x="none" axf:float-y="before"
          axf:float-reference="column" axf:float-move="auto-move">
  ...
</fo:float>
<!-- XHTML+CSS example -->
<div style="-ah-float-x: none; -ah-float-y: before;
            -ah-float-reference: column; -ah-float-move: auto-move">
  ...
</div>

See individual extension properties for details.

The values left, right, top, bottom, center, inside, and outside which express absolute directions have the ambiguity to extend to both <float-x> and <float-y>. This can be solved as follows.

  • none is ignored.
  • When one of before, after, start, end or alternate is contained, either <float-x> or <float-y> will be selected. The remaining ambiguous value will become another value.
  • When none of before, after, start, end or alternate is contained, the first value which expresses the absolute direction will be <float-x>, the latter value will be <float-y>.

axf:float-x / CSS -ah-float-x

Specifies horizontal (or vertical if writing-mode is vertical) float alignment.

Value: none | start | end | left | right | top | bottom | center | inside | outside | alternate
Initial: none
Applies to: fo:float / floated elements
Inherited: no
Percentages: N/A

Values have the following meanings.

none

Not floated horizontally (or vertically if writing-mode is vertical).

start

Floated to the start side. Same as left in horizontal left-to-right writing-mode.

end

Floated to the end side. Same as right in horizontal left-to-right writing-mode.

left

Floated to the left side. Used only for horizontal writing. It cannot be specified for vertical writing.

right

Floated to the right side. Used only for horizontal writing. It cannot be specified for vertical writing.

top

Floated to the top. Used only for vertical writing. It cannot be specified for horizontal writing.

bottom

Floated to the bottom. Used only for vertical writing. It cannot be specified for horizontal writing.

center

Floated to the center horizontally (or vertically if writing-mode is vertical).

inside

Floated to the inside (left side on a right page, right side on a left page). Used only for horizontal writing. It cannot be specified for vertical writing.

outside

Floated to the outside (right side on a right page, left side on a left page). Used only for horizontal writing. It cannot be specified for vertical writing.

alternate

When the float area is in the first column, it's considered as end is specified, when the float area is in the last column, it's considered as start is specified, in other cases, it's considered as center is specified.

axf:float-y / CSS -ah-float-y

Specifies vertical (or horizontal if writing-mode is vertical) float alignment.

Value: none | before | after | top | bottom | left | right | center | inside | outside
Initial: none
Applies to: fo:float / floated elements
Inherited: no
Percentages: N/A

Values have the following meanings.

none

Not floated vertically (or horizontally if writing-mode is vertical).

before

Floated to the before side. Same as top in horizontal left-to-right writing-mode.

after

Floated to the after side. Same as bottom in horizontal left-to-right writing-mode.

top

Floated to the top. Used only for horizontal writing. It cannot be specified for vertical writing.

bottom

Floated to the bottom. Used only for horizontal writing. It cannot be specified for vertical writing.

left

Floated to the left side. Used only for vertical writing. It cannot be specified for horizontal writing.

right

Floated to the right side. Used only for vertical writing. It cannot be specified for horizontal writing.

center

Floated to the center vertically (or horizontally if writing-mode is vertical).

inside

Floated to the inside (left side on a right page, right side on a left page). Used only for vertical writing. It cannot be specified for horizontal writing.

outside

Floated to the outside (right side on a right page, left side on a left page). Used only for vertical writing. It cannot be specified for horizontal writing.

axf:float-reference / CSS -ah-float-reference

Specifies reference area where the float is placed.

Value: auto | normal | page | multicol | column
Initial: auto
Applies to: fo:float / floated elements
Inherited: no
Percentages: N/A

Values have the following meanings.

auto

Same as normal. However, when float-y is none in CSS, the float positioning is affected by block indents where the block contains the float anchor.

normal

The float is placed in the current reference area.

page

The float is placed in the page area (region-body).

multicol

The float is placed in the multi-column area.

column

The float is placed in the column area.

When float-y is none, the reference area in x-axis will be set.

When using with CSS, if float-y is none and the float-reference is auto the float positioning is affected by block indents where the block contains the float anchor, but by specifying normal, page, or column, it is possible to position floats regardless of the block indents.

axf:float-move / CSS -ah-float-move

Specifies whether the float moves to the next page (or column).

Value: auto | next | auto-next | auto-move | keep | keep-float
Initial: auto
Applies to: fo:float / floated elements
Inherited: no
Percentages: N/A

Values have the following meanings.

auto

Same as keep if float-y is none, same as auto-next otherwise.

next

The float is moved to the next page (or column).

auto-next

The float is moved to the next page (or column) if there is not enough space in the current page (or column).

auto-move

The float is moved to the next page (or column) if there is not enough space in the current page (or column). It is also possible that the float anchor and around text are moved to the next page (or column) instead.

keep

The float and its anchor are always placed on the same page (or column). If there is not enough space for that, a page (or column) break occurs before the float anchor and a blank space is left.

keep-float

Although it is almost the same as keep, the following points differ. With keep, keep-with-next="always" is automatically set to anchor area and a page break (or column break) is deterred between the next area. However, it is not performed by keep-float. The difference on operation will appear when the height of anchor area is zero.

If both float-x and float-y are none, the object is not floated and the float-move specification is ineffective.

axf:float-wrap / CSS -ah-float-wrap

Specifies the text wrapping.

Value: auto | wrap | skip
Initial: auto
Applies to: fo:float / floated elements
Inherited: no
Percentages: N/A

Values have the following meanings.

auto

Same as wrap if float-x is other than none. Same as skip if it is none.

wrap

Wraps the text around the float. However, when there is a space on both side of a float within the column (by specifying center to float-x or float-offset-x), it is the same as skip.

skip

The text doesn't wrap around the float. The text is positioned by skipping the float.

axf:float-min-wrap-x / CSS -ah-float-min-wrap-x

Specifies the minimum width for the text wrapping around the float.

Value: normal | <length> | <percentage>
Initial: normal
Applies to: fo:float / floated elements
Inherited: no
Percentages: refer to the size of containing block

If the width for the text wrapping around the float is smaller than the width specified by this property, the text doesn't wrap.

The initial value, normal is minimum wrapping width of normal floats. It is same as 0pt.

axf:float-min-wrap-y / CSS -ah-float-min-wrap-y

Specifies the minimum extent for the text placed before and after the float.

Value: normal | <length> | <percentage>
Initial: normal
Applies to: fo:float / floated elements
Inherited: no
Percentages: refer to the size of containing block

When the float-y value is not none and there is remaining space to place the text before or after the float within the formatting target area, if the extent of that space is smaller than the extent specified by this property, the text is not placed to that space.

When the float-y value is none and the float-move value is auto-next and there is remaining space to place the text after the float within the formatting target area, if the extent of that space is smaller than the extent specified by this property, the float position will move so that the extent may become zero. The text placed after the float will move in front of the float.

When the float-y value is none and the float-move value is auto-move, the behavior is similar to auto-next; if the space extent for the text not only after but also before the float is smaller than the extent specified by this property within the formatting target area, the float position will move so that the extent may become zero. The text placed before the float will move after the float.

The initial value, normal is the same as 0pt.

axf:float-centering-x / CSS -ah-float-centering-x

Specifies whether the float is centered when the width for the text wrapping around the float is insufficient.

Value: none | auto | <length> | <percentage>
Initial: none
Applies to: fo:float / floated elements
Inherited: no
Percentages: refer to the size of containing block

Values have the following meanings.

none

The float is not centered.

auto

The float is centered when the width for the text wrapping around the float is less than the width specified by the float-min-wrap-x property.

<length>
<percentage>

The float is centered when the width for the text wrapping around the float is less than the width specified by this property.

axf:float-centering-y / CSS -ah-float-centering-y

Specifies whether the float is centered when the extent for the text placed before and after the float is insufficient.

Value: none | auto | <length> | <percentage>
Initial: none
Applies to: fo:float / floated elements
Inherited: no
Percentages: refer to the size of containing block

Values have the following meanings.

none

The float is not centered.

auto

The float is centered when the extent for the text placed before and after the float is less than the extent specified by the float-min-wrap-y property.

<length>
<percentage>

The float is centered when the extent for the text placed before and after the float is less than the extent specified by this property.

axf:float-margin-x / CSS -ah-float-margin-x

Specifies the space between the float and the text wrapping around the float (in x-axis).

Value: [ <length> | <percentage> ] [ <length> | <percentage> ]?
Initial: 0pt
Applies to: fo:float / floated elements
Inherited: no
Percentages: refer to the size of containing block

When two values are specified, the first one will be the value of the start side, the next one will be the value of the end side.

axf:float-margin-y / CSS -ah-float-margin-y

Specifies the space between the float and the text before and after the float (in y-axis).

Value: [ <length> | <percentage> ] [ <length> | <percentage> ]?
Initial: 0pt
Applies to: fo:float / floated elements
Inherited: no
Percentages: refer to the size of containing block

When two values are specified, the first one will be the value of the before side, the next one will be the value of the after side.

axf:float-float-margin-x / CSS -ah-float-float-margin-x

Specifies the space between the float and another neighboring float (in x-axis).

Value: auto | [[ <length> | <percentage> ] [ <length> | <percentage> ]?]
Initial: auto
Applies to: fo:float / floated elements
Inherited: no
Percentages: refer to the size of containing block

The initial value auto is same as the float-margin-x value. When two values are specified, the first one will be the value of the start side, the next one will be the value of the end side.

The float-float-margin-x value cannot exceed the float-margin-x value.

axf:float-float-margin-y / CSS -ah-float-float-margin-y

Specifies the space between the float and another neighboring float (in y-axis).

Value: auto | [[ <length> | <percentage> ] [ <length> | <percentage> ]?]
Initial: auto
Applies to: fo:float / floated elements
Inherited: no
Percentages: refer to the size of containing block

The initial value auto is same as the float-margin-y value. When two values are specified, the first one will be the value of the before side, the next one will be the value of the after side.

The float-float-margin-y value cannot exceed the float-margin-y value.

axf:float-offset-x / CSS -ah-float-offset-x

Specifies the offset placement for the float (in x-axis).

Value: <length> | <percentage>
Initial: 0pt
Applies to: fo:float / floated elements
Inherited: no
Percentages: refer to the size of containing block minus the size of the float

If float-x is start, the offset to the end side is specified. If it is end, the offset to the start side is specified.

axf:float-offset-y / CSS -ah-float-offset-y

Specifies the offset placement for the float (in y-axis).

Value: <length> | <percentage>
Initial: 0pt
Applies to: fo:float / floated elements
Inherited: no
Percentages: refer to the size of containing block minus the size of the float

If float-y is before, the offset to the after side is specified. If it is after, the offset to the before side is specified.

Unit 'gr' to specify spanning columns

The unit 'gr' is a special length unit and it counts both column-width and column-gap as 1gr. n-column-spanning can be specified as (2n-1)gr. Fractions of gr unit can be used to specify halfway length of column-width or column-gap. Negative value cannot be specified.

The following is an example of two-column-spanning float:

<fo:float axf:float="multicol top left">
  <fo:block-container width="3gr">
    <fo:block>This is a two-column-spanning float.</fo:block>
  </fo:block-container>
</fo:float>

Note that the '3gr' means 2 column-widths plus 1 column-gap.

0.5gr = 0.5 columnWidth
1gr = 1 columnWidth
1.5gr = 1 columnWidth + 0.5 columnGap
2gr = 1 columnWidth + 1 columnGap
2.5gr = 1 columnWidth + 1 columnGap + 0.5 columnWidth
3gr = 1 columnWidth + 1 columnGap + 1 columnWidth
(2n-1)gr = n columnWidth + (n-1) columnGap

CAUTION: gr is defined only to the float specified as axf:float="multicol". It is not applicable to the other floats or properties other than float. If applied, the operation will be indefinite.

Footnotes/Sidenotes by CSS

In order to express footnotes by CSS, (-ah-)float: footnote and @footnote are used. The following shows a very easy example of a footnote.

span.footnote { -ah-float: footnote; } @page { @footnote { border-top: solid; -ah-float: page bottom; } } <p> Lorem dignissim<span class="footnote">Quisque suscipit ante vel eros.</span>, orci ac porta blandit, ... </p>

Thereby, the portion enclosed with <span class="footnote"> and </span> will be placed at the bottom of the page as a footnote, that portion will be replaced with a reference mark. (-ah-) float: footnote expresses a footnote body. (Equivalent to <fo:footnote-body> in FO). The appearance of a footnote can be specified with @footnote. You can specify the appropriate position of footnotes using (-ah-)float. display: inline is not supported.

The appearance of a reference mark can be specified by ::footnote-call. The number added to a footnote can be specified by ::footnote-marker. Those default appearances are specified in the default stylesheet (html.css). The following example shows the way to put letters of the alphabet, like A, B, C... as an alternative method of numbering. You can specify the same values that can be specified to list-style-type.

::footnote-call, ::footnote-marker { content: counter(footnote, upper-alpha); }

To reset the counter, specify counter-reset: footnote to @page, etc. accordingly.

In order to express sidenotes by CSS, (-ah-)float: sidenote and @sidenote are used. The same way as footnotes applies to sidenotes.

span.sidenote { -ah-float: sidenote; } @page { @sidenote { -ah-float: outside; clear: both; width: 20% } } <p> Lorem dignissim<span class="sidenote">Quisque suscipit ante vel eros.</span>, orci ac porta blandit, ... </p>

The default stylesheet does not include the setting of ::sidenote-call and ::sidenote-marker.

Extended Float Examples

Page Float Examples

In the following example, the float is placed on top of a page.

<fo:float axf:float="page top"> <fo:block>This is a page float.</fo:block> </fo:float>

In the following example, the float is placed on bottom of a page.

<fo:float axf:float="page bottom"> <fo:block>This is a page float.</fo:block> </fo:float>

Multi-column Float Examples

In the following example, the float is placed on the top right corner spanning three columns on a multi-column area.

<fo:float axf:float="multicol top right"> <fo:block-container width="5gr"> <fo:block>This is a multicol float.</fo:block> </fo:block-container> </fo:float>

In the following example, the float is placed on the bottom inside corner on a multi-column area.

<fo:float axf:float="multicol bottom inside"> <fo:block-container width="1gr"> <fo:block>This is a multicol float.</fo:block> </fo:block-container> </fo:float>

Column Float Examples

In the following example, the float is placed on top of a column.

<fo:float axf:float="column top"> <fo:block>This is a column float.</fo:block> </fo:float>

In the following example, the float is placed on bottom of a column.

<fo:float axf:float="column bottom"> <fo:block>This is a column float.</fo:block> </fo:float>

Float Move Example

Since float is arranged at the place of the anchor area, when an image, etc. are contained and there is not enough space for that, it will be sent to the next page. As a result, a blank space will remain in the lower part of the page. In order to avoid this, use the axf:float-move property to move float automatically from the anchor area. Note that the blank space will remain when there is no room to move.

The following example arranges an image with no text wrap on the right, left or center of a page. If there is not enough space at this time, only an image will move to the next page leaving an anchor to that position. Note that it's necessary to specify axf:float-x at this time.

<fo:float axf:float-x="center" axf:float-y="none" axf:float-move="auto-next" axf:float-wrap="skip" axf:float-reference="page"> <fo:block> <fo:external-graphic src="any-image"/> </fo:block> </fo:float>

In the above example, if axf:float-move="auto-move" is specified, an anchor (and text around it) will move to the next page depending on the situation of the blank space. As a result, it looks like the image moves to the previous page.

You may not want to move the float across over the chapter or the paragraph. Since the float does not move over other float, it is realizable by putting the dummy float into the break of the chapter or the paragraph. The following shows how the empty float prevents the other float from moving across the chapter.

<fo:float axf:float-x="end" axf:float-move="keep"/> <fo:block page-break-before="always"> New-Chapter ...

You may want to allow the float in a new chapter to move to the previous. In the above example, since keep-with-next="always" is set to the empty float, there is no room for the float to move before the new chapter. By specifying axf:float-move="keep-float", the setting will be cleared, then this empty float will be arranged at the last of a previous page and the float can move between the next block afterwards.

Restrictions

AH Formatter V6.5 Float Extensions have the following restrictions.