Implementing Properties

Date: Wed, 18 Dec 2002 16:25:24 +0000 (+0000) Subject: W.I.P. changes to alt.design pages. X-Git-Tag: Alt-Design-integration-base~237 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=82016acb52a3177d3a1e164608e143e11b1ce5c6;p=xmlgraphics-fop.git W.I.P. changes to alt.design pages. git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@195778 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/src/documentation/content/xdocs/design/alt.design/alt-properties.xml b/src/documentation/content/xdocs/design/alt.design/alt-properties.xml index ce5396618..990af1359 100644 --- a/src/documentation/content/xdocs/design/alt.design/alt-properties.xml +++ b/src/documentation/content/xdocs/design/alt.design/alt-properties.xml @@ -3,170 +3,151 @@ "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd"> -

- Implementing Properties +

+ Implementing Properties - + -

- +

An alternative properties implementation - The following discussion focusses on the relationship between - Flow Objects in the Flow Object tree, and properties. There - is no (or only passing) discussion of the relationship between - properties and traits, and by extension, between properties - and the Area tree. The discussion is illustrated with some - pseudo-UML diagrams. + The following discussion focusses on the relationship between + Flow Objects in the Flow Object tree, and properties. There + is no (or only passing) discussion of the relationship between + properties and traits, and by extension, between properties + and the Area tree.

- Property handling is complex and expensive. Varying numbers of - properties apply to individual Flow Objects - (FOs) in the FO - tree but any property may effectively be - assigned a value on any element of the tree. If that property - is inheritable, its defined value will then be available to - any children of the defining FO. + Property handling is complex and expensive. Varying numbers of + properties apply to individual Flow Objects + (FOs) in the FO tree but + any property may effectively be assigned a value on any + element of the tree. If that property is inheritable, its + defined value will then be available to any children of the + defining FO.

- (XSL 1.0 Rec) 5.1.4 Inheritance - ...The inheritable properties can be placed on any formatting - object. + (XSL 1.0 Rec) 5.1.4 Inheritance + ...The inheritable properties can be placed on any formatting + object.

- Even if the value is not inheritable, it may be accessed by - its children through the inherit keyword or the - from-parent() core function, and potentially by - any of its descendents through the - from-nearest-specified-value() core function. + Even if the value is not inheritable, it may be accessed by + its children through the inherit keyword or the + from-parent() core function, and potentially by + any of its descendents through the + from-nearest-specified-value() core function.

- In addition to the assigned values of properties, almost every - property has an initial value which is used - when no value has been assigned. + In addition to the assigned values of properties, almost every + property has an initial value which is used + when no value has been assigned.

The history problem -

- The difficulty and expense of handling properties comes from - this univeral inheritance possibility. The list of properties - which are assigned values on any particular FO - element will not generally be large, but a current value is - required for each property which applies to the FO - being processed. -

- The environment from which these values may be selected - includes, for each FO, for each applicable property, - the value assigned on this FO, the value which - applied to the parent of this FO, the nearest value - specified on an ancestor of this element, and the initial - value of the property. -

- Data requirement and structure -

- This determines the minimum set of properties and associated - property value assignments that is necessary for the - processing of any individual FO. Implicit in this - set is the set of properties and associated values, - effective on the current FO, that were assigned on - that FO. -

- This minimum requirement - the initial value, the - nearest ancestor specified value, the parent computed value - and the value assigned to the current element - - suggests a stack implementation. -

+ The difficulty and expense of handling properties comes from + this univeral inheritance possibility. The list of properties + which are assigned values on any particular FO + element will not generally be large, but a current value is + required for each property which applies to the FO + being processed. +

+ The environment from which these values may be selected + includes, for each FO, for each applicable + property, the value assigned on this FO, + the value which applied to the parent of this FO, + the nearest value specified on an ancestor of this element, + and the initial value of the property. +

- Stack considerations -

- One possibility is to push to the stack only a minimal set - of required elements. When a value is assigned, the - relevant form or forms of that value (specified, computed, - actual) are pushed onto the stack. As long as each - FO maintains a list of the properties which were - assigned from it, the value can be popped when the focus of - FO processing retreats back up the FO tree. -

- The complication is that, for elements which are not - automatically inherited, when an FO is encountered - which does not assign a value to the - property, the initial value must either be already at the - top of the stack or be pushed onto the stack. -

- As a first approach, the simplest procedure may be to push a - current value onto the stack for every element - initial - values for non-inherited properties and the parental value - otherwise. Then perform any processing of assigned values. - This simplifies program logic at what is hopefully a small - cost in memory and processing time. It may be tuned in a - later iteration. -

- Stack implementation -

- Initial attempts at this implementation have used - LinkedLists as the stacks, on the assumption - that -

random access would not be required
- pushing and popping of list elements requires nearly - constant (low) time -
no penalty for first addition to an empty list
efficient access to both bottom and top of stack

- However, it may be required to perform stack access - operations from an arbitrary place on the stack, in which - case it would probably be more efficient to use - ArrayLists instead. -

+ The Construction Hierarchy +

+ Properties are resoved in the FO tree in a + strictly hierarchical manner. Nodes are detected in the + input in a pre-order traversal, and are + built in the same order. This imples that there are two + phases, or states, of property resolution and construction. + Any particular FO node is either in a state of constructing + its own subtree, or in a stable state where the subtree + construction is complete. These states have differenct data + requirements. +

Subtree building: + In this state, all properties defined on this node, or any + of its ancestors must be available to the subtree. In + effect, any property defined on this node must be + available to its descendants, as all properties defined on + any ancestor are available to this node. +
Stable: subtree building complete: + In this state, only the properties applicable to + this node need be available. +

- Class vs instance -

- An individual stack would contain values for a particular - property, and the context of the stack is the property class - as a whole. The property instances would be represented by - the individual values on the stack. If properties are to be - represented as instantiations of the class, the stack - entries would presumably be references to, or at least - referenced from, individual property objects. However, the - most important information about individual property - instances is the value assigned, and the relationship of - this property object to its ancestors and its descendents. - Other information would include the ownership of a property - instance by a particular FO, and, in the other - direction, the membership of the property in the set of - properties for which an FO has defined values. -

- In the presence of a stack, however, none of this required - information mandates the instantiation of properties. All - of the information mentioned so far can be effectively - represented by a stack position and a link to an - FO. If the property stack is maintained in - parallel with a stack of FOs, even that link is - implicit in the stack position. -

+ Representing Properties: <property> Classes +

+ Class vs instance +

+ What information is required of <property> objects? + More particularly, what information is particular to the + <property> classes, and what to the instantiated + objects? The answer to this question depend largely on + how the <poroperty> objects are used in the context + of layout and Area tree construction. The approach taken + in this implementation is that properties are simply flags + on certain data values associated with FOs. The semantics + of these flags are determined within the layout engine. +

+ Certain constant information attaches to individual + <property> classes. This information is detailed in + the descriptions of individual properties in Section + 7 of the specification. Such information is + represented in class fields and data + structures within the classes. +

+ The "instance" information content of a <property> + is: +

+ explicitly, the PropertyValue datum of + the property, and +
+ implicitly, the Flow Object to which + the property is attached. +

+ Properties, then, serve essentially to link FO + instances with PropertyValue instances, + attaching certain invariant semantic markers to the + PropertyValues in the process. In this implementation, + these functions can be realised entirely within the + <property> classes themselves, + without the need to instantiate any objects. In practice, + <property> singletons are + instantiated to make access to some invariants simpler. +

- Next: property classes overview. + Next: property classes overview.

- + diff --git a/src/documentation/content/xdocs/design/alt.design/classes-overview.xml b/src/documentation/content/xdocs/design/alt.design/classes-overview.xml index 161901385..01624ca84 100644 --- a/src/documentation/content/xdocs/design/alt.design/classes-overview.xml +++ b/src/documentation/content/xdocs/design/alt.design/classes-overview.xml @@ -3,201 +3,188 @@ "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd"> -

- Property classes overview +

+ Property classes overview + email="pbwest@powerup.com.au"/> -

- +

- Classes overview -

- The class of all properties -

- If individual properties can have a "virtual reality" on the - stack, where is the stack itself to be instantiated? One - possibility is to have the stacks as static - data structures within the individual property classes. - However, the reduction of individual property instances to - stack entries allows the possibility of further - virtualization of property classes. If the individual - properties can be represented by an integer, i.e. a - static final int, the set of individual - property stacks can be collected together into one array. - Where to put such an overall collection? Creating an - über-class to accommodate everything that applies to - property classes as a whole allows this array to be defined - as a static final something[]. -

- The overall property classes -

