From e817266a9f7d1b0579839cc2383fe988ab5c3bc8 Mon Sep 17 00:00:00 2001 From: arved Date: Sun, 17 Mar 2002 17:24:10 +0000 Subject: Extra design commentary git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@194703 13f79535-47bb-0310-9956-ffa450edef68 --- docs/design/alt.design/AbsolutePosition.dia | Bin 0 -> 949 bytes docs/design/alt.design/AbsolutePosition.png | Bin 0 -> 4890 bytes docs/design/alt.design/AbsolutePosition.png.xml | 21 ++ docs/design/alt.design/BorderCommonStyle.png | Bin 0 -> 4140 bytes docs/design/alt.design/BorderCommonStyle.png.xml | 20 ++ docs/design/alt.design/PropNames.dia | Bin 0 -> 807 bytes docs/design/alt.design/PropNames.png | Bin 0 -> 3428 bytes docs/design/alt.design/PropNames.png.xml | 21 ++ docs/design/alt.design/Properties.dia | Bin 0 -> 1900 bytes docs/design/alt.design/Properties.png | Bin 0 -> 32437 bytes docs/design/alt.design/Properties.png.xml | 21 ++ docs/design/alt.design/PropertyClasses.dia | Bin 0 -> 2180 bytes docs/design/alt.design/PropertyClasses.png | Bin 0 -> 17581 bytes docs/design/alt.design/PropertyConsts.dia | Bin 0 -> 1573 bytes docs/design/alt.design/PropertyConsts.png | Bin 0 -> 20379 bytes docs/design/alt.design/PropertyConsts.png.xml | 20 ++ docs/design/alt.design/PropertyStaticsOverview.dia | Bin 0 -> 1333 bytes docs/design/alt.design/PropertyStaticsOverview.png | Bin 0 -> 7503 bytes docs/design/alt.design/SAXParsing.dia | Bin 0 -> 3068 bytes docs/design/alt.design/SAXParsing.png | Bin 0 -> 24482 bytes docs/design/alt.design/VerticalAlign.dia | Bin 0 -> 964 bytes docs/design/alt.design/VerticalAlign.png | Bin 0 -> 7091 bytes docs/design/alt.design/VerticalAlign.png.xml | 21 ++ docs/design/alt.design/XML-event-buffer.dia | Bin 0 -> 2004 bytes docs/design/alt.design/XML-event-buffer.png | Bin 0 -> 20415 bytes docs/design/alt.design/XMLEventQueue.dia | Bin 0 -> 2322 bytes docs/design/alt.design/XMLEventQueue.png | Bin 0 -> 11643 bytes docs/design/alt.design/alt.properties.xml | 167 ++++++++++ docs/design/alt.design/book.xml | 21 ++ docs/design/alt.design/classes-overview.xml | 201 ++++++++++++ docs/design/alt.design/dirlist.html | 55 ++++ docs/design/alt.design/parserPersistence.png | Bin 0 -> 8330 bytes docs/design/alt.design/processPlumbing.dia | Bin 0 -> 1974 bytes docs/design/alt.design/processPlumbing.png | Bin 0 -> 8689 bytes docs/design/alt.design/properties-classes.xml | 140 +++++++++ .../alt.design/property-super-classes-full.dia | Bin 0 -> 3115 bytes .../alt.design/property-super-classes-full.png | Bin 0 -> 89360 bytes docs/design/alt.design/propertyExpressions.xml | 341 +++++++++++++++++++++ docs/design/alt.design/xml-parsing.xml | 224 ++++++++++++++ docs/design/alt.design/xmlevent-queue.dia | Bin 0 -> 2655 bytes docs/design/alt.design/xmlevent-queue.png | Bin 0 -> 12326 bytes docs/design/understanding/area_tree.xml | 13 + docs/design/understanding/book.xml | 23 ++ docs/design/understanding/fo_tree.xml | 184 +++++++++++ docs/design/understanding/handling_attributes.xml | 13 + docs/design/understanding/images.xml | 146 +++++++++ docs/design/understanding/layout_managers.xml | 13 + docs/design/understanding/layout_process.xml | 13 + docs/design/understanding/pdf_library.xml | 78 +++++ docs/design/understanding/properties.xml | 130 ++++++++ docs/design/understanding/renderers.xml | 13 + docs/design/understanding/status.xml | 17 + docs/design/understanding/svg.xml | 57 ++++ docs/design/understanding/understanding.xml | 94 ++++++ docs/design/understanding/xml_parsing.xml | 106 +++++++ 55 files changed, 2173 insertions(+) create mode 100644 docs/design/alt.design/AbsolutePosition.dia create mode 100644 docs/design/alt.design/AbsolutePosition.png create mode 100644 docs/design/alt.design/AbsolutePosition.png.xml create mode 100644 docs/design/alt.design/BorderCommonStyle.png create mode 100644 docs/design/alt.design/BorderCommonStyle.png.xml create mode 100644 docs/design/alt.design/PropNames.dia create mode 100644 docs/design/alt.design/PropNames.png create mode 100644 docs/design/alt.design/PropNames.png.xml create mode 100644 docs/design/alt.design/Properties.dia create mode 100644 docs/design/alt.design/Properties.png create mode 100644 docs/design/alt.design/Properties.png.xml create mode 100644 docs/design/alt.design/PropertyClasses.dia create mode 100644 docs/design/alt.design/PropertyClasses.png create mode 100644 docs/design/alt.design/PropertyConsts.dia create mode 100644 docs/design/alt.design/PropertyConsts.png create mode 100644 docs/design/alt.design/PropertyConsts.png.xml create mode 100644 docs/design/alt.design/PropertyStaticsOverview.dia create mode 100644 docs/design/alt.design/PropertyStaticsOverview.png create mode 100644 docs/design/alt.design/SAXParsing.dia create mode 100644 docs/design/alt.design/SAXParsing.png create mode 100644 docs/design/alt.design/VerticalAlign.dia create mode 100644 docs/design/alt.design/VerticalAlign.png create mode 100644 docs/design/alt.design/VerticalAlign.png.xml create mode 100644 docs/design/alt.design/XML-event-buffer.dia create mode 100644 docs/design/alt.design/XML-event-buffer.png create mode 100644 docs/design/alt.design/XMLEventQueue.dia create mode 100644 docs/design/alt.design/XMLEventQueue.png create mode 100644 docs/design/alt.design/alt.properties.xml create mode 100644 docs/design/alt.design/book.xml create mode 100644 docs/design/alt.design/classes-overview.xml create mode 100644 docs/design/alt.design/dirlist.html create mode 100644 docs/design/alt.design/parserPersistence.png create mode 100644 docs/design/alt.design/processPlumbing.dia create mode 100644 docs/design/alt.design/processPlumbing.png create mode 100644 docs/design/alt.design/properties-classes.xml create mode 100644 docs/design/alt.design/property-super-classes-full.dia create mode 100644 docs/design/alt.design/property-super-classes-full.png create mode 100644 docs/design/alt.design/propertyExpressions.xml create mode 100644 docs/design/alt.design/xml-parsing.xml create mode 100644 docs/design/alt.design/xmlevent-queue.dia create mode 100644 docs/design/alt.design/xmlevent-queue.png create mode 100644 docs/design/understanding/area_tree.xml create mode 100644 docs/design/understanding/book.xml create mode 100644 docs/design/understanding/fo_tree.xml create mode 100644 docs/design/understanding/handling_attributes.xml create mode 100644 docs/design/understanding/images.xml create mode 100644 docs/design/understanding/layout_managers.xml create mode 100644 docs/design/understanding/layout_process.xml create mode 100644 docs/design/understanding/pdf_library.xml create mode 100644 docs/design/understanding/properties.xml create mode 100644 docs/design/understanding/renderers.xml create mode 100644 docs/design/understanding/status.xml create mode 100644 docs/design/understanding/svg.xml create mode 100644 docs/design/understanding/understanding.xml create mode 100644 docs/design/understanding/xml_parsing.xml (limited to 'docs/design') diff --git a/docs/design/alt.design/AbsolutePosition.dia b/docs/design/alt.design/AbsolutePosition.dia new file mode 100644 index 000000000..a2d6421a3 Binary files /dev/null and b/docs/design/alt.design/AbsolutePosition.dia differ diff --git a/docs/design/alt.design/AbsolutePosition.png b/docs/design/alt.design/AbsolutePosition.png new file mode 100644 index 000000000..ed8a3691b Binary files /dev/null and b/docs/design/alt.design/AbsolutePosition.png differ diff --git a/docs/design/alt.design/AbsolutePosition.png.xml b/docs/design/alt.design/AbsolutePosition.png.xml new file mode 100644 index 000000000..7b2cde0bc --- /dev/null +++ b/docs/design/alt.design/AbsolutePosition.png.xml @@ -0,0 +1,21 @@ + + + + +
+ AbsolutePosition diagram + + + +
+ + + +
+ + + diff --git a/docs/design/alt.design/BorderCommonStyle.png b/docs/design/alt.design/BorderCommonStyle.png new file mode 100644 index 000000000..67cc9f8ee Binary files /dev/null and b/docs/design/alt.design/BorderCommonStyle.png differ diff --git a/docs/design/alt.design/BorderCommonStyle.png.xml b/docs/design/alt.design/BorderCommonStyle.png.xml new file mode 100644 index 000000000..f57865bc2 --- /dev/null +++ b/docs/design/alt.design/BorderCommonStyle.png.xml @@ -0,0 +1,20 @@ + + + + +
+ BorderCommonStyle diagram + + + +
+ + + +
+ + + diff --git a/docs/design/alt.design/PropNames.dia b/docs/design/alt.design/PropNames.dia new file mode 100644 index 000000000..81db6a0c9 Binary files /dev/null and b/docs/design/alt.design/PropNames.dia differ diff --git a/docs/design/alt.design/PropNames.png b/docs/design/alt.design/PropNames.png new file mode 100644 index 000000000..8287e0875 Binary files /dev/null and b/docs/design/alt.design/PropNames.png differ diff --git a/docs/design/alt.design/PropNames.png.xml b/docs/design/alt.design/PropNames.png.xml new file mode 100644 index 000000000..829509d8b --- /dev/null +++ b/docs/design/alt.design/PropNames.png.xml @@ -0,0 +1,21 @@ + + + + + +
+ ..fo.PropNames diagram + + + +
+ + + +
+ + + diff --git a/docs/design/alt.design/Properties.dia b/docs/design/alt.design/Properties.dia new file mode 100644 index 000000000..25d482d5d Binary files /dev/null and b/docs/design/alt.design/Properties.dia differ diff --git a/docs/design/alt.design/Properties.png b/docs/design/alt.design/Properties.png new file mode 100644 index 000000000..10da5f23c Binary files /dev/null and b/docs/design/alt.design/Properties.png differ diff --git a/docs/design/alt.design/Properties.png.xml b/docs/design/alt.design/Properties.png.xml new file mode 100644 index 000000000..f2a53578c --- /dev/null +++ b/docs/design/alt.design/Properties.png.xml @@ -0,0 +1,21 @@ + + + + + +
+ ..fo.Properties diagram + + + +
+ + + +
+ + + diff --git a/docs/design/alt.design/PropertyClasses.dia b/docs/design/alt.design/PropertyClasses.dia new file mode 100644 index 000000000..5a02f6780 Binary files /dev/null and b/docs/design/alt.design/PropertyClasses.dia differ diff --git a/docs/design/alt.design/PropertyClasses.png b/docs/design/alt.design/PropertyClasses.png new file mode 100644 index 000000000..e58ca94bf Binary files /dev/null and b/docs/design/alt.design/PropertyClasses.png differ diff --git a/docs/design/alt.design/PropertyConsts.dia b/docs/design/alt.design/PropertyConsts.dia new file mode 100644 index 000000000..ed30cc6bc Binary files /dev/null and b/docs/design/alt.design/PropertyConsts.dia differ diff --git a/docs/design/alt.design/PropertyConsts.png b/docs/design/alt.design/PropertyConsts.png new file mode 100644 index 000000000..b6df72f84 Binary files /dev/null and b/docs/design/alt.design/PropertyConsts.png differ diff --git a/docs/design/alt.design/PropertyConsts.png.xml b/docs/design/alt.design/PropertyConsts.png.xml new file mode 100644 index 000000000..73d509cae --- /dev/null +++ b/docs/design/alt.design/PropertyConsts.png.xml @@ -0,0 +1,20 @@ + + + + +
+ ..fo.PropertyConsts diagram + + + +
+ + + +
+ + + diff --git a/docs/design/alt.design/PropertyStaticsOverview.dia b/docs/design/alt.design/PropertyStaticsOverview.dia new file mode 100644 index 000000000..2ef800725 Binary files /dev/null and b/docs/design/alt.design/PropertyStaticsOverview.dia differ diff --git a/docs/design/alt.design/PropertyStaticsOverview.png b/docs/design/alt.design/PropertyStaticsOverview.png new file mode 100644 index 000000000..fdda19e74 Binary files /dev/null and b/docs/design/alt.design/PropertyStaticsOverview.png differ diff --git a/docs/design/alt.design/SAXParsing.dia b/docs/design/alt.design/SAXParsing.dia new file mode 100644 index 000000000..74a525ecf Binary files /dev/null and b/docs/design/alt.design/SAXParsing.dia differ diff --git a/docs/design/alt.design/SAXParsing.png b/docs/design/alt.design/SAXParsing.png new file mode 100644 index 000000000..f2652e1f7 Binary files /dev/null and b/docs/design/alt.design/SAXParsing.png differ diff --git a/docs/design/alt.design/VerticalAlign.dia b/docs/design/alt.design/VerticalAlign.dia new file mode 100644 index 000000000..519715a1a Binary files /dev/null and b/docs/design/alt.design/VerticalAlign.dia differ diff --git a/docs/design/alt.design/VerticalAlign.png b/docs/design/alt.design/VerticalAlign.png new file mode 100644 index 000000000..860d5bdff Binary files /dev/null and b/docs/design/alt.design/VerticalAlign.png differ diff --git a/docs/design/alt.design/VerticalAlign.png.xml b/docs/design/alt.design/VerticalAlign.png.xml new file mode 100644 index 000000000..6ff21bb00 --- /dev/null +++ b/docs/design/alt.design/VerticalAlign.png.xml @@ -0,0 +1,21 @@ + + + + + +
+ VerticalAlign diagram + + + +
+ + + +
+ + + diff --git a/docs/design/alt.design/XML-event-buffer.dia b/docs/design/alt.design/XML-event-buffer.dia new file mode 100644 index 000000000..ec8b131f6 Binary files /dev/null and b/docs/design/alt.design/XML-event-buffer.dia differ diff --git a/docs/design/alt.design/XML-event-buffer.png b/docs/design/alt.design/XML-event-buffer.png new file mode 100644 index 000000000..4ee16e913 Binary files /dev/null and b/docs/design/alt.design/XML-event-buffer.png differ diff --git a/docs/design/alt.design/XMLEventQueue.dia b/docs/design/alt.design/XMLEventQueue.dia new file mode 100644 index 000000000..6a39a3734 Binary files /dev/null and b/docs/design/alt.design/XMLEventQueue.dia differ diff --git a/docs/design/alt.design/XMLEventQueue.png b/docs/design/alt.design/XMLEventQueue.png new file mode 100644 index 000000000..477abd79a Binary files /dev/null and b/docs/design/alt.design/XMLEventQueue.png differ diff --git a/docs/design/alt.design/alt.properties.xml b/docs/design/alt.design/alt.properties.xml new file mode 100644 index 000000000..a0bb5ef6c --- /dev/null +++ b/docs/design/alt.design/alt.properties.xml @@ -0,0 +1,167 @@ + + + + +
+ Implementing Properties + + + +
+ + + + + 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. + +

