AbsolutePosition diagram

From: Keiron Liddle Date: Mon, 2 Dec 2002 12:59:12 +0000 (+0000) Subject: no longer needed, moved to src/documentation/content/xdocs/design/ X-Git-Tag: Alt-Design-integration-base~281 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=ded83aa5f9ae2d7e9b15ab61a1842ffcc63a947a;p=xmlgraphics-fop.git no longer needed, moved to src/documentation/content/xdocs/design/ git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@195704 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/design/alt.design/AbsolutePosition.png b/docs/design/alt.design/AbsolutePosition.png deleted file mode 100644 index ed8a3691b..000000000 Binary files a/docs/design/alt.design/AbsolutePosition.png and /dev/null differ diff --git a/docs/design/alt.design/AbsolutePosition.png.xml b/docs/design/alt.design/AbsolutePosition.png.xml deleted file mode 100644 index 57af6a926..000000000 --- a/docs/design/alt.design/AbsolutePosition.png.xml +++ /dev/null @@ -1,21 +0,0 @@ - - - - -

- AbsolutePosition diagram - - - -

- - - -

- - - diff --git a/docs/design/alt.design/BorderCommonStyle.png b/docs/design/alt.design/BorderCommonStyle.png deleted file mode 100644 index 67cc9f8ee..000000000 Binary files a/docs/design/alt.design/BorderCommonStyle.png and /dev/null differ diff --git a/docs/design/alt.design/BorderCommonStyle.png.xml b/docs/design/alt.design/BorderCommonStyle.png.xml deleted file mode 100644 index a81ba9cae..000000000 --- a/docs/design/alt.design/BorderCommonStyle.png.xml +++ /dev/null @@ -1,20 +0,0 @@ - - - - -

- BorderCommonStyle diagram - - - -

- - - -

- - - diff --git a/docs/design/alt.design/PropNames.png b/docs/design/alt.design/PropNames.png deleted file mode 100644 index 8287e0875..000000000 Binary files a/docs/design/alt.design/PropNames.png and /dev/null differ diff --git a/docs/design/alt.design/PropNames.png.xml b/docs/design/alt.design/PropNames.png.xml deleted file mode 100644 index c851da75e..000000000 --- a/docs/design/alt.design/PropNames.png.xml +++ /dev/null @@ -1,21 +0,0 @@ - - - - - -

- ..fo.PropNames diagram - - - -

- - - -

- - - diff --git a/docs/design/alt.design/Properties.png b/docs/design/alt.design/Properties.png deleted file mode 100644 index 10da5f23c..000000000 Binary files a/docs/design/alt.design/Properties.png and /dev/null differ diff --git a/docs/design/alt.design/Properties.png.xml b/docs/design/alt.design/Properties.png.xml deleted file mode 100644 index 749ac651e..000000000 --- a/docs/design/alt.design/Properties.png.xml +++ /dev/null @@ -1,21 +0,0 @@ - - - - - -

- ..fo.Properties diagram - - - -

- - - -

- - - diff --git a/docs/design/alt.design/PropertyClasses.png b/docs/design/alt.design/PropertyClasses.png deleted file mode 100644 index e58ca94bf..000000000 Binary files a/docs/design/alt.design/PropertyClasses.png and /dev/null differ diff --git a/docs/design/alt.design/PropertyConsts.png b/docs/design/alt.design/PropertyConsts.png deleted file mode 100644 index b6df72f84..000000000 Binary files a/docs/design/alt.design/PropertyConsts.png and /dev/null differ diff --git a/docs/design/alt.design/PropertyConsts.png.xml b/docs/design/alt.design/PropertyConsts.png.xml deleted file mode 100644 index 69f71afcc..000000000 --- a/docs/design/alt.design/PropertyConsts.png.xml +++ /dev/null @@ -1,20 +0,0 @@ - - - - -

- ..fo.PropertyConsts diagram - - - -

- - - -

- - - diff --git a/docs/design/alt.design/PropertyStaticsOverview.png b/docs/design/alt.design/PropertyStaticsOverview.png deleted file mode 100644 index fdda19e74..000000000 Binary files a/docs/design/alt.design/PropertyStaticsOverview.png and /dev/null differ diff --git a/docs/design/alt.design/SAXParsing.png b/docs/design/alt.design/SAXParsing.png deleted file mode 100644 index f2652e1f7..000000000 Binary files a/docs/design/alt.design/SAXParsing.png and /dev/null differ diff --git a/docs/design/alt.design/VerticalAlign.png b/docs/design/alt.design/VerticalAlign.png deleted file mode 100644 index 860d5bdff..000000000 Binary files a/docs/design/alt.design/VerticalAlign.png and /dev/null differ diff --git a/docs/design/alt.design/VerticalAlign.png.xml b/docs/design/alt.design/VerticalAlign.png.xml deleted file mode 100644 index 61c60b354..000000000 --- a/docs/design/alt.design/VerticalAlign.png.xml +++ /dev/null @@ -1,21 +0,0 @@ - - - - - -

- VerticalAlign diagram - - - -

- - - -

- - - diff --git a/docs/design/alt.design/XML-event-buffer.png b/docs/design/alt.design/XML-event-buffer.png deleted file mode 100644 index 4ee16e913..000000000 Binary files a/docs/design/alt.design/XML-event-buffer.png and /dev/null differ diff --git a/docs/design/alt.design/XMLEventQueue.png b/docs/design/alt.design/XMLEventQueue.png deleted file mode 100644 index 477abd79a..000000000 Binary files a/docs/design/alt.design/XMLEventQueue.png and /dev/null differ diff --git a/docs/design/alt.design/alt.properties.xml b/docs/design/alt.design/alt.properties.xml deleted file mode 100644 index 51caba702..000000000 --- a/docs/design/alt.design/alt.properties.xml +++ /dev/null @@ -1,167 +0,0 @@ - - - - -