- This approach has been taken for the experimental code. - Rather than simply creating a overall class containing - common elements of properties and acting as a superclass, - advantage has been taken of the facility for nesting of - top-level classes. All of the individual property classes - are nested within the Properties class. - This has advantages and disadvantages. -

Disadvantages: - The file becomes extremely cumbersome. This can cause - problems with "intelligent" editors. E.g. - XEmacs syntax highlighting virtually grinds to a - halt with the current version of this file.

- - Possible problems with IDEs. There may be speed problems - or even overflow problems with various IDEs. The current - version of this and related files had only been tried with - the [X]Emacs JDE environment, without difficulties - apart from the editor speed problems mentioned - above.

- - Retro look and feel. Not the done Java thing.

-
Advantages: - Everything to do with properties in the one place (more or - less.)

- - Eliminates the need for a large part of the (sometimes) - necessary evil of code generation. The One Big File of - foproperties.xml, with its ancillary xsl, is - absorbed into the One Bigger File of - Properties.java. The huge advantage of this - is that it is Java. -

- The property information classes -

- In fact, in order to keep the size of the file down to more - a more manageable level, the property information classes of - static data and methods have been split tentatively into - three: -

PropNames: - Contains an array, propertyNames, of the names of - all properties, and a set of enumeration constants, one - for each property name in the PropertyNames - array. These constants index the name of the properties - in propertyNames, and must be manually kept in - sync with the entries in the array. (This was the last of - the classes split off from the original single class; - hence the naming tiredness.) -

-
PropertyConsts: - Contains two basic sets of data:
- Property-indexed arrays and property set - definitions.

- - Property-indexed arrays are elaborations - of the property indexing idea discussed in relation to the - arrays of property stacks. One of the arrays is

- - public static final LinkedList[] - propertyStacks

- - This is an array of stacks, implemented as - LinkedLists, one for each property.

- - The other arrays provide indexed access to fields which - are, in most cases, common to all of the properties. An - exception is

- - public static final Method[] - complexMethods

- - which contains a reference to the method - complex() which is only defined for - properties which have complex value parsing requirements. - It is likely that a similar array will be defined for - properties which allow a value of auto.

- - The property-indexed arrays are initialized by - static initializers in this class. The - PropNames class and - Properties - nested classes are scanned in order to obtain or derive - the data necessary for initialization.

- - Property set definitions are - HashSets of properties (represented by - integer constants) which belong to each of the categories - of properties defined. They are used to simplify the - assignment of property sets to individual FOs. - Representative HashSets include - backgroundProps and - tableProps.

-
Properties: -
- This class contains only sets of constants for use by the - individual property classes, but it also importantly - serves as a container for all of the property classes, and - some convenience pseudo-property classes.

- - Constants sets include:

- - Datatype constants. A bitmap set of - integer constants over a possible range of 2^0 to 2^31 - (represented as -2147483648). E.g.
- INTEGER = 1
- ENUM = 524288

- Some of the definitions are bit-ORed - combinations of the basic values. Used to set the - dataTypes field of the property - classes.

- - Trait mapping constants. A bitmap set of - integer constants over a possible range of 2^0 to 2^31 - (represented as -2147483648), representing the manner in - which a property maps into a trait. Used to set - the traitMapping field of the property - classes.

- - Initial value constants. A sequence of - integer constants representing the datatype of the initial - value of a property. Used to set the - initialValueType field of the property - classes.

- - Inheritance value constants. A sequence - of integer constants representing the way in which the - property is normally inherited. Used to set the - inherited field of the property - classes.

- - Nested property classes. The - Properties class serves as the holding pen for - all of the individual property classes, and for property - pseudo-classes which contain data common to a number of - actual properties, e.g. ColorCommon. -

+ Properties: packages +

+ org.apache.fop.fo +
+
PropNames
+
+ This class maintains an array of property names, + synchronized to a complete set of property name constants for + indexing property-based arrays. It includes methods to + convert an + index to a name and to convert a property + name to an index. +
+ +
+ PropertyConsts +
+
+ A singleton instance of PropertyConsts + is created by the static initializer of the pconsts field. + Working from the <property> indices defined in + PropNames, the methods in this class collect and supply + the values of fields defined in <property> objects + into arrays.
+ + The heart of this class in the method setupProperty, which constructs the + <property> name from the index, instantiates a + singleton of the appropriate class, and extracts static + fields by reflection from that instance into the arrays + of field values. +
+ +
PropertySets
+
+ This class provides a number of + ROBitSets representing many of the sets + of properties defined in Section 7 of the + specification. Note that the Border, + Padding and Background sets are + defined separately. +
+ +
FOPropertySets
+
+ This class provides a number of + ROBitSets representing sets of + properties which are applicable in particular subtrees + of the FO tree. These sets are provided so that other + properties can be ignored during processing of the + subtrees. +
+ +
ShorthandPropSets
+
+ This class contains arrays of shorthand property + indices and compound property + indices, and ROBitSets + representing the expansion sets of these shorthands and + compounds. Various methods useful in the expansion of + these properties are also included. +
+ +
FOAttributes
+
+
+
+ org.apache.fop.fo.properties +
+
Property
+
+ The base class for all individual <property> classes. +
+
ColumnNumber
+
+ The actual <property> class with the lowest index + number, followed in the oindex order by properties + required for further processing, e.g. FontSize. +
+
....
+
....
+
Background
+
+ First in index order of the remainining shorthand + properties, followed in index order by all other + remaining shorthands. +
+
....
+
....
+
AbsolutePosition
+
+ First in index order of the remaining properties. + Within this ordering, compound properties precede their + expansion properties, and corresponding relative + properties precede corresponding absolute properties. +
+
....
+
....
+
ZIndex
+
+ The <property> class with the highest index + number. +
+
+
+ org.apache.fop.fo.expr +
+
PropertyTokenizer
+
+ The tokenizer for the <property> expression + parser. Defines a set of token constants and + returns these with associated token values. +
+ +
PropertyParser
+
+ This extends PropertyTokenizer. It + parses <property> expressions on the basis of the + tokens passed to it by its superclass, generating + PropertyValues, including + PropertyValueLists. +
+ +
PropertyException
+
+ The basic class for all <property>-related + exceptions. It extends + FOPException. It is housed in this + package by historical accident. +
+ +
+ DataTypeNotImplementedException
+ FunctionNotImplementedException
+ PropertyNotImplementedException +
+
+ A set of particular exceptions extending + PropertyException. Also in this package + by accident. +
+ +
+
org.apache.fop.datatypes
org.apache.fop.datatypes.indirect

- Previous: alt.properties + Previous: alt.properties

+ + diff --git a/src/documentation/content/xdocs/design/alt.design/compound-properties.xml b/src/documentation/content/xdocs/design/alt.design/compound-properties.xml index bd326a4da..509434989 100644 --- a/src/documentation/content/xdocs/design/alt.design/compound-properties.xml +++ b/src/documentation/content/xdocs/design/alt.design/compound-properties.xml @@ -3,216 +3,216 @@ "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd"> -

- Compound properties +

+ Compound properties -

- +

Compound properties in XSLFO - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Property type	Section	Inherited	'inherit'
<length-range>
minimum
optimum
maximum
block-progression-dimension	7.14.1	no	yes
inline-progression-dimension	7.14.5	no	yes
leader-length	7.21.4	yes	yes
<length-conditional>
length
conditionality
border-after-width	7.7.12	no	yes
border-before-width	7.7.9	no	yes
border-end-width	7.7.18	no	yes
border-start-width	7.7.15	no	yes
padding-after	7.7.32	no	yes
padding-before	7.7.31	no	yes
padding-end	7.7.34	no	yes
padding-start	7.7.33	no	yes
<length-bp-ip-direction>
block-progression-direction
inline-progression-direction
border-separation	7.26.5	yes	yes
<space>
minimum
optimum
maximum
precedence
conditionality
letter-spacing	7.16.2	yes	yes
line-height	7.15.4	yes	yes
space-after	7.10.6	no	yes
space-before	7.10.5	no	yes
space-end	7.11.1	no	yes
space-start	7.11.2	no	yes
word-spacing	7.16.8	yes	yes
<keep>
within-line
within-column
within-page
keep-together	7.19.3	yes	yes
keep-with-next	7.19.4	no	yes
keep-with-previous	7.19.5	no	yes
Property type	Section	Inherited	'inherit'
<length-range>
minimum
optimum
maximum
block-progression-dimension	7.14.1	no	yes
inline-progression-dimension	7.14.5	no	yes
leader-length	7.21.4	yes	yes
<length-conditional>
length
conditionality
border-after-width	7.7.12	no	yes
border-before-width	7.7.9	no	yes
border-end-width	7.7.18	no	yes
border-start-width	7.7.15	no	yes
padding-after	7.7.32	no	yes
padding-before	7.7.31	no	yes
padding-end	7.7.34	no	yes
padding-start	7.7.33	no	yes
<length-bp-ip-direction>
block-progression-direction
inline-progression-direction
border-separation	7.26.5	yes	yes
<space>
minimum
optimum
maximum
precedence
conditionality
letter-spacing	7.16.2	yes	yes
line-height	7.15.4	yes	yes
space-after	7.10.6	no	yes
space-before	7.10.5	no	yes
space-end	7.11.1	no	yes
space-start	7.11.2	no	yes
word-spacing	7.16.8	yes	yes
<keep>
within-line
within-column
within-page
keep-together	7.19.3	yes	yes
keep-with-next	7.19.4	no	yes
keep-with-previous	7.19.5	no	yes

