3.1 Document Classes

All other elements can only specify their dimensions in terms of distance from the edges of a reference area. (This is more a feature than a limitation; to set any dimension explicitly, you always have an option of wrapping the desired element into a block- or an inline-container).

4.5.3 Positioning a Block-Area: Margins and Indents

Each block-area has two traits that specify its position and size in the inline-progression-dimension : start-indent and end-indent . They specify the distance from an edge of the content rectangle of the area ( start-edge for start-indent , end-edge for end-indent ) to the respective edge of the content-rectangle of its closest ancestor reference area. Each formatting object that produces areas may have properties that map directly to these traits (and are named the same). See Figure 4-6.

XSL has an alternative mechanism for setting indent traits: an area can be positioned using margin properties. There are four margin properties: margin-top , margin-bottom , margin-left , and margin-right . A margin property specifies the distance from the respective edge of the content-rectangle of the closest ancestor reference-area to the edge of the border-rectangle of the current area. Margin properties can only be absolutely oriented: no writing-mode relative equivalents are provided. There is also a short form ^[1] property margin that sets all the four margins simultaneously, using standard CSS2 rules. ^[2]

In XSL, indents are inheritable. Unless you set them explicitly (in either of the two ways described previously), the content-rectangle of a nested area gets the same inline-progression-dimension as that of an embracing area. Inheritance is discussed further in Appendix E. If you add padding and/or border to the nested area, its border-rectangle will extend outside the content-rectangle of its parent. Note that this differs from CSS2 habits: there, the border-rectangle of a contained box always fits inside the content-rectangle of the container one. If you want to enforce CSS2-style box nesting, you have to specify margin="0pt" explicitly on every contained block.

For the sake of completeness, let's now mention the effects that side floats have on the placement of block-areas. These are areas specified to float in the start or end direction, as might be found in an explanatory note. A side float F is said to intrude into a block-area B if:

• B and F have the same nearest ancestor reference-area.

• There is a line parallel to the inline-progression-direction that intersects border rectangles of both B and F . Think of this as the float stealing space from the block.

Intruding floats make no impact on the placement of normal block-areas. However, they do influence the inline-progression-dimension of the following types of areas:

• line-areas

• reference-areas (generated by a fo:block-container element)

• Areas generated by list-item-body

If an area belongs to one of these types, and has one or more side-floats intruding into it, then its start-indent and end-indent are calculated from the inner side of the float box, rather than from the respective edge of an ancestor-reference-area.

In a typical case, a paragraph of text with an intruding float will have lines shortened to make room for the float. Note that the block itself is not influenced by the float; if it has a border around it, the float will be pasted inside the border. On the other hand, a block-container with an automatically determined width will shrink as a whole, leaving the float outside. ^[3]

4.5.4 Stacking Block-Areas and Spaces

Let's now consider how block-areas are stacked one after another in the block-progression-dimension . We have already seen that the XSL model is based on spaces; now we will see which properties can be used to constrain spaces between areas, and how they interact.

What is a space? Informally speaking, a space is a distance between the area's border-rectangle and the closest visible mark left on the page by any normally positioned area. This mark may be left by a nonzero border, by padding (because padding may contain background), or by a nonempty content-rectangle of any area. Border and padding need not belong to the next or previous area: they may be left by an embracing block that happens to start or end just before or after the current area. Note also that for two consecutive areas, the space-before of the first area is equal to the space-after of the second area. See Figure 4-7.

Spaces before and after a block-area are controlled by space-before and space-after properties. These two properties are compound , with the following components:

.minimum

A length. Default is 0pt.

.optimum

A length. Default is 0pt.

.maximum

A length. Default is 0pt.

precedence

A number or a special token, force . Default is 0.

conditionality

Either discard or retain . Default is discard .

There is also a shorthand notation: by specifying space-before="X" you set all numerical components ( .minimum , .optimum , and .maximum ) to the same value of X .

These compound properties represent a very versatile mechanism: you can constrain a range for the space (from minimum to maximum ), indicate the preferred value ( optimum ), set the relative strength for the constraints ( precedence ), or define space behavior when there is no adjacent area in the same reference-area ( conditionality ).

This complexity is due to the fact that space constraints are not independent. When two consecutive areas meet, there may be several space constraints applicable : a single space value should be chosen to satisfy them all (or rather, to satisfy them to the best extent). In this situation, it is desirable to give a stylesheet writer the maximum control over the selection of the correct space.

As I mentioned earlier, a space constraint between two consecutive areas A and B can be specified in any of the following ways (see Figure 4-8):

• As a space-after of A

• As a space-before of B

• As a space-after of any block-area A1 descendant of A such that there is no other content, padding, or border between A1 and B

• As a space-before of any block-area B1 descendant of B such that there is no other content, padding, or border between A and B1

