4.1 Area model details

4.1.1 Geometric rendered areas

The result of formatting is the generation of geometric areas for rendering based upon an area model which:

• is a superset of CSS2 box formatting model,

• includes references to areas by other areas,

• defines relationships and space adjustment between areas generated for letters , words, lines, and blocks.

Areas are arranged hierarchically as a result of interpreting formatting objects.

• Each branch of the tree collects areas that are related .

  • A single XSL-FO object can generate areas for multiple area tree branches.

• Each area has a relative or absolute position described by a spacing constraint.

• Each area may have content to display.

• Each area may have visual or aural presentations different from those of other areas.

• Areas define placement of every glyph, shape, and image with spacing constraints.

Not all kinds of areas can be directly specified by the XSL-FO instance.

• For example, lines in a block are areas synthesized only by the formatter during the flowing of information.

• Objects and properties in the XSL-FO instance can influence the presentation of the synthesized areas;

  • e.g., initial-property-set object influences the first generated line of a block;

    • it is an empty formatting object that does not generate any areas;

  • e.g., line-height property governs how much of a block is taken up by each of the lines.

A paginated area and static areas can be defined for each page.

• Paginated areas accept content to be flowed and trigger the generation of as many pages as needed to fit the flow of information to be rendered;

  • they are defined as descendants of flow objects.

• Static areas are rendered on every page that is generated by pagination;

  • they are defined as descendants of static-content objects.

• A page's geometry need not contain any region that is accepting flow;

  • such a page is rendered with only the static content, and the formatter moves to the next page geometry in the sequence of pages.

A single object can create many areas.

• Not all generated areas of a given sequence need be adjacent, nor hierarchically related to each other.

  • One object can add areas to separate area tree branches.

• The name of the formatting object that produces the desired areas is not important.

  • The objective is to position information on the page; the choice of which formatting object to use to create the needed areas is based on the semantics of the formatting object, not its name.

    • E.g., a list-block can be used to lay out synchronized pairs of paragraphs of different languages, even though the essence of the information being formatted is not a list.

The hierarchical area tree has familial relationships between nodes of the tree;

• a node can be child, sibling, parent, descendant, ancestor , or root;

• a set of nodes are ordered within the parent;

  • there is only one order of sibling nodes;

  • this ordering defines initial, preceding , following, and final relationships;

• there are two traversals of the tree when dealing with child nodes of the parent;

  • pre-order traversal orders the parent before the children, e.g.:

    • determining the "next" area for keep-with-next ,

    • determining preference in markers for retrieve-marker ;

  • post-order traversal orders the parent after the children, e.g.:

    • determining the "previous" area for keep-with-previous ;

  • neither traversal order changes the order of the children themselves .

The root node is not an area.

• All other nodes are rectangular areas on the result canvas.

• Areas in the tree may be of zero size;

  • this may be useful for placing identification information in the tree without occupying real estate on the page;

  • a page with only a zero- sized area is not an empty page and is considered to have an area present on the page for the purposes of resolving the first and last areas in a reference area.

The area tree can have very many areas described.

• Even every glyph (character shape) has its own area.

• Every area has its own placement direction and spacing constraint.

• There is no obligation on the formatter to serialize or externalize the area tree.

Most nodes generate a singular area.

• There is an exception for ligatures that have leaf nodes combined to produce a single area, e.g.:

  • combinations of English letters into a single glyph such as "a" and "e" becoming " ",

  • combinations of Arabic characters based on location and sibling characters .

The formatter has sufficient information in the finalized areas to effect the rendering.

• Missing or conflicting constraints are resolved by the formatter in an implementation-dependent fashion;

  • these may be constrained by the rendering technology used by the formatter.

• Page fidelity is an important portability issue.

  • Two conforming XSL-FO formatters need not produce identical renderings .

  • Formatters can create different area trees based on different interpretation of unspecified traits, e.g.:

    • hyphenation and justification rules,

    • default value for inter-line leading.

  • The rendering process can create different results depending on unspecified traits, e.g.:

    • font.

4.1.2 Directions and writing modes

Orientations and directions are defined for a reference area.

• Every reference area has an orientation with respect the definition of the "top" of the area and its writing direction.

• Descendent reference areas can have orientations modified relative to the containing reference area.

• Descendent areas that are not reference areas cannot have their orientations changed.

Reference areas are found in many places in the area tree, including

• region reference area (perimeter regions ),

• main reference area (page bodies),

• before-float reference area (before floats),

• footnote reference area (footnotes),

• span reference area ( spanned columns ),

• normal-flow reference area (columns),

• lines in a block,

• title ,

• block-container and inline-container ,