- + diff --git a/src/documentation/content/xdocs/design/alt.design/coroutines.xml b/src/documentation/content/xdocs/design/alt.design/coroutines.xml index cc18f1248..d5ad8f12b 100644 --- a/src/documentation/content/xdocs/design/alt.design/coroutines.xml +++ b/src/documentation/content/xdocs/design/alt.design/coroutines.xml @@ -3,116 +3,117 @@ "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd"> -

- Implementing co-routines +

+ Implementing co-routines -

- +

Implementing Co-routines in FOP

- All general page layout systems have to solve the same - fundamental problem: expressing a flow of text with its own - natural structure as a series of pages corresponding to the - physical and logical structure of the output medium. This - simple description disguises many complexities. Version 1.0 - of the Recommendation, in Section 3, Introduction to - Formatting , includes the following comments. + All general page layout systems have to solve the same + fundamental problem: expressing a flow of text with its own + natural structure as a series of pages corresponding to the + physical and logical structure of the output medium. This + simple description disguises many complexities. Version 1.0 + of the Recommendation, in Section 3, Introduction to + Formatting , includes the following comments.

- [Formatting] comprises several steps, some of which depend on - others in a non-sequential way.
...and...
- [R]efinement is not necessarily a straightforward, sequential - procedure, but may involve look-ahead, back-tracking, or - control-splicing with other processes in the formatter. + [Formatting] comprises several steps, some of which depend on + others in a non-sequential way.
...and...
+ [R]efinement is not necessarily a straightforward, sequential + procedure, but may involve look-ahead, back-tracking, or + control-splicing with other processes in the formatter.

Section 3.1, Conceptual Procedure, includes:

- The procedure works by processing formatting objects. Each - object, while being processed, may initiate processing in - other objects. While the objects are hierarchically - structured, the processing is not; processing of a given - object is rather like a co-routine which may pass control to - other processes, but pick up again later where it left off. + The procedure works by processing formatting objects. Each + object, while being processed, may initiate processing in + other objects. While the objects are hierarchically + structured, the processing is not; processing of a given + object is rather like a co-routine which may pass control to + other processes, but pick up again later where it left off.

Application of co-routines -

- If one looks only at the flow side of the equation, it's - difficult to see what the problem might be. The ordering of - the elements of the flow is preserved in the area tree, and - where elements are in an hierarchical relationship in the - flow, they will generally be in an hierarchical relationship - in the area tree. In such circumstances, the recursive - processing of the flow seems quite natural. -

- The problem becomes more obvious when one thinks about the - imposition of an unrelated page structure over the - hierarchical structure of the document content. Take, e.g., - the processing of a nested flow structure which, at a certain - point, is scanning text and generating line-areas, nested - within other block areas and possibly other line areas. The - page fills in the middle of this process. Processing at the - lowest level in the tree must now suspend, immediately - following the production of the line-area which filled the - page. This same event, however, must also trigger the closing - and flushing to the area tree of every open area of which the last - line-area was a descendant. -

- Once all of these areas have been closed, some dormant process - or processes must wake up, flush the area sub-tree - representing the page, and open a new page sub-tree in the - area tree. Then the whole nested structure of flow objects - and area production must be re-activated, at the point in - processing at which the areas of the previous page were - finalised, but with the new page environment. The most - natural way of expressing the temporal relationship of these - processes is by means of co-routines. -

- Normal sub-routines (methods) display a hierarchical - relationship where process A suspends on invoking process B, - which on termination returns control to A which resumes from - the point of suspension. Co-routines instead have a parallel - relationship. Process A suspends on invoking process B, but - process B also suspends on returning control to process A. To - process B, this return of control appears to be an invocation - of process A. When process A subsequently invokes B and - suspends, B behaves as though its previous invocation of A has - returned, and it resumes from the point of that invocation. - So control bounces between the two, each one resuming where it - left off.

- Figure 1 -

- For example, think of a page-production method working on a - complex page-sequence-master. -

- - void makePages(...) { - ... - while (pageSequence.hasNext()) { - ... - page = generateNextPage(...); - boolean over = flow.fillPage(page); - if (over) return; - } - } - -

- The fillPage() method, when it fills a page, will - have unfinished business with the flow, which it will want to - resume at the next call; hence co-routines. One way to - implement them in Java is by threads synchronised on some - common argument-passing object. -

+ If one looks only at the flow side of the equation, it's + difficult to see what the problem might be. The ordering of + the elements of the flow is preserved in the area tree, and + where elements are in an hierarchical relationship in the + flow, they will generally be in an hierarchical relationship + in the area tree. In such circumstances, the recursive + processing of the flow seems quite natural. +

+ The problem becomes more obvious when one thinks about the + imposition of an unrelated page structure over the + hierarchical structure of the document content. Take, e.g., + the processing of a nested flow structure which, at a certain + point, is scanning text and generating line-areas, nested + within other block areas and possibly other line areas. The + page fills in the middle of this process. Processing at the + lowest level in the tree must now suspend, immediately + following the production of the line-area which filled the + page. This same event, however, must also trigger the closing + and flushing to the area tree of every open area of which the last + line-area was a descendant. +

+ Once all of these areas have been closed, some dormant process + or processes must wake up, flush the area sub-tree + representing the page, and open a new page sub-tree in the + area tree. Then the whole nested structure of flow objects + and area production must be re-activated, at the point in + processing at which the areas of the previous page were + finalised, but with the new page environment. The most + natural way of expressing the temporal relationship of these + processes is by means of co-routines. +

+ Normal sub-routines (methods) display a hierarchical + relationship where process A suspends on invoking process B, + which on termination returns control to A which resumes from + the point of suspension. Co-routines instead have a parallel + relationship. Process A suspends on invoking process B, but + process B also suspends on returning control to process A. To + process B, this return of control appears to be an invocation + of process A. When process A subsequently invokes B and + suspends, B behaves as though its previous invocation of A has + returned, and it resumes from the point of that invocation. + So control bounces between the two, each one resuming where it + left off.

+ Figure 1 +

+ For example, think of a page-production method working on a + complex page-sequence-master. +

+ + void makePages(...) { + ... + while (pageSequence.hasNext()) { + ... + page = generateNextPage(...); + boolean over = flow.fillPage(page); + if (over) return; + } + } + +

+ The fillPage() method, when it fills a page, will + have unfinished business with the flow, which it will want to + resume at the next call; hence co-routines. One way to + implement them in Java is by threads synchronised on some + common argument-passing object. +

- + diff --git a/src/documentation/content/xdocs/design/alt.design/footnotes.xml b/src/documentation/content/xdocs/design/alt.design/footnotes.xml index 42c467dda..4afda6e25 100644 --- a/src/documentation/content/xdocs/design/alt.design/footnotes.xml +++ b/src/documentation/content/xdocs/design/alt.design/footnotes.xml @@ -3,138 +3,138 @@ "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd"> -

- Implementing footnotes +

+ Implementing footnotes -

- +

Implementing footnotes in FOP

- Footnotes present difficulties for page layout primarily - because their point of invocation in the flow is different - from their point of appearance in the area tree. All of the - content lines of a footnote may appear on the same page as its - invocation point, all may appear on a following page, or the - lines may be split over a page or pages. (This characteristic - leads to another problem when a footnote overflows the last - page of flow content, but that difficulty will not be - discussed here.) This note considers some aspects of the - implementation of footnotes in a galley-based design. + Footnotes present difficulties for page layout primarily + because their point of invocation in the flow is different + from their point of appearance in the area tree. All of the + content lines of a footnote may appear on the same page as its + invocation point, all may appear on a following page, or the + lines may be split over a page or pages. (This characteristic + leads to another problem when a footnote overflows the last + page of flow content, but that difficulty will not be + discussed here.) This note considers some aspects of the + implementation of footnotes in a galley-based design.