- 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/block-stacking-constraints.png b/docs/design/alt.design/block-stacking-constraints.png deleted file mode 100644 index 2387a815a..000000000 Binary files a/docs/design/alt.design/block-stacking-constraints.png and /dev/null differ diff --git a/docs/design/alt.design/block-stacking-keeps.png b/docs/design/alt.design/block-stacking-keeps.png deleted file mode 100644 index dce2518d0..000000000 Binary files a/docs/design/alt.design/block-stacking-keeps.png and /dev/null differ diff --git a/docs/design/alt.design/block-stacking.png b/docs/design/alt.design/block-stacking.png deleted file mode 100644 index afc2b0a66..000000000 Binary files a/docs/design/alt.design/block-stacking.png and /dev/null differ diff --git a/docs/design/alt.design/book.xml b/docs/design/alt.design/book.xml deleted file mode 100644 index 92779bdb8..000000000 --- a/docs/design/alt.design/book.xml +++ /dev/null @@ -1,32 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/design/alt.design/classes-overview.xml b/docs/design/alt.design/classes-overview.xml deleted file mode 100644 index d00762466..000000000 --- a/docs/design/alt.design/classes-overview.xml +++ /dev/null @@ -1,201 +0,0 @@ - - - - - -

- 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/compound-properties.xml b/docs/design/alt.design/compound-properties.xml deleted file mode 100644 index 94d4b2580..000000000 --- a/docs/design/alt.design/compound-properties.xml +++ /dev/null @@ -1,218 +0,0 @@ - - - - - -

- Compound properties - - - -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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

- - - diff --git a/docs/design/alt.design/coroutines.png b/docs/design/alt.design/coroutines.png deleted file mode 100644 index d00478a6a..000000000 Binary files a/docs/design/alt.design/coroutines.png and /dev/null differ diff --git a/docs/design/alt.design/coroutines.xml b/docs/design/alt.design/coroutines.xml deleted file mode 100644 index b76eab1b8..000000000 --- a/docs/design/alt.design/coroutines.xml +++ /dev/null @@ -1,118 +0,0 @@ - - - - - -

- Implementing co-routines - - - -

- - - -

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

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

Section 3.1, Conceptual Procedure, includes:

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

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

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

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

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

- Figure 1 -

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

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

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

- - - - diff --git a/docs/design/alt.design/footnotes.xml b/docs/design/alt.design/footnotes.xml deleted file mode 100644 index a97f1aed6..000000000 --- a/docs/design/alt.design/footnotes.xml +++ /dev/null @@ -1,137 +0,0 @@ - - - - - -

- Implementing footnotes - - - -

- - - -

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

- -

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

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

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

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

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

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

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

- Figure 1 Columns before first footnote. -

- - -

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

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

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

- - - To be developed. - - - - diff --git a/docs/design/alt.design/galley-preprocessing.png b/docs/design/alt.design/galley-preprocessing.png deleted file mode 100644 index 3a87d58f3..000000000 Binary files a/docs/design/alt.design/galley-preprocessing.png and /dev/null differ diff --git a/docs/design/alt.design/galleys.xml b/docs/design/alt.design/galleys.xml deleted file mode 100644 index 0175a583e..000000000 --- a/docs/design/alt.design/galleys.xml +++ /dev/null @@ -1,210 +0,0 @@ - - - - - -

- Galleys - - - -

- - - - -

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

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

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

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

- - -

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

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

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

- - - -

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

- - -

- Galleys are processed in two basic processing environments: -

- -

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

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

- - -

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

- - - - -

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

- Figure 1 -

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

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

- - - - diff --git a/docs/design/alt.design/initial-column-values.png b/docs/design/alt.design/initial-column-values.png deleted file mode 100644 index 103887e07..000000000 Binary files a/docs/design/alt.design/initial-column-values.png and /dev/null differ diff --git a/docs/design/alt.design/intro.xml b/docs/design/alt.design/intro.xml deleted file mode 100644 index 0af32f20e..000000000 --- a/docs/design/alt.design/intro.xml +++ /dev/null @@ -1,86 +0,0 @@ - - - - - -

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

- - - -

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

- The main aims of this redesign effort are: -

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

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

- Representing properties, for most purposes, as integers. -
- Distributing FOP processing over a number of threads with - single-point downstream communication and flow control by - means of traditional producer/consumer queues. The threads - so far under consideration are: -
- XML parser
- FO tree builder
- layout engine
- Area tree builder
-
- Representing trees with explicit Tree objects, rather than - as implicit relationships among other objects. -
- Caching integrated into the tree node access methods. -

- -

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

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

- - - - - - diff --git a/docs/design/alt.design/keeps.xml b/docs/design/alt.design/keeps.xml deleted file mode 100644 index 3ff533924..000000000 --- a/docs/design/alt.design/keeps.xml +++ /dev/null @@ -1,109 +0,0 @@ - - - - - -

- Keeps and breaks - - - -

- - - -

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

- -

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

- - -

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

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

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

- Figure 1 -

- -

- The three basic links are: -

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

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

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