+ 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. + +

+ 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. +

+ + +

+ 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. +

+ +

+ 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. +

+ + +

+ 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. +

+ +

+ 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. +

    +     +     + +

    + 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. +

    +     +

    + Next: property classes overview. +

    +     + +     diff --git a/docs/design/alt.design/book.xml b/docs/design/alt.design/book.xml new file mode 100644 index 000000000..5ae28c1f9 --- /dev/null +++ b/docs/design/alt.design/book.xml @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/design/alt.design/classes-overview.xml b/docs/design/alt.design/classes-overview.xml new file mode 100644 index 000000000..fab8e921d --- /dev/null +++ b/docs/design/alt.design/classes-overview.xml @@ -0,0 +1,201 @@ + + + + + +
    + Property classes overview + + + +
    + + + + +

    + 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[]. +

    +     + +

    + 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. +
    +
    +     + +

    + 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. +
    +
    + +

    + Previous: alt.properties +

    +

    + Next: Properties classes +

    + + + diff --git a/docs/design/alt.design/dirlist.html b/docs/design/alt.design/dirlist.html new file mode 100644 index 000000000..6a4cf9ddd --- /dev/null +++ b/docs/design/alt.design/dirlist.html @@ -0,0 +1,55 @@ + + + + alt.design + + +

    Directory listing of alt.design

    +
    + 
    