Footnotes and galleys -

- In the structure described in the introduction to FOP galleys, - footnotes would be pre-processed as galleys themselves, but - they would remain attached as subtrees to their points of - invocation in the main text. Allocation to a - footnote-reference-area would only occur in the resolution - to Area nodes. -

- When footnotes are introduced, the communication between - galleys and layout manager, as mentioned above, would be - affected. The returned information would two b-p-d values: - the primary line-area b-p-d impact and the footnote b-p-d - impact. The distinction is necessary for two reasons; to - alert the layout manager to the first footnote of the page, - and because the footnote b-p-d will always impact the - main-reference-area b-p-d, whereas the primary inline-area - may not, e.g. in the case of multiple span-areas. -

+ In the structure described in the introduction to FOP galleys, footnotes would be + pre-processed as galleys themselves, but they would remain + attached as subtrees to their points of invocation in the + main text. Allocation to a footnote-reference-area would + only occur in the resolution to Area nodes. +

+ When footnotes are introduced, the communication between + galleys and layout manager, as mentioned above, would be + affected. The returned information would two b-p-d values: + the primary line-area b-p-d impact and the footnote b-p-d + impact. The distinction is necessary for two reasons; to + alert the layout manager to the first footnote of the page, + and because the footnote b-p-d will always impact the + main-reference-area b-p-d, whereas the primary inline-area + may not, e.g. in the case of multiple span-areas. +

Multiple columns and footnotes - - A possible method for multi-column layout and balancing - with footnotes, using a galley-based approach. - -

- This note assumes a galley, as discussed elsewhere, flowing text with - footnotes and possibly other blocks into a possibly - multi-column area. The logic of flowing into multiple - columns is trivially applied to a single column. The galley - is manipulated within the context of the layout - tree. -

- Associated with the galley are two sets of data. - One contains the maps of all "natural" break-points and - the of all hyphenation break-points. This set is - constructed at the time of construction of the galley and - is a constant for a given galley. The second contains - dynamic data which represents one possible attempt to lay - out the galley. There may be multiple sets of such data - to reflect varying attempts. The data of this set are, - essentially, representations of line-areas, with the supporting - information necessary to determine these line-areas. -

- The line-area data includes the boundaries within the - galley of each line-area, the boundaries of each column - and the boundaries of the "page", or main area. When a - line-area boundary occurs at a hyphenation point, a - "virtual hyphen" is assumed and accounted for in the - i-p-d. As mentioned, individual footnote galleys will - hang from the parent galley. The associated data of the - footnote galleys is similar: a once-only break-points map, - and one or more line-area maps. No column boundaries are - required, but a page boundary is required at the end of - the last footnote or where a footnote breaks across a page - boundary. -

- A number of b-p-d values are also maintained. For each - line-area, the b-p-d, the main area b-p-d increment, the - footnote b-p-d increment and the footnote's page-related - b-p-d increment are required. The main-area b-p-d - increments for any particular line-area are dependent on - the column position of the line-area. Total b-p-d's are - also kept: total footnote b-p-d, total main area b-p-d, - and totals for each column.

- Figure 1 Columns before first footnote. -

+ + A possible method for multi-column layout and balancing + with footnotes, using a galley-based approach. + +

+ This note assumes a galley, as discussed elsewhere, flowing text with + footnotes and possibly other blocks into a possibly + multi-column area. The logic of flowing into multiple + columns is trivially applied to a single column. The galley + is manipulated within the context of the layout + tree. +

+ Associated with the galley are two sets of data. + One contains the maps of all "natural" break-points and + the of all hyphenation break-points. This set is + constructed at the time of construction of the galley and + is a constant for a given galley. The second contains + dynamic data which represents one possible attempt to lay + out the galley. There may be multiple sets of such data + to reflect varying attempts. The data of this set are, + essentially, representations of line-areas, with the supporting + information necessary to determine these line-areas. +

+ The line-area data includes the boundaries within the + galley of each line-area, the boundaries of each column + and the boundaries of the "page", or main area. When a + line-area boundary occurs at a hyphenation point, a + "virtual hyphen" is assumed and accounted for in the + i-p-d. As mentioned, individual footnote galleys will + hang from the parent galley. The associated data of the + footnote galleys is similar: a once-only break-points map, + and one or more line-area maps. No column boundaries are + required, but a page boundary is required at the end of + the last footnote or where a footnote breaks across a page + boundary. +

+ A number of b-p-d values are also maintained. For each + line-area, the b-p-d, the main area b-p-d increment, the + footnote b-p-d increment and the footnote's page-related + b-p-d increment are required. The main-area b-p-d + increments for any particular line-area are dependent on + the column position of the line-area. Total b-p-d's are + also kept: total footnote b-p-d, total main area b-p-d, + and totals for each column.

+ Figure 1 Columns before first footnote. +

Balancing columns -

- Figure 2 Adding a line area with first - footnote. -

- Columns are balanced dynamically in the galley preliminary - layout. While the galley retains its basic linear - structure, the accompanying data structures accomplish - column distribution and balancing. As each line-area is - added, the columns are re-balanced. N.B. - This re-balancing involves only some of the dynamic data - associated with the participating galley(s). The data - structures associating breakpoints with the beginning and - end of individual line areas does not change in - re-balancing; only the association of line-area with column, - and, possibly, the various impact values for each line-area. -

- Figure 3 Adding a line area with next - footnote. -

+ Figure 2 Adding a line area with first + footnote. +

+ Columns are balanced dynamically in the galley preliminary + layout. While the galley retains its basic linear + structure, the accompanying data structures accomplish + column distribution and balancing. As each line-area is + added, the columns are re-balanced. N.B. + This re-balancing involves only some of the dynamic data + associated with the participating galley(s). The data + structures associating breakpoints with the beginning and + end of individual line areas does not change in + re-balancing; only the association of line-area with column, + and, possibly, the various impact values for each line-area. +

+ Figure 3 Adding a line area with next + footnote. +

Layout managers in the flow of control - To be developed. + To be developed.

- + diff --git a/src/documentation/content/xdocs/design/alt.design/galleys.xml b/src/documentation/content/xdocs/design/alt.design/galleys.xml index 2cedc4802..3e09c931d 100644 --- a/src/documentation/content/xdocs/design/alt.design/galleys.xml +++ b/src/documentation/content/xdocs/design/alt.design/galleys.xml @@ -3,214 +3,215 @@ "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd"> -

- Galleys +

+ Galleys -

- +

Layout galleys in FOP

Galleys in Lout -

- Jeffrey H. Kingston, in The - Design and Implementation of the Lout Document Formatting - Language Section 5, describes the - galley abstraction which he implemented in - Lout. A document to be formatted is a stream of - text and symbols, some of which are receptive - symbols. The output file is the first receptive - symbol; the formatting document is the first galley. The - archetypical example of a receptive symbol is - @FootPlace and its corresponding galley - definition, @FootNote. -

- Each galley should be thought of as a concurrent process, and - each is associated with a semaphore (or synchronisation - object.) Galleys are free to "promote" components into - receptive targets as long as

- an appropriate target has been encountered in the file, -
- the component being promoted contains no unresolved galley - targets itself, and -
- there is sufficient room for the galley component at the - target. -

- If these conditions are not met, the galley blocks on its - semaphore. When conditions change so that further progress - may be possible, the semaphore is signalled. Note that the - galleys are a hierarchy, and that the processing and - promotion of galley contents happens bottom-up. -

+ Jeffrey H. Kingston, in The + Design and Implementation of the Lout Document Formatting + Language Section 5, describes the + galley abstraction which he implemented in + Lout. A document to be formatted is a stream of + text and symbols, some of which are receptive + symbols. The output file is the first receptive + symbol; the formatting document is the first galley. The + archetypical example of a receptive symbol is + @FootPlace and its corresponding galley + definition, @FootNote. +

+ Each galley should be thought of as a concurrent process, and + each is associated with a semaphore (or synchronisation + object.) Galleys are free to "promote" components into + receptive targets as long as

+ an appropriate target has been encountered in the file, +
+ the component being promoted contains no unresolved galley + targets itself, and +
+ there is sufficient room for the galley component at the + target. +

+ If these conditions are not met, the galley blocks on its + semaphore. When conditions change so that further progress + may be possible, the semaphore is signalled. Note that the + galleys are a hierarchy, and that the processing and + promotion of galley contents happens bottom-up. +

Some features of galleys -