- - - - diff --git a/docs/design/alt.design/line-area-5.png b/docs/design/alt.design/line-area-5.png deleted file mode 100644 index 6c467be24..000000000 Binary files a/docs/design/alt.design/line-area-5.png and /dev/null differ diff --git a/docs/design/alt.design/line-area-6.png b/docs/design/alt.design/line-area-6.png deleted file mode 100644 index 0001a0a4b..000000000 Binary files a/docs/design/alt.design/line-area-6.png and /dev/null differ diff --git a/docs/design/alt.design/parserPersistence.png b/docs/design/alt.design/parserPersistence.png deleted file mode 100644 index 342a933b4..000000000 Binary files a/docs/design/alt.design/parserPersistence.png and /dev/null differ diff --git a/docs/design/alt.design/processPlumbing.png b/docs/design/alt.design/processPlumbing.png deleted file mode 100644 index 182d3c68e..000000000 Binary files a/docs/design/alt.design/processPlumbing.png and /dev/null differ diff --git a/docs/design/alt.design/properties-classes.xml b/docs/design/alt.design/properties-classes.xml deleted file mode 100644 index 6f652fd4d..000000000 --- a/docs/design/alt.design/properties-classes.xml +++ /dev/null @@ -1,140 +0,0 @@ - - - - - -

- 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.png b/docs/design/alt.design/property-super-classes-full.png deleted file mode 100644 index dea871d3c..000000000 Binary files a/docs/design/alt.design/property-super-classes-full.png and /dev/null differ diff --git a/docs/design/alt.design/propertyExpressions.xml b/docs/design/alt.design/propertyExpressions.xml deleted file mode 100644 index 7ebbcd4fe..000000000 --- a/docs/design/alt.design/propertyExpressions.xml +++ /dev/null @@ -1,341 +0,0 @@ - - - - - -

- 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
	Angle	In degrees(deg), gradients(grad) or - radians(rad)
	Ems	Relative length in ems
	Frequency	In hertz(Hz) or kilohertz(kHz)
	IntegerType	-
	Length	In centimetres(cm), millimetres(mm), - inches(in), points(pt), picas(pc) or pixels(px)
	Percentage	-
	Time	In 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. -
		Country	An RFC 3066/ISO 3166 country code.
		Language	An RFC 3066/ISO 639 language code.
		Script	An 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/spaces.xml b/docs/design/alt.design/spaces.xml deleted file mode 100644 index 80bb8c46d..000000000 --- a/docs/design/alt.design/spaces.xml +++ /dev/null @@ -1,177 +0,0 @@ - - - - - -

- Keeps and space-specifiers - - - -

- - - -

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

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

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

- - -

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

Figure 1

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

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

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

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

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

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

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

Figure 2

- -

- - -

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

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

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

- - - - diff --git a/docs/design/alt.design/traits.xml b/docs/design/alt.design/traits.xml deleted file mode 100644 index c983c371a..000000000 --- a/docs/design/alt.design/traits.xml +++ /dev/null @@ -1,369 +0,0 @@ - - - - - -

- Traits - - - -

Trait	Applies to	Refs	Derived from
Common Traits
block-progression-direction	All areas	- 4.2.2 Common Traits - 7.27.7 writing-mode -	- 7.27.7 reference-orientation -
inline-progression-direction	All areas	- 4.2.2 Common Traits - 7.27.7 writing-mode -	- 7.27.7 reference-orientation -
shift-direction	Inline areas
glyph-orientation	Glyph-areas	- 4.2.2 Common Traits - 4.6.2 Glyph-areas - 4.7.2 Line-building - 4.9.5 Intrinsic Marks - 7.8.1 Fonts and Font Data - 7.27 Writing-mode-related Properties -	- 7.27.2 glyph-orientation-horizontal - 7.27.3 glyph-orientation-vertical - 7.27.1 direction - 7.27.7 writing-mode -
is-reference-area	All areas	- 5.6 Non-property Based Trait Generation -	- Set "true" on: - simple-page-master - title - region-body - region-before - region-after - region-start - region-end - block-container - inline-container - table - table-caption - table-cell -
is-viewport-area		- 4.2.2 Common Traits -
top-position
bottom-position
left-position
right-position
left-offset
top-offset
is-first
is-last
generated-by
returned-by
nominal-font
blink		- 5.5.6 Text-decoration Property - -	- 7.16.4 "text-decoration" - -
underline-score		- 5.5.6 Text-decoration Property - -	- 7.16.4 "text-decoration" - -
underline-score-color		- 5.5.6 Text-decoration Property - -	- 7.16.4 "text-decoration" - -
overline-score		- 5.5.6 Text-decoration Property - -	- 7.16.4 "text-decoration" - -
overline-score-color		- 5.5.6 Text-decoration Property - -	- 7.16.4 "text-decoration" - -
through-score		- 5.5.6 Text-decoration Property - -	- 7.16.4 "text-decoration" - -
through-score-color		- 5.5.6 Text-decoration Property - -	- 7.16.4 "text-decoration" - -
Other Indirectly Derived Traits
alignment-point	-	- 4.1 Introduction -
alignment-baseline	-	- 4.1 Introduction -
baseline-shift	-	- 4.1 Introduction -
dominant-baseline-identifier	-	- 4.1 Introduction -
actual-baseline-table	-	- 4.1 Introduction -
start-intrusion-adjustment	-	- 4.1 Introduction -
end-intrusion-adjustment	-	- 4.1 Introduction -
page-number	-	- 4.1 Introduction -
script	-	- 4.1 Introduction -