• table , table-caption , and table- cell .

Stacking rules govern how adjacent areas created by objects in flow are related along directions.

• All objects are defined as stacking in a particular direction relative to their adjacent objects or other objects.

• Some objects are "out of line" in the stacking order;

  • their position is related to objects other than those that are adjacent.

• General rules of thumb with powerful nuances are available for specific requirements.

Various directions govern the placement of objects relative to their siblings.

• Block-progression direction:

  • is the stacking of lines and blocks relative to other lines and blocks in an area,

  • is the stacking of rows in a table.

• Inline-progression direction:

  • is the stacking of glyph areas and other inline areas within a line,

  • is the stacking of cells in a table row,

  • defines the shift direction which:

    • is used for subscripts and superscripts rendered in inline areas,

    • is perpendicular to inline-progression direction,

    • is inverse of the initial block-progression direction,

  • defines glyph direction which:

    • is oriented to the top of the glyph,

    • initially is the same as the direction of the top of the reference area,

    • can be rotated or inverted clockwise relative to top of reference area.

Writing-mode-related properties reflect cultural practices of flowing information on a page, as shown in Figure 4-3.

• For example, an indent at the start of a line in a left-to-right writing mode is on the opposite side of the page compared to the indent at the start of a line in a right-to-left writing mode.

• Before, after, start, and end edges of each writing mode are relative to the reference orientation that defines the top edge of the area.

  • Using top, bottom, left, and right ignores the writing mode and is less portable.

Figure 4-3. Possible writing modes

Two properties govern progression direction of adjacent areas on the page.

• reference-orientation :

  • defines the direction of the top edge of a reference area relative to containing reference area,

  • can be positive (counter-clockwise) or negative, in multiples of 90 degrees.

• writing-mode :

  • specifies the inline-progression direction and the block-progression direction, in the form of two-letter codes separated by a hyphen, relative to the top of the reference area,

  • can be lr-tb or lr meaning left-to-right for inline, top-to-bottom for block, e.g.:

    • Western European writing systems,

  • can be rl-tb or rl meaning right-to-left for inline, top-to-bottom for block, e.g.:

    • Hebrew and Arabic writing systems,

  • can be tb-lr or tb meaning left-to-right for inline, top-to-bottom for block, e.g.:

    • traditional Japanese and Chinese writing systems.

• A combination of these properties can be used on other objects to define other direction-related traits, e.g.:

  • placement and orientation of perimeter regions within pages,

  • placement of columns within body region,

  • placement and orientation of rows and columns within tables,

  • changes within paginated content and static content in a region, e.g.:

    • by using block-container objects at the block level,

    • by using inline-container objects at the inline level.

• These properties can only be specified for reference areas.

Bidirectional writing is inherently supported by XSL-FO processors.

• One of the most powerful features of XSL-FO is that the stylesheet writer need not be aware of the writing direction of the characters used in the XML documents being formatted;

  • e.g., right-to-left characters can be intermixed with left-to-right characters.

• The formatter automatically accommodates bidirectional writing based upon the inherent properties of the Unicode characters in the content.

  • It makes the job easier for the stylesheet writer in that the directions of the individual characters do not need to be detected and accommodated.

• bidi-override object is only used when direction inferred by the Unicode character is not as desired.

  • A common misconception is that this must be used to support bidirectionality when, in fact, it is used only when the bidirectionality needs to be embedded or overridden.

4.1.3 Margins, spaces, and positioning

Areas are positioned by specifying the spaces around them.

• Areas that are flowed adjacent to each other are separated by their spacing specifications.

• Floats and footnotes are positioned out-of-line as defined by the Recommendation.

• Only a block-container can be positioned arbitrarily on the page.

  • This is indicated by using absolute-position which implies

    • either a relative distance from its siblings,

      • as if it were a simple block (" auto "),

    • or an absolute distance from an ancestor, in particular:

      • from the parent area boundaries (" absolute "),

      • from the page area boundaries (" fixed ").

  • Distances from ancestral area edges are specified using top , bottom , left , or right .

Spaces and non-page margins define the same values, but from different perspectives.

• space-* specifications are relative to the writing direction:

  • space-before , space-after , space-start , space-end .

• margin-* specifications are relative to the reference orientation:

  • margin-top , margin-bottom , margin-left , margin-right .

Page margins

• Margins of page regions are fixed to the page boundaries and physical orientation:

  • margin-top , margin-bottom , margin-left , margin-right .

Discarding space

• A space specification can have a property of being discarded when the area it is associated with is the first or last in a reference area.

4.1.4 Lengths and spacing

Lengths can be specified in both absolute and relative terms.