- It is essential to note that galleys are self-managing; they - are effectively layout bots which require only a - receptive area. If a galley fills a receptive area (say, at - the completion of a page), the galley will wait on its - semaphore, and will remain stalled until a new receptive - area is uncovered in the continued processing (say, as the - filled page is flushed to output and a new empty page is - generated.) -

- Difficulties with this approach become evident when there - are mutual dependencies between receptive areas which - require negotiation between the respective galleys, and, in - some cases, arbitrary deadlock breaking when there is no - clear-cut resolution to conflicting demands. Footnote - processing and side floats are examples. A thornier example - is table column layout in auto mode, where the - column widths are determined by the contents. In - implementing galleys in FOP, these difficulties must be - taken into account, and some solutions proposed. -

- Galleys model the whole of the process of creating the final - formatted output; the document as a whole is regarded as a - galley which flushes in to the output file. -

+ It is essential to note that galleys are self-managing; they + are effectively layout bots which require only a + receptive area. If a galley fills a receptive area (say, at + the completion of a page), the galley will wait on its + semaphore, and will remain stalled until a new receptive + area is uncovered in the continued processing (say, as the + filled page is flushed to output and a new empty page is + generated.) +

+ Difficulties with this approach become evident when there + are mutual dependencies between receptive areas which + require negotiation between the respective galleys, and, in + some cases, arbitrary deadlock breaking when there is no + clear-cut resolution to conflicting demands. Footnote + processing and side floats are examples. A thornier example + is table column layout in auto mode, where the + column widths are determined by the contents. In + implementing galleys in FOP, these difficulties must be + taken into account, and some solutions proposed. +

+ Galleys model the whole of the process of creating the final + formatted output; the document as a whole is regarded as a + galley which flushes in to the output file. +

The layout tree - -

- This proposal for implementing galleys in FOP makes use of a - layout tree. As with the layout managers already - proposed, the layout tree acts as a bridge between the FO Tree and the Area Tree. If the elements of - the FO Tree are FO nodes, and the elements of the Area Tree - are Area nodes, representing areas to be drawn on the output - medium, the elements of the layout tree are galley - nodes and area tree fragments. - The area tree fragments are the final stages of the - resolution of the galleys; the output of the galleys will be - inserted directly into the Area Tree. The tree structure - makes it clear that the whole of the formatting process in - FOP, under this model, is a hierarchical series of galleys. - The dynamic data comes from fo:flow and fo:static-content, - and the higher-level receptive areas are derived from the - layout-master-set. -

+ +

+ This proposal for implementing galleys in FOP makes use of a + layout tree. As with the layout managers already + proposed, the layout tree acts as a bridge between the FO Tree and the Area Tree. If the elements of the + FO Tree are FO nodes, and the elements of the Area Tree are + Area nodes, representing areas to be drawn on the output + medium, the elements of the layout tree are galley + nodes and area tree fragments. + The area tree fragments are the final stages of the + resolution of the galleys; the output of the galleys will be + inserted directly into the Area Tree. The tree structure + makes it clear that the whole of the formatting process in + FOP, under this model, is a hierarchical series of galleys. + The dynamic data comes from fo:flow and fo:static-content, + and the higher-level receptive areas are derived from the + layout-master-set. +

Processing galleys -

- Galleys are processed in two basic processing environments: -

- Inline- and block-progression dimensions known -

- The galley at set-up is provided with both an - inline-progression-dimension (i-p-d) and - a block-progression-dimension (b-p-d). - In this case, no further intervention is necessary to lay - out the galley. The galley has the possibility of laying - itself out, creating all necessary area nodes. This does - not preclude the possibility that some children of this - galley will not be able to be so directly laid out, and - will fall into the second category. -

- While the option of "automatic" layout exists, to use - such a method would relinquish the possibility of - monitoring the results of such layout and performing - fine-tuning. -

- Inline- ior block-progression-dimensions unknown -

- The galley cannot immediately be provided with an i-p-d - ior a b-p-d. This will occur in some of the difficult - cases mentioned earlier. In these cases, the parent - galley acts as a layout manager, similar to the sense used - in another - discussion. The children, lacking full receptive - area dimensions, will proceed with galley pre-processing, - a procedure which will, of necessity, be followed - recursively by all of its children down to the atomic - elements of the galley. These atomic elements are the - individual fo:character nodes and images of fixed - dimensions. -

+ Galleys are processed in two basic processing environments: +

+ Inline- and block-progression dimensions known +

+ The galley at set-up is provided with both an + inline-progression-dimension (i-p-d) and + a block-progression-dimension (b-p-d). + In this case, no further intervention is necessary to lay + out the galley. The galley has the possibility of laying + itself out, creating all necessary area nodes. This does + not preclude the possibility that some children of this + galley will not be able to be so directly laid out, and + will fall into the second category. +

+ While the option of "automatic" layout exists, to use + such a method would relinquish the possibility of + monitoring the results of such layout and performing + fine-tuning. +

+ Inline- ior block-progression-dimensions unknown +

+ The galley cannot immediately be provided with an i-p-d + ior a b-p-d. This will occur in some of the difficult + cases mentioned earlier. In these cases, the parent + galley acts as a layout manager, similar to the sense used + in another + discussion. The children, lacking full receptive + area dimensions, will proceed with galley pre-processing, + a procedure which will, of necessity, be followed + recursively by all of its children down to the atomic + elements of the galley. These atomic elements are the + individual fo:character nodes and images of fixed + dimensions. +

Galley pre-processing - -

- Galley pre-processing involves the spatial resolution of - objects from the flows to the greatest extent possible - without information on the dimensions of the target area. - Line-areas have a block progression dimension which is - determined by their contents. To achieve full generality in - layouts of indeterminate dimensions, the contents of - line-areas should be laid out as though their inline - progression dimension were limited only by their content. - In terms of inline-areas, galleys would process text and - resolve the dimensions of included images. Text would be - collected into runs with the same alignment - characteristics. In the process, all possible "natural" and - hyphenation break-points can be determined. Where a - line-area contains mixed fonts or embedded images, the b-p-d - of the individual line-areas which are eventually stacked - will, in general, depend on the line break points, but the - advantage of this approach is that such actual selections - can be backed out and new break points selected with a - minimum of re-calculation. This can potentially occur - whenever a first attempt at page layout is backed out. -

- Figure 1 -

- Once this pre-processing has been achieved, it is - envisaged that a layout manager might make requests to the - galley of its ability to fill an area of a given - inline-progression-dimension. A positive response would - be accompanied by the block-progression-dimension. The - other possibilities are a partial fill, which would also - require b-p-d data, and a failure due to insufficient - i-p-d, in which case the minimum i-p-d requirement would - be returned. Note that decisions about the - actual dimensions of line-areas to be filled can be - deferred until all options have been tested. -

- The other primary form of information provided by a - pre-processed galley is its minimum and maximum i-p-d, so - that decisions can be made by the parent on the spacing of - table columns. Apart from information requests, - higher-level processes can either make requests of the - galleys for chunks of nominated sizes, or simply provide the - galley with an i-p-d and b-p-d, which will trigger the - flushing of the galley components into Area nodes. Until - they have flushed, the galleys must be able to respond to a - sequence of information requests, more or less in the manner - of a request iterator, and separately manage the flushing of - objects into the area tree. The purpose of the "request - iterator" would be to support "incremental" information - requests like getNextBreakPosition. -

+ +

+ Galley pre-processing involves the spatial resolution of + objects from the flows to the greatest extent possible + without information on the dimensions of the target area. + Line-areas have a block progression dimension which is + determined by their contents. To achieve full generality in + layouts of indeterminate dimensions, the contents of + line-areas should be laid out as though their inline + progression dimension were limited only by their content. + In terms of inline-areas, galleys would process text and + resolve the dimensions of included images. Text would be + collected into runs with the same alignment + characteristics. In the process, all possible "natural" and + hyphenation break-points can be determined. Where a + line-area contains mixed fonts or embedded images, the b-p-d + of the individual line-areas which are eventually stacked + will, in general, depend on the line break points, but the + advantage of this approach is that such actual selections + can be backed out and new break points selected with a + minimum of re-calculation. This can potentially occur + whenever a first attempt at page layout is backed out. +

+ Figure 1 +

+ Once this pre-processing has been achieved, it is + envisaged that a layout manager might make requests to the + galley of its ability to fill an area of a given + inline-progression-dimension. A positive response would + be accompanied by the block-progression-dimension. The + other possibilities are a partial fill, which would also + require b-p-d data, and a failure due to insufficient + i-p-d, in which case the minimum i-p-d requirement would + be returned. Note that decisions about the + actual dimensions of line-areas to be filled can be + deferred until all options have been tested. +

