12.6.5 Column-set-sequence Flow Object Class

A column-set-sequence flow object is formatted to produce a sequence of column-set areas. A column-set area is a display area. A column-set area is produced by creating and filling an area container. A column-set area contains a set of parallel columns. Typically, column-set areas may be used to fill page-regions; however, column-set areas may also be used to fill other column-set areas. The structure and positioning of each column-set area shall be controlled by the column-set-model to which it conforms. A column-set-sequence flow object shall only be displayed.

A column-set-sequence has the following characteristics.

• column-set-model-map: is a list of lists each with two members, the first a page-model and the second a column-set-model; whenever an area from this column-set-sequence is placed in an area whose nearest ancestor of type page-region uses the specified page-model, then the specified column-set-model shall be used. The initial value is the empty list.

• column-set-model: is a column-set-model specifying the default column-set-model to use if none of the column-set-models specified in the column-set-model-map: characteristic are applicable or #f if there is no default column-set-model. If the value is #f, then it shall be an error if a result area is to be placed within a page-region whose page-model is not listed in the value of the column-set-model-map: characteristic. The initial value is #f.

• position-preference: is either #f or one of the symbols top or bottom. This applies if the flow object is directed into a port on a column-set-sequence flow object that is flowed into both the top-float and bottom-float zones of a column-subset and indicates whether the areas from this flow object may be flowed into only one of the zones. This characteristic is not inherited. The default value is #f.

• span: is a strictly positive integer specifying the number of columns that the areas resulting from this flow object shall span. This characteristic shall apply if the flow object is directed into a port on a column-set-sequence flow object that is flowed into the top-float, bottom-float, or body-text zone of a spannable column-subset. The initial value is 1.

• span-weak?: is a boolean specifying whether the areas resulting from this flow object span weakly rather than strongly. See section 12.6.5.1, Column-set-model. This characteristic applies if the flow object is directed into a port on a column-set-sequence flow object that is flowed into the top-float, bottom-float, or body-text zone of a spannable column-subset and has a span: characteristic with a value greater than 1. The initial value is #f.

• space-before: is an object of type display-space specifying space to be inserted before, in the placement direction, the areas produced by the flow object. This characteristic is not inherited. The default is for no space before to be inserted.

• space-after: is an object of type display-space specifying space to be inserted after, in the placement direction, the areas produced by the flow object. This characteristic is not inherited. The default is for no space after to be inserted.

• keep-with-previous?: is a boolean specifying whether the flow object shall be kept in the same area as the previous flow object. This characteristic is not inherited. The default value is #f.

• keep-with-next?: is a boolean specifying whether the flow object shall be kept in the same area as the next flow object. This characteristic is not inherited. The default value is #f.

• break-before: is #f or one of the symbols page, page-region, column, or column-set specifying that the flow object shall start an area of that type. This characteristic is not inherited. The default is #f.

• break-after: is #f or one of the symbols page, page-region, column, or column-set specifying that the flow object shall end an area of that type. This characteristic is not inherited. The default is #f.

• keep: is one of the following:

• #t meaning that the areas produced by this flow object shall be kept together within the smallest possible area.

• the symbol page indicating that the areas produced by the flow object shall lie within the same page; in this case, the flow object shall have an ancestor flow object of class page-sequence.

• the symbol column-set indicating that the areas produced by the flow object shall lie within the same column set; in this case, the flow object shall have an ancestor of class column-set-sequence.

• the symbol column indicating that the areas produced by the flow object shall lie within the same column set, and that the first column that each area spans in the column set shall be the same.

• #f indicating that this characteristic is to be ignored.

This characteristic is not inherited. The default value is #f.

• may-violate-keep-before?: is a boolean which, if true, specifies that constraints imposed by the keep: characteristics of ancestor flow objects on the relative positioning of this flow object and its previous flow object may not be respected. This characteristic is not inherited. The default value is #f.

• may-violate-keep-after?: is a boolean which, if true, specifies that constraints imposed by keep: characteristics of ancestor flow objects on the relative positioning of this flow object and its next flow object may not be respected. This characteristic is not inherited. The default value is #f.

A column-set-sequence flow object has a port for each port listed in a column-subset-flow-map for any of its column-set-models.

12.6.5.1 Column-set-model

A column-set-model specifies the possible hierarchy of areas for each column-set. For some possible examples of column-sets and column-subset configurations, see Figures 16, An Example of Column-Subsets and 17, Another Example of Column-Subsets.

