diff options
| author | Jeremias Maerki <jeremias@apache.org> | 2005-06-24 09:32:20 +0000 |
|---|---|---|
| committer | Jeremias Maerki <jeremias@apache.org> | 2005-06-24 09:32:20 +0000 |
| commit | f7aa56bc54d36ea5654963bdadc48517061e86ca (patch) | |
| tree | 03e3e8b2f7a9367153af4566b21920a2148242b6 /src | |
| parent | a800d9550b0e196b2b32e7c6f09423df45110a55 (diff) | |
| download | xmlgraphics-fop-f7aa56bc54d36ea5654963bdadc48517061e86ca.tar.gz xmlgraphics-fop-f7aa56bc54d36ea5654963bdadc48517061e86ca.zip | |
CVS -> SVN.
Recreated Clay's changes (hopefully all of them).
Removed alt.design stuff.
git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@201586 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'src')
31 files changed, 274 insertions, 5264 deletions
diff --git a/src/documentation/content/xdocs/design/alt.design/PropNames-png.xml b/src/documentation/content/xdocs/design/alt.design/PropNames-png.xml deleted file mode 100644 index 944bb0076..000000000 --- a/src/documentation/content/xdocs/design/alt.design/PropNames-png.xml +++ /dev/null @@ -1,36 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!-- - Copyright 1999-2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> - -<document> - <header> - <title>..fo.PropNames diagram</title> - <authors> - <person id="pbw" name="Peter B. West" - email="pbwest@powerup.com.au"/> - </authors> - </header> - <body> - <section> - <title>PropNames.class</title> - <figure src="images/design/alt.design/PropNames.png" alt="PropNames.class diagram"/> - </section> - </body> -</document> - diff --git a/src/documentation/content/xdocs/design/alt.design/alt-properties.xml b/src/documentation/content/xdocs/design/alt.design/alt-properties.xml deleted file mode 100644 index 82fa4b907..000000000 --- a/src/documentation/content/xdocs/design/alt.design/alt-properties.xml +++ /dev/null @@ -1,169 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!-- - Copyright 1999-2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> - -<document> - <header> - <title>Implementing Properties</title> - <authors> - <person id="pbw" name="Peter B. West" email="pbwest@powerup.com.au"/> - </authors> - </header> - <body> - <section> - <title>An alternative properties implementation</title> - <note> - 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. - </note> - <p> - Property handling is complex and expensive. Varying numbers of - properties <strong>apply</strong> to individual Flow Objects - <strong>(FOs)</strong> in the <strong>FO tree </strong> 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. - </p> - <note> - <em>(XSL 1.0 Rec)</em> <strong>5.1.4 Inheritance</strong> - ...The inheritable properties can be placed on any formatting - object. - </note> - <p> - Even if the value is not inheritable, it may be accessed by - its children through the <code>inherit</code> keyword or the - <code>from-parent()</code> core function, and potentially by - any of its descendents through the - <code>from-nearest-specified-value()</code> core function. - </p> - <p> - In addition to the assigned values of properties, almost every - property has an <strong>initial value</strong> which is used - when no value has been assigned. - </p> - <section> - <title>The history problem</title> - <p> - The difficulty and expense of handling properties comes from - this univeral inheritance possibility. The list of properties - which are assigned values on any particular <em>FO</em> - element will not generally be large, but a current value is - required for each property which applies to the <em>FO</em> - being processed. - </p> - <p> - The environment from which these values may be selected - includes, for each <em>FO</em>, <strong>for each applicable - property</strong>, the value assigned on this <em>FO</em>, - the value which applied to the parent of this <em>FO</em>, - the nearest value specified on an ancestor of this element, - and the initial value of the property. - </p> - </section> - <section> - <title>The construction hierarchy</title> - <p> - Properties are resoved in the <strong>FO tree</strong> in a - strictly hierarchical manner. Nodes are detected in the - input in a <strong>pre-order</strong> traversal, and are - built in the same order. This imples that there are two - phases, or states, of property resolution and construction. - Any particular FO node is either in a state of constructing - its own subtree, or in a stable state where the subtree - construction is complete. These states have differenct data - requirements. - </p> - <dl> - <dt>Subtree building</dt> - <dd> - In this state, all properties defined on this node, or any - of its ancestors must be available to the subtree. In - effect, any property defined on this node must be - available to its descendants, as all properties defined on - any ancestor are available to this node. - </dd> - <dt>Stable: subtree building complete</dt> - <dd> - In this state, only the properties <strong>applicable to - this node</strong> need be available. - </dd> - </dl> - </section> - <section> - <title>Representing properties: <property> classes</title> - <section> - <title>Class vs instance</title> - <p> - What information is required of <property> objects? - More particularly, what information is particular to the - <property> classes, and what to the instantiated - objects? The answer to this question depend largely on - how the <property> objects are used in the context - of layout and Area tree construction. The approach taken - in this implementation is that properties are simply flags - on certain data values associated with FOs. The semantics - of these flags are determined within the layout engine. - </p> - <p> - Certain constant information attaches to individual - <property> classes. This information is detailed in - the descriptions of individual properties in <em>Section - 7</em> of the specification. Such information is - represented in <strong>class</strong> fields and data - structures within the classes. - </p> - <p> - The "instance" information content of a <property> - is: - </p> - <ul> - <li> - explicitly, the <code>PropertyValue</code> datum of - the property, and - </li> - <li> - implicitly, the <strong>Flow Object</strong> to which - the property is attached. - </li> - </ul> - <p> - Properties, then, serve essentially to link <em>FO - instances</em> with <em>PropertyValue instances</em>, - attaching certain invariant semantic markers to the - PropertyValues in the process. In this implementation, - these functions can be realised entirely within the - <property> <strong>classes</strong> themselves, - without the need to instantiate any objects. In practice, - <strong><property> singletons</strong> are - instantiated to make access to some invariants simpler. - </p> - </section> - </section> - <p> - <strong>Next:</strong> <link href="classes-overview.html" - >property classes overview.</link> - </p> - </section> - </body> -</document> - diff --git a/src/documentation/content/xdocs/design/alt.design/compound-properties.xml b/src/documentation/content/xdocs/design/alt.design/compound-properties.xml deleted file mode 100644 index 0409b06a5..000000000 --- a/src/documentation/content/xdocs/design/alt.design/compound-properties.xml +++ /dev/null @@ -1,234 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!-- - Copyright 1999-2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> - -<document> - <header> - <title>Compound properties</title> - <authors> - <person name="Peter B. West" email="pbwest@powerup.com.au"/> - </authors> - </header> - <body> - <section> - <title>Compound properties in XSLFO</title> - <table> - <tr> - <th>Property type</th> - <th>Section</th> - <th>Inherited</th> - <th>'inherit'</th> - </tr> - <tr> - <th><length-range></th> - </tr> - <tr> - <th>minimum</th> - </tr> - <tr> - <th>optimum</th> - </tr> - <tr> - <th>maximum</th> - </tr> - <tr> - <td>block-progression-dimension</td> - <td>7.14.1</td> - <td>no</td> - <td>yes</td> - </tr> - <tr> - <td>inline-progression-dimension</td> - <td>7.14.5</td> - <td>no</td> - <td>yes</td> - </tr> - <tr> - <td>leader-length</td> - <td>7.21.4</td> - <td>yes</td> - <td>yes</td> - </tr> - <tr> - <th><length-conditional></th> - </tr> - <tr> - <th>length</th> - </tr> - <tr> - <th>conditionality</th> - </tr> - <tr> - <td>border-after-width</td> - <td>7.7.12</td> - <td>no</td> - <td>yes</td> - </tr> - <tr> - <td>border-before-width</td> - <td>7.7.9</td> - <td>no</td> - <td>yes</td> - </tr> - <tr> - <td>border-end-width</td> - <td>7.7.18</td> - <td>no</td> - <td>yes</td> - </tr> - <tr> - <td>border-start-width</td> - <td>7.7.15</td> - <td>no</td> - <td>yes</td> - </tr> - <tr> - <td>padding-after</td> - <td>7.7.32</td> - <td>no</td> - <td>yes</td> - </tr> - <tr> - <td>padding-before</td> - <td>7.7.31</td> - <td>no</td> - <td>yes</td> - </tr> - <tr> - <td>padding-end</td> - <td>7.7.34</td> - <td>no</td> - <td>yes</td> - </tr> - <tr> - <td>padding-start</td> - <td>7.7.33</td> - <td>no</td> - <td>yes</td> - </tr> - <tr> - <th><length-bp-ip-direction></th> - </tr> - <tr> - <th>block-progression-direction</th> - </tr> - <tr> - <th>inline-progression-direction</th> - </tr> - <tr> - <td>border-separation</td> - <td>7.26.5</td> - <td>yes</td> - <td>yes</td> - </tr> - <tr> - <th><space></th> - </tr> - <tr> - <th>minimum</th> - </tr> - <tr> - <th>optimum</th> - </tr> - <tr> - <th>maximum</th> - </tr> - <tr> - <th>precedence</th> - </tr> - <tr> - <th>conditionality</th> - </tr> - <tr> - <td>letter-spacing</td> - <td>7.16.2</td> - <td>yes</td> - <td>yes</td> - </tr> - <tr> - <td>line-height</td> - <td>7.15.4</td> - <td>yes</td> - <td>yes</td> - </tr> - <tr> - <td>space-after</td> - <td>7.10.6</td> - <td>no</td> - <td>yes</td> - </tr> - <tr> - <td>space-before</td> - <td>7.10.5</td> - <td>no</td> - <td>yes</td> - </tr> - <tr> - <td>space-end</td> - <td>7.11.1</td> - <td>no</td> - <td>yes</td> - </tr> - <tr> - <td>space-start</td> - <td>7.11.2</td> - <td>no</td> - <td>yes</td> - </tr> - <tr> - <td>word-spacing</td> - <td>7.16.8</td> - <td>yes</td> - <td>yes</td> - </tr> - <tr> - <th><keep></th> - </tr> - <tr> - <th>within-line</th> - </tr> - <tr> - <th>within-column</th> - </tr> - <tr> - <th>within-page</th> - </tr> - <tr> - <td>keep-together</td> - <td>7.19.3</td> - <td>yes</td> - <td>yes</td> - </tr> - <tr> - <td>keep-with-next</td> - <td>7.19.4</td> - <td>no</td> - <td>yes</td> - </tr> - <tr> - <td>keep-with-previous</td> - <td>7.19.5</td> - <td>no</td> - <td>yes</td> - </tr> - </table> - </section> - </body> -</document> - diff --git a/src/documentation/content/xdocs/design/alt.design/coroutines.xml b/src/documentation/content/xdocs/design/alt.design/coroutines.xml deleted file mode 100644 index b21dd6959..000000000 --- a/src/documentation/content/xdocs/design/alt.design/coroutines.xml +++ /dev/null @@ -1,135 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!-- - Copyright 1999-2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> - -<document> - <header> - <title>Implementing co-routines</title> - <authors> - <person name="Peter B. West" email="pbwest@powerup.com.au"/> - </authors> - </header> - <body> - <section> - <title>Implementing Co-routines in FOP</title> - <p> - 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, <em>Introduction to - Formatting </em>, includes the following comments. - </p> - <note> - [Formatting] comprises several steps, some of which depend on - others in a non-sequential way.<br/> ...and...<br/> - [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. - </note> - <p>Section 3.1, <em>Conceptual Procedure</em>, includes:</p> - <note> - 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. - </note> - <section> - <title>Application of co-routines</title> - <p> - 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. - </p> - <p> - 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. - </p> - <p> - 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. - </p> - <p> - 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.<br/><br/> - <strong>Figure 1</strong> - </p> - <figure src="images/design/alt.design/coroutines.png" - alt="Co-routine diagram"/> - <p> - For example, think of a page-production method working on a - complex page-sequence-master. - </p> - <source> - void makePages(...) { - ... - while (pageSequence.hasNext()) { - ... - page = generateNextPage(...); - boolean over = flow.fillPage(page); - if (over) return; - } - } - </source> - <p> - The <code>fillPage()</code> 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. - </p> - </section> - </section> - </body> -</document> - diff --git a/src/documentation/content/xdocs/design/alt.design/footnotes.xml b/src/documentation/content/xdocs/design/alt.design/footnotes.xml deleted file mode 100644 index ebaee47c4..000000000 --- a/src/documentation/content/xdocs/design/alt.design/footnotes.xml +++ /dev/null @@ -1,156 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!-- - Copyright 1999-2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> - -<document> - <header> - <title>Implementing footnotes</title> - <authors> - <person name="Peter B. West" email="pbwest@powerup.com.au"/> - </authors> - </header> - <body> - <section> - <title>Implementing footnotes in FOP</title> - <p> - 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. - </p> - <section> - <title>Footnotes and galleys</title> - <p> - In the structure described in the <link href= "galleys.html" - >introduction to FOP galleys</link>, 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. - </p> - <p> - When footnotes are introduced, the communication between - galleys and layout manager, as mentioned <link href= - "galleys.html#pre-processing" >above</link>, 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. - </p> - </section> - <section> - <title>Multiple columns and footnotes</title> - <note> - A possible method for multi-column layout and balancing - with footnotes, using a galley-based approach. - </note> - <p> - This note assumes a galley, as discussed <link href= - "galleys.html" >elsewhere</link>, 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 <em>layout - tree</em>. - </p> - <p> - 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. - </p> - <p> - 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. - </p> - <p> - 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.<br/><br/> - <strong>Figure 1</strong> Columns before first footnote. - </p> - <figure src= - "images/design/alt.design/initial-column-values.png" alt= - "Columns before first footnote"/> - </section> - <section> - <title>Balancing columns</title> - <p> - <strong>Figure 2</strong> Adding a line area with first - footnote. - </p> - <figure src= "images/design/alt.design/line-area-5.png" - alt= "Columns after adding first footnote"/> - <p> - 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. <strong>N.B.</strong> - 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. - <br/><br/> - <strong>Figure 3</strong> Adding a line area with next - footnote. - </p> - <figure src= "images/design/alt.design/line-area-6.png" - alt= "Columns after adding next footnote"/> - </section> - <section> - <title>Layout managers in the flow of control</title> - <note>To be developed.</note> - </section> - </section> - </body> -</document> - diff --git a/src/documentation/content/xdocs/design/alt.design/galleys.xml b/src/documentation/content/xdocs/design/alt.design/galleys.xml deleted file mode 100644 index 04a1d824d..000000000 --- a/src/documentation/content/xdocs/design/alt.design/galleys.xml +++ /dev/null @@ -1,233 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!-- - Copyright 1999-2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> - -<document> - <header> - <title>Galleys</title> - <authors> - <person name="Peter B. West" email="pbwest@powerup.com.au"/> - </authors> - </header> - <body> - <section> - <title>Layout galleys in FOP</title> - <section> - <title>Galleys in Lout</title> - <p> - Jeffrey H. Kingston, in <link href = - "http://snark.niif.spb.su/~uwe/lout/design.pdf" ><em>The - Design and Implementation of the Lout Document Formatting - Language</em> Section 5</link>, describes the - <strong>galley</strong> abstraction which he implemented in - <em>Lout</em>. A document to be formatted is a stream of - text and symbols, some of which are <strong>receptive - symbols</strong>. The output file is the first receptive - symbol; the formatting document is the first galley. The - archetypical example of a receptive symbol is - <strong>@FootPlace</strong> and its corresponding galley - definition, <strong>@FootNote</strong>. - </p> - <p> - 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</p> - <ul> - <li> - an appropriate target has been encountered in the file, - </li> - <li> - the component being promoted contains no unresolved galley - targets itself, and - </li> - <li> - there is sufficient room for the galley component at the - target. - </li> - </ul> - <p> - 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 <em>bottom-up</em>. - </p> - </section> - <section> - <title>Some features of galleys</title> - <p> - It is essential to note that galleys are self-managing; they - are effectively layout <em>bots</em> 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.) - </p> - <p> - 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 <em>auto</em> 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. - </p> - <p> - 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. - </p> - </section> - <section> - <title>The layout tree</title> - <anchor id="layout-tree"/> - <p> - This proposal for implementing galleys in FOP makes use of a - <strong>layout tree</strong>. As with the <link href= - "../layout.html" >layout managers</link><em></em> already - proposed, the layout tree acts as a bridge between the <link - href= "../fotree.html" >FO Tree</link> and the <link href= - "../areas.html" >Area Tree</link>. 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 <strong>galley - nodes</strong> and <strong>area tree fragments</strong>. - 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 - <em>layout-master-set</em>. - </p> - </section> - <section> - <title>Processing galleys</title> - <p> - Galleys are processed in two basic processing environments: - </p> - <section> - <title>Inline- and block-progression dimensions known</title> - <p> - The galley at set-up is provided with both an - <em>inline-progression-dimension</em> (<em>i-p-d</em>) and - a <em>block-progression-dimension</em> (<em>b-p-d</em>). - 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. - </p> - <p> - 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. - </p> - </section> - <section> - <title>Inline- ior block-progression-dimensions unknown</title> - <p> - 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 <link href= "../layout.html" >another - discussion</link>. 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 <em>fo:character</em> nodes and images of fixed - dimensions. - </p> - </section> - </section> - <section> - <title>Galley pre-processing</title> - <anchor id="pre-processing"/> - <p> - 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. - <br/><br/> - <strong>Figure 1</strong> - </p> - <figure - src="images/design/alt.design/galley-preprocessing.png" - alt="Galley pre-processing diagram"/> - <p> - 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. - </p> - <p> - 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 <em>getNextBreakPosition</em>. - </p> - </section> - </section> - </body> -</document> - diff --git a/src/documentation/content/xdocs/design/alt.design/index.xml b/src/documentation/content/xdocs/design/alt.design/index.xml deleted file mode 100644 index b728213fd..000000000 --- a/src/documentation/content/xdocs/design/alt.design/index.xml +++ /dev/null @@ -1,143 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!-- - Copyright 1999-2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> - -<!-- $Id$ --> - -<document> - <header> - <title>FOP Alternative Design</title> - <subtitle>Alternative Design Approach to FOP</subtitle> - <version>$Revision$ $Name$</version> - <authors> - <person name="Peter B. West" email="pbwest@powerup.com.au"/> - </authors> - </header> - - <body> - <section> - <title>Alternative Design</title> - <p> - 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. - </p> - <p> - The main aims of this redesign effort are: - </p> - <ul> - <li>full conformance with the Recommendation</li> - <li>no limitation on the size of files</li> - <li>increased performance</li> - <li>reduced memory footprint</li> - </ul> - <p> - Secondary aims include: - </p> - <ul> - <li>increased performance</li> - <li>reduced memory footprint</li> - </ul> - <p> - In order to achieve these aims, the primary areas - of design interest are: - </p> - <ul> - <li> - Representing properties, for most purposes, as integers. - </li> - <li> - Implementing a top-down processing model for each of the - processing components. - </li> - <li> - 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: - <ul> - <li>XML parser</li> - <li>FO tree builder</li> - <li>layout engine</li> - <li>Area tree builder</li> - </ul> - </li> - <li> - Redesigning XML parsing and FO tree building using a - <strong>pull-parsing</strong> methodology with integrated FO - input validation. - </li> - <li> - Representing vital relationships among the elements with - appropriate data structures. These include: - <ul> - <li> - Representing trees with explicit Tree objects, rather than - as implicit relationships among other objects. - </li> - <li> - Drawing threads through the tree nodes to - represent linear layout relationships for resolving - keeps, breaks and space specifiers. - </li> - </ul> - </li> - <li> - Caching integrated into the tree node access methods. - </li> - </ul> - <section> - <title>Status and availability</title> - <p> - The <em>ALT DESIGN</em> effort is not taking place on the - main line of development, represented by the <em>HEAD</em> - tag on the CVS trunk. The source is available via the - FOP_0-20-0_Alt-Design tag. This code has only a - non-<em>Ant</em> build environment based on some small unix - shell scripts and the <em>jikes</em> compiler. The parser - stage and the FO tree building code is present. The first - example of producer/consumer binding is working, the Tree - class and the Node class with inner <em>iterator</em> - classes are available and working. Property handling is - almost complete, and all FO classes are present and - sufficiently complete to allow for FO tree building. - </p> - <p> - <link href= - "http://marc.theaimsgroup.com/%3Fl=fop-dev%26m=103890259919360%26w=2" - >Preliminary results</link> and <link href= - "http://marc.theaimsgroup.com/%3Fl=fop-dev%26m=103918886413611%26w=2" - >follow-up testing</link> of FO tree building shows memory - reductions of almost 50% compared to the most recently tuned - version of the maintenance version of the code (FOP 0.20.5 - RC). Alt-Design FO tree building was also slightly faster, - in spite of the use of pull parsing implemented on top of - SAX. - </p> - <p> - Currently, only <link href="mailto:pbwest@powerup.com.au">Peter - West</link> is working on the ALT DESIGN sub-project. - </p> - </section> - </section> - - </body> -</document> - diff --git a/src/documentation/content/xdocs/design/alt.design/keeps.xml b/src/documentation/content/xdocs/design/alt.design/keeps.xml deleted file mode 100644 index eb26ba8a8..000000000 --- a/src/documentation/content/xdocs/design/alt.design/keeps.xml +++ /dev/null @@ -1,126 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!-- - Copyright 1999-2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> - -<document> - <header> - <title>Keeps and breaks</title> - <authors> - <person name="Peter B. West" email="pbwest@powerup.com.au"/> - </authors> - </header> - <body> - <section> - <title>Keeps and breaks in layout galleys</title> - <p> - The <link href= "galleys.html" >layout galleys</link> and the - <link href= "galleys.html#layout-tree" >layout tree</link> - 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. - </p> - <section> - <title>Breaks</title> - <p> - 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. - </p> - </section> - <section> - <title>Keeps</title> - <p> - 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. - <br/>TODO REWORK THIS for block vs inline - </p> - <p> - 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. - </p> - <p> - 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. - </p> - <p> - <strong>Figure 1</strong> - </p> - <anchor id="Figure1"/><figure src= - "images/design/alt.design/block-stacking.png" alt= "Simple - block-stacking diagram"/> - <p> - The three basic links are: - </p> - <ul> - <!-- one of (dl sl ul ol li) --> - <li>Leading edge to leading edge of first normal child.</li> - <li>Trailing edge to leading edge of next normal - sibling.</li> - <li>Trailing edge to trailing edge of parent.</li> - </ul> - <p> - 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. - </p> - <p> - 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. - </p> - </section> - </section> - </body> -</document> - diff --git a/src/documentation/content/xdocs/design/alt.design/properties-classes.xml b/src/documentation/content/xdocs/design/alt.design/properties-classes.xml deleted file mode 100644 index 7cb8979b9..000000000 --- a/src/documentation/content/xdocs/design/alt.design/properties-classes.xml +++ /dev/null @@ -1,168 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!-- - Copyright 1999-2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> - -<document> - <header> - <title>Properties classes</title> - <authors> - <person name="Peter B. West" email="pbwest@powerup.com.au"/> - </authors> - </header> - <body> - <section> - <title>The <em>org.apache.fop.fo.properties</em> classes</title> - <section> - <title>Introduction</title> - <p> - In respect of their fields and data structures, the - <property> classes have a <em>virtual</em> - instantiation in the arrays of the <em>singleton</em> <fork - href= "PropertyConsts.html" - ><code>PropertyConsts</code></fork> object, created during - the <fork href= "PropertyConsts.html#pconsts" >static - initialization</fork> of the class. The methods of these - classes are accessed through an array of <em>singelton</em> - instances of the individual <property> classes, which - is maintained in <fork href= - "PropertyConsts.html#properties" >PropertyConsts</fork>. - - - these classes are intended to - remain as repositories of static data and methods. The name - of each property is entered in the - <code>PropNames.propertyNames</code> array of - <code>String</code>s, and each has a unique integer constant - defined, corresponding to the offset of the property name in - that array. - </p> - <section> - <title>Fields common to all classes</title> - <dl> - <dt><code>final int dataTypes</code></dt> - <dd> - 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 <code>Properties</code>, and - may consist of more than one of those constants, - bit-ORed together. - </dd> - <dt><code>final int traitMapping</code></dt> - <dd> - This field defines the mapping of properties to traits - in the <code>Area tree</code>. The value is chosen from the - trait mapping constants defined in <code>Properties</code>, - and may consist of more than one of those constants, - bit-ORed together. - </dd> - <dt><code>final int initialValueType</code></dt> - <dd> - 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 - <code>Properties</code>. - </dd> - <dt><code>final int inherited</code></dt> - <dd> - This field defines the kind of inheritance applicable to - the property. The value is chosen from the inheritance - constants defined in <code>Properties</code>. - </dd> - </dl> - </section> - <section> - <title>Datatype dependent fields</title> - <dl> - <dt>Enumeration types</dt> - <dd> - <strong><code>final String[] enums</code></strong><br/> - This array contains the <code>NCName</code> text - values of the enumeration. In the current - implementation, it always contains a null value at - <code>enum[0]</code>.<br/> <br/> - - <strong><code>final String[] - enumValues</code></strong><br/> When the number of - enumeration values is small, - <code>enumValues</code> is a reference to the - <code>enums</code> array.<br/> <br/> - - <strong><code>final HashMap - enumValues</code></strong><br/> When the number of - enumeration values is larger, - <code>enumValues</code> is a - <code>HashMap</code> statically initialized to - contain the integer constant values corresponding to - each text value, indexed by the text - value.<br/> <br/> - - <strong><code>final int</code></strong> - <em><code>enumeration-constants</code></em><br/> A - unique integer constant is defined for each of the - possible enumeration values.<br/> <br/> - </dd> - <dt>Many types: - <code>final</code> <em>datatype</em> - <code>initialValue</code></dt> - <dd> - When the initial datatype does not have an implicit - initial value (as, for example, does type - <code>AUTO</code>) the initial value for the property is - assigned to this field. The type of this field will - vary according to the <code>initialValueType</code> - field. - </dd> - <dt>AUTO: <code>PropertyValueList auto(property, - list)></code></dt> - <dd> - When <em>AUTO</em> is a legal value type, the - <code>auto()</code> method must be defined in the property - class.<br/> - <em>NOT YET IMPLEMENTED.</em> - </dd> - <dt>COMPLEX: <code>PropertyValueList complex(property, - list)></code></dt> - <dd> - <em>COMPLEX</em> 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 - <code>complex()</code> method must be defined in the - property class. - </dd> - </dl> - </section> - </section> - <section> - <title>Nested property pseudo-classes</title> - <p> - The property pseudo-classes are classes, like - <code>ColorCommon</code> which contain values, particularly - <em>enums</em>, which are common to a number of actual - properties. - </p> - </section> - <p> - <strong>Previous:</strong> <link href= "classes-overview.html" - >property classes overview.</link> - </p> - </section> - </body> -</document> - diff --git a/src/documentation/content/xdocs/design/alt.design/properties/PropertyConsts-class.ehtml b/src/documentation/content/xdocs/design/alt.design/properties/PropertyConsts-class.ehtml deleted file mode 100644 index 3af13c57d..000000000 --- a/src/documentation/content/xdocs/design/alt.design/properties/PropertyConsts-class.ehtml +++ /dev/null @@ -1,103 +0,0 @@ -<?xml version="1.0"?> -<!-- - Copyright 1999-2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<html> - <body marginheight="0" marginwidth="0" topmargin="0" leftmargin="0" - text="#000000" bgcolor="#FFFFFF"> - <script type="text/javascript" src="codedisplay.js" /> - <div class="content"> - <h1>PropertyConsts Description</h1> - <p> - <font size="-2">by Peter B. West</font> - </p> - <ul class="minitoc"> - <li> - <a href="#N10014">Introduction</a> - </li> - </ul> - - <a name="N10014"></a> - <h3>Introduction</h3> - <p> - - <span id = "span00" ></span ><a href="javascript:toggleCode( - 'span00', 'PropertyConsts.html#PropertyConstsClass', '400', - '100%' )">This class</a>, and the singleton object which is - <span id = "span01" ></span ><a href="javascript:toggleCode( - 'span01', 'PropertyConsts.html#pconsts', '400', '100%' - )">generated by the static initializer</a>, is essentially a - repository of <property> class instances and the static - data from those classes of <span - class="codefrag">org.apache.fop.fo.property</span>. The heart - of this class is the method <span id = "span03" ></span ><a - href= "javascript:toggleCode( 'span03', - 'PropertyConsts.html#setupProperty', '400', '100%' )"><span - class="codefrag" >setupProperty</span ></a>. Whenever access - to the data or methods of a property class is required, this - method in the singleton must be called to ensure that an - instance of the property exists and that the static data from - that instance has been extracted. - </p> - - <div class="frame note"> - <div class="label">Note</div> - <div class="content"> - An alternative to this requirement would be to pre-load all - of the individual property classes during the system - initialization phase. This is not done currently because of - the start-up expense of the required class loading for over - three hundred classes, and the relatively low added expense - of checking for the existence of a property instance before - every access. Given that FOP is increasingly used in a - server environment, it may prove acceptable in the long run - to change to pre-loading. - </div> - </div> - - <p> - The class name is generated and stored in the <span id = - "span04" ></span ><a href="javascript:toggleCode( 'span04', - 'PropertyConsts.html#classNames', '400', '100%' )"><span - class="codefrag" >classNames</span ></a> array; a class - instance is generated from the name and stored in the <span id - = "span05" ></span ><a href="javascript:toggleCode( 'span05', - 'PropertyConsts.html#classes', '400', '100%' )"><span - class="codefrag" >classes</span ></a> array; and an instance - of the class is generated from the class object and stored in - the <span id = "span06" ></span ><a - href="javascript:toggleCode( 'span06', - 'PropertyConsts.html#properties', '400', '100%' )"><span - class="codefrag" >properties</span ></a> array. - </p> - - <p> - The other data gathering facilities and access methods of this - class will be examined in conjunction with the various types - of property classes. - </p> - - <p> - <strong>Previous:</strong> <a href = "classes-overview.html" - >Property classes overview</a> - </p> - <p> - <strong>Next:</strong> <a href= "simple-properties.html" - >Simple property classes</a> - </p> - </div> - </body> -</html> diff --git a/src/documentation/content/xdocs/design/alt.design/properties/classes-overview.ehtml b/src/documentation/content/xdocs/design/alt.design/properties/classes-overview.ehtml deleted file mode 100644 index 8a1892f3c..000000000 --- a/src/documentation/content/xdocs/design/alt.design/properties/classes-overview.ehtml +++ /dev/null @@ -1,371 +0,0 @@ -<?xml version="1.0"?> -<!-- - Copyright 1999-2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<html> - <body marginheight= "0" marginwidth= "0" topmargin= "0" leftmargin= "0" text= "#000000" bgcolor= "#FFFFFF" > - <script type="text/javascript" src="codedisplay.js" /> - <div class= "content" > - <h1>Property classes overview</h1> - <p> - <font size= "-2" >by Peter B. West</font> - </p> - <ul class= "minitoc" > - <li> - <a href = "#N10014" >Properties: packages</a> - <ul class= "minitoc" > - <li> - <a href = "#N10019" >org.apache.fop.fo</a> - </li> - <li> - <a href = "#N100AC" >org.apache.fop.fo.properties</a> - </li> - <li> - <a href = "#N100EE" >org.apache.fop.fo.expr</a> - </li> - <li> - <a href = "#N10134" >org.apache.fop.datatypes</a> - </li> - <li> - <a href = "#N101A2" - >org.apache.fop.datatypes.indirect</a> - </li> - </ul> - </li> - </ul> - <a name= "N10014" ></a> <h3>Properties: packages</h3> - <a name= "N10019" ></a> <h4>org.apache.fop.fo</h4> - <!-- N.B. height for toggleCode changed from 50% to 400 because - Mozilla seems to get confused by percentage heights within - table elements. - --> - <dl> - <dt> - <span id="span00" ></span> - <a href = "javascript:toggleCode('span00', - 'PropNames.html#PropNamesClass', '400', '100%' - )" ><em>PropNames</em></a> - </dt> - <dd> - This class maintains an array of <span id="span01" - ></span><a href= "javascript:toggleCode( 'span01', - 'PropNames.html#propertyNames', '400', '100%' )" >property - names</a>, synchronized to a complete set of property name - <span id="span02" ></span><a href = "javascript:toggleCode( - 'span02', 'PropNames.html#NO_PROPERTY', '400', '100%' )" - >constants</a> for indexing property-based arrays. It - includes methods to <span id="span03" ></span><a href = - "javascript:toggleCode( 'span03', - 'PropNames.html#getPropertyName', '400', '100%' )" >convert - an index to a name</a> and to <span id="span04" ></span><a - href = "javascript:toggleCode( 'span04', - 'PropNames.html#getPropertyIndex', '400', '100%' )" >convert - a property name to an index</a>. - </dd> - <dt> - <a href = "PropertyConsts-class.html" ><em>PropertyConsts</em></a> - </dt> - <dd> - A singleton instance of <span class= "codefrag" - >PropertyConsts</span> is created by the static initializer - of the <span id="span05" ></span><a href = - "javascript:toggleCode( 'span05', - 'PropertyConsts.html#pconsts', '400', '100%' )" >pconsts</a> - field. Working from the property indices defined in - PropNames, the methods in this class collect and supply the - values of fields defined in property objects into - arrays.<br/> The heart of this class in the method <span - id="span06" ></span><a href = "javascript:toggleCode( - 'span06', 'PropertyConsts.html#setupProperty', '400', '100%' - )" >setupProperty</a>, which constructs the property name - from the index, instantiates a singleton of the appropriate - class, and extracts static fields by reflection from that - instance into the arrays of field values. - </dd> - <dt> - <span id="span07" ></span><a href = "javascript:toggleCode( - 'span07', 'PropertySets.html#PropertySetsClass', '400', - '100%' )" ><em>PropertySets</em></a> - </dt> - <dd> - This class provides a number of <span class= "codefrag" - >ROBitSet</span>s representing many of the sets of - properties defined in <em>Section 7</em> of the - specification. Note that the <span id="span08" ></span - ><a href= "javascript:toggleCode( 'span08', - 'PropertySets.html#borderProps', '400', '100%' )" - ><em>Border</em></a>, <span id="span09" ></span ><a href= - "javascript:toggleCode( 'span09', - 'PropertySets.html#paddingProps', '400', '100%' )" - ><em>Padding</em></a> and <span id="span10" ></span><a - href= "javascript:toggleCode( 'span10', - 'PropertySets.html#backgroundProps', '400', '100%' - )"><em>Background</em></a> sets are defined separately. - </dd> - <dt> - <span id="span11" ></span><a href = "javascript:toggleCode( - 'span11', '../FOPropertySets.html#FOPropertySetsClass', - '400', '100%' )"><em>FOPropertySets</em></a> - </dt> - <dd> - This class provides a number of <span class= "codefrag" - >ROBitSet</span>s representing sets of properties which are - applicable in particular subtrees of the FO tree. These - sets are provided so that other properties can be ignored - during processing of the subtrees. - </dd> - <dt> - <span id="span12" ></span><a href = "javascript:toggleCode( - 'span12', 'ShorthandPropSets.html#ShorthandPropSetsClass', - '400', '100%' )"><em>ShorthandPropSets</em></a> - </dt> - <dd> - This class contains arrays of <span id="span13" ></span><a - href = "javascript:toggleCode( 'span13', - 'ShorthandPropSets.html#shorthands', '400', '100%' )" - >shorthand property indices</a> and <span id="span14" - ></span><a href = "javascript:toggleCode( 'span14', - 'ShorthandPropSets.html#compounds', '400', '100%' )" - >compound property indices</a>, and <span class= "codefrag" - >ROBitSet</span>s representing the expansion sets of these - shorthands and compounds. Various methods useful in the - expansion of these properties are also included. - </dd> - <dt> - <span id="span15" ></span><a href = "javascript:toggleCode( - 'span15', 'FOAttributes.html#FOAttributesClass', '400', - '100%' )"><em>FOAttributes</em></a> - </dt> - <dd> - This class manages the attribute set that is associated with - a SAX <span class= "codefrag" >startElement</span> event. - <em>fo:</em> namespace attributes are entered into a <span - id = "span16" ></span ><a href = "javascript:toggleCode( - 'span16', 'FOAttributes.html#foAttrMap', '400', '100%' )" - ><span class= "codefrag" >HashMap</span></a>, indexed by the - <em>fo:</em> property index. As other namespaces are - encountered, the values are entered into namespace-specific - <span id="span17" ></span><a href = "javascript:toggleCode( - 'span17', 'FOAttributes.html#nSpaceAttrMaps', '400', '100%' - )"><span class= "codefrag" >HashMap</span>s</a>, indexed by - the <em>local name</em> of the attribute. - </dd> - </dl> - <a name= "N100AC" ></a><a name= "property-classes" ></a> - <h4>org.apache.fop.fo.properties</h4> - <dl> - <dt> - <span id="span18" ></span><a href="javascript:toggleCode( - 'span18', 'Property.html#PropertyClass', '400', '100%' )" - ><em>Property</em></a> - </dt> - <dd> - The base class for all individual property classes. - There are 320 properties in all. - </dd> - <dt> - <em>ColumnNumber</em> - </dt> - <dd> - The actual property class with the lowest index - number, followed in the index order by properties required - for further processing, e.g. FontSize. - </dd> - <dt> - <em>....</em> - </dt> - <dd>....</dd> - <dt> - <em>Background</em> - </dt> - <dd> - First in index order of the remainining shorthand - properties, followed in index order by all other remaining - shorthands. - </dd> - <dt> - <em>....</em> - </dt> - <dd>....</dd> - <dt> - <em>AbsolutePosition</em> - </dt> - <dd> - First in index order of the remaining properties. Within - this ordering, compound properties precede their expansion - properties, and corresponding relative properties precede - corresponding absolute properties. - </dd> - <dt> - <em>....</em> - </dt> - <dd>....</dd> - <dt> - <em>ZIndex</em> - </dt> - <dd> - The property class with the highest index - number. - </dd> - </dl> - <a name= "N100EE" ></a> - <h4>org.apache.fop.fo.expr</h4> - <dl> - <dt> - <span id="span19" ></span><a href = "javascript:toggleCode( - 'span19', 'PropertyTokenizer.html#PropertyTokenizerClass', - '400', '100%' )"><em>PropertyTokenizer</em></a> - </dt> - <dd> - The tokenizer for the property expression parser. Defines a - set of <span id="span20" ></span><a href = - "javascript:toggleCode( 'span20', - 'PropertyTokenizer.html#EOF', '400', '100%' )" >token - constants</a> and returns these with associated token - values. - </dd> - <dt> - <span id="span21" ></span><a href = "javascript:toggleCode( - 'span21', 'PropertyParser.html#PropertyParserClass', '400', - '100%' )"><em>PropertyParser</em></a> - </dt> - <dd> - This extends <span class= "codefrag" - >PropertyTokenizer</span>. It parses property - expressions on the basis of the tokens passed to it by its - superclass, generating <span class= "codefrag" - >PropertyValue</span>s, including <span class= "codefrag" - >PropertyValueList</span>s. - </dd> - <dt> - <em>PropertyException</em> - </dt> - <dd> - The basic class for all property-related exceptions. - It extends <span class= "codefrag" >FOPException</span>. It - is housed in this package by historical accident. - </dd> - <dt> - <em>DataTypeNotImplementedException</em> - <br/> - <em>FunctionNotImplementedException</em> - <br/> - <em>PropertyNotImplementedException</em> - </dt> - <dd> - A set of particular exceptions extending <span class= - "codefrag" >PropertyException</span>. Also in this package - by accident. - </dd> - </dl> - <a name= "N10134" ></a> - <h4>org.apache.fop.datatypes</h4> - <dl> - <dt> - <span id="span22" ></span><a href = "javascript:toggleCode( - 'span22', 'PropertyValue.html#PropertyValueInterface', - '400', '100%' )"><em>PropertyValue</em></a> - </dt> - <dd> - An <em>interface</em> which all <span class= "codefrag" - >PropertyValue</span> classes must implement. In addition - to a few methods, <span class= "codefrag" - >PropertyValue</span> defines the set of <span id="span23" - ></span><a href = "javascript:toggleCode( 'span23', - 'PropertyValue.html#NO_TYPE', '400', '100%' )" - >constants</a> which the <span class= "codefrag" - >getType()</span> method may return; i.e. the valid set of - <span class= "codefrag" >PropertyValue</span> types. - </dd> - <dt> - <span id="span24" ></span><a href = "javascript:toggleCode( - 'span24', - 'AbstractPropertyValue.html#AbstractPropertyValueClass', - '400', '100%' )"><em>AbstractPropertyValue</em></a> - </dt> - <dd> - An abstract implementation of the <span class= "codefrag" - >PropertyValue</span> interface. Most actual property value - classes extend <span class= "codefrag" - >AbstractPropertyValue</span>. - </dd> - <dt> - <span id="span25" ></span><a href = "javascript:toggleCode( - 'span25', 'PropertyValueList.html#PropertyValueListClass', - '400', '100%' )"><em>PropertyValueList</em></a> - </dt> - <dd> - This class extends <span class= "codefrag" - >LinkedList</span> and implements <span class= "codefrag" - >PropertyValue</span>. It is used whenever the process of - resolving a property expression yields a list of <span - class= "codefrag" >PropertyValue</span> elements; notably - during the processing of shorthands and "compound" - properties. - </dd> - <dt> - <em>StringType</em> - </dt> - <dd> - A basic type extending <span class= "codefrag" - >AbstractPropertyValue</span>. Extended by <span class= - "codefrag" >NCName</span>. - </dd> - <dt> - <em>NCName</em> - </dt> - <dd> - Extends <span class= "codefrag" >StringType</span> to represent - NCName strings. - </dd> - <dt> - <em>EnumType</em> - </dt> - <dd> - Extends <span class= "codefrag" - >AbstractPropertyValue</span> to represented enumerated - types. - </dd> - <dt> - <em>Other types</em> - </dt> - <dd> - All other types extend one of the above classes. - </dd> - </dl> - <a name= "N101A2" ></a> - <h4>org.apache.fop.datatypes.indirect</h4> - <dl> - <dt> - <em>IndirectValue</em> - </dt> - <dd> - The base type for all indirect value types; extends - <span class= "codefrag" >AbstractPropertyValue</span>. - </dd> - </dl> - <p> - <strong>Previous:</strong> <a href = "introduction.html" - >Introduction</a> - </p> - <p> - <strong>Next:</strong> <a href= "PropertyConsts-class.html" - >The PropertyConsts class</a> - </p> - </div> - - </body> -</html> diff --git a/src/documentation/content/xdocs/design/alt.design/properties/enumerated-values.ehtml b/src/documentation/content/xdocs/design/alt.design/properties/enumerated-values.ehtml deleted file mode 100644 index c8cf8b50a..000000000 --- a/src/documentation/content/xdocs/design/alt.design/properties/enumerated-values.ehtml +++ /dev/null @@ -1,324 +0,0 @@ -<?xml version="1.0"?> -<!-- - Copyright 1999-2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<html> - <body marginheight="0" marginwidth="0" topmargin="0" leftmargin="0" text="#000000" bgcolor="#FFFFFF"> - <script type="text/javascript" src="codedisplay.js" /> - <div class="content"> - <h1>Enumerated Data Values</h1> - <ul class="minitoc"> - <li> - <a href="#N1000C">Enumerated Data Values</a> - <ul class="minitoc"> - <li> - <a href="#N10020">Array representation</a> - </li> - <li> - <a href="#N1005C">HashMap representation</a> - </li> - <li> - <a href="#N1009D"> - Factoring Out Common Enumeration Values - </a> - </li> - <li> - <a href="#N100DD">Mapped Numeric Values</a> - </li> - </ul> - </li> - </ul> - - <a name="N1000C"></a> - <h3>Enumerated Data Values</h3> - <p> - Property classes which allow enumerated data types must encode - integer constants representing the enumeration tokens, and - must provide a way of translating between the tokens and the - integers, and <em>vice versa</em>. Depending on the number of - tokens in an enumeration set, the mapping from token to - integer is maintained in an array or a <span - class="codefrag">HashMap</span>. The switch-over point from - array to <span class="codefrag">HashMap</span> was determined - by some highly implementation-dependent testing to be in the - region of four to five elements. - </p> - <p> - Many properties share common sets of enumeration tokens, - e.g. those which allow color values, and those applying to - borders and padding. A special case of enumerated value is - the mapped numeric enumeration, in which a token maps to a - Numeric value. These situations are discussed below. - </p> - <a name="N10020"></a> - <h4>Array representation</h4> - <!-- N.B. height for toggleCode changed from 50% to 400 because - Mozilla seems to get confused by percentage heights within - table elements. - --> - <p> - - <span id = "span00" ></span ><a href= "javascript:toggleCode( - 'span00', 'Direction.html#DirectionClass', '400', '100%' )" - ><span - class="codefrag">org.apache.fop.fo.properties.Direction</span></a> - is an example of a class which supports an enumerated value - with a small set of tokens. The <span id = "span01" ></span - ><a href= "javascript:toggleCode( 'span01', - 'Direction.html#dataTypes', '400', '100%' )" ><span - class="codefrag">dataTypes</span></a> field contains the <span - id = "span02" ></span ><a href= "javascript:toggleCode( - 'span02', 'Property.html#NOTYPE', '400', '100%' )" ><span - class="codefrag">ENUM</span> data type constant, defined in - <span class="codefrag">Property</span></a>. The enumeration - integer constants are defined as <span class="codefrag">public - static final int</span> values, <span id = "span03" ></span - ><a href= "javascript:toggleCode( 'span03', - 'Direction.html#LTR', '400', '100%') "><span class="codefrag' - )" >LTR</span> and <span class="codefrag">RTL</span></a>. - Associating enumeration tokens with these integer constants - occurs in the array <a href= - "javascript:window.top.displayCode( 'Direction.html#rwEnums' - )" ><span class="codefrag">String[] rwEnums</span></a>, which - is initialized with the token strings. By convention, zero is - never used to represent a valid enumeration constant, anywhere - in this code. It is, of course, critical that synchronization - between <span class="codefrag">rwEnums</span> and the - enumeration constants be maintained. - </p> - <p> - The publicly accessible mapping from enumeration token to - enumeration constant is achieved through the method <span id = - "span04" ></span ><a href= "javascript:toggleCode( 'span04', - 'Direction.html#getEnumIndex', '400', '100%' )" ><span - class="codefrag">int getEnumIndex(String)</span></a>. The - corresponding mapping from enumeration constant to enumeration - token is achieved through the method <span id = "span05" - ></span ><a href= "javascript:toggleCode( 'span05', - 'Direction.html#getEnumText', '400', '100%' )" ><span - class="codefrag">String getEnumText(int)</span></a>. - </p> - <a name="N1005C"></a> - <h4>HashMap representation</h4> - <p> - - <span id = "span06" ></span ><a href= "javascript:toggleCode( - 'span06', 'RenderingIntent.html#RenderingIntentClass', '400', - '100%' )" ><span class="codefrag" - >org.apache.fop.fo.properties.RenderingIntent</span ></a> is - an example of a class which supports an enumerated value with - a larger set of tokens. The <span id = "span07" ></span ><a - href= "javascript:toggleCode( 'span07', - 'RenderingIntent.html#dataTypes', '400', '100%' )" ><span - class="codefrag">dataTypes</span></a> field contains the <span - id = "span08" ></span ><a href= "javascript:toggleCode( - 'span08', 'Property.html#NOTYPE', '400', '100%' )" ><span - class="codefrag">ENUM</span> data type constant, defined in - <span class="codefrag">Property</span></a>. Enumeration - integer constants are defined as <span id = "span09" ></span - ><a href= "javascript:toggleCode( 'span09', - 'RenderingIntent.html#PERCEPTUAL', '400', '100%' )" ><span - class="codefrag">public static final int</span></a> values. - Zero is never used to represent a valid enumeration constant. - The enumeration tokens are stored in the array <span id = - "span10" ></span ><a href= "javascript:toggleCode( 'span10', - 'RenderingIntent.html#rwEnums', '400', '100%' )" ><span - class="codefrag">String[] rwEnums</span></a>, which is - initialized with the token strings. Association of - enumeration tokens with the integer constants occurs in the - <span class="codefrag">HashMap</span> <span id = "span11" - ></span ><a href= "javascript:toggleCode( 'span11', - 'RenderingIntent.html#rwEnumHash"><span class="codefrag', - '400', '100%' )" > rwEnumHash</span></a>, which is initialized - from the token array in a <span class="codefrag">static - {}</span> initializer. It is, of course, critical that - synchronization between <span class="codefrag">rwEnums</span> - and the enumeration constants be maintained. - </p> - <p> - The publicly accessible mapping from enumeration token to - enumeration constant is achieved through the method <span id = - "span12" ></span ><a href= "javascript:toggleCode( 'span12', - 'RenderingIntent.html#getEnumIndex', '400', '100%' )" ><span - class="codefrag">int getEnumIndex(String)</span></a>. The - corresponding mapping from enumeration constant to enumeration - token is achieved through the method <span id = "span13" - ></span ><a href= "javascript:toggleCode( 'span13', - 'RenderingIntent.html#getEnumText', '400', '100%' )" ><span - class="codefrag">String getEnumText(int)</span></a>. - </p> - <a name="N1009D"></a> - <h4 id="common-enum-values"> - Factoring Out Common Enumeration Values - </h4> - <p> - When a number of properties support a common enumerated value, - that value and its associated access methods may be factored - out to a new class, which each of the properties then extends. - An example of such a common super-class is <span id = "span14" - ></span ><a href= "javascript:toggleCode( 'span14', - 'BorderCommonStyle.html#BorderCommonStyleClass', '400', '100%' - )" ><span class="codefrag">BorderCommonStyle</span></a>. Like - a property with a normal HashMap representation of an - enumerated value, BorderCommonStyle defines <span id = - "span15" ></span ><a href= "javascript:toggleCode( 'span15', - 'BorderCommonStyle.html#HIDDEN', '400', '100%' )" ><span - class="codefrag">public static final int</span></a> - enumeration integer constants. Similarly, the enumeration - tokens are stored in the array <span id = "span16" ></span ><a - href= "javascript:toggleCode( 'span16', - 'BorderCommonStyle.html#rwEnums', '400', '100%' )" ><span - class="codefrag">String[] rwEnums</span></a>, and the - association of enumeration tokens with the integer constants - occurs in the <span class="codefrag">HashMap</span> <span id = - "span17" ></span ><a href= "javascript:toggleCode( 'span17', - 'BorderCommonStyle.html#rwEnumHash', '400', '100%' )" ><span - class="codefrag"> rwEnumHash</span></a>, initialized in a - <span class="codefrag">static {}</span> initializer. The - mapping methods <span id = "span18" ></span ><a href= - "javascript:toggleCode( 'span18', - 'BorderCommonStyle.html#getEnumIndex', '400', '100%' )" ><span - class="codefrag">int getEnumIndex(String)</span></a> and <span - id = "span19" ></span ><a href= "javascript:toggleCode( - 'span19', 'BorderCommonStyle.html#getEnumText', '400', '100%' - )" ><span class="codefrag">String getEnumText(int)</span></a> - are also present. - </p> - <p> - Notice, however, that the class has none of the static data - constants described in the discussion of <a - href="simple-properties.html">simple properties</a>. These - values are defined in the individual sub-classes of this - class, e.g. <span id = "span20" ></span ><a href= - "javascript:toggleCode( 'span20', - 'BorderLeftStyle.html#BorderLeftStyleClass', '400', '100%' )" - ><span class="codefrag">BorderLeftStyle</span></a>. None of - the above fields or methods occur, and <span - class="codefrag">BorderLeftStyle</span> is left looking like - an example of a simple property. The enumeration mapping - methods are, however, available through the super-class <span - class="codefrag">BorderCommonStyle</span>. - </p> - <a name="N100DD"></a> - <h4>Mapped Numeric Values</h4> - <p> - In "normal" enumerated values, the token is, effectively, - passed directly into the layout operation of the flow object - to which the property is applied. Some enumerated values, - however, generate a <span class="codefrag">Numeric</span> - result. Their resolution involves mapping the token to the - indicated <span class="codefrag">Numeric</span> value. - </p> - <p> - An example is the <span id = "span21" ></span ><a href= - "javascript:toggleCode( 'span21', - 'BorderCommonWidth.html#BorderCommonWidthClass', '400', '100%' - )" ><span class="codefrag">BorderCommonWidth</span></a> - property. This, like the example of <a - href="#common-enum-values"><span - class="codefrag">BorderCommonStyle</span></a> above, also - represents common enumerated values which have been factored - out to form a super-class for particular properties. <span - class="codefrag">BorderCommonWidth</span>, therefore, also - defines <span id = "span22" ></span ><a href= - "javascript:toggleCode( 'span22', - 'BorderCommonWidth.html#THIN', '400', '100%' )" ><span - class="codefrag">enumeration constant values</span></a> and an - array of tokens. In this case, there is no <span - class="codefrag">HashMap</span>, because of the limited number - of tokens, but the mapping methods <span id = "span23" ></span - ><a href= "javascript:toggleCode( 'span23', - 'BorderCommonWidth.html#getEnumIndex', '400', '100%' )" ><span - class="codefrag">int getEnumIndex(String)</span></a> and <span - id = "span24" ></span ><a href= "javascript:toggleCode( - 'span24', 'BorderCommonWidth.html#getEnumText', '400', '100%' - )" ><span class="codefrag">String getEnumText(int)</span></a> - are present. - </p> - <p> - The added element in this property is the array <span id = - "span25" ></span ><a href= "javascript:toggleCode( 'span25', - 'BorderCommonWidth.html#mappedPoints', '400', '100%' )" ><span - class="codefrag">double[] mappedPoints</span></a>. The - entries in this array must by maintained in syncronization - with the <span id = "span26" ></span ><a href= - "javascript:toggleCode( 'span26', - 'BorderCommonWidth.html#rwEnums', '400', '100%' )" ><span - class="codefrag">String[] rwEnums</span></a> array of tokens - and the set of <span id = "span27" ></span ><a href= - "javascript:toggleCode( 'span27', - 'BorderCommonWidth.html#THIN', '400', '100%' )" >enumeration - constants</a>. The mapping from token to Numeric value is - achieved by the <span id = "span28" ></span ><a href= - "javascript:toggleCode( 'span28', - 'BorderCommonWidth.html#getMappedLength', '400', '100%' )" - ><span class="codefrag">Numeric getMappedLength(FONode, int, - int)</span></a> method. - </p> - <p> - - <span id = "span29" ></span ><a href= "javascript:toggleCode( - 'span29', 'BorderLeftWidth.html#BorderLeftWidthClass', '400', - '100%' )" ><span class="codefrag">BorderLeftWidth</span></a> - extends <span id = "span30" ></span ><a href= - "javascript:toggleCode( 'span30', 'BorderCommonWidth.html', - '400', '100%' )" ><span - class="codefrag">BorderCommonWidth</span></a>. It includes - the basic static data, like <a - href="simple-properties.html">simple properties</a>, and, in - this case, the <span id = "span31" ></span ><a href= - "javascript:toggleCode( 'span31', - 'BorderLeftWidth.html#getInitialValue', '400', '100%' )" - ><span class="codefrag">PropertyValue - getInitialValue(int)</span></a> method to derive the initial - value. - </p> - <a name="N10139"></a> - <h4>Deriving Mapped Numeric Values</h4> - <p> - As usual with property values, the usual method of deriving a - mapped numeric value is by calling the <span id = "span32" - ></span ><a href= "javascript:toggleCode( 'span32', - '../PropertyConsts.html#getMappedNumeric', '400', '100%' )" - ><span class="codefrag">Numeric getMappedNumeric(FONode, int, - int)</span></a> method in <span id = "span33" ></span ><a - href= "javascript:toggleCode( 'span33', - '../PropertyConsts.html#pconsts', '400', '100%' )" ><span - class="codefrag">pconsts</span></a>. All properties which - support a mapped numeric value must have a <span - class="codefrag">Numeric getMappedNumeric(FONode, int)</span> - method, which will be called through its singleton instance, - stored in the <span id = "span34" ></span ><a href= - "javascript:toggleCode( 'span34', - 'PropertyConsts.html#properties', '400', '100%' )" ><span - class= "codefrag" >properties</span ></a> array, by the <span - class="codefrag">PropertyConsts</span> method. - </p> - - <p> - <strong>Previous:</strong> <a href= "getInitialValue.html" - >getInitialValue()</a> - </p> - <!-- - <p> - <strong>Next:</strong> <a href= "getInitialValue.html" - >getInitialValue()</a> - </p> ---> - - </div> - </body> -</html> diff --git a/src/documentation/content/xdocs/design/alt.design/properties/getInitialValue.ehtml b/src/documentation/content/xdocs/design/alt.design/properties/getInitialValue.ehtml deleted file mode 100644 index f59218bec..000000000 --- a/src/documentation/content/xdocs/design/alt.design/properties/getInitialValue.ehtml +++ /dev/null @@ -1,160 +0,0 @@ -<?xml version="1.0"?> -<!-- - Copyright 1999-2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<html> - <body marginheight="0" marginwidth="0" topmargin="0" leftmargin="0" text="#000000" bgcolor="#FFFFFF"> - <script type="text/javascript" src="codedisplay.js" /> - <div class="content"> - <h1>Generating Initial Values</h1> - <p> - <font size="-2">by Peter B. West</font> - </p> - <ul class="minitoc"> - <li> - <a href="#N10014">Introduction</a> - </li> - <li> - <a href="#N10021"> - Generating and Accessing Initial Values - </a> - <ul class="minitoc"> - <li> - <a href="#N10062">Properties without - getInitialValue()</a> - </li> - </ul> - </li> - </ul> - - <a name="N10014"></a> - <h3>Introduction</h3> - <p> - The <a href="simple-properties.html">previous section</a> - discussed the common data elements in the simplest examples of - property classes. This section discusses more complex classes - whose facilities are accessed only through various methods. - </p> - - <a name="N10021"></a> - <h3> - Generating and Accessing Initial Values - </h3> - <!-- N.B. height for toggleCode changed from 50% to 400 because - Mozilla seems to get confused by percentage heights within - table elements. - --> - <p> - - <span id = "span00" ></span ><a href= "javascript:toggleCode( - 'span00', 'AutoRestore.html', '400', '100%' )" ><span - class="codefrag" - >org.apache.fop.fo.properties.AutoRestore</span></a> is an - example of the next most complex property class. In addition - to all of the common static fields, these classes have initial - data value types which require the dynamic generation of a - PropertyValue instance. - </p> - <p> - The method <span id = "span01" ></span ><a href= - "javascript:toggleCode( 'span01', - 'AutoRestore.html#getInitialValue', '400', '100%' )" ><span - class="codefrag">PropertyValue getInitialValue(int)</span></a> - returns an instance of PropertyValue of the appropriate - subclass containing the initial value for this property. Like - the static data fields, this value is, in turn, stored in the - array of initial values maintained in the <span id = "span02" - ></span ><a href= "javascript:toggleCode( 'span02', - 'PropertyConsts.html#PropertyConstsClass', '400', '100%' )" - ><span class="codefrag">PropertyConsts</span></a> singleton - <span id = "span03" ></span ><a href= "javascript:toggleCode( - 'span03', 'PropertyConsts.html#pconsts', '400', '100%' )" - ><span class="codefrag">pconsts</span></a>.` As with the - fields, the first invocation of the method <span id = "span04" - ></span ><a href= "javascript:toggleCode( 'span04', - 'PropertyConsts.html#setupProperty', '400', '100%' )" ><span - class="codefrag">setupProperty</span></a> on the property - instantiates the singleton instance of the class, and stores - that instance in the in the <span id = "span05" ></span ><a - href= "javascript:toggleCode( 'span05', - 'PropertyConsts.html#properties', '400', '100%' )" ><span - class="codefrag">Property[] properties</span></a> array of - <span id = "span06" ></span ><a href= "javascript:toggleCode( - 'span06', 'PropertyConsts.html#pconsts', '400', '100%' )" - ><span class="codefrag">pconsts</span></a>. - </p> - <p> - Unlike the static data fields, however, the initial value is - not immediately generated. It is generated by a call to <span - id = "span07" ></span ><a href= "javascript:toggleCode( - 'span07', 'PropertyConsts.html#getInitialValue', '400', '100%' - )" ><span class="codefrag">PropertyValue - getInitialValue(int)</span></a> in <span id = "span08" ></span - ><a href= "javascript:toggleCode( 'span08', - 'PropertyConsts.html#pconsts', '400', '100%' )" ><span - class="codefrag">pconsts</span></a>. This call, in turn, - locates the relevant instance of the particular property class - in the <span id = "span09" ></span ><a href= - "javascript:toggleCode( 'span09', - 'PropertyConsts.html#properties', '400', '100%' )" ><span - class= "codefrag" >properties</span> array of <span class= - "codefrag" >PropertyConsts</span></a>, and invokes the <span - class= "codefrag" >getInitialValue()</span> of that instance. - A side-effect of this call is to store the initial value in - <span id = "span10" ></span ><a href= "javascript:toggleCode( - 'span10', 'PropertyConsts.html#initialValues', '400', '100%' - )" ><span class="codefrag">PropertyValue[] - initialValues</span></a>. - </p> - <a name="N10062"></a> - <h4>Properties without - getInitialValue()</h4> - <p> - What about property classes which have no <span - class="codefrag">getInitialValue()</span> method? The - simplest classes, e.g. <span - class="codefrag">Character</span>, fall into this category. - As <a href="classes-overview.html#property-classes">noted - previously</a>, all of the property classes extend <span - class="codefrag">org.apache.fop.fo.properties.Property</span>. - <span id = "span11" ></span ><a href= "javascript:toggleCode( - 'span11', 'Property.html#PropertyClass', '400', '100%' )" - ><span class="codefrag">Property</span></a> provides a base - <span id = "span12" ></span ><a href= "javascript:toggleCode( - 'span12', 'Property.html#getInitialValue', '400', '100%' )" - ><span class="codefrag">PropertyValue - getInitialValue(int)</span></a> method to which the simple - classes fall back. Note that it is only valid for <span - class="codefrag">NOTYPE_IT</span>, <span - class="codefrag">AUTO_IT</span>, <span - class="codefrag">NONE_IT</span> and <span - class="codefrag">AURAL_IT</span> initial value types, so all - classes which have any other initial value type must override - this method. - </p> - - <p> - <strong>Previous:</strong> <a href = "simple-properties.html" - >Simple property classes</a> - </p> - <p> - <strong>Next:</strong> <a href= "enumerated-values.html" - >Enumerated values</a> - </p> - - </div> - </body> -</html> diff --git a/src/documentation/content/xdocs/design/alt.design/properties/introduction.xml b/src/documentation/content/xdocs/design/alt.design/properties/introduction.xml deleted file mode 100644 index 0d45933fa..000000000 --- a/src/documentation/content/xdocs/design/alt.design/properties/introduction.xml +++ /dev/null @@ -1,169 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!-- - Copyright 1999-2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> - -<document> - <header> - <title>Implementing Properties</title> - <authors> - <person id="pbw" name="Peter B. West" email="pbwest@powerup.com.au"/> - </authors> - </header> - <body> - <section> - <title>An alternative properties implementation</title> - <note> - 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. - </note> - <p> - Property handling is complex and expensive. Varying numbers of - properties <strong>apply</strong> to individual Flow Objects - <strong>(FOs)</strong> in the <strong>FO tree </strong> 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. - </p> - <note> - <em>(XSL 1.0 Rec)</em> <strong>5.1.4 Inheritance</strong> - ...The inheritable properties can be placed on any formatting - object. - </note> - <p> - Even if the value is not inheritable, it may be accessed by - its children through the <code>inherit</code> keyword or the - <code>from-parent()</code> core function, and potentially by - any of its descendents through the - <code>from-nearest-specified-value()</code> core function. - </p> - <p> - In addition to the assigned values of properties, almost every - property has an <strong>initial value</strong> which is used - when no value has been assigned. - </p> - <section> - <title>The history problem</title> - <p> - The difficulty and expense of handling properties comes from - this univeral inheritance possibility. The list of properties - which are assigned values on any particular <em>FO</em> - element will not generally be large, but a current value is - required for each property which applies to the <em>FO</em> - being processed. - </p> - <p> - The environment from which these values may be selected - includes, for each <em>FO</em>, <strong>for each applicable - property</strong>, the value assigned on this <em>FO</em>, - the value which applied to the parent of this <em>FO</em>, - the nearest value specified on an ancestor of this element, - and the initial value of the property. - </p> - </section> - <section> - <title>The construction hierarchy</title> - <p> - Properties are resoved in the <strong>FO tree</strong> in a - strictly hierarchical manner. Nodes are detected in the - input in a <strong>pre-order</strong> traversal, and are - built in the same order. This imples that there are two - phases, or states, of property resolution and construction. - Any particular FO node is either in a state of constructing - its own subtree, or in a stable state where the subtree - construction is complete. These states have differenct data - requirements. - </p> - <dl> - <dt>Subtree building</dt> - <dd> - In this state, all properties defined on this node, or any - of its ancestors must be available to the subtree. In - effect, any property defined on this node must be - available to its descendants, as all properties defined on - any ancestor are available to this node. - </dd> - <dt>Stable: subtree building complete</dt> - <dd> - In this state, only the properties <strong>applicable to - this node</strong> need be available. - </dd> - </dl> - </section> - <section> - <title>Representing properties: <property> classes</title> - <section> - <title>Class vs instance</title> - <p> - What information is required of property objects? - More particularly, what information is particular to the - property classes, and what to the instantiated - objects? The answer to this question depend largely on - how the property objects are used in the context - of layout and Area tree construction. The approach taken - in this implementation is that properties are simply flags - on certain data values associated with FOs. The semantics - of these flags are determined within the layout engine. - </p> - <p> - Certain constant information attaches to individual - property classes. This information is detailed in - the descriptions of individual properties in <em>Section - 7</em> of the specification. Such information is - represented in <strong>class</strong> fields and data - structures within the classes. - </p> - <p> - The "instance" information content of a property - is: - </p> - <ul> - <li> - explicitly, the <code>PropertyValue</code> datum of - the property, and - </li> - <li> - implicitly, the <strong>Flow Object</strong> to which - the property is attached. - </li> - </ul> - <p> - Properties, then, serve essentially to link <em>FO - instances</em> with <em>PropertyValue instances</em>, - attaching certain invariant semantic markers to the - PropertyValues in the process. In this implementation, - these functions can be realised entirely within the - property <strong>classes</strong> themselves, - without the need to instantiate any objects. In practice, - <strong>property singletons</strong> are - instantiated to make access to some invariants simpler. - </p> - </section> - </section> - <p> - <strong>Next:</strong> <link href="classes-overview.html" - >property classes overview.</link> - </p> - </section> - </body> -</document> - diff --git a/src/documentation/content/xdocs/design/alt.design/properties/propertyExpressions.ehtml b/src/documentation/content/xdocs/design/alt.design/properties/propertyExpressions.ehtml deleted file mode 100644 index 83e18e026..000000000 --- a/src/documentation/content/xdocs/design/alt.design/properties/propertyExpressions.ehtml +++ /dev/null @@ -1,457 +0,0 @@ -<?xml version="1.0"?> -<!-- - Copyright 1999-2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<html> - <head> - <META http-equiv="Content-Type" content="text/html; - charset=ISO-8859-1" /> - <title>Property Expression Parsing</title> - </head> - <body marginheight="0" marginwidth="0" topmargin="0" leftmargin="0" text="#000000" bgcolor="#FFFFFF"> - <script type="text/javascript" src="codedisplay.js" /> - <div class="content"> - <h1>Property Expression Parsing</h1> - <p> - <font size="-2">by Peter B. West</font> - </p> - <ul class="minitoc"> - <li> - <a href="#N10014">Property expression parsing</a> - <ul class="minitoc"> - <li> - <a href="#N10044">Data types</a> - </li> - <li> - <a href="#N10252">Tokenizer</a> - </li> - <li> - <a href="#N1029C">Parser</a> - </li> - </ul> - </li> - </ul> - - <a name="N10014"></a> - <h3>Property expression parsing</h3> - <!-- N.B. height for toggleCode changed from 50% to 400 because - Mozilla seems to get confused by percentage heights within - table elements. - --> - <p> - The parsing of property value expressions is handled by two - closely related classes: <span id = "span00" ></span ><a href= - "javascript:toggleCode( 'span00', - 'PropertyTokenizer.html#PropertyTokenizerClass', '400', '100%' - )" ><span class= "codefrag" - >org.apache.fop.fo.expr.PropertyTokenizer</span></a> and its - subclass, <span id = "span01" ></span ><a href= - "javascript:toggleCode( 'span01', - 'PropertyParser.html#PropertyParserClass', '400', '100%' )" - ><span class= "codefrag" - >org.apache.fop.fo.expr.PropertyParser</span></a>, and by - <span class= "codefrag" >refineParsing(int, FONode, - PropertyValue)</span> methods in the individual property - classes. <span class= "codefrag" >PropertyTokenizer</span>, - as the name suggests, handles the tokenizing of the - expression, handing <span id = "span02" ></span ><a href= - "javascript:toggleCode( 'span02', - 'PropertyTokenizer.html#EOF', '400', '100%' )" - ><em>tokens</em></a> back to its subclass, <span class= - "codefrag" >PropertyParser</span>. <span class= "codefrag" - >PropertyParser</span>, in turn, returns a <span id = "span03" - ></span ><a href= "javascript:toggleCode( 'span03', - 'PropertyValueList.html#PropertyValueListClass', '400', '100%' - )" ><span class= "codefrag">PropertyValueList</span></a>, a - list of <span id = "span04" ></span ><a href= - "javascript:toggleCode( 'span04', - 'PropertyValue.html#PropertyValueInterface', '400', '100%' )" - ><span class= "codefrag">PropertyValue</span></a>s. - </p> - <p> - The tokenizer and parser rely in turn on the datatype - definitions from the <span class= "codefrag" - >org.apache.fop.datatypes</span> package, which include the - <span id = "span05" ></span ><a href= "javascript:toggleCode( - 'span05', 'PropertyValue.html#NO_TYPE', '400', '100%' )" - ><span class= "codefrag" >PropertyValue</span> datatype - constant definitions</a>. - </p> - <a name="N10044"></a> - <h4>Data types</h4> - <p> - The data types currently defined in - <span class= "codefrag" >org.apache.fop.datatypes</span> include: - </p> - <table class="ForrestTable" cellspacing="1" cellpadding="4"> - - <tr> - <th colspan="2" rowspan="1">Numbers and lengths</th> - </tr> - - <tr> - <th colspan="1" rowspan="1">Numeric</th> - <td colspan="3" rowspan="1"> - The fundamental length data type. <em>Numerics</em> of - various types are constructed by the classes listed - below. - </td> - </tr> - - <tr> - <td colspan="1" rowspan="1"></td> - <th colspan="3" - rowspan="1">Constructor classes for <em>Numeric</em></th> - </tr> - - <tr> - <td colspan="1" rowspan="1"></td> - <td colspan="1" rowspan="1">Ems</td> - <td colspan="2" rowspan="1">Relative length in <em>ems</em></td> - </tr> - - <tr> - <td colspan="1" rowspan="1"></td> - <td colspan="1" rowspan="1">IntegerType</td> - <td colspan="1" rowspan="1"></td> - </tr> - - <tr> - <td colspan="1" rowspan="1"></td> - <td colspan="1" rowspan="1">Length</td> - <td colspan="2" rowspan="1">In centimetres(cm), millimetres(mm), - inches(in), points(pt), picas(pc) or pixels(px)</td> - </tr> - - <tr> - <td colspan="1" rowspan="1"></td> - <td colspan="1" rowspan="1">Percentage</td> - <td colspan="1" rowspan="1"></td> - </tr> - - <tr> - <th colspan="1" rowspan="1">Other Numeric</th> - <td colspan="3" rowspan="1"> - Other numeric vaues which do not interact with the - lengths represented by <em>Numeric</em> values. - </td> - </tr> - - <tr> - <td colspan="1" rowspan="1"></td> - <td colspan="1" rowspan="1">Angle</td> - <td colspan="2" rowspan="1">In degrees(deg), gradients(grad) or - radians(rad)</td> - </tr> - - <tr> - <td colspan="1" rowspan="1"></td> - <td colspan="1" rowspan="1">Frequency</td> - <td colspan="2" rowspan="1">In hertz(Hz) or kilohertz(kHz)</td> - </tr> - - <tr> - <td colspan="1" rowspan="1"></td> - <td colspan="1" rowspan="1">Time</td> - <td colspan="1" rowspan="1">In seconds(s) or milliseconds(ms)</td> - </tr> - - <tr> - <th colspan="2" rowspan="1">Strings</th> - </tr> - - <tr> - <th colspan="1" rowspan="1">StringType</th> - <td colspan="3" rowspan="1"> - Base class for data types which result in a <em>String</em>. - </td> - </tr> - - <tr> - <td colspan="1" rowspan="1"></td> - <th colspan="1" rowspan="1">Literal</th> - <td colspan="2" rowspan="1"> - A subclass of <em>StringType</em> for literals which - exceed the constraints of an <em>NCName</em>. - </td> - </tr> - - <tr> - <td colspan="1" rowspan="1"></td> - <th colspan="1" rowspan="1">MimeType</th> - <td colspan="2" rowspan="1"> - A subclass of <em>StringType</em> for literals which - represent a mime type. - </td> - </tr> - - <tr> - <td colspan="1" rowspan="1"></td> - <th colspan="1" rowspan="1">UriType</th> - <td colspan="2" rowspan="1"> - A subclass of <em>StringType</em> for literals which - represent a URI, as specified by the argument to - <em>url()</em>. - </td> - </tr> - - <tr> - <td colspan="1" rowspan="1"></td> - <th colspan="1" rowspan="1">NCName</th> - <td colspan="2" rowspan="1"> - A subclass of <em>StringType</em> for literals which - meet the constraints of an <em>NCName</em>. - </td> - </tr> - - <tr> - <td colspan="1" rowspan="1"></td> - <td colspan="1" rowspan="1"></td> - <th colspan="1" rowspan="1">Country</th> - <td colspan="1" rowspan="1">An RFC 3066/ISO 3166 country code.</td> - </tr> - - <tr> - <td colspan="1" rowspan="1"></td> - <td colspan="1" rowspan="1"></td> - <th colspan="1" rowspan="1">Language</th> - <td colspan="1" rowspan="1">An RFC 3066/ISO 639 language code.</td> - </tr> - - <tr> - <td colspan="1" rowspan="1"></td> - <td colspan="1" rowspan="1"></td> - <th colspan="1" rowspan="1">Script</th> - <td colspan="1" rowspan="1">An ISO 15924 script code.</td> - </tr> - - <tr> - <th colspan="2" rowspan="1">Enumerated types</th> - </tr> - - <tr> - <th colspan="1" rowspan="1">EnumType</th> - <td colspan="3" rowspan="1"> - An integer representing one of the tokens in a set of - enumeration values. - </td> - </tr> - - <tr> - <td colspan="1" rowspan="1"></td> - <th colspan="1" rowspan="1">MappedNumeric</th> - <td colspan="2" rowspan="1"> - A subclass of <em>EnumType</em>. Maintains a - <em>Numeric</em> with the value to which the associated - "raw" enumeration token maps. E.g., the - <em>font-size</em> enumeration value "medium" maps to - the <em>Numeric</em> "12pt". - </td> - </tr> - - <tr> - <th colspan="2" rowspan="1">Colors</th> - </tr> - - <tr> - <th colspan="1" rowspan="1">ColorType</th> - <td colspan="3" rowspan="1"> - Maintains a four-element array of float, derived from - the name of a standard colour, the name returned by a - call to <em>system-color()</em>, or an RGB - specification. - </td> - </tr> - - <tr> - <th colspan="2" rowspan="1">Fonts</th> - </tr> - - <tr> - <th colspan="1" rowspan="1">FontFamilySet</th> - <td colspan="3" rowspan="1"> - Maintains an array of <em>String</em>s containing a - prioritized list of possibly generic font family names. - </td> - </tr> - - <tr> - <th colspan="2" rowspan="1">Pseudo-types</th> - </tr> - - <tr> - <td colspan="4" rowspan="1"> - A variety of pseudo-types have been defined as - convenience types for frequently appearing enumeration - token values, or for other special purposes. - </td> - </tr> - - <tr> - <th colspan="1" rowspan="1">Inherit</th> - <td colspan="3" rowspan="1"> - For values of <em>inherit</em>. - </td> - </tr> - - <tr> - <th colspan="1" rowspan="1">Auto</th> - <td colspan="3" rowspan="1"> - For values of <em>auto</em>. - </td> - </tr> - - <tr> - <th colspan="1" rowspan="1">None</th> - <td colspan="3" rowspan="1"> - For values of <em>none</em>. - </td> - </tr> - - <tr> - <th colspan="1" rowspan="1">Bool</th> - <td colspan="3" rowspan="1"> - For values of <em>true/false</em>. - </td> - </tr> - - <tr> - <th colspan="1" rowspan="1">FromNearestSpecified</th> - <td colspan="3" rowspan="1"> - Created to ensure that, when associated with - a shorthand, the <em>from-nearest-specified-value()</em> - core function is the sole component of the expression. - </td> - </tr> - - <tr> - <th colspan="1" rowspan="1">FromParent</th> - <td colspan="3" rowspan="1"> - Created to ensure that, when associated with - a shorthand, the <em>from-parent()</em> - core function is the sole component of the expression. - </td> - </tr> - - </table> - <a name="N10252"></a> - <h4>Tokenizer</h4> - <p> - As mentioned above, the <span class= "codefrag" - >PropertyTokenizer</span> hands <span id = "span06" ></span - ><a href= "javascript:toggleCode( 'span06', - 'PropertyTokenizer.html#EOF', '400', '100%' )" - ><em>tokens</em></a> back to its subclass, <span class= - "codefrag" >PropertyParser</span>. Most of these tokens are - self-explanatory, but a few need further comment. - </p> - <dl> - - <dt>AUTO</dt> - - <dd> - Because of its frequency of occurrence, and the fact that it - is always the <em>initial value</em> 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. - </dd> - - <dt>NONE</dt> - - <dd> - Similarly to AUTO, NONE has been promoted to a pseudo-type - because of its frequency. - </dd> - - <dt>BOOL</dt> - - <dd> - There is a <em>de facto</em> 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. - </dd> - - <dt>MIMETYPE</dt> - - <dd> - The property <span class= "codefrag" >content-type</span> - introduces this complication. It can have two values of the - form <strong>content-type:</strong><em>mime-type</em> - (e.g. <span class= "codefrag" - >content-type="content-type:xml/svg"</span>) or - <strong>namespace-prefix:</strong><em>prefix</em> - (e.g. <span class= "codefrag" - >content-type="namespace-prefix:svg"</span>). The - experimental code reduces these options to the payload in - each case: an <span class= "codefrag" >NCName</span> in the - case of a namespace prefix, and a MIMETYPE in the case of a - content-type specification. <span class= "codefrag" - >NCName</span>s cannot contain a "/". - </dd> - - </dl> - <a name="N1029C"></a> - <h4>Parser</h4> - <p> - The parser returns a <span id = "span07" ></span ><a href= - "javascript:toggleCode( 'span07', - 'PropertyValueList.html#PropertyValueListClass', '400', '100%' - )" ><span class= "codefrag" >PropertyValueList</span ></a>, - necessary because of the possibility that a list of <span id = - "span08" ></span ><a href= "javascript:toggleCode( 'span08', - 'PropertyValue.html#PropertyValueInterface', '400', '100%' )" - ><span class= "codefrag" >PropertyValue</span ></a> elements - may be returned from the expressions of some properties. - </p> - <p> - - <span class= "codefrag" >PropertyValueList</span>s may contain - <span class= "codefrag" >PropertyValue</span>s or other <span - class= "codefrag" >PropertyValueList</span>s. This latter - provision is necessitated by some of the more peculiar - expression possibilities, <em>e.g.</em> <em>font</em> and - <em>text-shadow</em>. <em>text-shadow</em> 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. - </p> - <p> - Other special cases include the processing of the core - functions <span class= "codefrag" >from-parent()</span> and - <span class= "codefrag" >from-nearest-specified-value()</span> - 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 <span - class= "codefrag" >FromParent</span> and <span - class= "codefrag" >FromNearestSpecified</span> 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.) - </p> - <p> - The experimental code is a simple extension of the existing - parser code, which itself borrowed heavily from James - Clark's XT processor. - </p> - - </div> - </body> -</html> diff --git a/src/documentation/content/xdocs/design/alt.design/properties/simple-properties.ehtml b/src/documentation/content/xdocs/design/alt.design/properties/simple-properties.ehtml deleted file mode 100644 index 73447d648..000000000 --- a/src/documentation/content/xdocs/design/alt.design/properties/simple-properties.ehtml +++ /dev/null @@ -1,260 +0,0 @@ -<?xml version="1.0"?> -<!-- - Copyright 1999-2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<html> - <body marginheight="0" marginwidth="0" topmargin="0" leftmargin="0" text="#000000" bgcolor="#FFFFFF"> - <script type="text/javascript" src="codedisplay.js" /> - <div class="content"> - <h1>Simple property Classes</h1> - <p> - <font size="-2">by Peter B. West</font> - </p> - <ul class="minitoc"> - <li> - <a href="#N10014">Introduction</a> - </li> - <li> - <a href="#N10026">Common data</a> - </li> - <li> - <a href="#N10075">Accessing property Data Constants</a> - </li> - </ul> - - <a name="N10014"></a> - <h3>Introduction</h3> - <!-- N.B. height for toggleCode changed from 50% to 400 because - Mozilla seems to get confused by percentage heights within - table elements. - --> - <p> - An <a href="classes-overview.html">overview of the properties - and classes</a> involved in handling properties has already - been given. This discussion will go in detail into the way - data are represented within properties. Iit is important to - keep in mind that the primary avenue of access to the data and - the methods of property classes is the <span id = "span00" - ></span ><a href= "javascript:toggleCode( 'span00', - 'PropertyConsts.html#PropertyConstsClass', '400', '100%' )" - ><span class="codefrag">PropertyConsts</span></a> class and - its singleton object. - </p> - - <a name="N10026"></a> - <h3>Common data</h3> - <p> - - <span id = "span01" ></span ><a href= "javascript:toggleCode( - 'span01', 'Character.html', '400', '100%' )" ><span - class="codefrag">org.apache.fop.fo.properties.Character</span></a> - is an example of a basic property class. The data fields - common to all properties are: - </p> - <dl> - - <dt> - - <span class="codefrag">final int dataTypes</span> - - </dt> - - <dd> - 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 <span id = "span02" ></span ><a - href= "javascript:toggleCode( 'span02', - 'Property.html#NOTYPE', '400', '100%' )" ><span - class="codefrag">org.apache.fop.fo.properties.Property</span></a>, - and may consist of more than one of those constants, - bit-ORed together. - </dd> - - <dt> - - <span class="codefrag">final int traitMapping</span> - - </dt> - - <dd> - This field defines the mapping of properties to traits in - the <span class="codefrag">Area tree</span>. The value is - chosen from the trait mapping constants defined in <span id - = "span03" ></span ><a href= "javascript:toggleCode( - 'span03', 'Property.html#NO_TRAIT', '400', '100%' )" ><span - class="codefrag">org.apache.fop.fo.properties.Property</span></a>, - and may consist of more than one of those constants, - bit-ORed together. - </dd> - - <dt> - - <span class="codefrag">final int initialValueType</span> - - </dt> - - <dd> - 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 <span id = "span04" - ></span ><a href= "javascript:toggleCode( 'span04', - 'Property.html#NOTYPE_IT', '400', '100%' )" ><span - class="codefrag">org.apache.fop.fo.properties.Property</span></a>. - In the simplest property classes, such as <span - class="codefrag">Character</span>, there is no defined - initial value type. - </dd> - - <dt> - - <span class="codefrag">final int inherited</span> - - </dt> - - <dd> - This field defines the kind of inheritance applicable to the - property. The value is chosen from the inheritance - constants defined in <span id = "span05" ></span ><a href= - "javascript:toggleCode( 'span05', 'Property.html#NO', '400', - '100%' )" ><span - class="codefrag">org.apache.fop.fo.properties.Property</span></a>. - </dd> - - </dl> - - <a name="N10075"></a> - <h3>Accessing property Data Constants</h3> - <p> - The constants above are generally accessed through the arrays - maintained in the <span id = "span06" ></span ><a href= - "javascript:toggleCode( 'span06', - 'PropertyConsts.html#PropertyConstsClass', '400', '100%' )" - ><span class="codefrag">PropertyConsts</span></a> singleton - <span id = "span07" ></span ><a href= "javascript:toggleCode( - 'span07', 'PropertyConsts.html#pconsts', '400', '100%' )" - ><span class="codefrag">pconsts</span></a>. The first - invocation of the method <span id = "span08" ></span ><a href= - "javascript:toggleCode( 'span08', - 'PropertyConsts.html#setupProperty', '400', '100%' )" ><span - class="codefrag">setupProperty</span></a> on the property - generates a <span class="codefrag">Class</span> instance for - the class, and stores it in the array <span id = "span09" - ></span ><a href= "javascript:toggleCode( 'span09', - 'PropertyConsts.html#classes', '400', '100%' )" ><span - class="codefrag">classes</span></a>. This <span - class="codefrag">Class</span> object is used, in turn, to - instantiate the singleton instance of the class, which is - stored in the <span id = "span10" ></span ><a href= - "javascript:toggleCode( 'span10', - 'PropertyConsts.html#properties', '400', '100%' )" ><span - class="codefrag">Property[] properties</span></a> array of - <span id = "span11" ></span ><a href= "javascript:toggleCode( - 'span11', '../PropertyConsts.html#pconsts', '400', '100%' )" - ><span class="codefrag">pconsts</span></a>. - </p> - <p> - - <em>Reflection</em> methods are then used, via the same <span - class="codefrag">Class</span> instance, to extract and store - the static data fields. These arrays and associated access - methods are: - </p> - <dl> - - <dt> - - <span id = "span12" ></span ><a href= - "javascript:toggleCode( 'span12', - 'PropertyConsts.html#datatypes', '400', '100%' )" ><span - class="codefrag">int[] datatypes</span></a> - - </dt> - - <dd> - - <span id = "span13" ></span ><a href= - "javascript:toggleCode( 'span13', - 'PropertyConsts.html#getDataTypes', '400', '100%' )" ><span - class="codefrag">int getDataTypes(int)</span></a> - - </dd> - - <dt> - - <span id = "span14" ></span ><a href= - "javascript:toggleCode( 'span14', - 'PropertyConsts.html#traitMappings', '400', '100%' )" ><span - class="codefrag">int[] traitMappings</span></a> - - </dt> - - <dd> - - <em>No access method yet defined.</em> - - </dd> - - <dt> - - <span id = "span15" ></span ><a href= - "javascript:toggleCode( 'span15', - 'PropertyConsts.html#initialValueTypes', '400', '100%' )" - ><span class="codefrag">int[] initialValueTypes</span></a> - - </dt> - - <dd> - - <span id = "span16" ></span ><a href= - "javascript:toggleCode( 'span16', - 'PropertyConsts.html#getInitialValueType', '400', '100%' )" - ><span class="codefrag">int - getInitialValueType(int)</span></a> - - </dd> - - <dt> - - <span id = "span17" ></span ><a href= - "javascript:toggleCode( 'span17', - 'PropertyConsts.html#inherited', '400', '100%' )" ><span - class="codefrag">int[] inherited</span></a> - - </dt> - - <dd> - - <span id = "span18" ></span ><a href= - "javascript:toggleCode( 'span18', - 'PropertyConsts.html#inheritance', '400', '100%' )" ><span - class="codefrag">int inheritance(int)</span></a> - - </dd> - - </dl> - - <p> - <strong>Previous:</strong> <a href = "PropertyConsts-class.html" - >PropertyConsts class</a> - </p> - <p> - <strong>Next:</strong> <a href= "getInitialValue.html" - >getInitialValue()</a> - </p> - - </div> - </body> -</html> diff --git a/src/documentation/content/xdocs/design/alt.design/spaces.xml b/src/documentation/content/xdocs/design/alt.design/spaces.xml deleted file mode 100644 index 74a68b59f..000000000 --- a/src/documentation/content/xdocs/design/alt.design/spaces.xml +++ /dev/null @@ -1,195 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!-- - Copyright 1999-2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> - -<document> - <header> - <title>Keeps and space-specifiers</title> - <authors> - <person name="Peter B. West" email="pbwest@powerup.com.au"/> - </authors> - </header> - <body> - <section> - <title>Keeps and space-specifiers in layout galleys</title> - <p> - The <link href= "galleys.html" >layout galleys</link> and the - <link href= "galleys.html#layout-tree" >layout tree</link> - which is the context of this discussion have been discussed - elsewhere. A <link href="keeps.html">previous document</link> - 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. - </p> - <section> - <title>Space-specifiers</title> - <note> - <strong>4.3 Spaces and Conditionality</strong> - ... 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. - </note> - <note> - 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. - </note> - <p> - 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 <em>stacking - constraints</em> as <em><space>s interaction</em> or - <em><space>s stacking interaction</em>. - </p> - </section> - <section> - <title>Block stacking constraints</title> - <p> - In the discussion of block stacking constraints in Section - 4.2.5, the notion of <em>fence</em> 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 - <link href="#Figure1">Figure 1</link>.) - </p> - <p><strong>Figure 1</strong></p><anchor id="Figure1"/> <figure - src= "images/design/alt.design/block-stacking-constraints.png" - alt= "block-stacking-constraints.png"/> - <note> - Figure 1 assumes a block-progression-direction of top to - bottom. - </note> - <p> - In <link href="#Figure1">Diagram a)</link>, 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. - </p> - <p> - In <link href="#Figure1">Diagram b)</link>, 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 <em>fence-before</em> P. The fence is notional; it has - no precise location, as the diagram may lead one to believe. - </p> - <p> - In <link href="#Figure1">Diagram c)</link>, 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. - </p> - <p> - The other form of fence occurs when the parent block is a - reference area. Diagram b) of <link href="#Figure2">Figure - 2</link> 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. - </p> - <p> - 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. - </p> - <p> - In the case of <link href="#Figure2">Diagram b)</link>, - 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 <link href="#Figure2">Diagram b)</link> makes - visually obvious, it is difficult to imagine which blocks - would have such a constraint, and what the ordering of the - constraint would be. - </p> - <p><strong>Figure 2</strong></p> - <anchor id="Figure2"/> - <figure src= "images/design/alt.design/block-stacking-keeps.png" - alt= "block-stacking-keeps.png"/> - </section> - <section> - <title>Keep relationships between blocks</title> - <p> - As complicated as space-specifiers become when - reference-areas are involved, the keep relationships as - described in the <link - href="keeps.html#Figure1">keeps</link> document, are - unchanged. This is also illustrated in <link - href="#Figure2">Figure 2</link>. 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. - </p> - <p> - 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. - </p> - <p> - 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 <em>prima facie</em>, the essential - logic of the keeps links remains. - </p> - </section> - </section> - </body> -</document> - diff --git a/src/documentation/content/xdocs/design/alt.design/traits.xml b/src/documentation/content/xdocs/design/alt.design/traits.xml deleted file mode 100644 index 1598b6e8e..000000000 --- a/src/documentation/content/xdocs/design/alt.design/traits.xml +++ /dev/null @@ -1,385 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!-- - Copyright 1999-2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> - -<document> - <header> - <title>Traits</title> - <authors> - <person name="Peter B. West" email="pbwest@powerup.com.au"/> - </authors> - </header> - <body> - <section> - <title>Traits</title> - <table> - <tr> - <th>Trait</th> - <th>Applies to</th> - <th>Refs</th> - <th>Derived from</th> - </tr> - <tr> - <th>Common Traits</th> - </tr> - <tr> - <td>block-progression-direction</td> - <td>All areas</td> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice4.html#area-common" - >4.2.2 Common Traits</link><br/> - <link href= - "http://www.w3.org/TR/xsl/slice7.html#writing-mode" - >7.27.7 writing-mode</link> - </td> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice7.html#reference-orientation" - >7.27.7 reference-orientation</link> - </td> - </tr> - <tr> - <td>inline-progression-direction</td> - <td>All areas</td> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice4.html#area-common" - >4.2.2 Common Traits</link><br/> - <link href= - "http://www.w3.org/TR/xsl/slice7.html#writing-mode" - >7.27.7 writing-mode</link> - </td> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice7.html#reference-orientation" - >7.27.7 reference-orientation</link> - </td> - </tr> - <tr> - <td>shift-direction</td> - <td>Inline areas</td> - </tr> - <tr> - <td>glyph-orientation</td> - <td>Glyph-areas</td> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice4.html#area-common" - >4.2.2 Common Traits</link><br/> - <link href= - "http://www.w3.org/TR/xsl/slice4.html#area-glyph" - >4.6.2 Glyph-areas</link><br/> - <link href= - "http://www.w3.org/TR/xsl/slice4.html#area-linebuild" - >4.7.2 Line-building</link><br/> - <link href= - "http://www.w3.org/TR/xsl/slice4.html#rend-intrinsic" - >4.9.5 Intrinsic Marks</link><br/> - <link href= - "http://www.w3.org/TR/xsl/slice7.html#font-model" - >7.8.1 Fonts and Font Data</link><br/> - <link href= - "http://www.w3.org/TR/xsl/slice7.html#writing-mode-related" - >7.27 Writing-mode-related Properties</link> - </td> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice7.html#glyph-orientation-horizontal" - >7.27.2 glyph-orientation-horizontal</link><br/> - <link href= - "http://www.w3.org/TR/xsl/slice7.html#glyph-orientation-vertical" - >7.27.3 glyph-orientation-vertical</link><br/> - <link href= - "http://www.w3.org/TR/xsl/slice7.html#direction" - >7.27.1 direction</link><br/> - <link href= - "http://www.w3.org/TR/xsl/slice7.html#writing-mode" - >7.27.7 writing-mode</link> - </td> - </tr> - <tr> - <td>is-reference-area</td> - <td>All areas</td> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice5.html#section-N6691-Non-property-Based-Trait-Generation" - >5.6 Non-property Based Trait Generation</link> - </td> - <td> - Set "true" on:<br/> - simple-page-master<br/> - title<br/> - region-body<br/> - region-before<br/> - region-after<br/> - region-start<br/> - region-end<br/> - block-container<br/> - inline-container<br/> - table<br/> - table-caption<br/> - table-cell - </td> - </tr> - <tr> - <td>is-viewport-area</td> - <td></td> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice4.html#area-common" - >4.2.2 Common Traits</link> - </td> - </tr> - <tr> - <td>top-position</td> - </tr> - <tr> - <td>bottom-position</td> - </tr> - <tr> - <td>left-position</td> - </tr> - <tr> - <td>right-position</td> - </tr> - <tr> - <td>left-offset</td> - </tr> - <tr> - <td>top-offset</td> - </tr> - <tr> - <td>is-first</td> - </tr> - <tr> - <td>is-last</td> - </tr> - <tr> - <td>generated-by</td> - </tr> - <tr> - <td>returned-by</td> - </tr> - <tr> - <td>nominal-font</td> - </tr> - <tr> - <td>blink</td> - <td></td> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice5.html#refine-text-decoration" - >5.5.6 Text-decoration Property - </link> - </td> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice7.html#text-decoration" - >7.16.4 "text-decoration" - </link> - </td> - </tr> - <tr> - <td>underline-score</td> - <td></td> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice5.html#refine-text-decoration" - >5.5.6 Text-decoration Property - </link> - </td> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice7.html#text-decoration" - >7.16.4 "text-decoration" - </link> - </td> - </tr> - <tr> - <td>underline-score-color</td> - <td></td> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice5.html#refine-text-decoration" - >5.5.6 Text-decoration Property - </link> - </td> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice7.html#text-decoration" - >7.16.4 "text-decoration" - </link> - </td> - </tr> - <tr> - <td>overline-score</td> - <td></td> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice5.html#refine-text-decoration" - >5.5.6 Text-decoration Property - </link> - </td> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice7.html#text-decoration" - >7.16.4 "text-decoration" - </link> - </td> - </tr> - <tr> - <td>overline-score-color</td> - <td></td> - - <td> - <link href= - "http://www.w3.org/TR/xsl/slice5.html#refine-text-decoration" - >5.5.6 Text-decoration Property - </link> - </td> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice7.html#text-decoration" - >7.16.4 "text-decoration" - </link> - </td> - </tr> - <tr> - <td>through-score</td> - <td></td> - - <td> - <link href= - "http://www.w3.org/TR/xsl/slice5.html#refine-text-decoration" - >5.5.6 Text-decoration Property - </link> - </td> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice7.html#text-decoration" - >7.16.4 "text-decoration" - </link> - </td> - </tr> - <tr> - <td>through-score-color</td> - <td></td> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice5.html#refine-text-decoration" - >5.5.6 Text-decoration Property - </link> - </td> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice7.html#text-decoration" - >7.16.4 "text-decoration" - </link> - </td> - </tr> - <tr> - <th>Other Indirectly Derived Traits</th> - </tr> - <tr> - <td>alignment-point</td> - <td/> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice4.html#area-intro" - >4.1 Introduction</link> - </td> - </tr> - <tr> - <td>alignment-baseline</td> - <td/> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice4.html#area-intro" - >4.1 Introduction</link> - </td> - </tr> - <tr> - <td>baseline-shift</td> - <td/> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice4.html#area-intro" - >4.1 Introduction</link> - </td> - </tr> - <tr> - <td>dominant-baseline-identifier</td> - <td/> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice4.html#area-intro" - >4.1 Introduction</link> - </td> - </tr> - <tr> - <td>actual-baseline-table</td> - <td/> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice4.html#area-intro" - >4.1 Introduction</link> - </td> - </tr> - <tr> - <td>start-intrusion-adjustment</td> - <td/> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice4.html#area-intro" - >4.1 Introduction</link> - </td> - </tr> - <tr> - <td>end-intrusion-adjustment</td> - <td/> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice4.html#area-intro" - >4.1 Introduction</link> - </td> - </tr> - <tr> - <td>page-number</td> - <td/> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice4.html#area-intro" - >4.1 Introduction</link> - </td> - </tr> - <tr> - <td>script</td> - <td/> - <td> - <link href= - "http://www.w3.org/TR/xsl/slice4.html#area-intro" - >4.1 Introduction</link> - </td> - </tr> - </table> - </section> - </body> -</document> - diff --git a/src/documentation/content/xdocs/design/alt.design/user-agent-refs.xml b/src/documentation/content/xdocs/design/alt.design/user-agent-refs.xml deleted file mode 100644 index 31b549708..000000000 --- a/src/documentation/content/xdocs/design/alt.design/user-agent-refs.xml +++ /dev/null @@ -1,929 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!-- - Copyright 1999-2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> - -<document> - <header> - <title>User agent refs</title> - <authors> - <person name="Peter B. West" email="pbwest@powerup.com.au"/> - </authors> - </header> - <body> - <section> - <title>User Agent references in XSLFO</title> - <section> - <title>4.9.2 Viewport Geometry</title> - <p> - 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 - <strong>user agent</strong>. Otherwise, both are zero. - </p> - </section> - <section> - <title>5.1.3 Actual Values</title> - <p> - 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 <strong>user - agent</strong> 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. - </p> - </section> - <section> - <title>5.5.7 Font Properties</title> - <p> - There is no XSL mechanism to specify a particular font; - instead, a selected font is chosen from the fonts available - to the <strong>User Agent</strong> 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. - </p> - </section> - <section> - <title>5.9.13.1 Pixels</title> - <p> - If the <strong>User Agent</strong> chooses a measurement for - a 'px' that does not match an integer number of device dots - in each axis it may produce undesirable effects... - </p> - </section> - <section> - <title>5.10.4 Property Value Functions</title> - <section> - <title>Function: object merge-property-values( NCName)</title> - <p> - 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 <strong>User - Agent</strong> state. If there is no such value, the - computed value of the parent fo:multi-properties is - returned... - </p> - <p> - The test for applicability of a <strong>User - Agent</strong> state is specified using the "active-state" - property. - </p> - </section> - </section> - <section> - <title>6.3 Formatting Objects Summary</title> - <section> - <title>multi-property-set</title> - <p> - The fo:multi-property-set is used to specify an - alternative set of formatting properties that, dependent - on a <strong>User Agent</strong> state, are applied to the - content. - </p> - </section> - <section> - <title>title</title> - <p> - The fo:title formatting object is used to associate a - title with a given page-sequence. This title may be used - by an interactive <strong>User Agent</strong> 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". - </p> - </section> - </section> - <section> - <title>6.4.1.2 Page-masters</title> - <p> - ... When pages are used with a <strong>User Agent</strong> - 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. - </p> - </section> - <section> - <title>6.4.20 fo:title</title> - <section> - <title>Common Usage:</title> - <p> - ... This title may be used by an interactive <strong>User - Agent</strong> to identify the pages. - </p> - </section> - </section> - <section> - <title>6.6.3 fo:character</title> - <section> - <title>Constraints:</title> - <p> - The dimensions of the areas are determined by the font - metrics for the glyph. - </p> - <p> - When formatting an fo:character with a - "treat-as-word-space" value of "true", the <strong>User - Agent</strong> may use a different method for determining - the inline-progression-dimension of the area. - </p> - </section> - </section> - <section> - <title>6.9 Dynamic Effects: Link and Multi Formatting - Objects</title> - <section> - <title>6.9.1 Introduction</title> - <p> - Dynamic effects, whereby user actions (including - <strong>User Agent</strong> 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: - </p> - <ul> - <li>One-directional single-target links.</li> - <li> - 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. - </li> - <li> - The ability to switch between different property values, - such as color or font-weight, depending on a - <strong>User Agent</strong> state, such as "hover". - </li> - </ul> - </section> - </section> - <section> - <title>6.10 Out-of-Line Formatting Objects</title> - <section> - <title>6.10.1.3 Conditional Sub-Regions</title> - <p> - ... There may be limits on how much space conditionally - generated areas can borrow from the - region-reference-area. It is left to the <strong>user - agent</strong> to decide these limits. - </p> - <p> - ... An interactive <strong>user agent</strong> 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. - </p> - </section> - </section> - <section> - <title>6.10.2 fo:float</title> - <section> - <title>Constraints:</title> - <p> - ... The <strong>user agent</strong> 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 <strong>user - agent</strong> 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. - </p> - <p> - The <strong>user agent</strong> 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. - </p> - </section> - </section> - <section> - <title>6.10.3 fo:footnote</title> - <section> - <title>Constraints:</title> - <p> - ... 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 <strong>user agent</strong> - must use the region-master of the last page that did - contain a region-body to hold the additional block-areas. - </p> - </section> - </section> - <section> - <title>7.3 Reference Rectangle for Percentage Computations</title> - <p>...</p> - <section> - <title>Exceptions ...</title> - <p> - 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 <strong>user agent</strong>. - </p> - </section> - </section> - <section> - <title>7.6.5 "pause-after" 7.6.6 "pause-before" 7.6.17 - "voice-family"</title> - <p> - Initial: depends on <strong>user agent</strong> - </p> - </section> - <section> - <title>7.7.1 "background-attachment"</title> - <section> - <title>fixed</title> - <p> - ... <strong>User agents</strong> 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. - </p> - </section> - </section> - <section> - <title>7.7.9 "border-before-width"</title> - <section> - <title><length-conditional></title> - <p> - ... 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 <strong>User - Agent</strong> dependent length. - </p> - </section> - </section> - <section> - <title>7.7.19 "border-top-color"</title> - <section> - <title><color></title> - <p> - ... If an element's border color is not specified with a - "border" property, <strong>user agents</strong> must use - the value of the element's "color" property as the - computed value for the border color. - </p> - </section> - </section> - <section> - <title>7.7.20 "border-top-style"</title> - <p> - Conforming HTML <strong>user agents</strong> may interpret - 'dotted', 'dashed', 'double', 'groove', 'ridge', 'inset', - and 'outset' to be 'solid'. - </p> - </section> - <section> - <title>7.7.21 "border-top-width"</title> - <section> - <title>thin ... medium ... thick ...</title> - <p> - ... The interpretation of the first three values depends - on the <strong>user agent</strong>. - </p> - </section> - </section> - <section> - <title>7.8.2 "font-family"</title> - <p>Initial: depends on <strong>user agent</strong></p> - </section> - <section> - <title>7.8.3 "font-selection-strategy"</title> - <p> - There is no XSL mechanism to specify a particular font; - instead, a selected font is chosen from the fonts available - to the <strong>User Agent</strong> 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. - </p> - <p> - ... This fallback may be to seek a match using a - <strong>User Agent</strong> default "font-family", or it may - be a more elaborate fallback strategy where, for example, - "Helvetica" would be used as a fallback for "Univers". - </p> - <p> - If no match has been found for a particular character, there - is no selected font and the <strong>User Agent</strong> - should provide a visual indication that a character is not - being displayed (for example, using the 'missing character' - glyph). - </p> - </section> - <section> - <title>7.8.4 "font-size"</title> - <section> - <title><absolute-size></title> - <p> - An <absolute-size> keyword refers to an entry in a - table of font sizes computed and kept by the <strong>user - agent</strong>. Possible values are:<br/>[ xx-small | - x-small | small | medium | large | x-large | xx-large ] - </p> - </section> - <section> - <title><relative-size></title> - <p> - A <relative-size> keyword is interpreted relative to - the table of font sizes and the font size of the parent - element. Possible values are:<br/>[ larger | smaller - ]<br/>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 <strong>user - agent</strong> is free to interpolate between table - entries or round off to the closest one. The <strong>user - agent</strong> may have to extrapolate table values if the - numerical value goes beyond the keywords. - </p> - </section> - <section> - <title><length></title> - <p> - A length value specifies an absolute font size (that is - independent of the <strong>user agent</strong>'s font - table). - </p> - </section> - </section> - <section> - <title>7.8.8 "font-variant"</title> - <section> - <title>small-caps</title> - <p> - ... If a genuine small-caps font is not available, - <strong>user agents</strong> should simulate a small-caps - font... - </p> - </section> - </section> - <section> - <title>7.8.9 "font-weight"</title> - <section> - <title>XSL modifications to the CSS definition:</title> - <p> - ... 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. <strong>User - agents</strong> 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 <strong>user agent</strong> will map - fonts within a family to weight values. However, the - following heuristics... - </p> - </section> - </section> - <section> - <title>7.13.1 "alignment-adjust"</title> - <section> - <title>auto</title> - <p> - ... If the baseline-identifier does not exist in the - baseline-table for the glyph or other inline-area, then - the <strong>User Agent</strong> may either use heuristics - to determine where that missing baseline would be or may - use the dominant-baseline as a fallback. - </p> - </section> - </section> - <section> - <title>7.13.3 "baseline-shift"</title> - <section> - <title>sub/super</title> - <p> - ... Because in most fonts the subscript position is - normally given relative to the "alphabetic" baseline, the - <strong>User Agent</strong> may compute the effective - position for sub/superscripts <em>[sub: spec typo!]</em> - when some other baseline is dominant. ... If there is no - applicable font data the <strong>User Agent</strong> may - use heuristics to determine the offset. - </p> - </section> - </section> - <section> - <title>7.13.5 "dominant-baseline"</title> - <p> - ... If there is no baseline-table in the nominal font or if - the baseline-table lacks an entry for the desired baseline, - then the <strong>User Agent</strong> may use heuristics to - determine the position of the desired baseline. - </p> - </section> - <section> - <title>7.14.11 "scaling-method"</title> - <section> - <title>auto</title> - <p> - The <strong>User Agent</strong> is free to choose either - resampling, integer scaling, or any other scaling method. - </p> - </section> - <section> - <title>integer-pixels</title> - <p> - The <strong>User Agent</strong> 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. - </p> - </section> - <section> - <title>resample-any-method</title> - <p> - The <strong>User Agent</strong> should resample the - supplied image to provide an image that fills the size - derived from the content-height, content-width, and - scaling properties. The <strong>user agent</strong> may - use any sampling method. - </p> - </section> - <p> - ... This is defined as a preference to allow the - <strong>user agent</strong> the flexibility to adapt to - device limitations and to accommodate over-constrained - situations involving min/max dimensions and scale factors. - </p> - </section> - <section> - <title>7.14.12 "width"</title> - <p> - ... The width of a replaced element's box is intrinsic and - may be scaled by the <strong>user agent </strong> if the - value of this property is different than 'auto'. - </p> - </section> - <section> - <title>7.15.4 "line-height"</title> - <section> - <title>normal</title> - <p> - Tells <strong>user agents</strong> to set the computed - value to a "reasonable" value based on the font size of - the element. - </p> - </section> - <p> - ... When an element contains text that is rendered in more - than one font, <strong>user agents</strong> should determine - the "line-height" value according to the largest font size. - </p> - </section> - <section> - <title>7.15.9 "text-align"</title> - <p> - ... The actual justification algorithm used is <strong>user - agent</strong> and written language dependent.<br/> - Conforming <strong>user agents</strong> 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. - </p> - </section> - <section> - <title>7.15.11 "text-indent"</title> - <p> - ... <strong>User agents</strong> should render this - indentation as blank space. - </p> - </section> - <section> - <title>7.16.2 "letter-spacing"</title> - <section> - <title>normal</title> - <p> - The spacing is the normal spacing for the current - font. This value allows the <strong>user agent</strong> to - alter the space between characters in order to justify - text. - </p> - </section> - <section> - <title><length></title> - <p> - 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. <strong>User agents</strong> may not further - increase or decrease the inter-character space in order to - justify text. - </p> - </section> - <p> - Character-spacing algorithms are <strong>user agent</strong> - dependent. Character spacing may also be influenced by - justification (see the "text-align" property).<br/> When the - resultant space between two characters is not the same as - the default space, <strong>user agents</strong> should not - use ligatures.<br/> Conforming <strong>user agents</strong> - may consider the value of the 'letter-spacing' property to - be 'normal'. - </p> - <section> - <title>XSL modifications to the CSS definition:</title> - <p> - ... 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 - <strong>User Agent</strong> specific. - </p> - <p> - ... The CSS statement that "Conforming <strong>user - agents</strong> may consider the value of the - 'letter-spacing' property to be 'normal'." does not apply - in XSL, if the <strong>User Agent</strong> implements the - "Extended" property set. - </p> - <p> - ... The algorithm for resolving the adjusted values - between word spacing and letter spacing is <strong>User - Agent</strong> dependent. - </p> - </section> - </section> - <section> - <title>7.16.4 "text-decoration"</title> - <p> - ... If the element has no content or no text content (e.g., - the IMG element in HTML), <strong>user agents</strong> must - ignore this property. - </p> - <section> - <title>blink</title> - <p> - ... Conforming <strong>user agents</strong> are not - required to support this value. - </p> - </section> - </section> - <section> - <title>7.16.6 "text-transform"</title> - <p> - ... Conforming <strong>user agents</strong> 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. - </p> - </section> - <section> - <title>7.16.8 "word-spacing"</title> - <p> - ... Word spacing algorithms are <strong>user - agent</strong>-dependent. - </p> - <section> - <title>XSL modifications to the CSS definition:</title> - <p> - ... The algorithm for resolving the adjusted values - between word spacing and letter spacing is <strong>User - Agent</strong> dependent. - </p> - </section> - </section> - <section> - <title>7.17.1 "color"</title> - <p>Initial: depends on <strong>user agent</strong></p> - </section> - <section> - <title>7.17.3 "rendering-intent"</title> - <section> - <title>auto</title> - <p> - This is the default behavior. The <strong>User - Agent</strong> 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 - <strong>user agent</strong> shall use the current profile - and force the intent, overriding any intent that might be - stored in the profile itself. - </p> - </section> - </section> - <section> - <title>7.20.2 "overflow"</title> - <section> - <title>scroll</title> - <p> - This value indicates that the content is clipped and that - if the <strong>user agent</strong> 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. - </p> - </section> - <section> - <title>auto</title> - <p> - The behavior of the "auto" value is <strong>user - agent</strong> dependent, but should cause a scrolling - mechanism to be provided for overflowing boxes. - </p> - </section> - </section> - <section> - <title>7.21.2 "leader-pattern"</title> - <section> - <title>dots</title> - <p> - ... The choice of dot character is dependent on the - <strong>user agent</strong>. - </p> - </section> - </section> - <section> - <title>7.21.4 "leader-length"</title> - <p> - ... <strong>User agents</strong> 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. - </p> - </section> - <section> - <title>7.25.11 "media-usage"</title> - <section> - <title>auto</title> - <p> - The <strong>User Agent</strong> determines which value of - "media-usage" (other than the "auto" value) is used. The - <strong>User Agent</strong> may consider the type of media - on which the presentation is to be placed in making this - determination.<br/> NOTE:<br/> For example, the - <strong>User Agent </strong> 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. - </p> - </section> - <section> - <title>bounded-in-one-dimension</title> - <p> - ... 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 <strong>User Agent</strong> - may recover as follows:... - </p> - </section> - <section> - <title>unbounded</title> - <p> - 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 <strong>User Agent</strong> may recover by ignoring the - specified value. ... - </p> - </section> - </section> - <section> - <title>7.25.13 "page-height"</title> - <section> - <title>auto</title> - <p> - The "page-height" shall be determined, in the case of - continuous media, from the size of the <strong>User - Agent</strong> window... - </p> - </section> - <section> - <title>NOTE:</title> - <p> - A <strong>User Agent</strong> 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 <strong>User Agent</strong> - 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. - </p> - </section> - </section> - <section> - <title>7.25.15 "page-width"</title> - <section> - <title>auto</title> - <p> - The "page-width" shall be determined, in the case of - continuous media, from the size of the <strong>User - Agent</strong> window... - </p> - </section> - </section> - <section> - <title>7.26.5 "border-separation"</title> - <section> - <title><length-bp-ip-direction></title> - <p> - ... Rows, columns, row groups, and column groups cannot - have borders (i.e., <strong>user agents</strong> must - ignore the border properties for those elements). - </p> - </section> - </section> - <section> - <title>7.26.7 "caption-side"</title> - <p> - ... 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 - <strong>user agent</strong> to chose a "reasonable width". - </p> - </section> - <section> - <title>7.27.2 "glyph-orientation-horizontal"</title> - <section> - <title><angle></title> - <p> - ... The <strong>User Agent</strong> shall round the value - of the angle to the closest of the permitted values. - </p> - </section> - </section> - <section> - <title>7.27.3 "glyph-orientation-vertical"</title> - <section> - <title>auto</title> - <p> - ... The determination of which characters should be - auto-rotated may vary across <strong>User Agents</strong>. - </p> - </section> - <section> - <title><angle></title> - <p> - ... The <strong>User Agent</strong> shall round the value - of the angle to the closest of the permitted values. - </p> - </section> - </section> - <section> - <title>7.27.6 "unicode-bidi"</title> - <section> - <title>XSL modifications to the CSS definition:</title> - <p> - ... Fallback:<br/> If it is not possible to present the - characters in the correct order, then the - <strong>UserAgent </strong> should display either a - 'missing character' glyph or display some indication that - the content cannot be correctly rendered. - </p> - </section> - </section> - <section> - <title>7.28.1 "content-type"</title> - <p> - ... This property specifies the content-type and may be used - by a <strong>User Agent</strong> to select a rendering - processor for the object. - </p> - <section> - <title>auto</title> - <p> - No identification of the content-type. The <strong>User - Agent</strong> may determine it by "sniffing" or by other - means. - </p> - </section> - </section> - <section> - <title>7.29.5 "border-color"</title> - <p> - ... If an element's border color is not specified with a - "border" property, <strong>user agents</strong> must use the - value of the element's "color" property as the computed - value for the border color. - </p> - </section> - <section> - <title>7.29.9 "border-spacing"</title> - <p> - ... Rows, columns, row groups, and column groups cannot have - borders (i.e., <strong>user agents</strong> must ignore the - border properties for those elements). - </p> - </section> - <section> - <title>7.29.13 "font"</title> - <p> - ... If no font with the indicated characteristics exists on - a given platform, the <strong>user agent</strong> should - either intelligently substitute (e.g., a smaller version of - the "caption" font might be used for the "small-caption" - font), or substitute a <strong>user agent</strong> default - font. - </p> - </section> - <section> - <title>7.29.19 "pause"</title> - <p>Initial: depends on <strong>user agent</strong></p> - </section> - <section> - <title>7.29.21 "size"</title> - <p> - ... Relative page boxes allow <strong>user agents</strong> - to scale a document and make optimal use of the target size. - </p> - <p> - ... <strong>User agents</strong> 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). - </p> - <ul> - <li> - Rendering page boxes that do not fit a target sheet<br/> - If a page box does not fit the target sheet dimensions, - the <strong>user agent</strong> may choose to: - <ul> - <li> - Rotate the page box 90 degrees if this will make the - page box fit. - </li> - <li>Scale the page to fit the target.</li> - </ul> - The <strong>user agent</strong> should consult the user - before performing these operations. - </li> - <li> - Positioning the page box on the sheet<br/> When the page - box is smaller than the target size, the <strong>user - agent</strong> is free to place the page box anywhere on - the sheet. - </li> - </ul> - </section> - <section> - <title>7.29.23 "white-space"</title> - <section> - <title>normal</title> - <p> - This value directs <strong>user agents</strong> to - collapse sequences of whitespace, and break lines as - necessary to fill line boxes. ... - </p> - </section> - <section> - <title>pre</title> - <p> - This value prevents <strong>user agents</strong> from - collapsing sequences of whitespace. ... - </p> - </section> - <p> - ... Conforming <strong>user agents</strong> may ignore the - 'white-space' property in author and user style sheets but - must specify a value for it in the default style sheet. - </p> - </section> - </section> - </body> -</document> - diff --git a/src/documentation/content/xdocs/design/alt.design/xml-parsing.ehtml b/src/documentation/content/xdocs/design/alt.design/xml-parsing.ehtml deleted file mode 100644 index 43033270a..000000000 --- a/src/documentation/content/xdocs/design/alt.design/xml-parsing.ehtml +++ /dev/null @@ -1,366 +0,0 @@ -<?xml version="1.0"?> -<!-- - Copyright 1999-2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!-- $Id$ --> -<html> - <body text="#000000" bgcolor="#FFFFFF"> - <script type="text/javascript" src="codedisplay.js" /> - <div class="content"> - <h1>Implementing Pull Parsing</h1> - <p> - <font size="-2">by Peter B. West</font> - </p> - <ul class="minitoc"> - <li> - <a href="#An+alternative+parsing+methodology">An alternative - parsing methodology</a> - <ul class="minitoc"> - <li> - <a href="#Structure+of+SAX+parsing">Structure of SAX parsing</a> - </li> - <li> - <a href="#Cluttered+callbacks">Cluttered callbacks</a> - </li> - <li> - <a href="#From+">From push to pull parsing</a> - </li> - <li> - <a href="#FoXMLEvent+me%5Bthods">FoXMLEvent me[thods</a> - </li> - <li> - <a href="#FOP+modularisation">FOP modularisation</a> - </li> - </ul> - </li> - </ul> - - <a name="N101C5"></a><a name="An+alternative+parsing+methodology"></a> - <h3>An alternative parsing methodology</h3> - <div style="margin-left: 0 ; border: 2px"> - <p> - 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: - </p> - <ul> - - <li> - better decomposition of FOP into processing phases - </li> - - <li> - top-down FO tree building, providing - </li> - - <li> - integrated validation of FO tree input. - </li> - - </ul> - <a name="N101DA"></a><a name="Structure+of+SAX+parsing"></a> - <h4>Structure of SAX parsing</h4> - <div style="margin-left: 0 ; border: 2px"> - <p> - 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 <span - class="codefrag">XMLReader</span> interface, of a <span - class="codefrag">ContentHandler</span> which contains a - callback routine for each of the event types encountered - by the parser, e.g., <span - class="codefrag">startDocument()</span>, <span - class="codefrag">startElement()</span>, <span - class="codefrag">characters()</span>, <span - class="codefrag">endElement()</span> and <span - class="codefrag">endDocument()</span>. Parsing is - initiated by a call to the <span - class="codefrag">parser()</span> method of the <span - class="codefrag">XMLReader</span>. Note that the call to - <span class="codefrag">parser()</span> and the calls to - individual callback methods are synchronous: <span - class="codefrag">parser()</span> will only return when the - last callback method returns, and each callback must - complete before the next is called.<br/> <br/> - - <strong>Figure 1</strong> - - </p> - <div align="center"> - <img class="figure" alt="SAX parsing schematic" - src="images/design/alt.design/SAXParsing.png" /></div> - <p> - 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. - </p> - <p> - 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 <span class="codefrag">parser()</span>, 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. - </p> - </div> - <a name="N10218"></a><a name="Cluttered+callbacks"></a> - <h4>Cluttered callbacks</h4> - <div style="margin-left: 0 ; border: 2px"> - <p> - 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 <span - class="codefrag">endElement()</span> 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 <span - class="codefrag">endElement()</span> method, when the end - of a page-sequence was detected. - </p> - <p> - 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. - </p> - </div> - <a name="N1022B"></a><a name="From+"></a> - <h4>From push to pull parsing</h4> - <div style="margin-left: 0 ; border: 2px"> - <p> - 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 <span class="codefrag">XMLEvent</span> - objects as a <em>producer</em>. 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 <em>consumer</em>. This, - essentially, is the difference between <em>push</em> and - <em>pull</em> parsing. In itself, this does not reduce - the footprint. This occurs when the approach is - generalised to modularise FOP processing.<br/> <br/> - <strong>Figure 2</strong> - - </p> - <div align="center"> - <img class="figure" alt="XML event buffer" - src="images/design/alt.design/pull-parsing.png" /></div> - <p> - The most useful change that this brings about is the switch - from <em>passive</em> to <em>active</em> XML element - processing. The process of parsing now becomes visible to - the controlling process. All local validation requirements, - all object and data structure building, are initiated by the - process(es) <em>get</em>ting from the queue - in the case - above, the FO tree builder. - </p> - </div> - <a name="N10260"></a><a name="FoXMLEvent+methods"></a> - <h4>FoXMLEvent methods</h4> - <div style="margin-left: 0 ; border: 2px"> - <a name="FoXMLEvent-methods"></a> - <p> - The experimental code uses a class <span id = "span00" - /><span class = "codefrag" ><a - href="javascript:toggleCode( 'span00', - 'FoXMLEvent.html#FoXMLEventClass', '400', '100%' - )">FoXMLEvent</a></span > to provide the objects which are - placed in the queue. <em>FoXMLEvent</em> includes a - variety of methods to access elements in the queue. - Namespace URIs encountered in parsing are maintained in an - <span id = "span01" /><span class="codefrag"><a - href="javascript:toggleCode( 'span01', - 'XMLNamespaces.html#XMLNamespacesClass', '400', '100%' - )">XMLNamespaces</a></span> object where they are - associated with a unique integer index. This integer - value is used in the signature of some of the access - methods. - </p> - <p> - The class which manages the buffer is <span id = "span02" - /><span class = "codefrag" ><a href = - "javascript:toggleCode( 'span02', - 'SyncedFoXmlEventsBuffer.html#SyncedFoXmlEventsBufferClass', - '400', '100%' )" >SyncedFoXmlEventsBuffer</a>.</span > - </p> - <dl> - - <dt> - <span id = "span03" /><a href="javascript:toggleCode( - 'span03', 'SyncedFoXmlEventsBuffer.html#getEvent', - '400', '100%' )">FoXMLEvent - getEvent(SyncedCircularBuffer events)</a> - </dt> - - <dd> - 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. - </dd> - - <dt> - <span id = "span04" /><a href="javascript:toggleCode( - 'span04', 'SyncedFoXmlEventsBuffer.html#getTypedEvent', - '400', '100%' )">FoXMLEvent getTypedEvent()</a> - </dt> - - <dd> - A series of these methods provide for the recovery only - of events of a particular event type, and possibly other - specific characteristics. <em>Get</em> methods discard - input which does not meet the requirements. E.g. - <dl> - <dt> - <span id = "span040" /><a - href="javascript:toggleCode( 'span040', - 'SyncedFoXmlEventsBuffer.html#getEndDocument', - '400', '100%' )">FoXMLEvent getEndDocument()</a> - </dt> - <dd> - Discard input until and EndDocument event occurs. - Return this event. - </dd> - <dt> - <span id = "span041" /><a - href="javascript:toggleCode( 'span041', - 'SyncedFoXmlEventsBuffer.html#getStartElement', - '400', '100%' )">FoXMLEvent getStartElement()</a> - </dt> - <dd> - A series of <span class = "codefrag" - >getStartElement</span > methods provide for - discarding input until a StartElement event of the - appropriate type occurs. This event is returned. - This series of methods includes some which accept a - list of Element specifiers. - </dd> - </dl> - </dd> - - <dt> - <span id = "span05" /><a href="javascript:toggleCode( - 'span05', - 'SyncedFoXmlEventsBuffer.html#expectTypedEvent', '400', - '100%' )">FoXMLEvent expectTypedEvent()</a> - </dt> - - <dd> - A series of these methods provide for the recovery only - of events of a particular event type, and possibly other - specific characteristics. <em>Expect</em> methods throw - an exception on input which does not meet the - requirements. <em>Expect</em> methods generally take a - <span class = "codefrag" >boolean</span> argument - specifying whitespace treatment. Examples include: - <dl> - <dt> - <span id = "span050" /><a - href="javascript:toggleCode( 'span050', - 'SyncedFoXmlEventsBuffer.html#expectEndDocument', - '400', '100%' )">FoXMLEvent expectEndDocument()</a> - </dt> - <dd> - Expect an EndDocument event. Return this event. - </dd> - <dt> - <span id = "span051" /><a - href="javascript:toggleCode( 'span051', - 'SyncedFoXmlEventsBuffer.html#expectStartElement', - '400', '100%' )">FoXMLEvent expectStartElement()</a> - </dt> - <dd> - A series of <span class = "codefrag" - >expectStartElement</span > methods provide for - examinging the pending input for a StartElement - event of the appropriate type. This event is - returned. This series of methods includes some - which accept a list of Element specifiers. - </dd> - </dl> - </dd> - </dl> - </div> - <a name="N102FE"></a><a name="FOP+modularisation"></a> - <h4>FOP modularisation</h4> - <div style="margin-left: 0 ; border: 2px"> - <p> - 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. - <br/> - <br/> - - <strong>Figure 3</strong> - - </p> - <div align="center"> - <img class="figure" alt="FOP modularisation" - src="images/design/alt.design/processPlumbing.png" /> - </div> - - <p> - In the case of communication between the FO tree - building process and the layout process, feedback is - required in order to parse expressions containing - lengths expressed as a percentage of some enclosing - area. This communication is incorporated within the - general model of inter-phase communication discussed above. - <br/><br/> - <strong>Figure 4</strong> - - </p> - <div align="center"> - <img class="figure" alt="FO - layout interaction" - src="images/design/alt.design/fo-layout-interaction.png" /> - </div> - - - </div> - </div> - - </div> - </body> -</html> diff --git a/src/documentation/content/xdocs/dev/api-doc.xml b/src/documentation/content/xdocs/dev/api-doc.xml index d63a27f59..f1a35feac 100644 --- a/src/documentation/content/xdocs/dev/api-doc.xml +++ b/src/documentation/content/xdocs/dev/api-doc.xml @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="UTF-8"?> <!-- - Copyright 1999-2004 The Apache Software Foundation + Copyright 1999-2005 The Apache Software Foundation Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -15,8 +15,7 @@ limitations under the License. --> <!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd"> <document> <header> <title>FOP Development: API Documentation (javadocs)</title> @@ -27,12 +26,12 @@ <title>On-line Access (through Gump)</title> <p>FOP (and many other Apache projects) use <link href="http://gump.apache.org/">Apache Gump</link> to do a test build several times each day. One of the useful byproducts of this process is that javadocs can be created and made available.</p> <p>First, determine which line of development code you wish to see. If you don't know, you probably want the "Maintenance Branch", which is the line that currently produces FOP releases. See <link href="index.html#lines">Development Lines</link> for more details.</p> - <warning>Javadocs for both development lines are made from current CVS code, and are not tied to any particular release. Both the documentation and the API may be different, even if you are working with the correct branch. Currently, the only way to obtain API documentation for a specific release is to <link href="#self-built">build it yourself</link>.</warning> + <warning>Javadocs for both development lines are made from current SVN code, and are not tied to any particular release. Both the documentation and the API may be different, even if you are working with the correct branch. Currently, the only way to obtain API documentation for a specific release is to <link href="#self-built">build it yourself</link>.</warning> <ul> <li><link href="http://gump.apache.org/javadoc/xml-fop-maintenance/build/javadocs/index.html">Javadocs for Maintenance Branch</link></li> <li><link href="http://gump.apache.org/javadoc/xml-fop/build/javadocs/index.html">Javadocs for Trunk (Redesign)</link></li> </ul> - <note>If the links return an "Object not found!" message or otherwise do not work properly, it is probably because of a build error. Please raise a question on the <link href="../maillist.html#fop-user">fop-user mailing list</link> so that any problems can be fixed before the next build.</note> + <note>If the links return an "Object not found!" message or otherwise do not work properly, it is probably because of a build error. Please raise a question on the <link href="../maillist.html#fop-user">FOP User Mailing List</link> so that any problems can be fixed before the next build.</note> </section> <section id="self-built"> <title>Building them Yourself</title> diff --git a/src/documentation/content/xdocs/dev/conventions.xml b/src/documentation/content/xdocs/dev/conventions.xml index 48d5f7291..9d2c05012 100644 --- a/src/documentation/content/xdocs/dev/conventions.xml +++ b/src/documentation/content/xdocs/dev/conventions.xml @@ -15,8 +15,7 @@ limitations under the License. --> <!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd"> <document> <header> <title>FOP Development: Coding Conventions</title> @@ -24,12 +23,12 @@ </header> <body> <p>Acknowledgement: Some content in this guide was adapted from other Apache projects such as Avalon, Cactus, Turbine and Velocity.</p> - <section id="cvs"> - <title>CVS Repository</title> + <section id="svn"> + <title>Subversion Repository</title> <p>Conventions in this section apply to Repository content, regardless of type:</p> <ul> <li>Files checked in must conform to the code conventions for that type of file (java files must conform to java requirements, xml to xml requirements, etc.). If a submitted patch does not conform, it is the responsibility of the committer to bring it into conformance before checking it in. Developers submitting patches are encouraged to follow the code conventions to reduce the work load on the the committers.</li> - <li>To reduce the amount of spurious deltas, all text (non-binary) files checked into CVS must have Unix-style line endings (LF only). Many IDEs and editors (even on non-Unix platforms) have settings that can facilitate this convention.</li> + <li>To reduce the amount of spurious deltas, all text (non-binary) files checked into SVN must have Unix-style line endings (LF only). Many IDEs and editors (even on non-Unix platforms) have settings that can facilitate this convention.</li> </ul> </section> <section id="java"> diff --git a/src/documentation/content/xdocs/dev/doc.xml b/src/documentation/content/xdocs/dev/doc.xml index 56d225fc8..070300cd5 100644 --- a/src/documentation/content/xdocs/dev/doc.xml +++ b/src/documentation/content/xdocs/dev/doc.xml @@ -1,6 +1,6 @@ <?xml version="1.0" standalone="no"?> <!-- - Copyright 1999-2004 The Apache Software Foundation + Copyright 1999-2005 The Apache Software Foundation Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -15,8 +15,7 @@ limitations under the License. --> <!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd"> <document> <header> <title>FOP Development: Managing Documentation</title> @@ -25,9 +24,9 @@ <body> <section id="general"> <title>General Information</title> - <p>All raw documentation content is managed in the FOP CVS repository. + <p>All raw documentation content is managed in the FOP SVN repository. Updates should be committed to the repository, then the repository files are used to generate usable output. -The remaining discussions on this page assume that the CVS repository is the starting place for processing. +The remaining discussions on this page assume that the SVN repository is the starting place for processing. The path to the documentation is xml-fop/src/documentation/content/xdocs.</p> <note>All documentation is maintained on the trunk. Although we are currently maintaining two sets of code (trunk and maintenance), there is only one set of documentation. @@ -67,9 +66,9 @@ Maintenance branch releases either copy the trunk content to the maintenance bra </tr> <tr> <td>Developer commits code to FOP repository.</td> - <td>FOP repository (cvs) at cvs.apache.org/home/cvs/xml-fop</td> + <td>FOP repository (SVN)</td> <td>Raw XML and other content</td> - <td><link href="http://cvs.apache.org/viewcvs.cgi/xml-fop/src/documentation/content/xdocs/">ViewCVS</link></td> + <td><link href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/trunk/src/documentation/content/xdocs/">ViewCVS</link></td> </tr> <tr> <td>Developer builds documentation and commits it to xml-site.</td> diff --git a/src/documentation/content/xdocs/dev/index.xml b/src/documentation/content/xdocs/dev/index.xml index d4bb03d05..27645416f 100644 --- a/src/documentation/content/xdocs/dev/index.xml +++ b/src/documentation/content/xdocs/dev/index.xml @@ -15,8 +15,7 @@ limitations under the License. --> <!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd"> <document> <header> <title>FOP Development: General Information</title> @@ -33,8 +32,27 @@ This certainly includes programmers, but may also include those contributing to <title>Development</title> <p>There are currently two branches of FOP :</p> <ul> - <li>The "maintenance branch" is the one that releases are currently generated from, and is also called the "maintenance branch". Because of limitations in its design, the FOP committers decided to freeze new development on this branch, and are providing only bug fixes. This branch is tagged as "fop-0_20_2-maintain" in the CVS repository. Please note that patches for enhancements to the maintenance branch will generally not be considered. Bug fixes are welcome there, but new developers are strongly encouraged to apply their efforts to the trunk development line.</li> - <li>The main development line is the future of FOP. It is currently not as mature as the "maintenance" branch, but has far greater long-term prospects. It is also known as the "root" or "trunk" or "redesign".</li> + <li> + The "maintenance branch" is the one that the last release was generated + from. Because of limitations in its design, the FOP committers decided + to freeze new development on this branch, and are providing only bug fixes. + Please note that patches for enhancements to the maintenance branch will + generally not be considered. Bug fixes are welcome there, but new developers + are strongly encouraged to apply their efforts to the trunk development line. + <note> + The SVN repository URL for the maintenance branch is:<br/> + <code>http://svn.apache.org/repos/asf/xmlgraphics/fop/branches/fop-0_20_2-maintain/</code> + </note> + </li> + <li> + The main development line is the future of FOP. It is currently not as + mature as the "maintenance branch", but has far greater long-term prospects. + It is also known as the "root" or "trunk" or "redesign". + <note> + The SVN repository URL for the trunk is:<br/> + <code>http://svn.apache.org/repos/asf/xmlgraphics/fop/trunk/</code> + </note> + </li> </ul> <p>Because there is a fair amount of common information between the maintenance and trunk development lines, we attempt to document them together, highlighting differences only where needed.</p> </section> @@ -120,22 +138,24 @@ To unsubscribe: Send email to <link href="mailto:fop-dev-unsubscribe@xmlgraphics <note>The Eyebrowse archives are currently broken!</note> </section> <section id="mail-fop-cvs"> - <title>Subscribe to the fop-cvs Mailing List</title> + <title>Subscribe to the fop-commits Mailing List</title> <p>When changes are committed to the code repository, a record of the diffs is emailed to the fop-cvs mailing list. FOP developers are encouraged to subscribe to this list because it helps in following the progress of the project. </p> <ul> - <li>Review the archives at <link href="http://mail-archives.eu.apache.org/mod_mbox/xmlgraphics-fop-commits/">http://mail-archives.eu.apache.org/mod_mbox/xmlgraphics-fop-commits/</link> (mod_mbox).</li> + <li>Review the archives at <link href="http://mail-archives.apache.org/mod_mbox/xmlgraphics-fop-commits/">http://mail-archives.apache.org/mod_mbox/xmlgraphics-fop-commits/</link> (mod_mbox).</li> <li>Review the archives at <link href="http://marc.theaimsgroup.com/?l=fop-cvs&r=1&w=2">Mailing list ARChives</link> (MARC) at the AIMS group (search).</li> <li>Subscribe by sending an email to <link href="mailto:fop-commits-subscribe@xmlgraphics.apache.org">fop-commits-subscribe@xmlgraphics.apache.org</link>.</li> </ul> </section> <section id="dev-code"> - <title>Download and Use the Developers' Code Using CVS</title> - <p>Between releases the newest code can be accessed via cvs. To do this you need to install a cvs - client on your computer, if it is not already there. An explanation how to connect to the - FOP source repository can be found at <link href="http://xmlgraphics.apache.org/repo.html">http://xmlgraphics.apache.org/repo.html</link>. - An introduction into cvs and the cvs manual can be found in the - <link href="http://xml.apache.org/library.html">reference library</link>.</p> + <title>Download and Use the Developers' Code Using Subversion</title> + <p> + Between releases the newest code can be accessed via SVN. To do this + you need to install a SVN client on your computer, if it is not already + there. An explanation how to connect to the FOP source repository can + be found at <link href="http://xmlgraphics.apache.org/repo.html">http://xmlgraphics.apache.org/repo.html</link>. + More information can be found on the <link href="tools.html">Tools page</link>. + </p> </section> <section id="patches"> <title>Submitting Patches</title> diff --git a/src/documentation/content/xdocs/dev/testing.xml b/src/documentation/content/xdocs/dev/testing.xml index 46a81459b..683edd331 100644 --- a/src/documentation/content/xdocs/dev/testing.xml +++ b/src/documentation/content/xdocs/dev/testing.xml @@ -1,6 +1,6 @@ <?xml version="1.0" standalone="no"?> <!-- - Copyright 1999-2004 The Apache Software Foundation + Copyright 1999-2005 The Apache Software Foundation Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -15,9 +15,7 @@ limitations under the License. --> <!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> - +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd"> <document> <header> <title>FOP Development: Testing</title> @@ -27,7 +25,7 @@ <body> <section id="build"> <title>"Build" Testing</title> - <p>Apache projects use an automated build tool called "gump" to create nightly builds from the CVS repository. Gump sends "nag" messages if the build fails. This can be considered a sort of basic test of the build process. To view the most recent logs of the gump builds:</p> + <p>Apache projects use an automated build tool called "gump" to create nightly builds from the SVN repository. Gump sends "nag" messages if the build fails. This can be considered a sort of basic test of the build process. To view the most recent logs of the gump builds:</p> <ul> <li><link href="http://gump.cocoondev.org/xml-fop.html">Gump build for the Trunk</link></li> <li><link href="http://gump.cocoondev.org/xml-fop-maintenance.html">Gump build for the Maintenance Branch</link></li> @@ -40,6 +38,15 @@ For these tests to occur, JUnit must be available to Ant (simply copy junit.jar The build will then report error(s) if the high-level APIs for Driver and the Transcoders fail. The tests do not check the output, but only ensure that something is generated and without exceptions.</p> </section> + <section id="layoutengine"> + <title>Layout Engine Testing</title> + <p> + The <link href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/trunk/test/layoutengine/"><code>test/layoutengine</code></link> + directory in the repository contains a test suite for checking the functionality of FOP's + layout engine. For information on how to create test cases for the layout engine, please + visit the <link href="http://wiki.apache.org/xmlgraphics-fop/HowToCreateLayoutEngineTests">Wiki page</link>. + </p> + </section> <section id="functional"> <title>Functional Testing</title> <warning>The "functional" testing section on this page is currently inoperative.</warning> @@ -106,11 +113,12 @@ test works as would be expected against the current build. <section> <title>How Testing Works</title> <p> -The tests are stored in the "<cvs_repository>/test" directory. +The tests are stored in the "<svn_repository>/test" directory. </p> <p> You can run the tests by specifying the build target "test" ie: <br/> -<code>build.sh test</code> +<code>ant.sh test</code> (Unix)<br/> +<code>ant test</code> (Windows)<br/> </p> <p> This will then compare the current code in the local src directory to a specified @@ -134,7 +142,8 @@ XML renderer. The XML files are then compared to see if there are any difference <title>SVG Testing</title> <p> The testing of SVG is not part of this testing system. SVG is tested for its rendering -accuracy by using the transcoding mechanism via Batik. So that the only part that needs +accuracy by using the transcoding mechanism via +<link href="ext:batik">Apache Batik</link>. So that the only part that needs testing is how the SVG image is embedded inside the flow of the fo document. </p> </section> diff --git a/src/documentation/content/xdocs/dev/tools.xml b/src/documentation/content/xdocs/dev/tools.xml index bbec5351e..48141519a 100644 --- a/src/documentation/content/xdocs/dev/tools.xml +++ b/src/documentation/content/xdocs/dev/tools.xml @@ -15,20 +15,29 @@ limitations under the License. --> <!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd"> <document> <header> <title>FOP Development: Developer Tools</title> <version>$Revision$</version> </header> <body> - <p>This page documents items that may be helpful to other developers, especially to those who are new to FOP. Exhaustive treatment of these topics is better suited to other fora, but the information presented here is intended to deal with FOP-specific issues related to these tools, especially "gotchas", and to help developers get jump-started.</p> + <p> + This page documents items that may be helpful to other developers, + especially to those who are new to FOP. Exhaustive treatment of these + topics is better suited to other fora, but the information presented + here is intended to deal with FOP-specific issues related to these + tools, especially "gotchas", and to help developers get jump-started. + </p> <section id="checklist"> <title>Developer Checklist</title> - <p>Here is a (probably not comprehensive) list of tools you will need to be a successful FOP developer:</p> + <p> + Here is a (probably not comprehensive) list of tools you will need + to be a successful FOP developer: + </p> <ul> <li>A java IDE (see <link href="#ide">IDE</link>).</li> + <li>A Subversion client (see <link href="#svn">Subversion</link>).</li> <li>Ant (see <link href="../compiling.html">Building FOP</link>).</li> <li>checkstyle (see <link href="conventions.html#java-checkstyle">Checkstyle</link> on the conventions page).</li> <li>JUnit (see <link href="testing.html#basic">Basic Testing</link>).</li> @@ -36,74 +45,78 @@ </section> <section id="general"> <title>General Developer Information</title> - <p>See <link href="http://www.apache.org/dev/contributors.html">the Apache Contributors Tech Guide</link> for useful information and links for Apache developers, including help with tools and procedures.</p> + <p> + See <link href="http://www.apache.org/dev/contributors.html">the Apache Contributors Tech Guide</link> + for useful information and links for Apache developers, including help + with tools and procedures. + </p> </section> - <section id="cvs"> - <title>Concurrent Versions System (CVS)</title> - <section id="cvs_general"> + <section id="svn"> + <title>Subversion (SVN)</title> + <section id="svn_general"> <title>General</title> - <p>Visit <link href="http://xmlgraphics.apache.org/repo.html">Apache XML Graphics Code Repositories</link> for useful information.</p> - <p>You will need a CVS client to be able to gain access to the FOP repository. For general CVS information, visit <link href="http://www.cvshome.org">CVS Home</link>. Nice GUI clients for Windows can be found at <link href="http://www.wincvs.org">WinCVS</link> and for Mac (68k, PPC) and Mac OS X from <link href="http://www.heilancoo.net/MacCVSClient/">MacCVSClient</link>.</p> - <p>Regardless of what platform you develop on, please be sure to submit patches that use Unix line endings. If you are using WinCVS or MacCVSClient, check code out this way by going to the Admin / Preferences menu item, clicking on the "Globals" tab, then select the "Checkout text files with the Unix LF (0xa)" option. You will also need to use an editor that supports opening and saving files using Unix line endings.</p> + <p> + Visit <link href="http://xmlgraphics.apache.org/repo.html">Apache XML Graphics Code Repositories</link> + for useful information. + </p> + <p> + You will need a SVN client to be able to gain access to the FOP repository. + For general SVN information, visit + <link href="http://subversion.tigris.org">Subversion Home</link>. + A comprehensive list of clients for all operating systems and many IDEs + can be found at + <link href="http://subversion.tigris.org/project_links.html">the Subversion Links page</link>. + For Microsoft Windows we recommend <link href="http://tortoisesvn.tigris.org">TortoiseSVN</link>. + The command-line client that comes with Subversion is also very easy to use. + </p> </section> - <section id="wincvs_download"> - <title>Step-by-step instructions for downloading FOP using WinCVS</title> + <section id="svn_download"> + <title>Step-by-step instruction for downloading FOP using the SVN command-line client</title> + <p> + On the command-line (Windows or Unix), simply run: + </p> + <source> +svn co http://svn.apache.org/repos/asf/xmlgraphics/fop/trunk/ fop-trunk + </source> + <p> + This will download the FOP trunk into the directory "fop-trunk". + </p> + </section> + <section id="tortoisesvn_download"> + <title>Step-by-step instructions for downloading FOP using TortoiseSVN (on Windows)</title> <ul> - <li>Select "Create / Checkout Module" menu item.</li> - <li>“Checkout Settings” Tab: - <ul> - <li>“Enter the module name and path on the server:”<br/> - <code>xml-fop</code> - </li> - <li>“Local folder to checkout to:”<br/>Enter your local directory</li> - </ul> - </li> - <li>“Checkout Options” Tab: - <ul> - <li>If you are checking out the trunk, unset all options.</li> - <li>If you are checking out the maintenance branch (currently distributed code), check “By revision/tag/branch:” and enter <code>fop-0_20_2-maintain</code>.</li> - </ul> - </li> - <li>“General” Tab: - <ul> - <li>“Enter the CVSROOT:”<br/> - <code>:pserver:anoncvs@cvs.apache.org:/home/cvspublic</code> - </li> - <li>“Authentication:”<br/> - <code>“passwd” file on the cvs server</code> - </li> - </ul> - </li> - <li>“Globals” Tab: - <ul> - <li>check “Checkout text files with the Unix LF (Oxa)”</li> - </ul> - </li> + <li>Create a new, empty directory in a place of your choice.</li> + <li>Right-click the new directory and select "SVN Checkout..." from the context menu.</li> + <li>Enter <code>http://svn.apache.org/repos/asf/xmlgraphics/fop/trunk/</code> as the URL of the repository.</li> <li>Click "OK" and the download should begin.</li> </ul> </section> - <section id="cvs_patch"> + <section id="patches"> <title>Creating Patches</title> <ul> <li> - <code>cd</code> to a directory that contains all of the changes that you wish to include in the patch. To comprehend the entire distribution, <code>cd</code> to the directory above the "xml-fop" directory that was created when you checked out the code.</li> - <li>Run: <code>cvs -q diff -wu <list of items to diff></code> - <br/>The <list of items to diff> is a space-separated list of files and directories relative to the current directory that you wish to include in the diff. For example, to include the entire distribution, assuming that you are in the directory, above xml-fop, simply enter "xml-fop". This will recursively go through the directories beneath xml-fop to diff each file.</li> - <li>If you are running WinCVS, select "Admin/Command Line" for a console in which to key the above command.</li> - <li>On a Linux/Unix machine, you will want to redirect the output from the above command into a file. If you are using GNU WinCVS, you can cut the output from the console window and paste it into a file. The "-w" ignores whitespace differences. The "-u" puts the diff in "universal" format. You may wish to use the "-N" option as well, which is supposed to treat new files as if there were an old 0 byte file -- in other words, it is supposed to include the new file in the patch. However, it only operates on files that have been "add"ed to the CVS repository, which cannot be done without commit access.</li> + <code>cd</code> to a directory that contains all of the changes + that you wish to include in the patch. To comprehend the entire + distribution, <code>cd</code> to the top directory where you + checked out the sources. + </li> + <li> + Run: <code>svn up</code> to make sure the diff is created against the latest sources. + </li> + <li> + Run: <code>svn diff >mypatch.diff</code> + <br/>This will write the patch to the file "mypatch.diff". + </li> + <li>If you are running TortoiseSVN, you can select "Create Patch..." in the TortoiseSVN context menu.</li> </ul> </section> - <section id="cvs-doc"> + <section id="svn-doc"> <title>Documentation</title> <ul> - <li>[online resource] <jump href="http://www.cvshome.org">The CVS Home Page</jump>.</li> - <li>[electronic manual] <jump href="http://www.cvshome.org/docs/manual">"The Cederqvist"</jump> (official CVS manual). -Note that this manual applies to the command-line version of CVS.</li> - <li>[book] <jump href="http://www.oreilly.com/catalog/cvs">Essential CVS</jump>, by Jennifer Vesperman (O'Reilly & Associates).</li> - <li>[book] <jump href="http://www.oreilly.com/catalog/cvspr2">The CVS Pocket Reference</jump>, by Gregor N. Purdy (O'Reilly & Associates).</li> - <li>[book] Open Source Development with CVS, by Moshe Bar and Karl Franz Fogel (Paraglyph Press, ISBN 1-932111-81-6).</li> - <li>[book] <jump href="http://www.oreilly.com/catalog/rcs">Applying RCS and SCCS</jump>, by Dan Bolinger and Tan Bronson (O'Reilly & Associates). -RCS is used by CVS for its file operations (CVS is kind of a wrapper around RCS).</li> + <li>[online resource] <jump href="http://subversion.tigris.org">The Subversion Home Page</jump>.</li> + <li>[electronic manual] <jump href="http://svnbook.red-bean.com">Version Control with Subversion</jump> (official Subversion manual). +Note that this manual applies to the command-line version of SVN.</li> + <li>[online resource] <jump href="http://subversion.tigris.org/project_links.html">Comprehensive list of links to documentation and Subversion clients and plugins.</jump></li> </ul> </section> </section> diff --git a/src/documentation/content/xdocs/download.xml b/src/documentation/content/xdocs/download.xml index a5723fc1d..a8405c877 100644 --- a/src/documentation/content/xdocs/download.xml +++ b/src/documentation/content/xdocs/download.xml @@ -1,6 +1,6 @@ <?xml version="1.0" standalone="no"?> <!-- - Copyright 1999-2004 The Apache Software Foundation + Copyright 1999-2005 The Apache Software Foundation Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -15,45 +15,135 @@ limitations under the License. --> <!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> - +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd"> <document> <header> - <title>FOP: Downloading A Distribution</title> + <title>Apache FOP: Downloading A Distribution</title> <version>$Revision$</version> </header> <body> - <section id="dist-type"> - <title>Binary or Source?</title> - <p>Most FOP users will want to download the latest binary distribution, which is ready to run "out of the box." -However, a source distribution will be preferable if you fall into one of the following categories:</p> - <ul> - <li>You wish to modify FOP.</li> - <li>You wish to use a version more recent than the latest release. For example, if you have read on the user mailing list that a bug has been fixed or a feature added that you are eager to try, you might download a source distribution from the CVS repository so that you don't have to wait for the next release.</li> - <li>You wish to build a local copy of the API documentation (javadocs).</li> - </ul> - </section> - <section id="binary"> - <title>Binary Download</title> - <p>Binary distributions include "-bin" in their names, and can be downloaded from a - <link href="http://www.apache.org/dyn/closer.cgi/xml/fop">FOP Distribution mirror</link>. - </p> - </section> - <section id="source"> - <title>Source Download</title> - <p>You must first determine which of the two main development branches you wish to download, "maintenance" or "redesign". -See <link href="dev/index.html">Development Introduction</link> for more details on the choices, and for the CVS tags to use when downloading the "maintenance" branch.</p> - <p>There are three ways to obtain a source distribution. Please note that they are listed from least current to most current:</p> - <ul> - <li>Download a released version from a <link href="http://www.apache.org/dyn/closer.cgi/xml/fop">FOP Distribution mirror</link>. Source distributions include "-src" in their names. Please note that official releases currently are <em>only</em> made from the "maintenance" branch.</li> - <li>Download a CVS snapshot from the cvs files <link href="http://xml.apache.org/from-cvs/xml-fop/">here</link>. These snapshots are built approximately every six hours, and have the GMT of their creation time embedded in their names. Please note that CVS snapshots are made only for the "redesign" branch.</li> - <li>Download directly from the CVS repository. -Anyone can do this using the <link href="http://xml.apache.org/cvs.html#AnonCVS">Anonymous CVS Server</link>. By default, the CVS code is up-to-the-minute, the same code that the developers are modifying. See the <link href="dev/tools.html#cvs">CVS section of Developer Tools</link> for more information on using CVS.</li> - </ul> - <p>With any source distribution, you will need to <link href="compiling.html">Build FOP</link> from the source files.</p> -</section> - </body> + <section id="dist-type"> + <title>Binary or Source?</title> + <p> + Most FOP users will want to download the latest binary distribution, + which is ready to run "out of the box." However, a source distribution + will be preferable if you fall into one of the following categories: + </p> + <ul> + <li> + You wish to modify FOP. + </li> + <li> + You wish to use a version more recent than the latest release. For + example, if you have read on the user mailing list that a bug has + been fixed or a feature added that you are eager to try, you might + download a source distribution from the CVS repository so that you + don't have to wait for the next release. + </li> + <li> + You wish to build a local copy of the API documentation (javadocs). + </li> + </ul> + </section> + <section id="binary"> + <title>Binary Download</title> + <p> + Binary distributions include "-bin" in their names, and can be downloaded from a + <link href="http://www.apache.org/dyn/closer.cgi/xml/fop">FOP Distribution mirror</link>. + </p> + </section> + <section id="source"> + <title>Source Download</title> + <p> + You must first determine which of the two main development branches you wish + to download, "maintenance" or "redesign". See + <link href="dev/index.html">Development Introduction</link> for more details + on the choices, and for the CVS tags to use when downloading the "maintenance" + branch. + </p> + <p> + There are several ways to obtain a source distribution. Please note that they + are listed from least current to most current: + </p> + <ul> + <li> + Download a released version from a + <link href="http://www.apache.org/dyn/closer.cgi/xml/fop">FOP Distribution mirror</link>. + Source distributions include "-src" in their names. Please note that official + releases currently are <em>only</em> made from the "maintenance" branch. + </li> + <!--li> + Download a CVS snapshot from the cvs files + <link href="http://xml.apache.org/from-cvs/xml-fop/">here</link>. + These snapshots are built approximately every six hours, and have the GMT of + their creation time embedded in their names. Please note that CVS snapshots + are made only for the "redesign" branch. + </li--> + <li> + Download directly from the SVN repository. + Anyone can do this using the + <link href="http://xmlgraphics.apache.org/repo.html">Anonymous SVN Server</link>. + By default, the code in SVN is up-to-the-minute, the same code that the developers + are modifying. See the <link href="dev/tools.html#svn">SVN section of Developer Tools</link> + for more information on using SVN. + </li> + </ul> + <p/> + <table> + <tr> + <th colspan="2">Maintenance Branch</th> + </tr> + <tr> + <td>Repository URL</td> + <td> + <link href="http://svn.apache.org/repos/asf/xmlgraphics/fop/branches/fop-0_20_2-maintain/"> + <code>http://svn.apache.org/repos/asf/xmlgraphics/fop/branches/fop-0_20_2-maintain/</code> + </link> + </td> + </tr> + <tr> + <td>Web view</td> + <td> + <link href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/branches/fop-0_20_2-maintain/"> + <code>http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/branches/fop-0_20_2-maintain/</code> + </link> + </td> + </tr> + <tr> + <th colspan="2">Trunk</th> + </tr> + <tr> + <td>Repository URL</td> + <td> + <link href="http://svn.apache.org/repos/asf/xmlgraphics/fop/trunk/"> + <code>http://svn.apache.org/repos/asf/xmlgraphics/fop/trunk/</code> + </link> + </td> + </tr> + <tr> + <td>Web view</td> + <td> + <link href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/trunk/"> + <code>http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop/trunk/</code> + </link> + </td> + </tr> + </table> + <p> + With any source distribution, you will need to + <link href="compiling.html">Build FOP</link> from the source files. + </p> + <fixme author="jeremias">Reenable the link to the SVN snapshots once they are available.</fixme> + </section> + <section id="archives"> + <title>Archive Download</title> + <p> + FOP Archive distributions are linked from the upper portion of the Apache FOP + Download Mirror Page and can be downloaded from the FOP Archives + <link href="http://archive.apache.org/dist/xml/fop/binaries/">binaries</link> & + <link href="http://archive.apache.org/dist/xml/fop/source/">source</link> links. + </p> + </section> + </body> </document> - <!-- Last Line of $RCSfile$ --> diff --git a/src/documentation/content/xdocs/gethelp.xml b/src/documentation/content/xdocs/gethelp.xml index 99cb5d6c4..760edbe2a 100644 --- a/src/documentation/content/xdocs/gethelp.xml +++ b/src/documentation/content/xdocs/gethelp.xml @@ -1,6 +1,6 @@ <?xml version="1.0" standalone="no"?> <!-- - Copyright 1999-2004 The Apache Software Foundation + Copyright 1999-2005 The Apache Software Foundation Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -15,8 +15,7 @@ limitations under the License. --> <!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd"> <document> <header> <title>FOP: Getting Help</title> @@ -72,6 +71,7 @@ If so, please do not post a mailing list question or report another issue, as th <section id="user-mailing-list"> <title>Submit Question to FOP User Mailing List</title> <p>See <link href="maillist.html#fop-user">FOP User Mailing List</link> for details.</p> + <note label="Important">Please don't write to any developer directly. Only if you submit questions to the <link href="maillist.html#fop-user">FOP User Mailing List</link> will other FOP users be able to profit from answers given to your question. Another point is that a developer may have gone inactive or is on holidays in which case you may not get an answer in time.</note> </section> <section id="enter-issue"> <title>Enter an Issue Report</title> diff --git a/src/documentation/content/xdocs/maillist.xml b/src/documentation/content/xdocs/maillist.xml index 5d2e40d3c..fe07842b3 100644 --- a/src/documentation/content/xdocs/maillist.xml +++ b/src/documentation/content/xdocs/maillist.xml @@ -15,8 +15,7 @@ limitations under the License. --> <!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd"> <document> <header> <title>FOP: Mailing List Resources</title> @@ -44,7 +43,7 @@ If you are using Microsoft Outlook, this setting can be found at the "Mail Forma <p>To review the archives, you have several options:</p> <ul> - <li>The <link href="http://mail-archives.eu.apache.org/mod_mbox/xmlgraphics-fop-users/">Apache Mailing List archive</link> (mod_mbox archive).</li> + <li>The <link href="http://mail-archives.apache.org/mod_mbox/xmlgraphics-fop-users/">Apache Mailing List archive</link> (mod_mbox archive).</li> <li>The <link href="http://xmlgraphics.apache.org/mail/fop-users/">Apache Mailing List archive</link> (gzip files).</li> <li>The <jump href="http://marc.theaimsgroup.com/?l=fop-user&r=1&w=2">Mailing list ARChives </jump> (MARC) at the AIMS group (search).</li> <li>The <jump href="http://mail-archives.apache.org/eyebrowse/SummarizeList?listName=fop-user@xml.apache.org">Apache Eyebrowse</jump> archive (search, list by date, author, subject, or thread).</li> @@ -55,7 +54,7 @@ If you are using Microsoft Outlook, this setting can be found at the "Mail Forma <title>Subscription Information</title> <ul> <li>See <link href="http://xmlgraphics.apache.org/mail.html">Apache XML Graphics Mailing Lists</link> for detailed subscription information.</li> - <li>To subscribe (digest only): Send email to <link href="mailto:fop-user-digest-subscribe@xmlgraphics.apache.org">fop-users-digest-subscribe@xmlgraphics.apache.org</link>.</li> + <li>To subscribe (digest only): Send email to <link href="mailto:fop-users-digest-subscribe@xmlgraphics.apache.org">fop-users-digest-subscribe@xmlgraphics.apache.org</link>.</li> <li>To subscribe fully: Send email to <link href="mailto:fop-users-subscribe@xmlgraphics.apache.org">fop-users-subscribe@xmlgraphics.apache.org</link>.</li> <li>For standard help: Send email to <link href="mailto:fop-users-help@xmlgraphics.apache.org">fop-users-help@xmlgraphics.apache.org</link>.</li> <li>To unsubscribe: Send email to <link href="mailto:fop-users-unsubscribe@xmlgraphics.apache.org">fop-users-unsubscribe@xmlgraphics.apache.org</link>.</li> diff --git a/src/documentation/content/xdocs/site.xml b/src/documentation/content/xdocs/site.xml index 599ded6a9..4797f245f 100644 --- a/src/documentation/content/xdocs/site.xml +++ b/src/documentation/content/xdocs/site.xml @@ -1,6 +1,6 @@ <?xml version="1.0"?> <!-- - Copyright 2002-2004 The Apache Software Foundation + Copyright 2002-2005 The Apache Software Foundation Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -19,7 +19,7 @@ <about label="About"> <index label="Introduction" href="index.html"/> <license label="Release Notes" href="relnotes.html"/> - <download label="Download" href="http://www.apache.org/dyn/closer.cgi/xml/fop/"/> + <download label="Download" href="download.html"/> <help label="Getting Help" href="gethelp.html"/> <faqs label="FAQs" href="faq.html"/> <maillist label="Mailing Lists" href="maillist.html"/> @@ -53,7 +53,7 @@ <xsl-fo label="XSL-FO" href="fo.html"/> <examples label="Examples" href="examples.html"/> <bugs label="Bugs" href="bugs.html"/> - <wiki label="Wiki" href="http://wiki.apache.org/xmlgraphics-fop/FOPProjectPages"/> + <wiki label="Wiki" href="http://wiki.apache.org/xmlgraphics-fop/FrontPage"/> <other label="Other" href="resources.html"/> </resources> @@ -97,7 +97,7 @@ <resources label="Resources"> <faq label="FAQs" href="faq.html"/> <tools label="Tools" href="tools.html"/> - <view-cvs label="ViewCVS" href="http://cvs.apache.org/viewcvs.cgi/xml-fop"/> + <viewcvs label="ViewCVS" href="http://svn.apache.org/viewcvs.cgi/xmlgraphics/fop"/> </resources> <subpackages label="SubPackages"> @@ -150,6 +150,8 @@ <input-modules href="userdocs/concepts/modules.html"/> <views href="userdocs/concepts/views.html"/> </cocoon--> + <xmlgraphics.apache.org href="http://xmlgraphics.apache.org"> + </xmlgraphics.apache.org> <xml.apache.org href="http://xml.apache.org/"> <forrest href="forrest/"/> <xindice href="xindice/"/> diff --git a/src/documentation/content/xdocs/team.xml b/src/documentation/content/xdocs/team.xml index 83eeefcf8..b37099b37 100644 --- a/src/documentation/content/xdocs/team.xml +++ b/src/documentation/content/xdocs/team.xml @@ -15,9 +15,7 @@ limitations under the License. --> <!-- $Id$ --> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> - +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd"> <document> <header> <title>FOP: Development Team</title> @@ -30,6 +28,7 @@ <link href="mailto:fop-dev@xmlgraphics.apache.org">fop-dev</link> mailing list.</p> <section id="commit-active"> <title>Active Committers</title> + <note label="Important">Please don't write to any developer directly if you need help on using FOP. Only if you submit questions to the <link href="maillist.html#fop-user">FOP User Mailing List</link> will other FOP users be able to profit from answers given to your question. Another point is that a developer may have gone inactive or is on holidays in which case you may not get an answer in time.</note> <ul> <li id="fb"><link href="mailto:bckfnn@worldonline.dk">Finn Bock</link> (FB)</li> <li id="cb"><link href="mailto:bowditch_chris@hotmail.com">Chris Bowditch</link> (CB) |