+ The other primary form of information provided by a + pre-processed galley is its minimum and maximum i-p-d, so + that decisions can be made by the parent on the spacing of + table columns. Apart from information requests, + higher-level processes can either make requests of the + galleys for chunks of nominated sizes, or simply provide the + galley with an i-p-d and b-p-d, which will trigger the + flushing of the galley components into Area nodes. Until + they have flushed, the galleys must be able to respond to a + sequence of information requests, more or less in the manner + of a request iterator, and separately manage the flushing of + objects into the area tree. The purpose of the "request + iterator" would be to support "incremental" information + requests like getNextBreakPosition. +

- + diff --git a/src/documentation/content/xdocs/design/alt.design/index.xml b/src/documentation/content/xdocs/design/alt.design/index.xml index 08e60f059..de27791e6 100644 --- a/src/documentation/content/xdocs/design/alt.design/index.xml +++ b/src/documentation/content/xdocs/design/alt.design/index.xml @@ -2,83 +2,126 @@ + + -

FOP Alternative Design Alternative Design Approach to FOP $Revision$ $Name$ -

- +

+ +

Alternative Design

- This section of the FOP web site contains notes on approaches - to an alternative design for FOP. The individual documents - here are fragmentary, being notes of particular issues, - without an overall framework as yet. + This section of the FOP web site contains notes on approaches + to an alternative design for FOP. The individual documents + here are fragmentary, being notes of particular issues, + without an overall framework as yet. +

+ The main aims of this redesign effort are:

full conformance with the Recommendation
no limitation on the size of files
increased performance
reduced memory footprint

- The main aims of this redesign effort are: + Secondary aims include:

full conformance with the Recommendation
increased performance
reduced memory footprint
no limitation on the size of files
increased performance
reduced memory footprint

- In order to achieve these aims, the primary areas - of design interest are: + In order to achieve these aims, the primary areas + of design interest are:

- Representing properties, for most purposes, as integers. -
- Distributing FOP processing over a number of threads with - single-point downstream communication and flow control by - means of traditional producer/consumer queues. The threads - so far under consideration are: -
- XML parser
- FO tree builder
- layout engine
- Area tree builder
-
- Representing trees with explicit Tree objects, rather than - as implicit relationships among other objects. -
- Caching integrated into the tree node access methods. -
+ Representing properties, for most purposes, as integers. +
+ Implementing a top-down processing model for each of the + processing components. +
+ Distributing FOP processing over a number of threads with + single-point downstream communication and flow control by + means of traditional producer/consumer queues. The threads + so far under consideration are: +
- XML parser
- FO tree builder
- layout engine
- Area tree builder
+
+ Redesigning XML parsing and FO tree building using a + pull-parsing methodology with integrated FO + input validation. +
+ Representing vital relationships among the elements with + appropriate data structures. These include: +
- + Representing trees with explicit Tree objects, rather than + as implicit relationships among other objects. +
- + Drawing threads through the tree nodes to + represent linear layout relationships for resolving + keeps, breaks and space specifiers. +
+
+ Caching integrated into the tree node access methods. +

- Status and availability -

- The ALT DESIGN effort is not taking place on the - main line of development, represented by the HEAD - tag on the CVS trunk. The source is available via the - FOP_0-20-0_Alt-Design tag. This code has only a crude, - non-Ant build environment, and is expected only to - compile at this stage. Only the parser stage and the first - stage of FO tree building is present. However, the first - example of producer/consumer binding is working, the Tree - class with inner Tree.Node and inner - Tree.Node.iterators classes are available and - working. Property handling is quite advanced, and is likely - to be almost complete some time in July, 2002. -

- Only Peter - West is working on the ALT DESIGN sub-project. -

+ Status and availability +

+ The ALT DESIGN effort is not taking place on the + main line of development, represented by the HEAD + tag on the CVS trunk. The source is available via the + FOP_0-20-0_Alt-Design tag. This code has only a + non-Ant build environment based on some small unix + shell scripts and the jikes compiler. The parser + stage and the FO tree building code is present. The first + example of producer/consumer binding is working, the Tree + class and the Node class with inner iterator + classes are available and working. Property handling is + almost complete, and all FO classes are present and + sufficiently complete to allow for FO tree building. +

+ Preliminary results and follow-up testing of FO tree building shows memory + reductions of almost 50% compared to the most recently tuned + version of the maintenance version of the code (FOP 0.20.5 + RC). Alt-Design FO tree building was also slightly faster, + in spite of the use of pull parsing implemented on top of + SAX. +

+ Currently, only Peter + West is working on the ALT DESIGN sub-project. +

- + + diff --git a/src/documentation/content/xdocs/design/alt.design/keeps.xml b/src/documentation/content/xdocs/design/alt.design/keeps.xml index d7fc973c7..0da02547d 100644 --- a/src/documentation/content/xdocs/design/alt.design/keeps.xml +++ b/src/documentation/content/xdocs/design/alt.design/keeps.xml @@ -3,108 +3,108 @@ "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd"> -

- Keeps and breaks +

+ Keeps and breaks -

- +

Keeps and breaks in layout galleys

- The layout galleys and the - layout tree - which is their context have been discussed elsewhere. Here we - discuss a possible method of implementing keeps and breaks - within the context of layout galleys and the layout tree. + The layout galleys and the + layout tree + which is their context have been discussed elsewhere. Here we + discuss a possible method of implementing keeps and breaks + within the context of layout galleys and the layout tree.

Breaks -

- Breaks may be handled by inserting a column- or page-break - pseudo-object into the galley stream. For break-before, the - object would be inserted before the area in which the flow - object, to which the property is attached, is leading. If - the flow object is leading in no ancestor context, the - pseudo-object is inserted before the object itself. - Corresponding considerations apply for break-after. - Selection of the position for these objects will be further - examined in the discussion on keeps. -

+ Breaks may be handled by inserting a column- or page-break + pseudo-object into the galley stream. For break-before, the + object would be inserted before the area in which the flow + object, to which the property is attached, is leading. If + the flow object is leading in no ancestor context, the + pseudo-object is inserted before the object itself. + Corresponding considerations apply for break-after. + Selection of the position for these objects will be further + examined in the discussion on keeps. +

Keeps -

- Conceptually, all keeps can be represented by a - keep-together pseudo-area. The keep-together property - itself is expressed during layout by wrapping all of the - generated areas in a keep-together area. Keep-with-previous - on formatting object A becomes a keep-together area spanning - the first non-blank normal area leaf node, L, generated by A - or its offspring, and the last non-blank normal area leaf - node preceding L in the area tree. Likewise, keep-with-next - on formatting object A becomes a keep-together area spanning - the last non-blank normal area leaf node, L, generated by A - or its offspring, and the first non-blank normal area leaf - node following L in the area tree. -
TODO REWORK THIS for block vs inline -

- The obvious problem with this arrangement is that the - keep-together area violate the hierarachical arrangement of - the layout tree. They form a concurrent structure focussed - on the leaf nodes. This seems to be the essential problem - of handling keep-with-(previous/next); that it cuts across - the otherwise tree-structured flow of processing. Such - problems are endemic in page layout. -

- In any case, it seems that the relationships between areas - that are of interest in keep processing need some form of - direct expression, parallel to the layout tree itself. - Restricting ourselves too block-level elements, and looking - only at the simple block stacking cases, we get a diagram - like the attached PNG. In order to track the relationships - through the tree, we need four sets of links. -

- Figure 1 -

- -

- The three basic links are: -

Leading edge to leading edge of first normal child.
Trailing edge to leading edge of next normal - sibling.
Trailing edge to trailing edge of parent.

- Superimposed on the basic links are bridging links which - span adjacent sets of links. These spanning links are the - tree violators, and give direct access to the areas which - are of interest in keep processing. They could be - implemented as double-linked lists, either within the layout - tree nodes or as separate structures. Gaps in the spanning - links are joined by simply reproducing the single links, as - in the diagram. The whole layout tree for a page is - effectively threaded in order of interest, as far as keeps - are concerned. -

- The bonus of this structure is that it looks like a superset - of the stacking constraints. It gives direct access to all - sets of adjacent edges and sets of edges whose space - specifiers need to be resolved. Fences can be easily enough - detected during the process of space resolution. -