The top-level area in the hierarchy is the column-set area. A column-set area shall have a filling-direction. If the column-set-model-definition does not contain a filling-direction-specification, then the filling-direction of the parent area shall be used. The size of the column-set area shall be fixed in the direction perpendicular to the filling-direction. It can be fixed either by a width-specification or a height-specification or because this direction is the direction perpendicular to the area's placement direction. The size of a column-set area in the filling-direction may be fixed, or it may grow according to the areas flowed into it.

The area container that produces the column-set shall be filled in a more complicated way than normal area containers. Areas are placed in the column-set area in such a way that they satisfy a number of different constraints.

The most basic constraint is that the areas shall not overlap. This constraint does not apply to decoration areas.

There is a partial ordering defined on the areas that have been placed in a column-set area. This is called the layout order.

NOTE 64

The layout order corresponds to the order in which the areas should be read.

A fundamental constraint on the filling of an area container is that if two areas placed in the column-set area container come from the same stream, then they shall be placed so that their layout order is consistent with their order in the stream.

The column-set area is divided geometrically in a direction parallel to the filling-direction into a number of columns.

NOTE 65

When an area is said to be divided in some direction, this means that it is divided in such a way that the dividing line is in that direction.

A column is not an area container. Each column has an extent that is fixed in the direction perpendicular to the filling-direction.

Each column is a member of exactly one column-subset. The layout order of columns in a column-subset is the order of the column-specifications in a column-subset specification. There is no layout order defined between columns in different column-sets.

NOTE 66

It is for this reason that the layout order is a partial order.

A column-subset is defined to be spannable unless a column in the column-subset is geometrically between any two other consecutive columns in the column-subset. For example, see Figure 19, Non-spannable Column-Subsets.

Each area to be placed in a column-set area shall be associated with a single column-subset. If the filling-direction of the column-set area is top-to-bottom, each area that is placed in the column-set area shall be placed so that the left edge is aligned with the left edge of a column in the column-subset and the right edge is aligned with the right edge of a column in the same column-subset. If the filling-direction of the column-set area is left-to-right or right-to-left, each area that is placed in the column-set area shall be placed so that its top edge is aligned with the top edge of a column in the column-subset and its bottom edge is aligned with the bottom edge of a column in the same column-subset. An area may span more than one column only if the column-subset is spannable. The number of columns in the column-subset that an area spans shall be equal to the value of the span: characteristic of the flow object from which the area comes.

An area that is to be placed in a column-set area shall be created in such a way that its size in the direction perpendicular to the filling direction is such that it exactly spans the required number of columns. In other words, the display-size of the area shall be equal to the distance between one edge of the first column it spans and the opposite edge of the last column it spans.

NOTE 67

This is an exception to the general principle that an area to be placed in an area container is created so that the area's size in the direction perpendicular to the area's placement direction is equal to the size of the area container in the direction perpendicular to the area container's filling-direction.

Each area that is to be placed in a column-set area container is labeled with a zone, which constrains the placement of the area relative to other areas. The allowed zones are top-float, body-text, bottom-float, and footnote. An area labeled with one zone shall be positioned so that it precedes, in the filling-direction, an area that is labeled with a zone that is later in the list, unless there is no column that is spanned by both areas. For example, see Figure 20, Column-set areas.

An area labeled with the footnote zone shall span exactly one column.

NOTE 68

Full-width footnotes in a multi-column layout may be achieved using a nested-column-set.

An area that spans more than one column may span either weakly or strongly depending on the value of the span-weak?: characteristic on the flow object from which the area comes. An area that spans more than one column strongly is defined to follow in the layout order any areas that:

• are in the same column-subset as the area,

• precede the area geometrically in the filling-direction,

• have a span that is completely included in the span of the area, and

• are labeled with the same zone as the area.

An area that spans more than one column weakly is defined to follow in the layout order exactly those areas that it would follow if it occupied only the first of the columns that it spans.

Two or more column-subsets may be tied together. Column-subsets that are tied together shall have the same number of columns. When an area spans strongly more than one column of a column-subset, then the layout order of each column-subset that is tied to that column-subset shall be modified as if an empty area had been created and placed at the same position in the filling-direction as the spanning area and with the same size in the filling-direction as the spanning area so that it spans the corresponding columns of the tied-column-subset; this area can overlap the spanning area.

NOTE 69

A sequence of columns containing sidenotes is usually tied to the sequence of columns containing the text to which the sidenotes refer.

