Introduction

diff --git a/src/documentation/content/xdocs/design/fotree.xml b/src/documentation/content/xdocs/design/fotree.xml index f53f32394..f277a406f 100644 --- a/src/documentation/content/xdocs/design/fotree.xml +++ b/src/documentation/content/xdocs/design/fotree.xml @@ -15,18 +15,28 @@

Introduction

-The FO Tree is an internal representation of the input FO document. -The tree is created by building the elements and attributes from -the SAX events. +The FO Tree is an internal representation of the input XSL-FO document. +The tree is created by building the elements and attributes from the SAX events. +The process of building the FO Tree corresponds to 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. +

The FO Tree is used as an intermediatory structure which is converted into the area tree. The complete FO tree should not be held in memory since FOP should be able to handle FO documents of any size.

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

FONode +

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

The class inheritance described above only describes the nature of the content. Every FO in FOP also has a parent, and a Vector of children. The @@ -38,16 +48,58 @@ constraints required by the FO hierarchy. FONode, among other things, ensures that FO's have a parent and that they may have children.

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

Making FO's +

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.

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

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

An FO maker is read from a hashmap lookup using the namespace and element name. This maker is then used to create a new class that represents an FO element. This is then added to the FO tree as a child of the current parent.

+ +

+ Properties + +

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

+ +

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.

Properties (recall that FO's have properties, areas have traits, and XML @@ -88,7 +140,72 @@ layout functionality.

- +

+ Foreign XML + +

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.

+ +

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

+ +

+ Unknown Elements +

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.

+ +

+ Page Masters +

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

+ +

+ Flow +

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.

+ +

+ Other Elements + +

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

diff --git a/src/documentation/content/xdocs/design/understanding/book.xml b/src/documentation/content/xdocs/design/understanding/book.xml index a37bd6e9a..090a80d8b 100644 --- a/src/documentation/content/xdocs/design/understanding/book.xml +++ b/src/documentation/content/xdocs/design/understanding/book.xml @@ -29,7 +29,6 @@ PARENT DIRECTORY!

diff --git a/src/documentation/content/xdocs/design/understanding/fo_tree.xml b/src/documentation/content/xdocs/design/understanding/fo_tree.xml deleted file mode 100644 index 8e8cfaca5..000000000 --- a/src/documentation/content/xdocs/design/understanding/fo_tree.xml +++ /dev/null @@ -1,140 +0,0 @@ - - - - -

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

- -

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

- -

- Properties - -

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

- -

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.

- -

- Foreign XML - -

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.

- -

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

- -

- Unknown Elements -

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.

- -

- Page Masters -

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

- -

- Flow -

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.

- -

- Other Elements - -

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

- - - - -- 2.39.5