+ Conceptually, all keeps can be represented by a + keep-together pseudo-area. The keep-together property + itself is expressed during layout by wrapping all of the + generated areas in a keep-together area. Keep-with-previous + on formatting object A becomes a keep-together area spanning + the first non-blank normal area leaf node, L, generated by A + or its offspring, and the last non-blank normal area leaf + node preceding L in the area tree. Likewise, keep-with-next + on formatting object A becomes a keep-together area spanning + the last non-blank normal area leaf node, L, generated by A + or its offspring, and the first non-blank normal area leaf + node following L in the area tree. +
TODO REWORK THIS for block vs inline +

+ The obvious problem with this arrangement is that the + keep-together area violate the hierarachical arrangement of + the layout tree. They form a concurrent structure focussed + on the leaf nodes. This seems to be the essential problem + of handling keep-with-(previous/next); that it cuts across + the otherwise tree-structured flow of processing. Such + problems are endemic in page layout. +

+ In any case, it seems that the relationships between areas + that are of interest in keep processing need some form of + direct expression, parallel to the layout tree itself. + Restricting ourselves too block-level elements, and looking + only at the simple block stacking cases, we get a diagram + like the attached PNG. In order to track the relationships + through the tree, we need four sets of links. +

+ Figure 1 +

+ The three basic links are: +

Leading edge to leading edge of first normal child.
Trailing edge to leading edge of next normal + sibling.
Trailing edge to trailing edge of parent.

+ Superimposed on the basic links are bridging links which + span adjacent sets of links. These spanning links are the + tree violators, and give direct access to the areas which + are of interest in keep processing. They could be + implemented as double-linked lists, either within the layout + tree nodes or as separate structures. Gaps in the spanning + links are joined by simply reproducing the single links, as + in the diagram. The whole layout tree for a page is + effectively threaded in order of interest, as far as keeps + are concerned. +

+ The bonus of this structure is that it looks like a superset + of the stacking constraints. It gives direct access to all + sets of adjacent edges and sets of edges whose space + specifiers need to be resolved. Fences can be easily enough + detected during the process of space resolution. +

- + diff --git a/src/documentation/content/xdocs/design/alt.design/properties-classes.xml b/src/documentation/content/xdocs/design/alt.design/properties-classes.xml index c077be44b..5b5225f8f 100644 --- a/src/documentation/content/xdocs/design/alt.design/properties-classes.xml +++ b/src/documentation/content/xdocs/design/alt.design/properties-classes.xml @@ -3,141 +3,141 @@ "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd"> -

- Properties$classes +

+ Properties$classes -

- +

fo.Properties and the nested properties classes -

Nested property classes -

- Given the intention that individual properties have only a - virtual instantiation in the arrays of - PropertyConsts, these classes are intended to - remain as repositories of static data and methods. The name - of each property is entered in the - PropNames.propertyNames array of - Strings, and each has a unique integer constant - defined, corresponding to the offset of the property name in - that array. -

- Fields common to all classes -

final int dataTypes: - This field defines the allowable data types which may be - assigned to the property. The value is chosen from the - data type constants defined in Properties, and - may consist of more than one of those constants, - bit-ORed together. -
final int traitMapping: - This field defines the mapping of properties to traits - in the Area tree. The value is chosen from the - trait mapping constants defined in Properties, - and may consist of more than one of those constants, - bit-ORed together. -
final int initialValueType: - This field defines the data type of the initial value - assigned to the property. The value is chosen from the - initial value type constants defined in - Properties. -
final int inherited: - This field defines the kind of inheritance applicable to - the property. The value is chosen from the inheritance - constants defined in Properties. -

- Datatype dependent fields -

Enumeration types

- final String[] enums
- This array contains the NCName text - values of the enumeration. In the current - implementation, it always contains a null value at - enum[0].

+

+ Given the intention that individual properties have only a + virtual instantiation in the arrays of + PropertyConsts, these classes are intended to + remain as repositories of static data and methods. The name + of each property is entered in the + PropNames.propertyNames array of + Strings, and each has a unique integer constant + defined, corresponding to the offset of the property name in + that array. +

+ Fields common to all classes +

final int dataTypes: + This field defines the allowable data types which may be + assigned to the property. The value is chosen from the + data type constants defined in Properties, and + may consist of more than one of those constants, + bit-ORed together. +
final int traitMapping: + This field defines the mapping of properties to traits + in the Area tree. The value is chosen from the + trait mapping constants defined in Properties, + and may consist of more than one of those constants, + bit-ORed together. +
final int initialValueType: + This field defines the data type of the initial value + assigned to the property. The value is chosen from the + initial value type constants defined in + Properties. +
final int inherited: + This field defines the kind of inheritance applicable to + the property. The value is chosen from the inheritance + constants defined in Properties. +

+ Datatype dependent fields +

Enumeration types: + final String[] enums
+ This array contains the NCName text + values of the enumeration. In the current + implementation, it always contains a null value at + enum[0].

- final String[] - enumValues
When the number of - enumeration values is small, - enumValues is a reference to the - enums array.

+ final String[] + enumValues
When the number of + enumeration values is small, + enumValues is a reference to the + enums array.

- final HashMap - enumValues
When the number of - enumeration values is larger, - enumValues is a - HashMap statically initialized to - contain the integer constant values corresponding to - each text value, indexed by the text - value.

+ final HashMap + enumValues
When the number of + enumeration values is larger, + enumValues is a + HashMap statically initialized to + contain the integer constant values corresponding to + each text value, indexed by the text + value.

- final int - enumeration-constants
A - unique integer constant is defined for each of the - possible enumeration values.

-
Many types: - final datatype - initialValue: - When the initial datatype does not have an implicit - initial value (as, for example, does type - AUTO) the initial value for the property is - assigned to this field. The type of this field will - vary according to the initialValueType - field. -
AUTO: PropertyValueList auto(property, - list)>: - When AUTO is a legal value type, the - auto() method must be defined in the property - class.
- NOT YET IMPLEMENTED. -
COMPLEX: PropertyValueList complex(property, - list)>: - COMPLEX is specified as a value type when complex - conditions apply to the selection of a value type, or - when lists of values are acceptable. To process and - validate such a property value assignment, the - complex() method must be defined in the - property class. -

+ final int + enumeration-constants
A + unique integer constant is defined for each of the + possible enumeration values.

+

Many types: + final datatype + initialValue

+ When the initial datatype does not have an implicit + initial value (as, for example, does type + AUTO) the initial value for the property is + assigned to this field. The type of this field will + vary according to the initialValueType + field. +

AUTO: PropertyValueList auto(property, + list)>

+ When AUTO is a legal value type, the + auto() method must be defined in the property + class.
+ NOT YET IMPLEMENTED. +

COMPLEX: PropertyValueList complex(property, + list)>

+ COMPLEX is specified as a value type when complex + conditions apply to the selection of a value type, or + when lists of values are acceptable. To process and + validate such a property value assignment, the + complex() method must be defined in the + property class. +

Nested property pseudo-classes -

- The property pseudo-classes are classes, like - ColorCommon which contain values, particularly - enums, which are common to a number of actual - properties. -

+ The property pseudo-classes are classes, like + ColorCommon which contain values, particularly + enums, which are common to a number of actual + properties. +

- Previous: property classes overview. + Previous: property classes overview.

- + diff --git a/src/documentation/content/xdocs/design/alt.design/spaces.xml b/src/documentation/content/xdocs/design/alt.design/spaces.xml index 40b028aaa..92577b3de 100644 --- a/src/documentation/content/xdocs/design/alt.design/spaces.xml +++ b/src/documentation/content/xdocs/design/alt.design/spaces.xml @@ -3,177 +3,177 @@ "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd"> -

- Keeps and space-specifiers +

+ Keeps and space-specifiers -

- +

Keeps and space-specifiers in layout galleys

- The layout galleys and the - layout tree - which is the context of this discussion have been discussed - elsewhere. A previous document - discussed data structures which might facilitate the lining of - blocks necessary to implement keeps. Here we discuss the - similarities between the keep data structures and those - required to implement space-specifier resolution. + The layout galleys and the + layout tree + which is the context of this discussion have been discussed + elsewhere. A previous document + discussed data structures which might facilitate the lining of + blocks necessary to implement keeps. Here we discuss the + similarities between the keep data structures and those + required to implement space-specifier resolution.

Space-specifiers - - 4.3 Spaces and Conditionality - ... Space-specifiers occurring in sequence may interact with - each other. The constraint imposed by a sequence of - space-specifiers is computed by calculating for each - space-specifier its associated resolved space-specifier in - accordance with their conditionality and precedence. - - - 4.2.5 Stacking Constraints ... The intention of the - definitions is to identify areas at any level of the tree - which have only space between them. - -

- The quotations above are pivotal to understanding the - complex discussion of spaces with which they are associated, - all of which exists to enable the resolution of adjacent - <space>s. It may be helpful to think of stacking - constraints as <space>s interaction or - <space>s stacking interaction. -