When the spanning area is synchronized using the side-sync procedure with an area in a tied-column-subset that does not span, then it shall be placed in the first column in the tied column-subset:

• whose corresponding column in the other column-subset is spanned by the spanning area, and

• which is not covered by the spanning area.

A column-set-model-definition defines variable to be an object of type column-set-model.

(column-set-model? obj)

Returns #t if obj is of type column-set-model, and otherwise returns #f.

[205] fill-out-specification = (fill-out expression)

The expression shall evaluate to a boolean. If it is #t, then each column-set area shall be filled out in the filling-direction to the maximum size allowed by the area in which it is placed.

For each column-subset in the column-set-model, there shall be a column-subset-specification.

[207] column-subset-flow-map = (flow ((port-specifier zone-name+))+ )

[208] zone-name = top-float | body-text | bottom-float | footnote

A column-subset-flow-map specifies that areas resulting from flow objects directed in port-specifier shall be labeled with one of the specified zone-names. Multiple zone-names may be specified for a single port-specifier only if the zone-names are top-float and bottom-float.

[209] top-float-space-below-specification = (top-float-space-below expression)

The expression shall evaluate to an object of type display-space specifying the size of a space to be added. For each column in the column-set that is spanned by an area in the top-float zone, a space of the specified size shall be added immediately after all the areas that span the column and that are in the top-float zone.

[210] bottom-float-space-above-specification = (bottom-float-space-above expression)

The expression shall evaluate to an object of type display-space specifying the size of a space to be added. For each column in the column-set that is spanned by an area in the bottom-float zone, a space of the specified size shall be added immediately before all the areas that span the column and that are in the bottom-float zone.

[211] balance-specification = (balance? expression)

The expression shall evaluate to a boolean. A value of #t indicates that a column-subset in the last column-set produced by a column-set-sequence shall be balanced. A value of #f indicates that it shall not be. If a column-subset is balanced, then free space shall be allocated evenly among all the columns in the column-subset. If a column-subset is not balanced, then free space shall be allocated to the columns in reverse order. The default is for the column-subset not to be balanced.

[212] justify-specification = (justify? expression)

The expression shall evaluate to a boolean specifying whether the column-subset is to be justified. If a column subset is to be justified, the free space shall be distributed before and after the areas in the column-subset according to the minimum and maximum allowed space specified in the display spaces. Otherwise, all free space shall be distributed at the end of each column. The default is for the column-subset not to be justified. A column-subset may only be justified if the fill-out-specification specifies that the column-set is to be filled out.

[213] justify-limit-specification = (justify-limit expression)

The expression shall evaluate to a number between 0 and 100. If the amount of free space in a column as a percentage of the total size of the column exceeds this, then that column shall not be justified. The default is 100.

[214] justify-last-limit-specification = (justify-last-limit expression)

The expression shall evaluate to a number between 0 and 100. A column shall not be justified if the amount of free space in a column in the last column-set in a column-set-sequence as a percentage of the total size of the column exceeds the number returned by the expression. The default is 0.

[215] length-deviation-specification = (length-deviation expression)

The expression shall evaluate to a positive length. When a column-subset is being justified or balanced, then the lengths of the columns may differ by up to this amount. The default is 0pt.

[216] length-decrease-order-specification = (length-decrease-order expression)

The expression shall evaluate to one of the following symbols:

• forward specifying that as columns progress in the forward direction their length shall not increase,

• backward specifying that as columns progress in the backward direction their length shall not increase,

or #f implying no additional constraint on the relative length of the columns.

[217] align-lines-specification = (align-lines? expression)

The expression shall evaluate to a boolean specifying, if true, that an attempt shall be made in the course of distributing free space to keep lines in different columns aligned.

If the column-set filling-direction is top-to-bottom, then the column-specification shall contain a width-specification and an x-origin-specification. If the column-set filling-direction is right-to-left or left-to-right, then the column-specification shall contain a height-specification and a y-origin-specification. These specifications give the geometry of the column.

[219] footnote-separator-specification = (footnote-separator generated-area-clauses)

A footnote-separator-specification specifies areas that shall be generated immediately before the areas in the footnote zone if the footnote zone contains any areas.

[220] tied-column-subset-specification = (tie column-subset-specification column-subset-specification+ )

A tied-column-subset-specification specifies two or more column-subsets that are tied together. See Figure 18, Multiple Column-Subsets.

NOTE 70

This may be used, for example, with sidenotes.