- - - diff --git a/docs/design/alt.design/user-agent-refs.xml b/docs/design/alt.design/user-agent-refs.xml deleted file mode 100644 index 2cca58beb..000000000 --- a/docs/design/alt.design/user-agent-refs.xml +++ /dev/null @@ -1,806 +0,0 @@ - - - - - -

- User agent refs - - - -

- - - -

- If the block-progression-dimension of the reference-area is - larger than that of the viewport-area and the overflow trait - for the reference-area is scroll, then the - inline-scroll-amount and block-scroll-amount are determined - by a scrolling mechanism, if any, provided by the - user agent. Otherwise, both are zero. -

- - -

- A computed value is in principle ready to be used, but a - user agent may not be able to make use of the value in a - given environment. For example, a user - agent may only be able to render borders with - integer pixel widths and may, therefore, have to adjust the - computed width to an integral number of media pixels. -

- - -

- There is no XSL mechanism to specify a particular font; - instead, a selected font is chosen from the fonts available - to the User Agent based on a set of - selection criteria. The selection criteria are the following - font properties: "font-family", "font-style", - "font-variant", "font-weight", "font-stretch", and - "font-size", plus, for some formatting objects, one or more - characters. -

- - -

- If the User Agent chooses a measurement for - a 'px' that does not match an integer number of device dots - in each axis it may produce undesirable effects... -

- - - -

- The merge-property-values function returns a value of the - property whose name matches the argument, or if omitted - for the property for which the expression is being - evaluated. The value returned is the specified value on - the last fo:multi-property-set, of the parent - fo:multi-properties, that applies to the User - Agent state. If there is no such value, the - computed value of the parent fo:multi-properties is - returned... -

- The test for applicability of a User - Agent state is specified using the "active-state" - property. -

- - - - -

- The fo:multi-property-set is used to specify an - alternative set of formatting properties that, dependent - on a User Agent state, are applied to the - content. -

- - -

- The fo:title formatting object is used to associate a - title with a given page-sequence. This title may be used - by an interactive User Agent to identify - the pages. For example, the content of the fo:title can be - formatted and displayed in a "title" window or in a "tool - tip". -

- - - -

- ... When pages are used with a User Agent - such as a Web browser, it is common that the each document - has only one page. The viewport used to view the page - determines the size of the page. When pages are placed on - non-interactive media, such as sheets of paper, pages - correspond to one or more of the surfaces of the paper. -

- - - -

- ... This title may be used by an interactive User - Agent to identify the pages. -

- - - - -

- The dimensions of the areas are determined by the font - metrics for the glyph. -

- When formatting an fo:character with a - "treat-as-word-space" value of "true", the User - Agent may use a different method for determining - the inline-progression-dimension of the area. -

- - - - -

- Dynamic effects, whereby user actions (including - User Agent state) can influence the - behavior and/or representation of portions of a document, - can be achieved through the use of the formatting objects - included in this section: -

One-directional single-target links.
- The ability to switch between the display of two or more - formatting object subtrees. This can be used for, e.g., - expandable/collapsible table of contents, display of an - icon or a full table or graphic. -
- The ability to switch between different property values, - such as color or font-weight, depending on a - User Agent state, such as "hover". -

- - - - -

- ... There may be limits on how much space conditionally - generated areas can borrow from the - region-reference-area. It is left to the user - agent to decide these limits. -

- ... An interactive user agent may choose - to create "hot links" to the footnotes from the - footnote-citation, or create "hot links" to the - before-floats from an implicit citation, instead of - realizing conditional sub-regions. -

- - - - -

- ... The user agent may make its own - determination, after taking into account the intrusion - adjustments caused by one or more overlapping side-floats, - that the remaining space in the - inline-progression-direction is insufficient for the next - side-float or normal block-area. The user - agent may address this by causing the next - side-float or normal block-area to "clear" one of the - relevant side-floats, as described in the "clear" property - description, so the intrusion adjustment is sufficiently - reduced. Of the side-floats that could be cleared to meet - this constraint, the side-float that is actually cleared - must be the one whose after-edge is closest to the - before-edge of the parent reference-area. -

- The user agent may determine sufficiency - of space by using a fixed length, or by some heuristic - such as whether an entire word fits into the available - space, or by some combination, in order to handle text and - images. -

- - - - -

- ... The second block-area and any additional block-areas - returned by an fo:footnote must be placed on the - immediately subsequent pages to the page containing the - first block-area returned by the fo:footnote, before any - other content is placed. If a subsequent page does not - contain a region-body, the user agent - must use the region-master of the last page that did - contain a region-body to hold the additional block-areas. -

- - - -

...

- -

- 5. When the absolute-position is "fixed", the containing - block is defined by the nearest ancestor viewport area. If - there is no ancestor viewport area, the containing block - is defined by the user agent. -

- - - -

Initial: depends on user agent

- - - -

- ... User agents may treat fixed as - scroll. However, it is recommended they interpret fixed - correctly, at least for the HTML and BODY elements, since - there is no way for an author to provide an image only for - those browsers that support fixed. -

- - - - -

- ... If border-before-width is specified using one of the - width keywords the .conditional component is set to - "discard" and the .length component to a User - Agent dependent length. -

- - - - -

- ... If an element's border color is not specified with a - "border" property, user agents must use - the value of the element's "color" property as the - computed value for the border color. -

- - - -