+ + 4.3 Spaces and Conditionality + ... Space-specifiers occurring in sequence may interact with + each other. The constraint imposed by a sequence of + space-specifiers is computed by calculating for each + space-specifier its associated resolved space-specifier in + accordance with their conditionality and precedence. + + + 4.2.5 Stacking Constraints ... The intention of the + definitions is to identify areas at any level of the tree + which have only space between them. + +

+ The quotations above are pivotal to understanding the + complex discussion of spaces with which they are associated, + all of which exists to enable the resolution of adjacent + <space>s. It may be helpful to think of stacking + constraints as <space>s interaction or + <space>s stacking interaction. +

Block stacking constraints -

- In the discussion of block stacking constraints in Section - 4.2.5, the notion of fence is introduced. For - block stacking constraints, a fence is defined as either a - reference-area boundary or a non-zero padding or border - specification. Fences, however, do not come into play - when determining the constraint between siblings. (See - Figure 1.) -

Figure 1

- - Figure 1 assumes a block-progression-direction of top to - bottom. - -

- In Diagram a), block A has - non-zero padding and borders, in addition to non-zero - spaces. Note, however, that the space-after of A is - adjacent to the space-before of block P, so borders and - padding on these siblings have no impact on the interaction - of their <space>s. The stacking constraint A,P is - indicated by the red rectangle enclosing the space-after of - A and the space-before of P. -

- In Diagram b), block B is the - first block child of P. The stacking constraint A,P is as - before; the stacking constraint P,B is the space-before of - B, as indicated by the enclosing magenta rectangle. In this - case, however, the non-zero border of P prevents the - interaction of the A,P and P,B stacking constraints. There - is a fence-before P. The fence is notional; it has - no precise location, as the diagram may lead one to believe. -

- In Diagram c), because of the - zero-width borders and padding on block P, the fence-before - P is not present, and the adjacent <space>s of blocks - A, P and B are free to interact. In this case, the stacking - constraints A,P and P,B are as before, but now there is an - additional stacking constraint A,B, represented by the light - brown rectangle enclosing the other two stacking - constraints. -

- The other form of fence occurs when the parent block is a - reference area. Diagram b) of Figure - 2 illustrates this situation. Block C is a - reference-area, involving a 180 degree change of - block-progression-direction (BPD). In the diagram, the - inner edge of block C represents the content rectangle, with - its changed BPD. The thicker outer edge represents the - outer boundary of the padding, border and spaces of C. -

- While not every reference-area will change the - inline-progression-direction (IPD) and BPD of an area, no - attempt is made to discriminate these cases. A - reference-area always a fence. The fence comes into play in - analogous circumstances to non-zero borders or padding. - Space resolution between a reference area and its siblings - is not affected. -

- In the case of Diagram b), - these are block stacking constraints B,C and C,A. Within - the reference-area, bock stacing constraints C,D and E,C are - unaffected. However, the fence prevents block stacking - constraints such as B,E or D,A. When there is a change of - BPD, as Diagram b) makes - visually obvious, it is difficult to imagine which blocks - would have such a constraint, and what the ordering of the - constraint would be. -

Figure 2

- -

+ In the discussion of block stacking constraints in Section + 4.2.5, the notion of fence is introduced. For + block stacking constraints, a fence is defined as either a + reference-area boundary or a non-zero padding or border + specification. Fences, however, do not come into play + when determining the constraint between siblings. (See + Figure 1.) +

Figure 1

+ + Figure 1 assumes a block-progression-direction of top to + bottom. + +

+ In Diagram a), block A has + non-zero padding and borders, in addition to non-zero + spaces. Note, however, that the space-after of A is + adjacent to the space-before of block P, so borders and + padding on these siblings have no impact on the interaction + of their <space>s. The stacking constraint A,P is + indicated by the red rectangle enclosing the space-after of + A and the space-before of P. +

+ In Diagram b), block B is the + first block child of P. The stacking constraint A,P is as + before; the stacking constraint P,B is the space-before of + B, as indicated by the enclosing magenta rectangle. In this + case, however, the non-zero border of P prevents the + interaction of the A,P and P,B stacking constraints. There + is a fence-before P. The fence is notional; it has + no precise location, as the diagram may lead one to believe. +

+ In Diagram c), because of the + zero-width borders and padding on block P, the fence-before + P is not present, and the adjacent <space>s of blocks + A, P and B are free to interact. In this case, the stacking + constraints A,P and P,B are as before, but now there is an + additional stacking constraint A,B, represented by the light + brown rectangle enclosing the other two stacking + constraints. +

+ The other form of fence occurs when the parent block is a + reference area. Diagram b) of Figure + 2 illustrates this situation. Block C is a + reference-area, involving a 180 degree change of + block-progression-direction (BPD). In the diagram, the + inner edge of block C represents the content rectangle, with + its changed BPD. The thicker outer edge represents the + outer boundary of the padding, border and spaces of C. +

+ While not every reference-area will change the + inline-progression-direction (IPD) and BPD of an area, no + attempt is made to discriminate these cases. A + reference-area always a fence. The fence comes into play in + analogous circumstances to non-zero borders or padding. + Space resolution between a reference area and its siblings + is not affected. +

+ In the case of Diagram b), + these are block stacking constraints B,C and C,A. Within + the reference-area, bock stacing constraints C,D and E,C are + unaffected. However, the fence prevents block stacking + constraints such as B,E or D,A. When there is a change of + BPD, as Diagram b) makes + visually obvious, it is difficult to imagine which blocks + would have such a constraint, and what the ordering of the + constraint would be. +

Figure 2

+ +

Keep relationships between blocks -

- As complicated as space-specifiers become when - reference-areas are involved, the keep relationships as - described in the keeps document, are - unchanged. This is also illustrated in Figure 2. Diagram b) shows the - relative placement of blocks in the rendered output when a - 180 degree change of BPD occurs, with blocks D and E - stacking in the reverse direction to blocks B and C. - Diagram c) shows what happens when the page is too short to - accommodate the last block. D is still laid out, but E is - deferred to the next page. -

- Note that this rendering reality is expressed directly in - the area (and layout) tree view. Consequently, any keep - relationships expressed as links threading through the - layout tree will not need to be modified to account for - reference-area boundaries, as is the case with similar - space-specifier edge links. E.g., a keep-with-next - condition on block B can be resolved along the path of these - links (B->C->D) into a direct relationship of B->D, - irrespective of the reference-area boundary. -

- While the same relationships obviously hold when a reference - area induces no change of BPD, the situation for BPD changes - perpendicular to the parent's BPD may not be so clear. In - general, it probably does not make much sense to impose keep - conditions across such a boundary, but there seems to be - nothing preventing such conditions. They can be dealt with - in the same way, i.e., the next leaf block linked in area - tree order must be the next laid out. If a keep condition - is in place, an attempt must be made to meet it. A number - of unusual considerations would apply, e.g. the minimum - inline-progression-dimension of the first leaf block within - the reference-area as compared to the minimum IPD of - subsequent blocks, but prima facie, the essential - logic of the keeps links remains. -

+ As complicated as space-specifiers become when + reference-areas are involved, the keep relationships as + described in the keeps document, are + unchanged. This is also illustrated in Figure 2. Diagram b) shows the + relative placement of blocks in the rendered output when a + 180 degree change of BPD occurs, with blocks D and E + stacking in the reverse direction to blocks B and C. + Diagram c) shows what happens when the page is too short to + accommodate the last block. D is still laid out, but E is + deferred to the next page. +

+ Note that this rendering reality is expressed directly in + the area (and layout) tree view. Consequently, any keep + relationships expressed as links threading through the + layout tree will not need to be modified to account for + reference-area boundaries, as is the case with similar + space-specifier edge links. E.g., a keep-with-next + condition on block B can be resolved along the path of these + links (B->C->D) into a direct relationship of B->D, + irrespective of the reference-area boundary. +

+ While the same relationships obviously hold when a reference + area induces no change of BPD, the situation for BPD changes + perpendicular to the parent's BPD may not be so clear. In + general, it probably does not make much sense to impose keep + conditions across such a boundary, but there seems to be + nothing preventing such conditions. They can be dealt with + in the same way, i.e., the next leaf block linked in area + tree order must be the next laid out. If a keep condition + is in place, an attempt must be made to meet it. A number + of unusual considerations would apply, e.g. the minimum + inline-progression-dimension of the first leaf block within + the reference-area as compared to the minimum IPD of + subsequent blocks, but prima facie, the essential + logic of the keeps links remains. +

- +