All these constraints are considered together and merged into a single value, or better, a single range specifier with .minimum , .maximum , and .optimum components. The final decision is delegated to the XSL formatter; it should stick to the resolved .optimum value whenever possible, and choose another value within the .minimum to .maximum range if there are other constraints to satisfy.

The merged space specifier is calculated by the following algorithm:

• If any space property has .precedence="force" (forcing spaces), all space specifiers but forcing ones are discarded. The resulting space specifier should have the sum of .minimum components as its .minimum , the sum of .optimum s as .optimum , and the sum of .maximum s as .maximum . In other words, forcing spaces are additive: they suppress all other spaces but don't merge with each other.

• Otherwise, spaces with the maximum value of .precedence are selected, and others are discarded. If there is more than one space specifier with the same precedence, the one with the higher .optimum value is selected. If there are two or more specifiers with the same .precedence and .optimum values, the resulting space specifier will be equal to the intersection of their ranges; that is, the .minimum will be equal to the greatest of all .minimum s, and the .maximum will be set to the smallest of all .maximum s.

If an area happens to be the first on the page with no preceding marks from which to count space-before , space-before is counted from the before-edge of the content-rectangle of the closest ancestor reference-area. Remember that in this case, only specifiers with .conditionality="retain" are taken into consideration.

Now let's see an example of how all this works. Figure 4-9 represents a typical configuration. Two blocks, each specifies a space: the first specifies a space-after and the second specifies a space-before . Example 4-1 demonstrates how to achieve this.

Example 4-1. Space resolution

<fo:block space-after.minimum="3pt">
            space-after.maximum="24pt"
             space-after.optimum="12pt">
  .....

</fo:block>
<fo:block space-before.minimum="6pt"
             space-before.maximum="18pt"
             space-before.optimum="12pt">
....
</fo:block>

The resolution is for the resultant minimum to be set to 6pt, the maximum to be set to 18pt, and the computed value, set to 12pt. This is shown in Figure 4-9, with the shaded area indicating the extents. When the optimum values are equal, take the greatest minimum and least maximum , so the resolved space in this case has a minimum of 6pt.

It is easy to create a contradictory set of space constraints. In such a case, formatter behavior is not described by the specification and remains application-specific. The stylesheet writer is responsible for the consistency of the constraint system. The space mechanism is powerful and versatile, but not fool proof.

This differs drastically from the CSS box model where top- and bottom-margins are a single value. Margins in CSS are self-contained and additive in most cases, and the margin merging algorithm is rudimentary — the widest margin is selected. XSL supports margin properties on before-edge and after-edge, too; they are converted into space-specifiers as follows :

margin-{correspondent}="X":
   .minimum = .optimum = .maximum = X
   .conditionality="retain"
   .precedence="force"

This permits you to simulate CSS-style box stacking in XSL. Note that CSS-style margins won't merge with each other and will overcome every non-forcing space specifier.

4.5.5 Stacking Inline-Areas

Stacking inline-areas inside a line-area is perfectly parallel to stacking block-areas inside a reference-area. An inline-area has traits to control free space left before and after it in the inline-progression-direction :

space-start

Controls how much space is left before the start-edge of the inline-area; it is set by the space-start compound property;

space-end

Controls how much space is left after the end-edge of the inline-area; it is set by the space-end compound property.

space-start and space-end for inline-areas are calculated by the same rules as space-before and space-after for block-areas (accounting for possible change of direction). Any conditionality components control constraint suppression at the start or end of a line-area.

Alignment of inline-areas in the block-progression-direction is controlled by the baseline mechanism (see Chapter 6).

4.5.6 Stacking Line-Areas

Stacking line-areas inside a block-area is less trivial. The distance between lines is controlled by the compound property line-height , with the same components as other space specifiers. Its interpretation depends on the algorithm selected for line-stacking. There are three algorithms available, switched by the line-stacking-strategy property on the parent block-area: font-height , max-height , and line-height .

To describe the placement of lines in terms of stacked areas, here are some terms. A line-area can be logically divided into three parts (see Figure 4-10):

• The allocation-rectangle is the central part of the line-area around the baseline. It roughly corresponds to the content-rectangle, but doesn't necessarily coincide with it. Its size in the block-progression-dimension is determined differently depending on the line-stacking-strategy selected.

• There are two spaces around the allocation-rectangle, which are both equal to half-leading . Half-leading spaces get .conditionality and .precedence attibutes from the line-height property and can be merged with other spaces and suppressed in the beginning or at the end of a reference area — just like other spaces. However, half-leading spaces never get merged with their likes.