• cm is centimeter;

• mm is millimeter;

• in is inch = 2.54 cm;

• pt is point = 1/72 in;

• pc is pica = 12 pt = 1/6 in;

• px is pixel = 1 device dot (nominally 1/90 " or .28 mm);

• em is the current font size (the only relative unit of measure);

  • use em-based values for spacing to protect relative appearance from changes in font size (e.g., " 2em " is twice the current font size).

• Note that there is no "ex" measurement.

  • Sometimes it is used in formatting specifications as the height of a lowercase letter in the current font size.

  • This is not a concept that is easily interpreted in all international character repertoires .

  • It is used in XSL-FO in the definition of one of the baselines for those scripts that have an ex value.

Spaces are used to position areas within other areas and can be influenced by

• specifying minimum, maximum, and optimum;

  • the preferred value is the optimum, but it cannot be less than minimum or more than maximum,

• specifying conditionality ;

  • the retain or discard values control whether the space specification is preserved at the start or end of a reference area,

• specifying precedence;

  • the value of force or an integer value controls which of the space specifications is in play after constraint calculation resolution,

• interaction of adjacent siblings' space specifications;

  • sizes and precedence determine rendered amount of space;

  • this is detailed.

Some properties can be specified using a percentage.

• When inherited, percentages are relative to their inherited value, e.g.:

  • font-size="150%" .

• When not inherited, percentages are relative to a reference rectangle;

  • for XSL-defined properties, this is the content rectangle;

  • for CSS-defined properties, this is closest non-line-area content rectangle;

  • exceptions exist for out-of-line constructs and the regions in which they are used (detailed in Recommendation, Section 7.3).

4.1.5 Area types

Different areas are characterized by their different purposes and uses.

• Reference area is an area that can have reference-related properties different from those of its parent area;

  • it can change the reference orientation and/or writing mode;

  • it also has special behaviors for first and last space specifications.

• Viewport area is the clipping/scrolling visible portion of a reference area.

• Allocation area is the basis of positioning and alignment of content within parent;

  • it defines the mechanics of how the stacking works.

• Block area is a collection of lines in the block-progression direction;

  • it creates a new set of lines, even if the block has a zero dimension.

• Line area is a collection of inline constructs in a block.

• Inline area is an atomic construct or collection of glyph constructs in the inline-progression direction.

• Glyph area is a single text character.

4.1.6 Stacking area and rectangle relationships

Areas stack in either the block-progression direction or the inline-progression direction using rectangles.

• The parent area's content rectangle constrains the position of the child areas therein.

• The child areas can only stack in one direction relative to the parent reference orientation.

  • One set of opposing edges of a child coincides with the parent content rectangle;

  • the other set of opposing edges of child coincides with the adjacent content rectangle,

    • or with the parent content rectangle if first or last in the stack.

Areas that are stacked adjacent to their siblings are considered "normal."

• Other areas are considered " non-normal " and stack elsewhere in the area tree, e.g.:

  • floats to the before, start, or end sides of the body region,

  • footnote bodies to the after edge of the body region,

  • absolutely positioned block containers to arbitrary locations.

A block area without borders is positioned between siblings;

• space-before and space-after determine its position between siblings;

• start-indent and end-indent determine its position within parent.

Initial property values are for "common sense" formatting.

• A lot of work can be done without changing initial values.

• A lot of finesse can be accomplished by specifying available alternatives.

A child area with a border contains nested rectangles.

• This allows for a rigorous specification of formatting intent, spaced relative to the directions of the parent area.

• Border rectangle is positioned relative to the parent or adjacent area using margin-* or space-* spacing properties.

  • Edges of border rectangle are identified by parent reference orientation.

• Padding rectangle is positioned relative to border rectangle using border-* width properties.

  • Edges of padding rectangle are identified by parent reference orientation.

• Content rectangle is positioned relative to padding rectangle using padding-* spacing properties.

  • Edges of content rectangle are identified by child reference orientation.

Border and padding widths are sometimes ignored.

• For example, they are not applicable to regions, floats, or footnote bodies.

• border-style value of " none " or " hidden " will set the border width to 0pt .

• border-before-width and border-after-width have .conditionality component with the initial value of " discard ";

  • it sets the .length component to 0pt if it is, respectively, the first or last area in a reference area;

  • they may be set to " retain " to preserve the .length component value.

An area is stacked within its parent's content rectangle using spacing extents, as shown in Figure 4-4.

• Names of extents are suffixed using the names of the edges from which they extend.

  • Each edge of the spaces, border, or padding may thus have individual values.

  • Shorthand properties are available to set all extents in one specification.

• Reference areas can have a location of "top" different from that of their parent area.

Figure 4-4. Nested rectangles in stacked block areas

The border rectangle is different from the spacing and padding rectangles.

• Spacing and padding rectangles and dimensions define invisible non-rendered areas.

• The border rectangle and border width properties define the thickness of a visible rendered border.

• Not shown are the *-top , *-bottom , *-left , and *-right properties for padding-* and border-* which directly correspond to the writing direction dependent properties.

An area's content rectangle in turn contains the area's children.

• The area's type governs what is allowed for the child areas.

  • Only a reference area's children can discard conditional spaces.

  • Only when the area is a reference area can the content rectangle have orientation properties different from itself.

    • Orientation properties and traits are relative to the "top" of the area.

    • Examples include reference-orientation , block-progression direction, etc.

  • An area's content rectangle orientation properties are relative to the content's own reference orientation, not the area's reference orientation.

• Proportional *-indent and margin-* specifications are calculated differently.

  • A proportional *-indent specification is based on the ancestral reference area.

  • A proportional margin-* specification is based on the containing block.

• Specifying conflicting values will over-constrain requirements.

  • margin-* properties take precedence over *-indent properties.

    • A specified start-indent or end-indent value is ignored if the corresponding margin-* property within the indent value is specified.

  • *-indent properties take precedence over space-* properties.

    • A specified space-* value is ignored if the corresponding start-indent or end-indent property within the indent value is in effect.

  • start-indent and the content's specified inline-progression dimension take precedence over end-indent .

    • Examples are inline-progression-dimension on the object or specified for the objects children's sizes.

    • If the inline-progression dimension is not explicitly set for the object or its children, the end-indent is respected.

4.1.7 Allocation rectangles and alignment

A child area's allocation rectangle describes constraints of position within parent.

• It defines the mechanics of the stacking of adjacent areas.

• Dimension is based on either the parent, border, or content edges.

  • Block and inline areas use different edges.

  • Inline areas of two different types (normal and large) use different edges.

• Orientation is based on parent area.

  • It may be different from content area.

• The start edge of an inline area's allocation rectangle defines the alignment point of the area.

  • This is used in glyph and other inline rendering.

• The space outside of the allocation rectangle can be discarded.

  • This happens only when the space is the first or last in a reference area.

  • The space-*.conditionality default of " discard " can be overridden to be " retain ".

Block area stacking and allocation rectangle definition is shown in Figure 4-5.

• All block areas are defined with the same relationship between sibling block areas.

Figure 4-5. Block-area allocation rectangle

Inline areas defined with a normal allocation rectangle are shown in Figure 4-6.

• Most inline areas are defined with the normal relationship between areas.

  • An example is text.

• Note how the bordering of such an area will not influence the line stacking and may cause undesirable overwriting of content on the previous and following lines.

Figure 4-6. Normal inline area allocation rectangle

Inline areas defined with a large allocation rectangle are shown in Figure 4-7.

• Some inline areas are defined with an alternative relationship between areas.

  • Examples are inline containers and graphic images.

• Note how the bordering of such an area will influence the line stacking and will not cause undesirable overwriting of content on the previous and following lines when the line-stacking strategy is based on the height of the content.

Figure 4-7. Large inline-area allocation rectangle

4.1.8 Line areas

Line areas are special areas only created by creating a block area.

• Line area traits are specified in the block properties.

• They stack in the block-progression direction.

• They have no borders or padding.

Line stacking strategy determines which rectangle describes the line.

• " nominal- requested -line-rectangle " is based on font height and:

  • is selected using the line-stacking-strategy value of " font-height ",

  • reaches above the text baseline by the text altitude,

  • reaches below the text baseline by the text depth,

  • provides constant baseline-to-baseline spacing.

• " maximum-line-rectangle " (the initial value for this property) is based on inline objects within line and:

  • is selected using the line-stacking-strategy value of " max-height ",

  • is equal to the maximum of the allocation-rectangle heights of all contained inline objects as well as that of the nominal-requested-line-rectangle ,

  • provides constant space between line areas.

• " per-inline-height-rectangle " is based on leading and:

  • is selected using the line-stacking-strategy value of " line-height ",

  • provides CSS-style line box stacking when using zero space before and space after.

Leading is calculated as difference between line height and font size.

• Leading is the space found between the lines of a block.

• The half-leading trait is used by the formatter before and after lines.

  • The use of half-leading accommodates adjacent lines with vastly different font sizes without having to decide which line's leading should apply.

  • Both lines' half-leading traits apply to the gap between lines.

• The initial value of line-height is " normal ".

  • Processor can implement any "reasonable" (sic) value based on font size.

  • A value between 1.0 and 1.2 is recommended.

  • When not specified, different initial values in different processors will yield different area trees and resulting formatting.

    • This is an important portability issue.

• You can override " normal " by specifying a number (e.g. " 1 " or " 1.1 ") or percentage factor of the current font size.

• You can also specify absolute length value.

Geometric font characteristics are based on the em box.

• This refers to the relative measure of the height of the glyphs in the font.

• A box that is 1 em wide by 1 em high is called the design space.

  • Note that creating an inline-container with a square dimension of 1  em, aligned on the after edge of the line and with a visible border, will render a checkbox without having to use a graphic image.

• Design space origin (dominant baseline) is different for ideographic, Indic, and other scripts (e.g. alphabetic and syllabic).

Inline constructs align along one of many baselines defined at the same time, as detailed in Area Alignment Properties ( 7.13 ). When not specified, the automatic dominant baseline is based on the current font. Different baselines are

• alphabetic :

  • is used for most alphabetic and syllabic scripts, e.g.:

    • Western, Southern Indic, non-ideographic Southeast Asian, etc.,

• ideographic :

  • is used by ideographic scripts for the bottom of the ideographic em box,

• hanging :

  • is used for certain Indic scripts,

• mathematical :

  • is used for mathematical symbols,

• after-edge :

  • is at the after edge of the reference area after accommodating line contents,

• before-edge :

  • is at the before edge of the reference area after accommodating line contents,

• central :

  • is at the computed center of the em box,

• middle :

  • is at the center of the ex box sitting on the alphabetic baseline,

  • is approximated by central when the script doesn't have x-height,

• text-after-edge :

  • is equal to the ideographic baseline for ideographic scripts,

  • is equal to the bottom of the space for descending characters for non-ideographic scripts,

    • often is slightly after than the ideographic baseline,

• text-before-edge :

  • is 1 em before the text-after edge.

Different values for alignment-adjust are shown in Figure 4-8.

1. This shows a bordered block with simple text along the dominant baseline with descending letters.

2. A graphic image sits on the dominant baseline (default).

   • Without manipulating alignment-adjust , the graphic sits "high" on the line.

3. A square inline container of size 1  em sits on the dominant baseline (default; alphabetic in this example).

   • Without manipulating alignment-adjust , the container sits "high" on the line.

4. A graphic image is aligned to the after-edge baseline.

   • This often looks more appealing by having a common edge with the text.

5. A container is aligned to the after-edge baseline.

   • This effect aligns everything with the "bottom" of the text box.

   • This often looks more appealing by not going above the top of the text characters.

6. A graphic image is aligned to the middle baseline.

   • The after edge of the graphic sits on the "middle" of the text box.

7. A container is aligned to the middle baseline.

   • The center line of the inline container is centered to the "middle" of the text box.

8. The leading is turned off by using line-height="1" .

   • This shows the before/after edges of the inline container touching the inside edges of the parent line area.

   • The half-leading seen in the previous example above and below the inline container has been removed by adjusting the line height.

Figure 4-8. Alignment of inline constructs

4.1.9 References in the area tree

The first normally-flowed area created by an object with a specified id property will have the value as a trait.

• The application generating the XSL-FO instance is responsible for the uniqueness of id values.

Objects can refer to other objects in the tree creating a reference to the area produced.

• Page number citations use ref-id .

• Hyperlink targets use internal-destination .

• When more than one object has the same identifier, references are resolved to the first area in the area tree created by the first object with the identifier.

• When no object has the required identifier, the formatter signals an error of being unable to meet the requirements.

Note it is unsafe to use XML ID and IDREF constructs directly in an XSL-FO instance when combining XML source documents.

• Each document has an independent value space for unique ID values.

• Using the ID values from multiple documents in a single XSL-FO document can introduce value conflicts.

  • The same ID may have been used in two documents and will end up being doubly used in the XSL-FO document.

It is safest when using XSLT to convert every ID and corresponding IDREF to the generate-id () value for the node corresponding to the element with the ID.

• The value space for generate-id() is guaranteed to be unique for every node of all node trees used in a single transformation process.

• For an element with an ID identifier, use the generated identifier of the element, e.g.:

  • id="{generate-id(.)}" .

• For a reference with an IDREF identifier, use the generated identifier of the referenced element, e.g.:

  • ref-id="{generate-id(id(@idref))}" ,

  • internal-destination="{generate-id(id(@idref))}" .

This is also the safest approach when synthesizing relationships where ID/IDREF is not used, e.g.:

• generate-id() can be used for automatically generated tables of contents.