12.5.1 Layout-driven Generated Text
This clause describes the facilities for generating text when the value of the text to be generated at some point in the flow object tree may not be known until some formatting has been done. The facilities in this clause require the page feature.

NOTE 47

Examples of layout-driven generated text include page numbers, per-page footnote numbers, and dictionary heads.
Each such piece of generated text is represented by an indirect flow object. An indirect flow object contains a specification for a list of flow objects.  The result of formatting an indirect flow object is the result of formatting the list of flow objects it specifies. Indirect flow objects are created only by using the procedures in section 12.5.1.1, Constructing Indirect Sosofos and are not created using the normal flow object creation mechanism.  The content of the indirect flow object is defined to be the list of flow objects that it specifies. For the purposes of inheritance, the contents of an indirect flow object have the indirect flow object as their flow parent.
The generated-object data type is the specification of an expression-language object.  The kernel of a generated-object is defined to be the object that is specified.  The kernel of a generated-object is not available directly but only through the procedures in section 12.5.1.1, Constructing Indirect Sosofos.
(generated-object? obj)
Returns #t if obj is of type generated-object, and otherwise returns #f.
12.5.1.1 Constructing Indirect Sosofos
(general-indirect-sosofo procedure generated-object )
Returns a sosofo containing a single indirect flow object, the content of which is an unlabeled sosofo that is the result of applying the procedure to a list of the kernels of the generated-objects. This requires the general-indirect feature.
(asis-indirect-sosofo generated-object)
Returns a sosofo containing a single indirect flow object whose content is the kernel of generated-object. The kernel of generated-object shall be a sosofo.

NOTE 48

