AH Formatter V7.0 - Float Extension

By implementing the advanced float features, AH Formatter V7.0 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 V7.0 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> element.

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 XSL-FO in AH Formatter V7.0, left/right are interpreted so that they indicate the physical direction. The same behavior also applies to clear.

Float Extension Properties

axf:float / CSS (-ah-)float

This is a shorthand property for setting float related extension properties. [CSS3-GCPM] Page floats (“float” has been removed from GCPM on and after May 13, 2014)

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. ☞ axf:float-x
<float-y> = none | before | after | top | bottom | left | right | center | inside | outside: Specifies vertical (or horizontal if writing-mode is vertical) float alignment. ☞ axf:float-y
<float-wrap> = wrap | skip: Specifies whether the text wraps around the float. ☞ axf:float-wrap
<float-reference> = auto | normal | page | multicol | column: Specifies reference area where the float is positioned. ☞ axf:float-reference
<float-move> = next | auto-next | auto-move | keep | keep-float: Specifies whether the float moves to the next page (or column). ☞ axf:float-move
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>

For more details, see individual extension properties.

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 that end is specified, when the float area is in the last column, it's considered that start is specified, in other cases, it's considered that 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 axf: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 axf:float-y is none, the reference area in x-axis will be set.

When using with CSS, if axf:float-y is none and the axf: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 axf: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 axf:float-x and axf:float-y are none, the object is not floated and the axf: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 axf: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 axf:float-x or axf: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 axf: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.

If the value of axf:float-y is none, it is processed as follows:

If the value of axf:float-move is auto-next and there is space left to place text after the float within the formatting target area, if its height (width in vertical writing) is smaller than the height (width in vertical writing) specified in this property, moves the float position so that its height (width in vertical writing) becomes zero. Text that was after the float will move before the float.
If the value of axf:float-move is auto-move, it is the same as the case of auto-next, but within the formatting target area, if the height (width in vertical writing) of the text placement space before the float, not only after the float, is smaller than the height (width in vertical writing) specified in this property, moves the float position so that its height (width in vertical writing) becomes zero. Text that was before the float will move after the float.
If the value of axf:float-move is other than these, text will wrap around if there is space left to place text after the float in the formatting target area, otherwise it will not wrap around.

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 axf: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 axf: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 axf: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 axf:float-float-margin-x value cannot exceed the axf: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 axf: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 axf:float-float-margin-y value cannot exceed the axf: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 axf: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 axf: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

“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:	The unit “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. ☞ [CSS3-GCPM] Footnotes

span.footnote { -ah-float: footnote; } @page { @footnote { border-top: solid; -ah-float: page bottom; } }

Lorem dignissimQuisque suscipit ante vel eros., orci ac porta blandit, ...

Thereby, the portion enclosed with to 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. footnote-display 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. ☞ [CSS3-GCPM] Sidenotes (@sidenote has been removed from GCPM on and after June 8, 2010)

span.sidenote { -ah-float: sidenote; } @page { @sidenote { -ah-float: outside; clear: both; width: 20% } }

Lorem dignissimQuisque suscipit ante vel eros., orci ac porta blandit, ...

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-y="none" 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 V7.0 Float Extensions have the following restrictions:

When axf:float-y is none, a float may be split when the page (column) breaks. Specify keep-together="always" if you want to avoid splitting the float.
When axf:float-y is none and the axf:float-reference value is multicol or page, the text doesn't wrap around the float except for the specified column, then the text and the float may overlap.
When axf:float="page before" is specified and xsl-before-float-separator is defined, it behaves as float="before" defined in the standard XSL specification. In other cases, xsl-before-float-separator will not be displayed.
Float Extensions may not be positioned correctly within <fo:table-cell> or <fo:block-container>.
When axf:float-y is not none, a float can be placed in <fo:region-body> or <axf:spread-region>. If you place such a float in any other region, it will not float.