Line-areas are stacked one after another inside a block-area, leaving no other space before or after them but the half-leadings from both sides. The gap between allocation rectangles of two adjacent line-areas consists of the half-leading-after of the first line plus the half-leading-before of the second line. (Note that these two spaces aren't merged.)

The available line-stacking strategies are line-height , font-height , and max-height .

Note that for lines built entirely of text using a nominal font, all three line-stacking strategies give the same value of base line separation (equal to the line-height ). They differ only in the treatment of large elements that go outside the nominal- requested -line-rectangle: the simplest strategy is font-height : separation between baselines of adjacent line areas is constant throughout the whole block and does not depend on the actual contents of any line. Inter-line distance should equal line-height.optimum , unless the formatter chooses another value in the range .minimum to .maximum to satisfy other constraints on block placement. Sizes of line-area elements are determined as follows:

• Allocation-rectangle for line-stacking-strategy="font-height" depends solely on the nominal font for the block. Its before-edge is offset by text-altitude from the baseline, and its after-edge is placed at text-depth from the baseline in the block-progression-direction . In the XSL spec, this is called nominal-requested-line-rectangle, and is likely to be the most common one used.

• Half-leading is half the difference between the line-height chosen and the height of the allocation rectangle:

  half-leading = (line-height - text-altitude - text-depth) / 2
  

In other words, this strategy stacks lines as if the whole block consisted entirely of plain text, with text-altitude and text-depth remaining constant across the block. Eventual inclusions of other font glyphs or large images don't influence the distance between the baselines. Using font-height will certainly make a mess of things if you include, for instance, graphics in your document. In such a case, use max-height .

max-height is a more complicated strategy. The half-leading is calculated by the same formula as with font-height and remains constant for all lines in the block. The allocation-rectangle, instead, is calculated in a more complex way: its dimension in the block-progression-dimension is determined by the elements whose before-edge and after-edge are the most distant from the baseline (for Western scripts these are determined by the tallest/deepest elements; that's why the strategy is called max-height ). With this strategy, the gaps between the lines remain constant across the block; if the line has elements bigger than glyphs of nominal font, its separation from its neighboring lines will be increased so as to leave the gap between lines equal to the constant value (two half-leadings). However, if the line consists only of small elements, the baseline separation is not stretched : the allocation-rectangle will always contain the nominal-requested-line-rectangle.

One more trait influences line placement with this strategy: line-height-shift-adjustment . It controls processing of areas whose baselines are shifted from the common baseline of the line-area. There can be two values for this trait:

consider-shifts

When calculating the allocation-rectangle, baseline shift elements are taken into account. For instance, if a line contains a subscript, the next line will be placed lower because the allocation-rectangle will extend to reach the after-edge of the subscript glyph.

disregard-shifts

Baseline shifts are disregarded. If a line contains subscripts or superscripts, its placement is not influenced by their presence.

The last strategy is line-height . This way of stacking lines comes from CSS and differs greatly from the preceding two. In this method, the line-height trait is considered a property of each inline-area, rather than the whole block-area, and may vary across the block: it is even possible that areas within the same line have different values of line-height . There is no common half-leading defined for the block; instead, every single area gets margins before and after it, depending on the local value of the line-height trait. The allocation-rectangle of the line-area is defined to be the least rectangle to include both the nominal-requested-line-rectangle and all inline-areas with their margins. Allocation-rectangles defined this way are stacked one after another, with no additional gap between them.

The algorithm to determine margins on inline-areas is similar to the method of calculating line separation in the max-height strategy:

• For inline images and reference-areas (containers), margins are set by normal space-specifiers that are treated as CSS margins: conditionality and precedence are neglected, and no merging ever occurs.

• For other types of areas, the half-leading is calculated as a function of line-height , text-altitude , and text-depth . The formula is the same as earlier for font-height and max-height , but trait values are taken from the inline-area. This half-leading is added before and after the content-rectangle (determined by text-altitude / text-depth traits). Note that the block-progression-dimension of the resulting margin-rectangle will be always equal to the line-height .

Within this strategy, line-height-shift-adjustment is also applicable and has the same meaning: when line-height-shift-adjustment="disregard-shifts" is set, all calculations are performed as if all inline-areas were aligned along the same baseline. This permits exclusion of inter-line gap widening due to subscripts and superscripts.

• font-height neglects big elements — line separation is always fixed. This strategy gives the tightest line placement. Other strategies can only increase inter-line spaces.

• max-height adjusts separation in such a way that visible gap between lines remains constant.

• line-height permits variation of the treatment of outstanding elements on a case-by-case basis.

[1]  Setting all components of a compound property by omitting the component specification is termed a short form .

[2]  In fact, margins are tolerated in XSL as a secondary mechanism to ensure CSS2 compatibility, but they don't integrate well with XSL layout model based on constrained spaces. We strongly advise using indents instead of margins.

[3]  This is expected to change significantly in the next version of the XSL spec.

CONTENTS