+drwxrwxr-x    2 pbw      pbw          4096 Jan 31 17:58 .
+drwxrwxr-x    5 pbw      pbw          4096 Jan 31 17:57 ..
+-rw-rw-r--    1 pbw      pbw           949 Jan 25 17:31 AbsolutePosition.dia
+-rw-rw-r--    1 pbw      pbw          4890 Jan 25 17:31 AbsolutePosition.png
+-rw-r--r--    1 pbw      pbw           579 Jan 25 23:47 AbsolutePosition.png.xml
+-rw-rw-r--    1 pbw      pbw          4140 Jan 25 17:31 BorderCommonStyle.png
+-rw-r--r--    1 pbw      pbw           584 Jan 26 12:29 BorderCommonStyle.png.xml
+-rw-rw-r--    1 pbw      pbw           807 Jan 25 17:31 PropNames.dia
+-rw-rw-r--    1 pbw      pbw          3428 Jan 25 17:31 PropNames.png
+-rw-r--r--    1 pbw      pbw           551 Jan 25 23:48 PropNames.png.xml
+-rw-rw-r--    1 pbw      pbw          1900 Jan 25 17:31 Properties.dia
+-rw-rw-r--    1 pbw      pbw         32437 Jan 25 17:31 Properties.png
+-rw-r--r--    1 pbw      pbw           556 Jan 25 23:48 Properties.png.xml
+-rw-rw-r--    1 pbw      pbw          2180 Jan 25 17:31 PropertyClasses.dia
+-rw-rw-r--    1 pbw      pbw         17581 Jan 25 17:31 PropertyClasses.png
+-rw-rw-r--    1 pbw      pbw          1573 Jan 25 17:31 PropertyConsts.dia
+-rw-rw-r--    1 pbw      pbw         20379 Jan 25 17:31 PropertyConsts.png
+-rw-r--r--    1 pbw      pbw           575 Jan 25 23:47 PropertyConsts.png.xml
+-rw-rw-r--    1 pbw      pbw          1333 Jan 25 17:31 PropertyStaticsOverview.dia
+-rw-rw-r--    1 pbw      pbw          7503 Jan 25 17:31 PropertyStaticsOverview.png
+-rw-rw-r--    1 pbw      pbw          3068 Jan 25 17:31 SAXParsing.dia
+-rw-rw-r--    1 pbw      pbw         24482 Jan 25 17:31 SAXParsing.png
+-rw-rw-r--    1 pbw      pbw           964 Jan 25 17:31 VerticalAlign.dia
+-rw-rw-r--    1 pbw      pbw          7091 Jan 25 17:31 VerticalAlign.png
+-rw-r--r--    1 pbw      pbw           565 Jan 25 23:48 VerticalAlign.png.xml
+-rw-rw-r--    1 pbw      pbw          2004 Jan 25 17:31 XML-event-buffer.dia
+-rw-rw-r--    1 pbw      pbw         20415 Jan 25 17:31 XML-event-buffer.png
+-rw-rw-r--    1 pbw      pbw          2322 Jan 25 17:31 XMLEventQueue.dia
+-rw-rw-r--    1 pbw      pbw         11643 Jan 25 17:31 XMLEventQueue.png
+-rw-r--r--    1 pbw      pbw          6584 Jan 26 11:56 alt.properties.xml
+-rw-rw-r--    1 pbw      pbw          1152 Jan 25 17:31 book.xml
+-rw-r--r--    1 pbw      pbw          7834 Jan 26 13:07 classes-overview.xml
+-rw-rw-r--    1 pbw      pbw          8330 Jan 25 17:31 parserPersistence.png
+-rw-rw-r--    1 pbw      pbw          1974 Jan 25 17:31 processPlumbing.dia
+-rw-rw-r--    1 pbw      pbw          8689 Jan 25 17:31 processPlumbing.png
+-rw-r--r--    1 pbw      pbw          5123 Jan 26 11:58 properties-classes.xml
+-rw-rw-r--    1 pbw      pbw          3115 Jan 25 17:31 property-super-classes-full.dia
+-rw-rw-r--    1 pbw      pbw         89360 Jan 25 17:31 property-super-classes-full.png
+-rw-r--r--    1 pbw      pbw         10221 Jan 25 23:49 propertyExpressions.xml
+-rw-r--r--    1 pbw      pbw          9361 Jan 26 11:59 xml-parsing.xml
+-rw-rw-r--    1 pbw      pbw          2655 Jan 25 17:31 xmlevent-queue.dia
+-rw-rw-r--    1 pbw      pbw         12326 Jan 25 17:31 xmlevent-queue.png
+
    +
    + + diff --git a/docs/design/alt.design/parserPersistence.png b/docs/design/alt.design/parserPersistence.png new file mode 100644 index 000000000..342a933b4 Binary files /dev/null and b/docs/design/alt.design/parserPersistence.png differ diff --git a/docs/design/alt.design/processPlumbing.dia b/docs/design/alt.design/processPlumbing.dia new file mode 100644 index 000000000..184e51524 Binary files /dev/null and b/docs/design/alt.design/processPlumbing.dia differ diff --git a/docs/design/alt.design/processPlumbing.png b/docs/design/alt.design/processPlumbing.png new file mode 100644 index 000000000..182d3c68e Binary files /dev/null and b/docs/design/alt.design/processPlumbing.png differ diff --git a/docs/design/alt.design/properties-classes.xml b/docs/design/alt.design/properties-classes.xml new file mode 100644 index 000000000..216f2b9e0 --- /dev/null +++ b/docs/design/alt.design/properties-classes.xml @@ -0,0 +1,140 @@ + + + + + +
    + Properties$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. +

    + +
    +
    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. +
    +
    +     + +
    +
    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 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. +
    +
    +     +     + +

    + 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. +

    + + + diff --git a/docs/design/alt.design/property-super-classes-full.dia b/docs/design/alt.design/property-super-classes-full.dia new file mode 100644 index 000000000..4fe8f750a Binary files /dev/null and b/docs/design/alt.design/property-super-classes-full.dia differ diff --git a/docs/design/alt.design/property-super-classes-full.png b/docs/design/alt.design/property-super-classes-full.png new file mode 100644 index 000000000..dea871d3c Binary files /dev/null and b/docs/design/alt.design/property-super-classes-full.png differ diff --git a/docs/design/alt.design/propertyExpressions.xml b/docs/design/alt.design/propertyExpressions.xml new file mode 100644 index 000000000..0900a323a --- /dev/null +++ b/docs/design/alt.design/propertyExpressions.xml @@ -0,0 +1,341 @@ + + + + + +
    + Property Expression Parsing + + + +
    + + + + + The following discussion of the experiments with alternate + property expression parsing is very much a work in progress, + and subject to sudden changes. + +

    + The parsing of property value expressions is handled by two + closely related classes: PropertyTokenizer and its + subclass, PropertyParser. + PropertyTokenizer, as the name suggests, handles + the tokenizing of the expression, handing tokens + back to its subclass, + PropertyParser. PropertyParser, in + turn, returns a PropertyValueList, a list of + PropertyValues. +

    +

    + The tokenizer and parser rely in turn on the datatype + definition from the org.apache.fop.datatypes + package and the datatype static final int + constants from PropertyConsts. +

    + +

    + The data types currently defined in + org.apache.fop.datatypes include: +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Numbers and lengths
    Numeric + The fundamental numeric data type. Numerics of + various types are constructed by the classes listed + below. +
    + Constructor classes for Numeric
    AngleIn degrees(deg), gradients(grad) or + radians(rad)
    EmsRelative length in ems
    FrequencyIn hertz(Hz) or kilohertz(kHz)
    IntegerType +
    LengthIn centimetres(cm), millimetres(mm), + inches(in), points(pt), picas(pc) or pixels(px)
    Percentage +
    TimeIn seconds(s) or milliseconds(ms)
    Strings
    StringType + Base class for data types which result in a String. +
    Literal + A subclass of StringType for literals which + exceed the constraints of an NCName. +
    MimeType + A subclass of StringType for literals which + represent a mime type. +
    UriType + A subclass of StringType for literals which + represent a URI, as specified by the argument to + url(). +
    NCName + A subclass of StringType for literals which + meet the constraints of an NCName. +
    CountryAn RFC 3066/ISO 3166 country code.
    LanguageAn RFC 3066/ISO 639 language code.
    ScriptAn ISO 15924 script code.
    Enumerated types
    EnumType + An integer representing one of the tokens in a set of + enumeration values. +
    MappedEnumType + A subclass of EnumType. Maintains a + String with the value to which the associated + "raw" enumeration token maps. E.g., the + font-size enumeration value "medium" maps to + the String "12pt". +
    Colors
    ColorType + Maintains a four-element array of float, derived from + the name of a standard colour, the name returned by a + call to system-color(), or an RGB + specification. +
    Fonts
    FontFamilySet + Maintains an array of Strings containing a + prioritized list of possibly generic font family names. +
    Pseudo-types
    + A variety of pseudo-types have been defined as + convenience types for frequently appearing enumeration + token values, or for other special purposes. +
    Inherit + For values of inherit. +
    Auto + For values of auto. +
    None + For values of none. +
    Bool + For values of true/false. +
    FromNearestSpecified + Created to ensure that, when associated with + a shorthand, the from-nearest-specified-value() + core function is the sole component of the expression. +
    FromParent + Created to ensure that, when associated with + a shorthand, the from-parent() + core function is the sole component of the expression. +
    +     + +

    + The tokenizer returns one of the following token + values: +

    + + static final int + EOF = 0 + ,NCNAME = 1 + ,MULTIPLY = 2 + ,LPAR = 3 + ,RPAR = 4 + ,LITERAL = 5 + ,FUNCTION_LPAR = 6 + ,PLUS = 7 + ,MINUS = 8 + ,MOD = 9 + ,DIV = 10 + ,COMMA = 11 + ,PERCENT = 12 + ,COLORSPEC = 13 + ,FLOAT = 14 + ,INTEGER = 15 + ,ABSOLUTE_LENGTH = 16 + ,RELATIVE_LENGTH = 17 + ,TIME = 18 + ,FREQ = 19 + ,ANGLE = 20 + ,INHERIT = 21 + ,AUTO = 22 + ,NONE = 23 + ,BOOL = 24 + ,URI = 25 + ,MIMETYPE = 26 + // NO_UNIT is a transient token for internal use only. It is + // never set as the end result of parsing a token. + ,NO_UNIT = 27 + ; + +

    + Most of these tokens are self-explanatory, but a few need + further comment. +

    +
    +
    AUTO
    +
    + Because of its frequency of occurrence, and the fact that + it is always the initial value for any property + which supports it, AUTO has been promoted into a + pseudo-type with its on datatype class. Therefore, it is + also reported as a token. +
    +
    NONE
    +
    + Similarly to AUTO, NONE has been promoted to a pseudo-type + because of its frequency. +
    +
    BOOL
    +
    + There is a de facto boolean type buried in the + enumeration types for many of the properties. It had been + specified as a type in its own right in this code. +
    +
    MIMETYPE
    +
    + The property content-type introduces this + complication. It can have two values of the form + content-type:mime-type + (e.g. content-type="content-type:xml/svg") or + namespace-prefix:prefix + (e.g. content-type="namespace-prefix:svg"). The + experimental code reduces these options to the payload + in each case: an NCName in the case of a + namespace prefix, and a MIMETYPE in the case of a + content-type specification. NCNames cannot + contain a "/". +
    +
    +     + +

    + The parser retuns a PropertyValueList, + necessary because of the possibility that a list of + PropertyValue elements may be returned from the + expressions of soem properties. +

    +

    + PropertyValueLists may contain + PropertyValues or other + PropertyValueLists. This latter provision is + necessitated for the peculiar case of of + text-shadow, which may contain whitespace separated + sublists of either two or three elements, separated from one + another by commas. To accommodate this peculiarity, comma + separated elements are added to the top-level list, while + whitespace separated values are always collected into + sublists to be added to the top-level list. +

    +

    + Other special cases include the processing of the core + functions from-parent() and + from-nearest-specified-value() when these + function calls are assigned to a shorthand property, or used + with a shorthand property name as an argument. In these + cases, the function call must be the sole component of the + expression. The pseudo-element classes + FromParent and + FromNearestSpecified are generated in these + circumstances so that an exception will be thrown if they + are involved in expression evaluation with other + components. (See Rec. Section 5.10.4 Property Value + Functions.) +

    +

    + The experimental code is a simple extension of the existing + parser code, which itself borrowed heavily from James + Clark's XT processor. +

    +     +     + +     diff --git a/docs/design/alt.design/xml-parsing.xml b/docs/design/alt.design/xml-parsing.xml new file mode 100644 index 000000000..3d83802ef --- /dev/null +++ b/docs/design/alt.design/xml-parsing.xml @@ -0,0 +1,224 @@ + + + + + +
    + Integrating XML Parsing + + + +
    + + + +

    + This note proposes an alternative method of integrating the + output of the SAX parsing of the Flow Object (FO) tree into + FOP processing. The pupose of the proposed changes is to + provide for better decomposition of the process of analysing + and rendering an fo tree such as is represented in the output + from initial (XSLT) processing of an XML source document. +

    + +

    + Figure 1 is a schematic representation of the process of SAX + parsing of an input source. SAX parsing involves the + registration, with an object implementing the + XMLReader interface, of a + ContentHandler which contains a callback + routine for each of the event types encountered by the + parser, e.g., startDocument(), + startElement(), characters(), + endElement() and endDocument(). + Parsing is initiated by a call to the parser() + method of the XMLReader. Note that the call to + parser() and the calls to individual callback + methods are synchronous: parser() will only + return when the last callback method returns, and each + callback must complete before the next is called.

    + Figure 1 +

    +
    +

    + In the process of parsing, the heirarchical structure of the + original FO tree is flattened into a number of streams of + events of the same type which are reported in the sequence + in which they are encountered. Apart from that, the API + imposes no structure or constraint which expresses the + relationship between, e.g., a startElement event and the + endElement event for the same element. To the extent that + such relationship information is required, it must be + managed by the callback routines. +

    +

    + The most direct approach here is to build the tree + "invisibly"; to bury within the callback routines the + necessary code to construct the tree. In the simplest case, + the whole of the FO tree is built within the call to + parser(), and that in-memory tree is subsequently + processed to (a) validate the FO structure, and (b) + construct the Area tree. The problem with this approach is + the potential size of the FO tree in memory. FOP has + suffered from this problem in the past. +

    + + +

    + On the other hand, the callback code may become increasingly + complex as tree validation and the triggering of the Area + tree processing and subsequent rendering is moved into the + callbacks, typically the endElement() method. + In order to overcome acute memory problems, the FOP code was + recently modified in this way, to trigger Area tree building + and rendering in the endElement() method, when + the end of a page-sequence was detected. +

    +

    + The drawback with such a method is that it becomes difficult + to detemine the order of events and the circumstances in + which any particular processing events are triggered. When + the processing events are inherently self-contained, this is + irrelevant. But the more complex and context-dependent the + relationships are among the processing elements, the more + obscurity is engendered in the code by such "side-effect" + processing. +

    +     + +

    + In order to solve the simultaneous problems of exposing the + structure of the processing and minimising in-memory + requirements, the experimental code separates the parsing of + the input source from the building of the FO tree and all + downstream processing. The callback routines become + minimal, consisting of the creation and buffering of + XMLEvent objects as a producer. All + of these objects are effectively merged into a single event + stream, in strict event order, for subsequent access by the + FO tree building process, acting as a + consumer. In itself, this does not reduce the + footprint. This occurs when the approach is generalised to + modularise FOP processing.

    Figure 2 +

    +
    +

    + The most useful change that this brings about is the switch + from passive to active XML element + processing. The process of parsing now becomes visible to + the controlling process. All local validation requirements, + all object and data structure building, is initiated by the + process(es) getting from the queue - in the case + above, the FO tree builder. +

    + + + +

    + The experimental code uses a class XMLEvent + to provide the objects which are placed in the queue. + XMLEvent includes a variety of methods to access + elements in the queue. Namespace URIs encountered in + parsing are maintined in a static + HashMap where they are associated with a unique + integer index. This integer value is used in the signature + of some of the access methods. +

    +
    +
    XMLEvent getEvent(SyncedCircularBuffer events)
    +
    + This is the basis of all of the queue access methods. It + returns the next element from the queue, which may be a + pushback element. +
    +
    XMLEvent getEndDocument(events)
    +
    + get and discard elements from the queue + until an ENDDOCUMENT element is found and returned. +
    +
    XMLEvent expectEndDocument(events)
    +
    + If the next element on the queue is an ENDDOCUMENT event, + return it. Otherwise, push the element back and throw an + exception. Each of the get methods (except + getEvent() itself) has a corresponding + expect method. +
    +
    XMLEvent get/expectStartElement(events)
    +
    Return the next STARTELEMENT event from the queue.
    +
    XMLEvent get/expectStartElement(events, String + qName)
    +
    + Return the next STARTELEMENT with a QName matching + qName. +
    +
    + XMLEvent get/expectStartElement(events, int uriIndex, + String localName) +
    +
    + Return the next STARTELEMENT with a URI indicated by the + uriIndex and a local name matching localName. +
    +
    + XMLEvent get/expectStartElement(events, LinkedList list) +
    +
    + list contains instances of the nested class + UriLocalName, which hold a + uriIndex and a localName. Return + the next STARTELEMENT with a URI indicated by the + uriIndex and a local name matching + localName from any element of + list. +
    +
    XMLEvent get/expectEndElement(events)
    +
    Return the next ENDELEMENT.
    +
    XMLEvent get/expectEndElement(events, qName)
    +
    Return the next ENDELEMENT with QName + qname.
    +
    XMLEvent get/expectEndElement(events, uriIndex, localName)
    +
    + Return the next ENDELEMENT with a URI indicated by the + uriIndex and a local name matching + localName. +
    +
    + XMLEvent get/expectEndElement(events, XMLEvent event) +
    +
    + Return the next ENDELEMENT with a URI matching the + uriIndex and localName + matching those in the event argument. This + is intended as a quick way to find the ENDELEMENT matching + a previously returned STARTELEMENT. +
    +
    XMLEvent get/expectCharacters(events)
    +
    Return the next CHARACTERS event.
    +
    +     + +

    + This same principle can be extended to the other major + sub-systems of FOP processing. In each case, while it is + possible to hold a complete intermediate result in memory, + the memory costs of that approach are too high. The + sub-systems - xml parsing, FO tree construction, Area tree + construction and rendering - must run in parallel if the + footprint is to be kept manageable. By creating a series of + producer-consumer pairs linked by synchronized buffers, + logical isolation can be achieved while rates of processing + remain coupled. By introducing feedback loops conveying + information about the completion of processing of the + elements, sub-systems can dispose of or precis those + elements without having to be tightly coupled to downstream + processes.

    + Figure 3 +

    +
    + + + + diff --git a/docs/design/alt.design/xmlevent-queue.dia b/docs/design/alt.design/xmlevent-queue.dia new file mode 100644 index 000000000..91e752473 Binary files /dev/null and b/docs/design/alt.design/xmlevent-queue.dia differ diff --git a/docs/design/alt.design/xmlevent-queue.png b/docs/design/alt.design/xmlevent-queue.png new file mode 100644 index 000000000..0bb019c65 Binary files /dev/null and b/docs/design/alt.design/xmlevent-queue.png differ diff --git a/docs/design/understanding/area_tree.xml b/docs/design/understanding/area_tree.xml new file mode 100644 index 000000000..bf8c63794 --- /dev/null +++ b/docs/design/understanding/area_tree.xml @@ -0,0 +1,13 @@ + + + +
    + Area Tree + All you wanted to know about the Area Tree ! + + +
    + +

    Yet to come :))

    + The series of notes for developers has started but it has not yet gone so far ! Keep watching     +     \ No newline at end of file diff --git a/docs/design/understanding/book.xml b/docs/design/understanding/book.xml new file mode 100644 index 000000000..505d3c06c --- /dev/null +++ b/docs/design/understanding/book.xml @@ -0,0 +1,23 @@ + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/design/understanding/fo_tree.xml b/docs/design/understanding/fo_tree.xml new file mode 100644 index 000000000..83e58ef8c --- /dev/null +++ b/docs/design/understanding/fo_tree.xml @@ -0,0 +1,184 @@ + + +
    + FO Tree + All you wanted to know about FO Tree ! + + +
    + +

    + The FO Tree is a representation of the XSL:FO document. This + represents the Objectify step from the + spec. The Refinement step is part of reading + and using the properties which may happen immediately or + during the layout process. +

    + + + +

    Each xml element is represented by a java object. For pagination the +classes are in org.apache.fop.fo.pagination.*, for elements in the flow +they are in org.apache.fop.fo.flow.* and some others are in +org.apache.fop.fo.*.

    + + + +

    The base class for all objects in the tree is FONode. The base class for +all FO Objects is FObj.

    + + + +

    (insert diagram here)

    + + + +

    There is a class for each element in the FO set. An object is created for +each element in the FO Tree. This object holds the properties for the FO +Object.

    + + + +

    + When the object is created it is setup. It is given its + element name, the FOUserAgent - for resolving properties + etc. - the logger and the attributes. The methods + handleAttributes() and + setuserAgent(), common to FONode, + are used in this process. The object will then be given any + text data or child elements. Then the end() + method is called. The end method is used by a number of + elements to indicate that it can do certain processing since + all the children have been added. +

    + + + +

    Some validity checking is done during these steps. The user can be warned of the error and processing can continue if possible. +

    + + +

    + The FO Tree is simply a heirarchy of java objects that + represent the fo elements from xml. The traversal is done by + the layout or structure process only in the flow elements. +

    + + + + + + + +

    The XML attributes on each element are passed to the object. The objects +that represent FO objects then convert the attributes into properties. +

    + + +

    Since properties can be inherited the PropertyList class handles resolving +properties for a particular element. +All properties are specified in an XML file. Classes are created +automatically during the build process. +

    + + +

    (insert diagram here)

    + + + +

    In some cases the element may be moved to have a different parent, for +example markers, or the inheritance could be different, for example +initial property set.

     + + + + + + + +

    The base class for foreign XML is XMLObj. This class handles creating a +DOM Element and the setting of attributes. It also can create a DOM +Document if it is a top level element, class XMLElement. +This class must be extended for the namespace of the XML elements. For +unknown namespaces the class is UnknowXMLObj.

    + + + +

    (insert diagram here)

    + + + +

    If some special processing is needed then the top level element can extend +the XMLObj. For example the SVGElement makes the special DOM required for +batik and gets the size of the svg. +

    + + +

    Foreign XML will usually be in an fo:instream-foreign-object, the XML will +be passed to the render as a DOM where the render will be able to handle +it. Other XML from an unknwon namespace will be ignored. +

    + + +

    By using element mappings it is possible to read other XML and either

    +
    • set information on the area tree
      • +
    • create pseudo FO Objects that create areas in the area tree
      • +
    • create FO Objects
    +     + + + + +

    If an element is in a known namespace but the element is unknown then an +Unknown object is created. This is mainly to provide information to the +user. +This could happen if the fo document contains an element from a different +version or the element is misspelt.

    +     + + + +

    + The first elements in a document are the elements for the + page master setup. This is usually only a small number and + will be used throughout the document to create new pages. + These elements are kept as a factory to create the page and + appropriate regions whenever a new page is requested by the + layout. The objects in the FO Tree that represent these + elements are themselves the factory. The root element keeps + these objects as a factory for the page sequences. +

    +     + + + +

    The elements that are in the flow of the document are a set of elements +that is needed for the layout process. Each element is important in the +creation of areas.

    +     + + + + + + + +

    + The remaining FO Objects are things like page-sequence, + title and color-profile. These are handled by their parent + element; i.e. the root looks after the declarations and the + declarations maintains a list of colour profiles. The + page-sequences are direct descendents of root. +

    +     + + + + + + + +
    • Create diagrams
      • +
    • Setup all properties and elements for XSL:FO
      • +
    • Setup user agent for property resolution
      • +
    • Verify all XML is handled appropriately
     \ No newline at end of file diff --git a/docs/design/understanding/handling_attributes.xml b/docs/design/understanding/handling_attributes.xml new file mode 100644 index 000000000..1ae043059 --- /dev/null +++ b/docs/design/understanding/handling_attributes.xml @@ -0,0 +1,13 @@ + + + +
    + Handling Attributes + All you wanted to know about FOP Handling Attributes ! + + +
    + +

    Yet to come :))

    + The series of notes for developers has started but it has not yet gone so far ! Keep watching     +     \ No newline at end of file diff --git a/docs/design/understanding/images.xml b/docs/design/understanding/images.xml new file mode 100644 index 000000000..6aaa82bc8 --- /dev/null +++ b/docs/design/understanding/images.xml @@ -0,0 +1,146 @@ + + + +
    + Images + All you wanted to know about Images in FOP ! + + +
    + + + + this is still in progress, input in the code is welcome. Needs documenting formats, testing. + So all those people interested in images should get involved. +

    Images may only be needed to be loaded when the image is rendered to the +output or to find the dimensions.
    +An image url may be invalid, this can be costly to find out so we need to +keep a list of invalid image urls.

    +

    We have a number of different caching schemes that are possible.

    +

    All images are referred to using the url given in the XSL:FO after +removing "url('')" wrapping. This does +not include any sort of resolving such as relative -> absolute. The +external graphic in the FO Tree and the image area in the Area Tree only +have the url as a reference. +The images are handled through a static interface in ImageFactory.

    + + +

    (insert image)

    + + + + + + +

    In a single threaded case with one document the image should be released +as soon as the renderer caches it. If there are multiple documents then +the images could be held in a weak cache in case another document needs to +load the same image.

    + + +

    In a multi threaded case many threads could be attempting to get the same +image. We need to make sure an image will only be loaded once at a +particular time. Once a particular document is finished then we can move +all the images to a common weak cache.

    +     + + + +

    All images are in a common cache regardless of context. To limit the size +of the cache the LRU image is removed to keep the amount of memory used +low. Each image can supply the amount of data held in memory.

    +     + + +

    Images are cached according to the context, using the FOUserAgent as a key. +Once the context is finished the images are added to a common weak hashmap +so that other contexts can load these images or the data will be garbage +collected if required.

    +

    If images are to be used commonly then we cannot dispose of data in the +FopImage when cached by the renderer. Also if different contexts have +different base directories for resolving relative url's then the loading +and caching must be separate. We can have a cache that shares images among +all contexts or only loads an image for a context.

    +     + +

    The cache uses an image loader so that it can synchronize the image +loading on an image by image basis. Finding and adding an image loader to +the cache is also synchronized to prevent thread problems.

    +     + + + + +

    +If an image cannot be loaded for some reason, for example the url is +invalid or the image data is corrupt or an unknown type. Then it should +only attempt to load the image once. All other attempts to get the image +should return null so that it can be easily handled.
    +This will prevent any extra processing or waiting.

    +     + + + +

    Once a stream is opened for the image url then a set of image readers is +used to determine what type of image it is. The reader can peek at the +image header or if necessary load the image. The reader can also get the +image size at this stage. +The reader then can provide the mime type to create the image object to +load the rest of the information.

     + + + + + + + +

    The data usually need for an image is the size and either a bitmap or the +original data. Images such as jpeg and eps can be embedded into the +document with the original data. SVG images are converted into a DOM which +needs to be rendered to the PDF. Other images such as gif, tiff etc. are +converted into a bitmap. +Data is loaded by the FopImage by calling load(type) where type is the type of data to load.

     + + + + +

    Different renderers need to have the information in different forms.

    + + + +
    original data
    JPG, EPS
    +
    bitmap
    gif, tiff, bmp, png
    +
    other
    SVG
    +     + + +
    bitmap
    JPG, gif, tiff, bmp, png
    +
    other
    SVG
    +     + + +
    bitmap
    JPG, gif, tiff, bmp, png
    +
    other
    SVG
     + + + +

    The renderer uses the url to retrieve the image from the ImageFactory and +then load the required data depending on the image mime type. If the +renderer can insert the image into the document and use that data for all +future references of the same image then it can cache the reference in the +renderer and the image can be released from the image cache.

     +     +     + + + + + + + + + + + + + diff --git a/docs/design/understanding/layout_managers.xml b/docs/design/understanding/layout_managers.xml new file mode 100644 index 000000000..6630ac64b --- /dev/null +++ b/docs/design/understanding/layout_managers.xml @@ -0,0 +1,13 @@ + + + +
    + Layout Managers + All you wanted to know about Layout Managers ! + + +
    + +

    Yet to come :))

    + The series of notes for developers has started but it has not yet gone so far ! Keep watching     +     \ No newline at end of file diff --git a/docs/design/understanding/layout_process.xml b/docs/design/understanding/layout_process.xml new file mode 100644 index 000000000..4c426d8eb --- /dev/null +++ b/docs/design/understanding/layout_process.xml @@ -0,0 +1,13 @@ + + + +
    + Layout Process + All you wanted to know about the Layout Process ! + + +
    + +

    Yet to come :))

    + The series of notes for developers has started but it has not yet gone so far ! Keep watching     +     \ No newline at end of file diff --git a/docs/design/understanding/pdf_library.xml b/docs/design/understanding/pdf_library.xml new file mode 100644 index 000000000..434cc03f8 --- /dev/null +++ b/docs/design/understanding/pdf_library.xml @@ -0,0 +1,78 @@ + + + +
    + PDF Library + All you wanted to know about the PDF Library ! + + +
    + + +

    The PDF Library is an independant package of classes in FOP. These class +provide a simple way to construct documents and add the contents. The +classes are found in org.apache.fop.pdf.*.

    + + + + + +

    This is where most of the document is created and put together.

    +

    It sets up the header, trailer and resources. Each page is made and added to the document. +There are a number of methods that can be used to create/add certain PDF objects to the document.

    +     + + +

    The PDF Document is built by creating a page for each page in the Area Tree.

    +

    This page then has all the contents added. + The page is then added to the document and available objects can be written to the output stream.

    +

    The contents of the page are things such as text, lines, images etc. +The PDFRenderer inserts the text directly into a pdf stream. +The text consists of markup to set fonts, set text position and add text.

    +

    Most of the simple pdf markup is inserted directly into a pdf stream. +Other more complex objects or commonly used objects are added through java classes. +Some pdf objects such as an image consists of two parts.

    +

    It has a separate object for the image data and another bit of markup to display the image in a certain position on the page. +

    The java objects that represent a pdf object implement a method that returns the markup for inserting into a stream. +The method is: byte[] toPDF().

    + +     + + + + + +

    Support for embedding fonts and using the default Acrobat fonts. +

     + + +

    Images can be inserted into a page. The image can either be inserted as a pixel map or directly insert a jpeg image. +

     + + +

    A number of filters are available to encode the pdf streams. These filters can compress the data or change it such as converting to hex. +

     + + +

    A pdf link can be added for an area on the page. This link can then point to an external destination or a position on any page in the document. +

     + + +

    The fill and stroke of graphical objects can be set with a colour, pattern or gradient. +

     + + +

    The are a number of other features for handling pdf markup relevent to creating PDF files for FOP.

    +     + + + +

    There are a large number of additional features that can be added to pdf.

    +

    Many of these can be handled with extensions or post processing.

    + +     + + + +     +     \ No newline at end of file diff --git a/docs/design/understanding/properties.xml b/docs/design/understanding/properties.xml new file mode 100644 index 000000000..529ec8673 --- /dev/null +++ b/docs/design/understanding/properties.xml @@ -0,0 +1,130 @@ + + + +
    + Properties + All you wanted to know about the Properties ! + + +
    + +

    During XML Parsing, the FO tree is constructed. For each FO object (some +subclass of FObj), the tree builder then passes the list of all +attributes specified on the FO element to the handleAttrs method. This +method converts the attribute specifications into a PropertyList.

    +

    The actual work is done by a PropertyListBuilder (PLB for short). The +basic idea of the PLB is to handle each attribute in the list in turn, +find an appropriate "Maker" for it, call the Maker to convert the +attribute value into a Property object of the correct type, and store +that Property in the PropertyList.

    + + + +

    +The PLB finds a "Maker" for the property based on the attribute name and +the element name. Most Makers are generic and handle the attribute on +any element, but it's possible to set up an element-specific property +Maker. The attribute name to Maker mappings are automatically created +during the code generation phase by processing the XML property +description files.

    +     + + +

    The PLB first looks to see if the font-size property is specified, since +it sets up relative units which can be used in other property +specifications. Each attribute is then handled in turn. If the attribute +specifies part of a compound property such as space-before.optimum, the +PLB looks to see if the attribute list also contains the "base" property +(space-before in this case) and processes that first.

     +

    There is a family of Maker objects for each of the property datatypes, +such as Length, Number, Enumerated, Space, etc. But since each Property +has specific aspects such as whether it's inherited, its default value, +its corresponding properties, etc. there is usually a specific Maker for +each Property. All these Maker classes are created during the code +generation phase by processing (using XSLT) the XML property description +files to create Java classes.

    + + +

    The Maker first checks for "keyword" values for a property. These are +things like "thin, medium, thick" for the border-width property. The +datatype is really a Length but it can be specified using these keywords +whose actual value is determined by the "User Agent" rather than being +specified in the XSL standard. For FOP, these values are currently +defined in foproperties.xml. The keyword value is just a string, so it +still needs to be parsed as described next.

    + + +

    The Maker also checks to see if the property is an Enumerated type and +then checks whether the value matches one of the specified enumeration +values.

    + + +

    Otherwise the Maker uses the property parser in the fo.expr package to +evaluate the attribute value and return a Property object. The parser +interprets the expression language and performs numeric operations and +function call evaluations.

    + + +

    If the returned Property value is of the correct type (specificed in +foproperties.xml, where else?), the Maker returns it. Otherwise, it may +be able to convert the returned type into the correct type.

    + + +

    Some kinds of property values can't be fully resolved during FO tree +building because they depend on layout information. This is the case of +length values specified as percentages and of the special +proportional-column-width(x) specification for table-column widths. +These are stored as special kinds of Length objects which are evaluated +during layout. Expressions involving "em" units which are relative to +font-size _are_ resolved during the FO tree building however.

     + + + +

    The PropertyList extends HashMap and its basic function is to associate +Property value objects with Property names. The Property objects are all +subclasses of the base Property class. Each one simply contains a +reference to one of the property datatype objects. Property provides +accessors for all known datatypes and various subclasses override the +accessor(s) which are reasonable for the datatype they store.

    + + +

    The PropertyList itself provides various ways of looking up Property +values to handle such issues as inheritance and corresponding +properties.

    + + +

    The main logic is:
    If the property is a writing-mode relative property (using start, end, +before or after in its name), the corresponding absolute property value +is returned if it's explicitly set on this FO.
    Otherwise, the +writing-mode relative value is returned if it's explicitly set. If the +property is inherited, the process repeats using the PropertyList of the +FO's parent object. (This is easy because each PropertyList points to +the PropertyList of the nearest ancestor FO.) If the property isn't +inherited or no value is found at any level, the initial value is +returned.

     + + + + +
    docs/design/properties.xml
    a more detailed version of this (generated +html in docs/html-docs/design/properties.html)
    + + +
    src/codegen/properties.dtd
    heavily commented DTD for foproperties.xml, +but may not be completely up-to-date
     + + + + +
    • explain PropertyManager vs. direct access
      • +
    • Explain corresponding properties
     + + + + +

    Lots of properties are incompletely handled, especially funny kinds of +keyword values and shorthand values (one attribute which sets several +properties)

     + +     +     \ No newline at end of file diff --git a/docs/design/understanding/renderers.xml b/docs/design/understanding/renderers.xml new file mode 100644 index 000000000..cf66e2b8e --- /dev/null +++ b/docs/design/understanding/renderers.xml @@ -0,0 +1,13 @@ + + + +
    + Renderers + All you wanted to know about the Renderers ! + + +
    + +

    Yet to come :))

    + The series of notes for developers has started but it has not yet gone so far ! Keep watching     +     \ No newline at end of file diff --git a/docs/design/understanding/status.xml b/docs/design/understanding/status.xml new file mode 100644 index 000000000..c1e7fb1ea --- /dev/null +++ b/docs/design/understanding/status.xml @@ -0,0 +1,17 @@ + + + +
    + Tutorial series Status + Current Status of tutorial about FOP and Design + + +
    +

    Peter said : Do we have a volunteer to track + Keiron's tutorials and turn them into web page documentation?

    The answer is yes + we have, but the work is on progress !

    Keiron has recently extended + the documentation generation on the CVS trunk to make this process a bit + easier. Keiron tells Peter that Apache is readying a major overhaul of its web + site and xml->html generation, but that should not deter us from proceeding + with documentation.     +     \ No newline at end of file diff --git a/docs/design/understanding/svg.xml b/docs/design/understanding/svg.xml new file mode 100644 index 000000000..7fd19f369 --- /dev/null +++ b/docs/design/understanding/svg.xml @@ -0,0 +1,57 @@ + + + +
    + SVG + All you wanted to know about SVG and FOP ! + + +
    + +

    SVG is rendered through Batik.

    The XML from the XSL:FO document + is converted into an SVG DOM with batik. This DOM is then set as the Document + on the Foreign Object area in the Area Tree.

    This DOM is then available to + be rendered by the renderer.

    SVG is rendered in the renderers via an + XMLHandler in the FOUserAgent. This XML handler is used to render the SVG. The + SVG is rendered by using batik. Batik converts the SVG DOM into an internal + structure that can be drawn into a Graphics2D. So for PDF we use a + PDFGraphics2D to draw into.

    This creates the necessary PDF information to + create the SVG image in the PDF document.

    Most of the work is done in the + PDFGraphics2D class. There are also a few bridges that are plugged into batik + to provide different behaviour for some SVG elements.

    Normally batik converts text into a set of curved + shapes.

    This is handled as any other shapes when rendering to the output. This + is not always desirable as the shapes have very fine curves. This can cause the + output to look a bit bad in PDF and PS (it can be drawn properly but is not by + default). These curves also require much more data than the original + text.

    To handle this there is a PDFTextElementBridge that is set when + using the bridge in batik. If the text is simple enough for the text to be + drawn in the PDF as with all other text then this sets the TextPainter to use + the PDFTextPainter. This inserts the text directly into the PDF using the + drawString method on the PDFGraphics2D.

    Text is considered simple if the + font is available, the font size is useable and there are no tspans or other + complications. This can make the resulting PDF significantly + smaller.

    To support links in PDF another batik + element bridge is used. The PDFAElementBridge creates a PDFANode which inserts + a link into the PDF document via the PDFGraphics2D.

    Since links are + positioned on the page without any transforms then we need to transform the + coordinates of the link area so that they match the current position of the a + element area. This transform may also need to account for the svg being + positioned on the page.

    Images are normally drawn + into the PDFGraphics2D. This then creates a bitmap of the image data that can + be inserted into the PDF document.

    As PDF can support jpeg images then another + element bridge is used so that the jpeg can be directly inserted into the + PDF.

    Batik provides a mechanism to + convert SVG into various formats. Through FOP we can convert an SVG document + into a single paged PDF document. The page contains the SVG drawn as best as + possible on the page. There is a PDFDocumentGraphics2D that creates a + standalone PDF document with a single page. This is then drawn into by batik in + the same way as with the PDFGraphics2D.

    When rendering to AWT the SVG is simply drawn onto the + awt canvas using batik.

    The PS Renderer uses a similar technique as the + PDF Renderer.

    The SVG Renderer simply embeds the SVG inside an svg + element.

    • To get accurate drawing + pdf transparency is needed.
    • The drawRenderedImage methods need + implementing.
    • Handle colour space better.
    • Improve link handling + with pdf.
    • Improve image handling.
     +     \ No newline at end of file diff --git a/docs/design/understanding/understanding.xml b/docs/design/understanding/understanding.xml new file mode 100644 index 000000000..c34ec730b --- /dev/null +++ b/docs/design/understanding/understanding.xml @@ -0,0 +1,94 @@ + + + +
    + Understanding FOP Design + Tutorial series about Design Approach to FOP + + +
    + + + + The content of this Understanding series + was all taken from the interactive fop development mailing + list discussion .
    We strongly advise you to join this + mailing list and ask question about this series there.
    + You can subscribe to fop-dev@xml.apache.org by sending an + email to fop-dev-subscribe@xml.apache.org.
    You will + find more information about how to get involved there.
    You can also read the archive of the discussion list fop-dev to get an + idea of the issues being discussed. +     + +

    + Welcome to the understanding series. This will be + a series of notes for developers to understand how FOP + works. We will + attempt to clarify the processes involved to go from xml(fo) + to pdf or other formats. Some areas will get more + complicated as we proceed. +

    +     + + + +

    FOP takes an xml file does its magic and then writes a document to a + stream.

    +

    xml -> [FOP] -> document

    +

    The document could be pdf, ps etc. or directed to a printer or the + screen. The principle remains the same. The xml document must be in the XSL:FO + format.

    +

    For convenience we provide a mechanism to handle XML+XSL as + input.

    +

    The xml document is always handled internally as SAX. The SAX events + are used to read the elements, attributes and text data of the FO document. + After the manipulation of the data the renderer writes out the pages in the + appropriate format. It may write as it goes, a page at a time or the whole + document at once. Once finished the document should contain all the data in the + chosen format ready for whatever use.

     +

    The fo data goes through a few stages. Each piece + of data will generally go through the process in the same way but some + information may be used a number of times or in a different order. To reduce + memory one stage will start before the previous is completed.

    +

    SAX Handler -> FO Tree -> Layout Managers -> Area Tree + -> Render -> document

    +

    In the case of rtf, mif etc.
    SAX Handler -> FO Tree -> + Structure Renderer -> document

    +

    The FO Tree is constructed from the xml document. It is an internal + representation of the xml document and it is like a DOM with some differences. + The Layout Managers use the FO Tree do their layout stuff and create an Area + Tree. The Area Tree is a representation of the final result. It is a + representation of a set of pages containing the text and other graphics. The + Area Tree is then given to a Renderer. The Renderer can read the Area Tree and + convert the information into the render format. For example the PDF Renderer + creates a PDF Document. For each page in the Area Tree the renderer creates a + PDF Page and places the contents of the page into the PDF Page. Once a PDF Page + is complete then it can be written to the output stream.

    +

    For the structure documents the Structure listener will read + directly from the FO Tree and create the document. These documents do not need + the layout process or the Area Tree.

     +

    Verify Structure Listener + concept.

     + +
    • XML parsing
      • +
    • FO Tree
      • +
    • Properties
      • +
    • Layout Managers
      • +
    • Layout Process
      • +
    • Handling Attributes
      • +
    • Area Tree
      • +
    • Renderers
      • +
    • Images
      • +
    • PDF Library
      • +
    • SVG
      • +
    +     + +     + diff --git a/docs/design/understanding/xml_parsing.xml b/docs/design/understanding/xml_parsing.xml new file mode 100644 index 000000000..a7c8d4a85 --- /dev/null +++ b/docs/design/understanding/xml_parsing.xml @@ -0,0 +1,106 @@ + + +
    + XML Parsing + All you wanted to know about XML Parsing ! + + +
    + + +

    Since everyone knows the basics we can get + into the various stages starting with the XML handling.

    +

    FOP can take the input XML in a number of ways: +

    +
      +
    • SAX Events through SAX Handler +
        +
      • + FOTreeBuilder is the SAX Handler which is + obtained through getContentHandler on + Driver. +
        • +
      +
      • +
    • + DOM which is converted into SAX Events +
        +
      • + The conversion of a DOM tree is done via the + render(Document) method on + Driver. +
        • +
      +
      • +
    • + data source which is parsed and converted into SAX Events +
        +
      • + The Driver can take an + InputSource as input. This can use a + Stream, String etc. +
        • +
      +
      • +
    • + XML+XSLT which is transformed using an XSLT Processor and + the result is fired as SAX Events +
        +
      • + XSLTInputHandler is used as an + InputSource in the + render(XMLReader, + InputSource) method on + Driver +
        • +
      +
      • +
    + +

    The SAX Events which are fired on the SAX Handler, class + FOTreeBuilder, must represent an XSL:FO document. If not there will be an + error. Any problems with the XML being well formed are handled here.

     +

    The element mapping is a hashmap of all + the elements in a particular namespace. This makes it easy to create a + different object for each element. Element mappings are static to save on + memory.

    To add an extension a developer can put in the classpath a jar + that contains the file /META-INF/services/org.apache.fop.fo.ElementMapping. + This must contain a line with the fully qualified name of a class that + implements the org.apache.fop.fo.ElementMapping interface. This will then be + loaded automatically at the start. Internal mappings are: FO, SVG and Extension + (pdf bookmarks)

     +

    The SAX Events will fire all the information + for the document with start element, end element, text data etc. This + information is used to build up a representation of the FO document. To do this + for a namespace there is a set of element mappings. When an element + namepsace + mapping is found then it can create an object for that element. If the element + is not found then it creates a dummy object or a generic DOM for unknown + namespaces.

    +

    The object is then setup and then given attributes for the element. + For the FO Tree the attributes are converted into properties. The FO objects + use a property list mapping to convert the attributes into a list of properties + for the element. For other XML, for example SVG, a DOM of the XML is + constructed. This DOM can then be passed through to the renderer. Other element + mappings can be used in different ways, for example to create elements that + create areas during the layout process or setup information for the renderer + etc.

    +

    + While the tree building is mainly about creating the FO Tree + there are some stages that can propagate to the renderer. At + the end of a page sequence we know that all pages in the + page sequence can be laid out without being effected by any + further XML. The significance of this is that the FO Tree + for the page sequence may be able to be disposed of. The + end of the XML document also tells us that we can finalise + the output document. (The layout of individual pages is + accomplished by the layout managers page at a time; + i.e. they do not need to wait for the end of the page + sequence. The page may not yet be complete, however, + containing forward page number references, for example.) +

    +     + +
    • Error handling for xml not well formed.
      • +
    • Error handling for other XML parsing errors.
    • Developer + info for adding namespace handlers.
     +     \ No newline at end of file -- cgit v1.2.3