Typically, the generated-object is created by one of the procedures in section 12.5.1.3, Reference Values.
(number-indirect-sosofo generated-object #!key format: add: multiple:)
Returns a sosofo containing a single indirect flow object whose content is the kernel of generated-object, which shall be an integer converted to a string and then to a sosofo.  The keyword arguments control the conversion of the integer to a string as follows:

•  format: is a string specifying the format to use for conversion of the number as in the format-number procedure.  The default is 1.

•  add: is an integer to be added to the kernel of generated-object before conversion. The default is 0.

•  multiple: is an integer.  The integers to be converted that are not multiples of this integer shall be converted to the empty string. The integer specified in the add: argument shall be added to the kernel of generated-object before testing whether it is a multiple. The default is 1.
12.5.1.2 Layout Numbering
The following procedures all return a generated-object whose kernel is a number that may depend on the result of formatting.  When the first-area-of-node: and last-area-of-node: arguments are allowed, the number is specified relative to a reference area. At most one of the first-area-of-node: and last-area-of-node: arguments shall be supplied. If the first-area-of-node: argument is supplied, then its value shall be a node, and the reference area is the first area resulting from the primary flow object of that node. If the last-area-of-node: argument is supplied, then its value shall be a node, and the reference area is the last area resulting from the primary flow object of that node. One of first-area-of-node: or last-area-of-node: shall be supplied unless either:

•  there is a current node when the procedure is evaluated, in which case the reference area is the first area resulting from the primary flow object of the current node, or

•  the procedure is used within a generate-specification, in which case the reference area is the generated area, or

•  the procedure is used in the construction of a decoration area, in which case the reference area is the decorated area.
Although a column is not an area, in this clause it is treated as an area, and an area is deemed to be in a particular column if it is in the column-set of that column and if that column is the first column in the column-set that the area spans.
It shall be an error to use one of the procedures defined in this clause in such a way that it requires the primary flow object of a node that has no primary flow object.
(page-number #!key first-area-of-node: last-area-of-node:)
Returns a generated-object whose kernel is the number of pages before or the same as the reference area.
(category-page-number #!key first-area-of-node: last-area-of-node:)
Returns a generated-object whose kernel is the number of pages before or the same as the reference area that has the same category as the page that is or that contains the reference area.
(page-number-in-node nd)
Returns a generated-object whose kernel is the number of pages that:

•  are before or contain the first of the areas generated by the indirect-sosofo in which the generated-object is used, and

•  contain areas from the flow object that corresponds to nd.

NOTE 49

This procedure could be used within a table header or footer.
(total-node-page-numbers nd)
Returns a generated-object whose kernel is the total number of pages that contain an area from the primary flow object associated with nd.
(column-number #!key first-area-of-node: last-area-of-node:)
Returns a generated-object whose kernel is the number of columns in the same column-subset as the reference area that is before or the same as the reference area.
(footnote-number symbol #!key first-area-of-node: last-area-of-node:)
Returns a generated-object whose kernel is the number of footnote areas that are before or the same as the reference area and are descendants of the nearest ancestor of the reference area that is of the type specified by symbol, which is one of page, page-region, or column.  For this purpose, a footnote area is an area which is the first in the sequence of areas produced from a flow object whose stream is directed into the footnote zone of a column-set-sequence flow object.
(line-number symbol #!key first-area-of-node: last-area-of-node:)
Returns a generated-object whose kernel is the number of line areas that are before or the same as the reference area and are descendants of the nearest ancestor of the reference area that is of the type specified by symbol, where symbol is  one of page, page-region, column, or paragraph. Line areas from paragraphs for which the numbered-lines?: characteristic was #f shall not be counted.
12.5.1.3 Reference Values
A flow object may have a number of named objects associated with it called reference values.
[185] reference-value-type-declaration = (declare-reference-value-type identifier)
A reference-value-type-declaration declares identifier to be the name of a reference-value type.  The identifier shall not be the name of a characteristic or of any other keyword argument accepted by a make-expression.
(first-area-reference-value symbol #!key default: inherit:)
(last-area-reference-value symbol #!key default: inherit:)
(last-preceding-area-reference-value symbol  #!key default:)
(all-area-reference-values symbol #!key unique: inherit:)
Each of these procedures may be used only in a generate-specification or in the construction of a decoration area.  The context in which these procedures are used determines a list of areas, the associated-areas list, on which these procedures operate.
When the procedures are used in the construction of a decoration area, the associated-areas list contains just the decorated area.  When the procedures are used in a generate-specification in a header-specification, footer-specification, or footnote-separator-specification in a column-specification, then the associated-area list contains the areas that are placed in the same column-set area container and that are in the body-text zone and that overlap the column.  When the procedures are used in a generate-specification in a header-specification or footer-specification, or in a page-region-specification, then the associated-area list contains the areas that are placed in the same page-region area container as the generated area.
A flow object is eligible if

•  it has a reference value symbol, or

•  it has an ancestor with a reference value symbol, and inherit: is specified and is not #f.
The relevant reference value for an eligible flow object is the reference value symbol of the eligible flow object, if the eligible flow object has the reference value symbol, and otherwise is the reference value symbol of the nearest ancestor of the eligible flow object that has the reference value symbol.
first-area-reference-value does a pre-order traversal of the flow object tree searching for the first eligible flow object that produces an area that

•  is one of the areas in the associated-area list, or

•  is contained in one of the areas in the associated-area list
and returns a generated-object whose kernel is the value of the relevant reference value for that flow object. When a flow object has more than one stream, then each stream is searched separately.  If the search finds flow objects in more than one stream, then the flow object that is earlier in the layout order of the area is returned.  If the search finds no flow object, the value of the default: argument is returned, which shall be a generated-object.
last-area-reference-value behaves the same as first-area-reference-value except that the order of the search is reversed.
last-preceding-area-reference-value does a pre-order traversal of the flow object tree searching for the last eligible flow object, all of whose areas are before all the areas in the associated-areas list, and returns a generated-object whose kernel is the value of the relevant reference value for that flow object. If no flow object is found, the value of the default: argument is returned, which shall be a generated-object.

NOTE 50

This procedure might be used in the default: argument for the first-area-reference-value procedure.
all-area-reference-values does a pre-order traversal of the flow object tree searching for all eligible flow objects that produce an area that is, or is contained in, one of the areas in the associated-area list; it returns a generated-object whose kernel is a list containing the value of the relevant reference value for each such eligible flow object in the order in which it was found.  If unique: is not #f, then duplicate (in the sense of equal?) values shall be discarded.