- Conforming HTML user agents may interpret - 'dotted', 'dashed', 'double', 'groove', 'ridge', 'inset', - and 'outset' to be 'solid'. -

- - - -

- ... The interpretation of the first three values depends - on the user agent. -

- - - -

Initial: depends on user agent

- - -

- ... This fallback may be to seek a match using a - User Agent default "font-family", or it may - be a more elaborate fallback strategy where, for example, - "Helvetica" would be used as a fallback for "Univers". -

- If no match has been found for a particular character, there - is no selected font and the User Agent - should provide a visual indication that a character is not - being displayed (for example, using the 'missing character' - glyph). -

- - - -

- - -

- A <relative-size> keyword is interpreted relative to - the table of font sizes and the font size of the parent - element. Possible values are:
[ larger | smaller - ]
For example, if the parent element has a font size - of "medium", a value of "larger" will make the font size - of the current element be "large". If the parent element's - size is not close to a table entry, the user - agent is free to interpolate between table - entries or round off to the closest one. The user - agent may have to extrapolate table values if the - numerical value goes beyond the keywords. -

- - -

- A length value specifies an absolute font size (that is - independent of the user agent's font - table). -

- - - - -

- ... If a genuine small-caps font is not available, - user agents should simulate a small-caps - font... -

- - - - -

- ... The association of other weights within a family to - the numerical weight values is intended only to preserve - the ordering of weights within that family. User - agents must map names to values in a way that - preserves visual order; a face mapped to a value must not - be lighter than faces mapped to lower values. There is no - guarantee on how a user agent will map - fonts within a family to weight values. However, the - following heuristics... -

- - - - -

- ... If the baseline-identifier does not exist in the - baseline-table for the glyph or other inline-area, then - the User Agent may either use heuristics - to determine where that missing baseline would be or may - use the dominant-baseline as a fallback. -

- - - - -

- ... Because in most fonts the subscript position is - normally given relative to the "alphabetic" baseline, the - User Agent may compute the effective - position for sub/superscripts [sub: spec typo!] - when some other baseline is dominant. ... If there is no - applicable font data the User Agent may - use heuristics to determine the offset. -

- - - -

- ... If there is no baseline-table in the nominal font or if - the baseline-table lacks an entry for the desired baseline, - then the User Agent may use heuristics to - determine the position of the desired baseline. -

- - - -

- The User Agent is free to choose either - resampling, integer scaling, or any other scaling method. -

- - -

- The User Agent should scale the image - such that each pixel in the original image is scaled to - the nearest integer number of device-pixels that yields an - image less-then-or-equal-to the image size derived from - the content-height, content-width, and scaling properties. -

- - -

- The User Agent should resample the - supplied image to provide an image that fills the size - derived from the content-height, content-width, and - scaling properties. The user agent may - use any sampling method. -

- -

- ... This is defined as a preference to allow the - user agent the flexibility to adapt to - device limitations and to accommodate over-constrained - situations involving min/max dimensions and scale factors. -

- - -

- ... The width of a replaced element's box is intrinsic and - may be scaled by the user agent if the - value of this property is different than 'auto'. -

- - - -

- Tells user agents to set the computed - value to a "reasonable" value based on the font size of - the element. -

- -

- ... When an element contains text that is rendered in more - than one font, user agents should determine - the "line-height" value according to the largest font size. -

- - -

- ... The actual justification algorithm used is user - agent and written language dependent.
- Conforming user agents may interpret the - value 'justify' as 'left' or 'right', depending on whether - the element's default writing direction is left-to-right or - right-to-left, respectively. -

- - -

- ... User agents should render this - indentation as blank space. -

- - - -

- The spacing is the normal spacing for the current - font. This value allows the user agent to - alter the space between characters in order to justify - text. -

- - -

- This value indicates inter-character space in addition to - the default space between characters. Values may be - negative, but there may be implementation-specific - limits. User agents may not further - increase or decrease the inter-character space in order to - justify text. -

- -

- Character-spacing algorithms are user agent - dependent. Character spacing may also be influenced by - justification (see the "text-align" property).
When the - resultant space between two characters is not the same as - the default space, user agents should not - use ligatures.
Conforming user agents - may consider the value of the 'letter-spacing' property to - be 'normal'. -

- -

- ... For "normal": .optimum = "the normal spacing for the - current font" / 2, .maximum = auto, .minimum = auto, - .precedence = force, and .conditionality = discard. A - value of auto for a component implies that the limits are - User Agent specific. -

- ... The CSS statement that "Conforming user - agents may consider the value of the - 'letter-spacing' property to be 'normal'." does not apply - in XSL, if the User Agent implements the - "Extended" property set. -

- ... The algorithm for resolving the adjusted values - between word spacing and letter spacing is User - Agent dependent. -

- - - -

- ... If the element has no content or no text content (e.g., - the IMG element in HTML), user agents must - ignore this property. -

- -

- ... Conforming user agents are not - required to support this value. -

- - - -

- ... Conforming user agents may consider the - value of "text-transform" to be "none" for characters that - are not from the ISO Latin-1 repertoire and for elements in - languages for which the transformation is different from - that specified by the case-conversion tables of Unicode or - ISO 10646. -

- - -

- ... Word spacing algorithms are user - agent-dependent. -

- -

- ... The algorithm for resolving the adjusted values - between word spacing and letter spacing is User - Agent dependent. -

- - - -

Initial: depends on user agent

- - - -

- This is the default behavior. The User - Agent determines the best intent based on the - content type. For image content containing an embedded - profile, it shall be assumed that the intent specified - within the profile is the desired intent. Otherwise, the - user agent shall use the current profile - and force the intent, overriding any intent that might be - stored in the profile itself. -

- - - - -

- This value indicates that the content is clipped and that - if the user agent uses a scrolling - mechanism that is visible on the screen (such as a scroll - bar or a panner), that mechanism should be displayed for a - box whether or not any of its content is clipped. -

- - -

- The behavior of the "auto" value is user - agent dependent, but should cause a scrolling - mechanism to be provided for overflowing boxes. -

- - - - -

- ... The choice of dot character is dependent on the - user agent. -

- - - -

- ... User agents may choose to use the value - of "leader-length.optimum" to determine where to break the - line, then use the minimum and maximum values during line - justification. -

- - - -

- The User Agent determines which value of - "media-usage" (other than the "auto" value) is used. The - User Agent may consider the type of media - on which the presentation is to be placed in making this - determination.
NOTE:
For example, the - User Agent could use the following - decision process. If the media is not continuous and is of - fixed bounded size, then the "paginate" (described below) - is used. Otherwise, the "bounded-in-one-dimension" is - used. -

- - -

- ... It is an error if more or less than one of - "page-height" or "page-width" is specified on the first - page master that is used. The User Agent - may recover as follows:... -

- - -

- Only one page is generated per fo:page-sequence descendant - from the fo:root. Neither "page-height" nor "page-width" - may be specified on any page master that is used. If a - value is specified for either property, it is an error and - a User Agent may recover by ignoring the - specified value. ... -

- - - - -

- The "page-height" shall be determined, in the case of - continuous media, from the size of the User - Agent window... -

- - -

- A User Agent may provide a way to declare - the media for which formatting is to be done. This may be - different from the media on which the formatted result is - viewed. For example, a browser User Agent - may be used to preview pages that are formatted for sheet - media. In that case, the size calculation is based on the - media for which formatting is done rather than the media - being currently used. -

- - - - -

- The "page-width" shall be determined, in the case of - continuous media, from the size of the User - Agent window... -

- - - - -

- ... Rows, columns, row groups, and column groups cannot - have borders (i.e., user agents must - ignore the border properties for those elements). -

- - - -

- ... For a caption that is on the left or right side of a - table box, on the other hand, a value other than "auto" for - "width" sets the width explicitly, but "auto" tells the - user agent to chose a "reasonable width". -

- - - -

- ... The User Agent shall round the value - of the angle to the closest of the permitted values. -

- - - - -

- ... The determination of which characters should be - auto-rotated may vary across User Agents. -

- - -

- ... The User Agent shall round the value - of the angle to the closest of the permitted values. -

- - - - -

- ... Fallback:
If it is not possible to present the - characters in the correct order, then the - UserAgent should display either a - 'missing character' glyph or display some indication that - the content cannot be correctly rendered. -

- - - -

- ... This property specifies the content-type and may be used - by a User Agent to select a rendering - processor for the object. -

- -

- No identification of the content-type. The User - Agent may determine it by "sniffing" or by other - means. -

- - - -

- ... If an element's border color is not specified with a - "border" property, user agents must use the - value of the element's "color" property as the computed - value for the border color. -

- - -

- ... Rows, columns, row groups, and column groups cannot have - borders (i.e., user agents must ignore the - border properties for those elements). -

- - -

- ... If no font with the indicated characteristics exists on - a given platform, the user agent should - either intelligently substitute (e.g., a smaller version of - the "caption" font might be used for the "small-caption" - font), or substitute a user agent default - font. -

- - -

Initial: depends on user agent

- - -

- ... Relative page boxes allow user agents - to scale a document and make optimal use of the target size. -

- ... User agents may allow users to control - the transfer of the page box to the sheet (e.g., rotating an - absolute page box that's being printed). -

- Rendering page boxes that do not fit a target sheet
- If a page box does not fit the target sheet dimensions, - the user agent may choose to: -
- - Rotate the page box 90 degrees if this will make the - page box fit. -
- Scale the page to fit the target.
- The user agent should consult the user - before performing these operations. -
- Positioning the page box on the sheet
When the page - box is smaller than the target size, the user - agent is free to place the page box anywhere on - the sheet. -

- - - -

- This value directs user agents to - collapse sequences of whitespace, and break lines as - necessary to fill line boxes. ... -

- - -

- This value prevents user agents from - collapsing sequences of whitespace. ... -

- -

- ... Conforming user agents may ignore the - 'white-space' property in author and user style sheets but - must specify a value for it in the default style sheet. -

- - - - diff --git a/docs/design/alt.design/xml-parsing.xml b/docs/design/alt.design/xml-parsing.xml deleted file mode 100644 index 4e7cf939d..000000000 --- a/docs/design/alt.design/xml-parsing.xml +++ /dev/null @@ -1,224 +0,0 @@ - - - - - -

- 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 hierarchical 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.png b/docs/design/alt.design/xmlevent-queue.png deleted file mode 100644 index 0bb019c65..000000000 Binary files a/docs/design/alt.design/xmlevent-queue.png and /dev/null differ diff --git a/docs/design/float.svg b/docs/design/float.svg deleted file mode 100755 index 4e32f7203..000000000 --- a/docs/design/float.svg +++ /dev/null @@ -1,48 +0,0 @@ - - - - diff --git a/docs/design/page.svg b/docs/design/page.svg deleted file mode 100755 index f809cf749..000000000 --- a/docs/design/page.svg +++ /dev/null @@ -1,50 +0,0 @@ - - - - diff --git a/docs/design/understanding/area_tree.xml b/docs/design/understanding/area_tree.xml deleted file mode 100644 index 4dbe9e6e4..000000000 --- a/docs/design/understanding/area_tree.xml +++ /dev/null @@ -1,117 +0,0 @@ - - - -

- Area Tree - All you wanted to know about the Area Tree ! - - -

- - -

The Area Tree is an internal representation of the result document. This -is a set of java classes that can put together a set of objects that -represent the pages and their contents.

This information is created by the layout managers and is rendered to the -output using a renderer.

The Area Tree follows the description of the area tree in the XSL:FO -specification.

The Area Tree consists of a set of pages, the actual implemenation places -these in -a set of page sequences.

- - -

A page consists of a page+viewport pair.

The PageViewPort and Page with the regions is created by the -LayoutMasterSet. The contents are then placed by the layout managers. Once -the layout of a page is complete then it is added to the Area Tree.

Inside the page is a set of RegionViewport+Region pairs for each region on -the page.

- - - -

Block level areas contain either other blocks or line areas (which is a -special block area).

-A block is either positoned or stacked with other block areas.

- - - -

Inline areas are stacked in a line area. Inline areas are objects such as -character, viewport, inline-container, leader and space. A special inline -area Word is also used for a group of consecutive characters.

The image and instream foreign object areas are placed inside a viewport. -The leader (with use content) and unresolved page number areas are -resolved to other inline areas.

Once a LineArea is filled with inline areas then the inline areas need to -be aligned and adjusted to fill the line properly.

- - - - -

A trait is information associated with an area. This could be information -such as text colour or is-first.

Traits provide information about an area. The traits are derived from -properties on the formatting object or are generated during the layout -process. Many of the layout traits do not have actual values but can be -derived from the Area Tree. Other traits that apply when rendering the -areas are set on the area. Since setting the same value on every area -would use a lot of memory then the traits are derived from default or -parent values.

A dominant trait on a block area is set, for example font colour, so that -every line area with the same dominant value can derive it. The text -inline areas then get the font colour set on the inline area or from the -line area or from the block area.

- - - -

The Area Tree maintains a set of mappings from the reference to pages.

The PageViewPort holds the list of forward references that need resolving -so that if a references is resolved during layout the page can be easily -found and then fixed. Once all the forward references are resolved then -the page is ready to be rendered.

To layout a page any areas that cannot be resolved need to reserve space. -Once the inline area is resolved then the complete line should be adjusted -to accomodate any change in space used by the area.

- - - -

We may need to cache pages due to forward references or when keeping all -pages.

This is done by serializing the Page. The PageViewport is retained to be -used as a key for page references and backward references. -The Page is serialized to an object stream and then all of the page -contents are released. The Page is then recoved by reading from the object -stream.

The PageViewport retains information about id areas for easy access.

- - - -

The Area Tree holds the Output Document extensions. This is information -such as pdf bookmarks or other output document specific information that -is not handled by XSL:FO.

It is also possible to create custom areas that extend a normal area. The -actual data that is rendered could be set in a different way or depend on -resolving a forward reference.

- - - -

To handle different situations the handler for the Area Tree handles each -page as it is added.

-The RenderPagesModel sends the page directly to the renderer if the page -is ready to be rendered. Once a page is rendered it is discarded. -The StorePagesModel stores all the pages so that any page can be later -accessed.

The Area Tree retains the concept of page sequences (this is not in the -area tree in the spec) so that this information can be passed to the -renderer. This is useful for setting the title and organising the groups -of page sequences.

- - - -

Sort out extensions concept, access to AreaTree.
Sort out trait handling.
Caching implementation.

- - - - \ No newline at end of file diff --git a/docs/design/understanding/book.xml b/docs/design/understanding/book.xml deleted file mode 100644 index 4e3013ca1..000000000 --- a/docs/design/understanding/book.xml +++ /dev/null @@ -1,23 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/design/understanding/fo_tree.xml b/docs/design/understanding/fo_tree.xml deleted file mode 100644 index cbe5e5f35..000000000 --- a/docs/design/understanding/fo_tree.xml +++ /dev/null @@ -1,184 +0,0 @@ - - -

- 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 deleted file mode 100644 index 81af0b40f..000000000 --- a/docs/design/understanding/handling_attributes.xml +++ /dev/null @@ -1,13 +0,0 @@ - - - -

- 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 deleted file mode 100644 index 68d71bcf2..000000000 --- a/docs/design/understanding/images.xml +++ /dev/null @@ -1,146 +0,0 @@ - - - -

- 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 deleted file mode 100644 index 297531b2d..000000000 --- a/docs/design/understanding/layout_managers.xml +++ /dev/null @@ -1,67 +0,0 @@ - - - -

- Layout Managers - All you wanted to know about Layout Managers ! - - -

- - - - -

The role of the layout managers is to build the Area Tree by using the -information from the FO Tree. The layout managers decide where information -is placed in the area tree.

A layout manager is typically associated with an FO Object but not always.

- - -

The layout managers are in between the FO Tree and the Area Tree. They get -information from the FO Tree and create areas and build the pages. They -hold the state of the layout process as it builds up the areas and pages. -They also manage the handling of breaks and spacing between areas.

- - -

FO Objects can have two types of properties, ones that relate to the layout and ones that relate to the rendering. THe layout related properties area used by the layout managers to determine how and where to create the areas. The render related properties should be passed through to the renderer in the most efficient way possible. -

- - - - -

When a block creating element is complete then it is possible to build the -block area and add it to the paprent.

A block area will contain either more block areas or line areas, which are -special block areas. The line areas are created by the LineLayoutManager -in which the inline areas flow into.

So a block area manager handles the lines or blocks as its children and -determines things like spacing and breaks.

In the case of tables and lists the blocks are stacked in a specific way -that needs to be handled by the layout manager.

- - - - - -

Side floats alter the length of the inline progression dimension for the -current line and following lines for the size of the float.

This means that the float needs to be handled by the block layout manager -so that it can adjust the available inline progression dimension for the -relevant line areas.

- - - - - -

Footnotes and Before Floats are placed in special areas in the body region -of the page. The size of these areas is determined by the content. This in -turn effects the available size of the main reference area that contains -the flow.

A layout manager handles the adding and removing of footnotes/floats, this in turn effects the available space in the main reference area.

- - -(note: more info to follow) - - - - \ No newline at end of file diff --git a/docs/design/understanding/layout_process.xml b/docs/design/understanding/layout_process.xml deleted file mode 100644 index cc9c7fc18..000000000 --- a/docs/design/understanding/layout_process.xml +++ /dev/null @@ -1,13 +0,0 @@ - - - -

- 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 deleted file mode 100644 index 642ca9ec3..000000000 --- a/docs/design/understanding/pdf_library.xml +++ /dev/null @@ -1,78 +0,0 @@ - - - -

- 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 deleted file mode 100644 index 442e3ed64..000000000 --- a/docs/design/understanding/properties.xml +++ /dev/null @@ -1,130 +0,0 @@ - - - -

- 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 deleted file mode 100644 index d3db3647c..000000000 --- a/docs/design/understanding/renderers.xml +++ /dev/null @@ -1,115 +0,0 @@ - - - -

- Renderers - All you wanted to know about the Renderers ! - - -

- - - - - -

A renderer is used to convert the Area Tree into the output document. -The renderer is given the tree one page at a time. All pages are supplied -in the order they appear in the document. In order to save memory it is -possble to render the pages out of order. Any page that is not reeady to -be rendered is setup by the renderer first so that it can reserve a space -or reference for when the page is ready to be rendered.

The AbstractRenderer does most of the work to iterate through the area -tree parts. This means that the most renderers simply need to implement -the specific parts with inserting text, images and lines. The methods can -easily be overridden to handle things in a different way or do some extra -processing.

- - - -

The fonts are setup by the renderer being used. The font metrics are used -during the layout process to determine the size of characters.

- - - -

The render context is used by handlers. It contains information about the -current state of the renderer. Such as the page, the position and any -other miscellanous objects that are required to draw into the page.

- - - - -

A document may contain information in the form of XML for an image or -instream foreign object. This XML is handled -through the user agent. A standard extension for PDF is the SVG handler.

-If there is XML in the SVG namespace it is given to the handler which -renders the SVG into the pdf document at the given location. -This separation means that other XML handlers can easily be added.

- - - -

Document level extensions are handled with an extension handler. This -handles the information from the AreaTree and adds renders it to the -document. An example is the pdf bookmarks. This information first needs to -have all references resolved. Then the extension handler is ready to put -the information into the pdf document.

- - - - - - -

This uses the PDFDocument classes to create a PDF document. This supports -out of order rendering as it is possible to reserve a pdf page object that -can be later filled. Most of the work is to insert text or create lines. -SVG is handled by the XML handler that uses the PDFGraphics2D and batik to -draw the svg into the pdf page.

-This also allows for font embedding.

- - -

This creates a single svg document that contains all the pages rendered -with page sequences horizontally and pages vertically. This also adds -links between the pages so that it can be viewed by clicking on the page -to go to the next page.

- - -

This simply outputs to a text document.

- -

This draws the pages into an AWT graphic.

- - -

Similar to PDF.

- - -

Creates an XML file that represents the AreaTree.

- - -

This prints the document using the java printing facitlities. The AWT -rendering is used to draw the pages onto the printjob. -

- -

These formats do not use this rendering mechanism.

- - - -

It is also possible to add other renderers. The renderer simply needs to -implement the Renderer interface. The AbstractRenderer does most of what -is needed so it is better to extend this. This means that you only need to -implement the basic functionality such as text and lines. -

- - -

The layout of the document depends mainly on the font being used. -If two renderers have the same font metrics then it is possible to render -the Area Tree in each renderer. This can be handled by the AreaTree -Handler.

- - - - -

Sort out multiple renderers concept.

- - - - - - \ No newline at end of file diff --git a/docs/design/understanding/status.xml b/docs/design/understanding/status.xml deleted file mode 100644 index f0bbdce30..000000000 --- a/docs/design/understanding/status.xml +++ /dev/null @@ -1,17 +0,0 @@ - - - -

- 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 deleted file mode 100644 index 942a91358..000000000 --- a/docs/design/understanding/svg.xml +++ /dev/null @@ -1,57 +0,0 @@ - - - -

- 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 deleted file mode 100644 index b748ffca1..000000000 --- a/docs/design/understanding/understanding.xml +++ /dev/null @@ -1,94 +0,0 @@ - - - -

- 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 deleted file mode 100644 index f249cbce9..000000000 --- a/docs/design/understanding/xml_parsing.xml +++ /dev/null @@ -1,106 +0,0 @@ - - -

- 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