diff options
| author | Peter Bernard West <pbwest@apache.org> | 2003-01-24 00:47:03 +0000 |
|---|---|---|
| committer | Peter Bernard West <pbwest@apache.org> | 2003-01-24 00:47:03 +0000 |
| commit | 1f123d45644f9302694751f80d2ebd3d9b8a8237 (patch) | |
| tree | 8b73f5b262a965b6c6bc50f8bf7c4b4dd8679c9f /src | |
| parent | c35eb77955ab418b372f75bc3baa2755cb57ba43 (diff) | |
| download | xmlgraphics-fop-1f123d45644f9302694751f80d2ebd3d9b8a8237.tar.gz xmlgraphics-fop-1f123d45644f9302694751f80d2ebd3d9b8a8237.zip | |
Using HTML files in src/documentation/content/design/alt.design/properties for code documentation tests.
git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@195880 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'src')
8 files changed, 0 insertions, 1279 deletions
diff --git a/src/documentation/content/xdocs/design/alt.design/properties/PropertyConsts-class.xml b/src/documentation/content/xdocs/design/alt.design/properties/PropertyConsts-class.xml deleted file mode 100644 index 9a90267fd..000000000 --- a/src/documentation/content/xdocs/design/alt.design/properties/PropertyConsts-class.xml +++ /dev/null @@ -1,30 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd"> -<document> - <header> - <title>PropertyConsts Description</title> - <authors> - <person id="pbw" name="Peter B. West" email="pbwest@powerup.com.au"/> - </authors> - </header> - <body> - <section> - <title>Introduction</title> - <p> - <fork href= "../PropertyConsts.html" >This class</fork>, and - the singleton object which is <fork href= - "../PropertyConsts.html#pconsts" >generated by the static - initializer</fork>, is essentially a repository of the static - data from the property classes of - <code>org.apache.fop.fo.property</code>, and a common point of - access for the methods of those classes. - </p> - </section> - <section> - <title>Common static data</title> - <p></p> - </section> - </body> -</document> - diff --git a/src/documentation/content/xdocs/design/alt.design/properties/book.xml b/src/documentation/content/xdocs/design/alt.design/properties/book.xml deleted file mode 100644 index 4cb6871b0..000000000 --- a/src/documentation/content/xdocs/design/alt.design/properties/book.xml +++ /dev/null @@ -1,23 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-cocoon2/src/documentation/xdocs/dtd/book-cocoon-v10.dtd"> - -<book software="FOP" - title="FOP Alternative Design Properties Notes" - copyright="@year@ The Apache Software Foundation" - xmlns:xlink="http://www.w3.org/1999/xlink" - > - <menu label="Index"> - <menu-item label="FOP Home" href="../../index.html"/> - <menu-item label="Alt Design" href="../index.html"/> - </menu> - <menu label="Alt properties"> - <menu-item label="Introduction" href="index.html"/> - <menu-item label="Classes overview" href="classes-overview.html"/> - <menu-item label="PropertyConsts" href="PropertyConsts-class.html"/> - <menu-item label="Simple Properties" href="simple-properties.html"/> - <menu-item label="getInitialValue" href="getInitialValue.html"/> - <menu-item label="Enumerated data" href="enumerated-values.html"/> - <menu-item label="Property parsing" href="propertyExpressions.html"/> - </menu> -</book> diff --git a/src/documentation/content/xdocs/design/alt.design/properties/classes-overview.xml b/src/documentation/content/xdocs/design/alt.design/properties/classes-overview.xml deleted file mode 100644 index b00a51d14..000000000 --- a/src/documentation/content/xdocs/design/alt.design/properties/classes-overview.xml +++ /dev/null @@ -1,276 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd"> - -<document> - <header> - <title>Property classes overview</title> - <authors> - <person id="pbw" name="Peter B. West" - email="pbwest@powerup.com.au"/> - </authors> - </header> - <body> - <section> - <title>Properties: packages</title> - <section> - <title>org.apache.fop.fo</title> - <dl> - <dt> - <fork href="PropNames.html"><em>PropNames</em></fork> - </dt> - <dd> - This class maintains an array of <fork href= - "PropNames.html#propertyNames" >property names</fork>, - synchronized to a complete set of property name <fork - href= "PropNames.html#NO_PROPERTY" >constants</fork> for - indexing property-based arrays. It includes methods to - <fork href= "PropNames.html#getPropertyName" >convert an - index to a name</fork> and to <fork href= - "PropNames.html#getPropertyIndex" >convert a property name - to an index</fork>. - </dd> - - <dt> - <fork href= "PropertyConsts-class.html" - ><em>PropertyConsts</em></fork> - </dt> - <dd> - A singleton instance of <code>PropertyConsts</code> is - created by the static initializer of the <fork href= - "PropertyConsts.html#pconsts" >pconsts</fork> 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 <fork href= - "PropertyConsts.html#setupProperty" >setupProperty</fork>, - 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> - <fork href= "PropertySets.html" - ><em>PropertySets</em></fork> - </dt> - <dd> - This class provides a number of - <code>ROBitSet</code>s representing many of the sets - of properties defined in <em>Section 7</em> of the - specification. Note that the <em>Border</em>, - <em>Padding</em> and <em>Background</em> sets are - defined separately. - </dd> - - <dt><fork href= "FOPropertySets.html" - ><em>FOPropertySets</em></fork></dt> - <dd> - This class provides a number of - <code>ROBitSet</code>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><fork href= "ShorthandPropSets.html" - ><em>ShorthandPropSets</em></fork></dt> - <dd> - This class contains arrays of <fork href= - "ShorthandPropSets.html#shorthands" >shorthand property - indices</fork> and <fork href= - "ShorthandPropSets.html#compounds" >compound property - indices</fork>, and <code>ROBitSet</code>s representing - the expansion sets of these shorthands and compounds. - Various methods useful in the expansion of these - properties are also included. - </dd> - - <dt> - <fork href= "FOAttributes.html" - ><em>FOAttributes</em></fork> - </dt> - <dd> - This class manages the attribute set that is associated - with a SAX <code>startElement</code> event. <em>fo:</em> - namespace attributes are entered into a - <code>HashMap</code>, indexed by the <em>fo:</em> - <property> index. As other namespaces are - encountered, the values are entered into - namespace-specific <code>HashMap</code>s, indexed by the - <em>local name</em> of the attribute. - </dd> - - </dl> - </section> - <section> - <title>org.apache.fop.fo.properties</title> - <dl> - <dt><em>Property</em></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> - </section> - <section> - <title>org.apache.fop.fo.expr</title> - <dl> - <dt><fork href= "PropertyTokenizer.html" - ><em>PropertyTokenizer</em></fork></dt> - <dd> - The tokenizer for the <property> expression parser. - Defines a set of <fork href= "PropertyTokenizer.html#EOF" - >token constants</fork> and returns these with associated - token values. - </dd> - - <dt><fork href= "PropertyParser.html" - ><em>PropertyParser</em></fork></dt> - <dd> - This extends <code>PropertyTokenizer</code>. It - parses <property> expressions on the basis of the - tokens passed to it by its superclass, generating - <code>PropertyValue</code>s, including - <code>PropertyValueList</code>s. - </dd> - - <dt><em>PropertyException</em></dt> - <dd> - The basic class for all <property>-related - exceptions. It extends - <code>FOPException</code>. 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 - <code>PropertyException</code>. Also in this package - by accident. - </dd> - - </dl> - </section> - <section> - <title>org.apache.fop.datatypes</title> - <dl> - <dt> - <fork href= "PropertyValue.html" - ><em>PropertyValue</em></fork> - </dt> - <dd> - An <em>interface</em> which all - <code>PropertyValue</code> classes must implement. In - addition to a few methods, <code>PropertyValue</code> - defines the set of <fork href= - "PropertyValue.html#NO_TYPE" >constants</fork> which the - <code>getType()</code> method may return; i.e. the valid - set of <code>PropertyValue</code> types. - </dd> - - <dt><em>AbstractPropertyValue</em></dt> - <dd> - An abstract implementation of the - <code>PropertyValue</code> interface. Most actual - property value classes extend - <code>AbstractPropertyValue</code>. - </dd> - - <dt><em>PropertyValueList</em></dt> - <dd> - This class extends <code>LinkedList</code> and implements - <code>PropertyValue</code>. It is used whenever the - process of resolving a property expression yields a list - of <code>PropertyValue</code> elements; notably during the - processing of shorthands and "compound" properties. - </dd> - - <dt><em>StringType</em></dt> - <dd> - A basic type extending <code>AbstractPropertyValue</code>. - Extended by <code>NCName</code>. - </dd> - - <dt><em>NCName</em></dt> - <dd> - Extends <code>StringType</code> to represent - NCName strings. - </dd> - - <dt><em>EnumType</em></dt> - <dd> - Extends <code>AbstractPropertyValue</code> to represented - enumerated types. - </dd> - - <dt> - <em>Other types</em> - </dt> - <dd> - All other types extend one of the above classes. - </dd> - - </dl> - </section> - <section> - <title>org.apache.fop.datatypes.indirect</title> - <dl> - <dt><em>IndirectValue</em></dt> - <dd> - The base type for all indirect value types; extends - <code>AbstractPropertyValue</code>. - </dd> - </dl> - </section> - </section> - <p> - <strong>Previous:</strong> <link href= "alt-properties.html" - >alt.properties</link> - </p> - <!-- - <p> - <strong>Next:</strong> <link href= "properties-classes.html" - >Properties classes</link> - </p> - --> - </body> -</document> - diff --git a/src/documentation/content/xdocs/design/alt.design/properties/enumerated-values.xml b/src/documentation/content/xdocs/design/alt.design/properties/enumerated-values.xml deleted file mode 100644 index f5019b76b..000000000 --- a/src/documentation/content/xdocs/design/alt.design/properties/enumerated-values.xml +++ /dev/null @@ -1,220 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd" > - -<document> - <header> - <title>Enumerated Data Values</title> - </header> - <body> - <section> - <title>Enumerated Data Values</title> - <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 <code>HashMap</code>. - The switch-over point from array to <code>HashMap</code> 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> - - <section> - <title id="enum-property-array" >Array representation</title> - - <p> - <fork href= "Direction.html" ><code - >org.apache.fop.fo.properties.Direction</code></fork > is an - example of a class which supports an enumerated value with a - small set of tokens. The <fork href= - "Direction.html#dataTypes" ><code>dataTypes</code></fork > - field contains the <fork href= "Property.html#NOTYPE" ><code - >ENUM</code> data type constant, defined in <code - >Property</code></fork >. The enumeration integer constants - are defined as <code>public static final int</code> - values, <fork href= "Direction.html#LTR" ><code>LTR</code> - and <code>RTL</code></fork >. Associating enumeration - tokens with these integer constants occurs in the array - <fork href= "Direction.html#rwEnums" ><code>String[] - rwEnums</code></fork >, 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 <code - >rwEnums</code> and the enumeration constants be - maintained.` - </p> - <p> - The publicly accessible mapping from enumeration token to - enumeration constant is achieved through the method <fork - href= "Direction.html#getEnumIndex" ><code>int - getEnumIndex(String)</code></fork >. The corresponding - mapping from enumeration constant to enumeration token is - achieved through the method <fork href= - "Direction.html#getEnumText" ><code>String - getEnumText(int)</code></fork >. - </p> - - </section> - - <section> - <title id="enum-property-hashmap" >HashMap representation</title> - - <p> - <fork href= "RenderingIntent.html" ><code - >org.apache.fop.fo.properties.RenderingIntent</code></fork > - is an example of a class which supports an enumerated value - with a larger set of tokens. The <fork href= - "RenderingIntent.html#dataTypes" ><code>dataTypes</code - ></fork > field contains the <fork href= - "Property.html#NOTYPE" ><code>ENUM</code> data type - constant, defined in <code>Property</code></fork >. - Enumeration integer constants are defined as <fork - href= "RenderingIntent.html#PERCEPTUAL" ><code>public static - final int</code></fork > values. Zero is never used to - represent a valid enumeration constant. The enumeration - tokens are stored in the array <fork href= - "RenderingIntent.html#rwEnums" ><code>String[] rwEnums</code - ></fork >, which is initialized with the token strings. - Association of enumeration tokens with the integer constants - occurs in the <code>HashMap</code> <fork href= - "RenderingIntent.html#rwEnumHash" ><code> rwEnumHash</code - ></fork >, which is initialized from the token array in a - <code>static {}</code> initializer. It is, of course, - critical that synchronization between <code>rwEnums</code> - and the enumeration constants be maintained.` - </p> - <p> - The publicly accessible mapping from enumeration token to - enumeration constant is achieved through the method <fork - href= "RenderingIntent.html#getEnumIndex" ><code>int - getEnumIndex(String)</code></fork >. The corresponding - mapping from enumeration constant to enumeration token is - achieved through the method <fork href= - "RenderingIntent.html#getEnumText" ><code>String - getEnumText(int)</code></fork >. - </p> - </section> - <section> - <title id= "common-enum-values" > - Factoring Out Common Enumeration Values - </title> - <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 - <fork href= "BorderCommonStyle.html" ><code - >BorderCommonStyle</code></fork >. Like a property with a - normal HashMap representation of an enumerated value, - BorderCommonStyle defines <fork href= - "BorderCommonStyle.html#PERCEPTUAL" ><code>public static - final int</code></fork > enumeration integer constants. - Similarly, the enumeration tokens are stored in the array - <fork href= "BorderCommonStyle.html#rwEnums" ><code - >String[] rwEnums</code></fork >, and the association of - enumeration tokens with the integer constants occurs in the - <code>HashMap</code> <fork href= - "BorderCommonStyle.html#rwEnumHash" ><code> - rwEnumHash</code></fork >, initialized in a <code>static - {}</code> initializer. The mapping methods <fork href= - "BorderCommonStyle.html#getEnumIndex" ><code>int - getEnumIndex(String)</code></fork > and <fork href= - "BorderCommonStyle.html#getEnumText" ><code>String - getEnumText(int)</code></fork > are also present. - </p> - - <p> - Notice, however, that the class has none of the static data - constants described in the discussion of <link href= - "simple-properties.html" >simple properties</link>. These - values are defined in the individual sub-classes of this - class, e.g. <fork href= "BorderLeftStyle.html" ><code - >BorderLeftStyle</code></fork >. None of the above fields - or methods occur, and <code>BorderLeftStyle</code> is left - looking like an example of a simple property. The - enumeration mapping methods are, however, available through - the super-class <code>BorderCommonStyle</code>. - </p> - - </section> - - <section> - <title>Mapped Numeric Values</title> - <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 <code>Numeric</code> result. Their - resolution involves mapping the token to the indicated - <code>Numeric</code> value. - </p> - <p> - An example is the <fork href= "BorderCommonWidth.html" - ><code>BorderCommonWidth</code></fork > property. This, - like the example of <link href= "#common-enum-values" ><code - >BorderCommonStyle</code></link > above, also represents - common enumerated values which have been factored out to - form a super-class for particular properties. <code - >BorderCommonWidth</code>, therefore, also defines <fork - href= "BorderCommonWidth.html#THIN" ><code>enumeration - constant values</code></fork > and an array of tokens. In - this case, there is no <code>HashMap</code>, because of the - limited number of tokens, but the mapping methods <fork - href= "BorderCommonWidth.html#getEnumIndex" ><code>int - getEnumIndex(String)</code></fork > and <fork href= - "BorderCommonWidth.html#getEnumText" ><code>String - getEnumText(int)</code></fork > are present. - </p> - - <p> - The added element in this property is the array <fork href= - "BorderCommonWidth.html#mappedPoints" ><code>double[] - mappedPoints</code></fork >. The entries in this array - must by maintained in syncronization with the <fork href= - "BorderCommonWidth.html#rwEnums" ><code>String[] - rwEnums</code></fork > array of tokens and the set of <fork - href= "BorderCommonWidth.html#THIN" >enumeration - constants</fork >. The mapping from token to Numeric value - is achieved by the <fork href= - "BorderCommonWidth.html#getMappedLength" ><code>Numeric - getMappedLength(FONode, int, int)</code></fork > method. - </p> - <p> - <fork href= "BorderLeftWidth.html" ><code - >BorderLeftWidth</code></fork > extends <fork href= - "BorderCommonWidth.html" ><code>BorderCommonWidth</code - ></fork >. It includes the basic static data, like <link - href= "simple-properties.html" >simple properties</link>, - and, in this case, the <fork href= - "BorderLeftWidth.html#getInitialValue" ><code>PropertyValue - getInitialValue(int)</code></fork > method to derive the - initial value. - </p> - <section> - <title>Deriving Mapped Numeric Values</title> - <p> - As usual with property values, the usual method of - deriving a mapped numeric value is by calling the <fork - href= "../PropertyConsts.html#getMappedNumeric" ><code - >Numeric getMappedNumeric(FONode, int, int)</code></fork - > method in <fork href= "../PropertyConsts.html#pconsts" - ><code>pconsts</code></fork >. All properties which - support a mapped numeric value must have a <code>Numeric - getMappedNumeric(FONode, int)</code> method, which will - be called through its singleton instance by the <code - >PropertyConsts</code> method. - </p> - </section> - </section> - </section> - </body> -</document> diff --git a/src/documentation/content/xdocs/design/alt.design/properties/getInitialValue.xml b/src/documentation/content/xdocs/design/alt.design/properties/getInitialValue.xml deleted file mode 100644 index 4f5a1351d..000000000 --- a/src/documentation/content/xdocs/design/alt.design/properties/getInitialValue.xml +++ /dev/null @@ -1,89 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd"> -<document> - <header> - <title>Generating Initial Values</title> - <authors> - <person id="pbw" name="Peter B. West" email="pbwest@powerup.com.au"/> - </authors> - </header> - <body> - <section> - <title>Introduction</title> - <p> - The <link href= "property-data.html" >previous section</link> - 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> - </section> - <section> - <title id= "initial-values" > - Generating & Accessing Initial Values - </title> - - <p> - <fork href= "AutoRestore.html" ><code - >org.apache.fop.fo.properties.AutoRestore</code ></fork> is an - example of a 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 <fork href= "AutoRestore.html#getInitialValue" - ><code >PropertyValue getInitialValue(int)</code ></fork > - 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 <fork href= - "../PropertyConsts.html" ><code >PropertyConsts</code ></fork> - singleton <fork href= "../PropertyConsts.html#pconsts" ><code - >pconsts</code ></fork>.` As with the fields, the first - invocation of the method <fork href= - "../PropertyConsts.html#setupProperty" ><code - >setupProperty</code ></fork> on the property instantiates the - singleton instance of the class, and stores that instance in - the in the <fork href= "../PropertyConsts.html#properties" - ><code >Property[] properties</code ></fork> array of <fork - href= "../PropertyConsts.html#pconsts" ><code >pconsts</code - ></fork>. - </p> - - <p> - Unlike the static data fields, however, the initial value is - not immediately generated. It is generated by a call to <fork - href= "../PropertyConsts.html#getInitialValue" ><code - >PropertyValue getInitialValue(int)</code ></fork> in <fork - href= "../PropertyConsts.html#pconsts" ><code >pconsts</code - ></fork>. A side-effect of this call is to store the initial - value in <fork - href="../PropertyConsts.html#initialValues"><code - >PropertyValue[] initialValues</code ></fork>. - </p> - <section> - <title>Properties without - <code>getInitialValue()</code></title> - <p> - What about property classes which have no - <code>getInitialValue()</code> method? The simplest - classes, e.g. <code>Character</code>, fall into this - category. As <link href= - "classes-overview.html#property-classes" >noted - previously</link >, all of the property classes extend <code - >org.apache.fop.fo.properties.Property</code >. <fork href= - "Property.html" ><code >Property</code ></fork > provides a - base <fork href= "Property.html#getInitialValue" ><code - >PropertyValue getInitialValue(int)</code ></fork> method to - which the simple classes fall back. Note that it is only - valid for <code >NOTYPE_IT</code >, <code >AUTO_IT</code >, - <code >NONE_IT</code > and <code >AURAL_IT</code > initial - value types, so all classes which have any other initial - value type must override this method. - </p> - </section> - </section> - </body> -</document> diff --git a/src/documentation/content/xdocs/design/alt.design/properties/index.xml b/src/documentation/content/xdocs/design/alt.design/properties/index.xml deleted file mode 100644 index 9414aa82c..000000000 --- a/src/documentation/content/xdocs/design/alt.design/properties/index.xml +++ /dev/null @@ -1,153 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.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.xml b/src/documentation/content/xdocs/design/alt.design/properties/propertyExpressions.xml deleted file mode 100644 index 97b8b7d55..000000000 --- a/src/documentation/content/xdocs/design/alt.design/properties/propertyExpressions.xml +++ /dev/null @@ -1,342 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd" > - -<document> - <header> - <title>Property Expression Parsing</title> - <authors> - <person id="pbw" name="Peter B. West" email="pbwest@powerup.com.au"/> - </authors> - </header> - <body> - <section> - <title>Property expression parsing</title> - <p> - The parsing of property value expressions is handled by two - closely related classes: <fork href= - "../PropertyTokenizer.html" ><code - >org.apache.fop.fo.expr.PropertyTokenizer</code ></fork > and - its subclass, <fork href= "../PropertyParser.html" ><code - >org.apache.fop.fo.expr.PropertyParser</code ></fork >, and by - refineParsing(int, FONode, PropertyValue) methods in the - individual property classes.. <code >PropertyTokenizer</code - >, as the name suggests, handles the tokenizing of the - expression, handing <em>tokens</em> back to its subclass, - <code >PropertyParser</code >. <code >PropertyParser</code >, - in turn, returns a <code >PropertyValueList</code >, a list of - <code >PropertyValue</code >s. - </p> - <p> - The tokenizer and parser rely in turn on the datatype - definition from the <code >org.apache.fop.datatypes</code > - package and the datatype <code >static final int</code > - constants from <code >PropertyConsts</code >. - </p> - <section> - <title>Data types</title> - <p> - The data types currently defined in - <code >org.apache.fop.datatypes</code > include: - </p> - <table> - <tr><th colspan="2" >Numbers and lengths</th></tr> - <tr> - <th>Numeric</th> - <td colspan="3" > - The fundamental numeric data type. <em>Numerics</em> of - various types are constructed by the classes listed - below. - </td> - </tr> - <tr> - <td/> - <th colspan="3" >Constructor classes for <em>Numeric</em></th> - </tr> - <tr> - <td/><td>Angle</td> - <td colspan="2" >In degrees(deg), gradients(grad) or - radians(rad)</td> - </tr> - <tr> - <td/><td>Ems</td> - <td colspan="2" >Relative length in <em>ems</em></td> - </tr> - <tr> - <td/><td>Frequency</td> - <td colspan="2" >In hertz(Hz) or kilohertz(kHz)</td> - </tr> - <tr> - <td/><td>IntegerType</td><td/> - </tr> - <tr> - <td/><td>Length</td> - <td colspan="2" >In centimetres(cm), millimetres(mm), - inches(in), points(pt), picas(pc) or pixels(px)</td> - </tr> - <tr> - <td/><td>Percentage</td><td/> - </tr> - <tr> - <td/><td>Time</td> - <td>In seconds(s) or milliseconds(ms)</td> - </tr> - <tr><th colspan="2" >Strings</th></tr> - <tr> - <th>StringType</th> - <td colspan="3" > - Base class for data types which result in a <em>String</em>. - </td> - </tr> - <tr> - <td/><th>Literal</th> - <td colspan="2" > - A subclass of <em>StringType</em> for literals which - exceed the constraints of an <em>NCName</em>. - </td> - </tr> - <tr> - <td/><th>MimeType</th> - <td colspan="2" > - A subclass of <em>StringType</em> for literals which - represent a mime type. - </td> - </tr> - <tr> - <td/><th>UriType</th> - <td colspan="2" > - 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/><th>NCName</th> - <td colspan="2" > - A subclass of <em>StringType</em> for literals which - meet the constraints of an <em>NCName</em>. - </td> - </tr> - <tr> - <td/><td/><th>Country</th> - <td>An RFC 3066/ISO 3166 country code.</td> - </tr> - <tr> - <td/><td/><th>Language</th> - <td>An RFC 3066/ISO 639 language code.</td> - </tr> - <tr> - <td/><td/><th>Script</th> - <td>An ISO 15924 script code.</td> - </tr> - <tr><th colspan="2" >Enumerated types</th></tr> - <tr> - <th>EnumType</th> - <td colspan="3" > - An integer representing one of the tokens in a set of - enumeration values. - </td> - </tr> - <tr> - <td/><th>MappedEnumType</th> - <td colspan="2" > - A subclass of <em>EnumType</em>. Maintains a - <em>String</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>String</em> "12pt". - </td> - </tr> - <tr><th colspan="2" >Colors</th></tr> - <tr> - <th>ColorType</th> - <td colspan="3" > - 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" >Fonts</th></tr> - <tr> - <th>FontFamilySet</th> - <td colspan="3" > - Maintains an array of <em>String</em>s containing a - prioritized list of possibly generic font family names. - </td> - </tr> - <tr><th colspan="2" >Pseudo-types</th></tr> - <tr> - <td colspan="4" > - 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>Inherit</th> - <td colspan="3" > - For values of <em>inherit</em>. - </td> - </tr> - <tr> - <th>Auto</th> - <td colspan="3" > - For values of <em>auto</em>. - </td> - </tr> - <tr> - <th>None</th> - <td colspan="3" > - For values of <em>none</em>. - </td> - </tr> - <tr> - <th>Bool</th> - <td colspan="3" > - For values of <em>true/false</em>. - </td> - </tr> - <tr> - <th>FromNearestSpecified</th> - <td colspan="3" > - 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>FromParent</th> - <td colspan="3" > - 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> - </section> - <section> - <title>Tokenizer</title> - <p> - The tokenizer returns one of the following token - values: - </p> - <source> - static final int - EOF = 0 - ,NCNAME = 1 - ,MULTIPLY = 2 - ,LPAR = 3 - ,RPAR = 4 - ,LITERAL = 5 - ,FUNCTION_LPAR = 6 - ,PLUS = 7 - ,MINUS = 8 - ,MOD = 9 - ,DIV = 10 - ,COMMA = 11 - ,PERCENT = 12 - ,COLORSPEC = 13 - ,FLOAT = 14 - ,INTEGER = 15 - ,ABSOLUTE_LENGTH = 16 - ,RELATIVE_LENGTH = 17 - ,TIME = 18 - ,FREQ = 19 - ,ANGLE = 20 - ,INHERIT = 21 - ,AUTO = 22 - ,NONE = 23 - ,BOOL = 24 - ,URI = 25 - ,MIMETYPE = 26 - // NO_UNIT is a transient token for internal use only. It is - // never set as the end result of parsing a token. - ,NO_UNIT = 27 - ; - </source> - <p> - 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 <code >content-type</code > introduces this - complication. It can have two values of the form - <strong>content-type:</strong><em>mime-type</em> - (e.g. <code >content-type="content-type:xml/svg"</code >) or - <strong>namespace-prefix:</strong><em>prefix</em> - (e.g. <code >content-type="namespace-prefix:svg"</code >). The - experimental code reduces these options to the payload - in each case: an <code >NCName</code > in the case of a - namespace prefix, and a MIMETYPE in the case of a - content-type specification. <code >NCName</code >s cannot - contain a "/". - </dd> - </dl> - </section> - <section> - <title>Parser</title> - <p> - The parser retuns a <code >PropertyValueList</code >, - necessary because of the possibility that a list of - <code >PropertyValue</code > elements may be returned from the - expressions of soem properties. - </p> - <p> - <code >PropertyValueList</code >s may contain - <code >PropertyValue</code >s or other - <code >PropertyValueList</code >s. This latter provision is - necessitated for the peculiar case of of - <em>text-shadow</em>, which may contain whitespace separated - sublists of either two or three elements, separated from one - another by commas. To accommodate this peculiarity, comma - separated elements are added to the top-level list, while - whitespace separated values are always collected into - sublists to be added to the top-level list. - </p> - <p> - Other special cases include the processing of the core - functions <code >from-parent()</code > and - <code >from-nearest-specified-value()</code > 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 - <code >FromParent</code > and - <code >FromNearestSpecified</code > 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> - </section> - </section> - </body> -</document> - diff --git a/src/documentation/content/xdocs/design/alt.design/properties/simple-properties.xml b/src/documentation/content/xdocs/design/alt.design/properties/simple-properties.xml deleted file mode 100644 index f73f56f48..000000000 --- a/src/documentation/content/xdocs/design/alt.design/properties/simple-properties.xml +++ /dev/null @@ -1,146 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" - "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd"> -<document> - <header> - <title>Simple <property> Classes</title> - <authors> - <person id="pbw" name="Peter B. West" email="pbwest@powerup.com.au"/> - </authors> - </header> - <body> - <section> - <title>Introduction</title> - <p> - An <link href= "../classes-overview.html" >overview of the - properties and classes</link> 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 <fork - href= "../PropertyConsts.html" ><code >PropertyConsts</code - ></fork> class and its singleton object. - </p> - </section> - <section> - <title>Common data</title> - - <p> - <fork href= "Character.html" ><code - >org.apache.fop.fo.properties.Character</code ></fork> is an - example of a basic property class. The data fields common to - all properties are: - </p> - - <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 <fork href= "Property.html#NOTYPE" - ><code >org.apache.fop.fo.properties.Property</code - ></fork>, 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 <fork href= - "Property.html#NO_TRAIT" ><code - >org.apache.fop.fo.properties.Property</code ></fork>, 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 <fork href= - "Property.html#NOTYPE_IT" ><code - >org.apache.fop.fo.properties.Property</code ></fork>. In - the simplest property classes, such as - <code>Character</code>, there is no defined initial value - type. - </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 <fork href= "Property.html#NO" ><code - >org.apache.fop.fo.properties.Property</code ></fork>. - </dd> - </dl> - </section> - <section> - <title>Accessing <property> Data Constants</title> - - <p> - The constants above are generally accessed through the arrays - maintained in the <fork href= "../PropertyConsts.html" ><code - >PropertyConsts</code ></fork> singleton <fork href= - "../PropertyConsts.html#pconsts" ><code >pconsts</code - ></fork>. The first invocation of the method <fork href= - "../PropertyConsts.html#setupProperty" ><code - >setupProperty</code ></fork> on the property generates a - <code >Class</code > instance for the class, and stores it in - the array <fork href= "../PropertyConsts.html#classes" ><code - >classes</code ></fork>. This <code>Class</code> object is - used, in turn, to instantiate the singleton instance of the - class, which is stored in the <fork href= - "../PropertyConsts.html#properties" ><code >Property[] - properties</code ></fork> array of <fork href= - "../PropertyConsts.html#pconsts" ><code >pconsts</code - ></fork>. - </p> - - <p> - <em>Reflection</em> methods are then used, via the same - <code>Class</code> instance, to extract and store the static - data fields. These arrays and associated access methods are: - </p> - - <dl> - <dt> - <fork href= "../PropertyConsts.html#datatypes" ><code >int[] - datatypes</code ></fork> - </dt> - <dd> - <fork href= "../PropertyConsts.html#getDataTypes" ><code - >int getDataTypes(int)</code ></fork> - </dd> - <dt> - <fork href= "../PropertyConsts.html#traitMappings" ><code - >int[] traitMappings</code ></fork> - </dt> - <dd> - <em>No access method yet defined.</em> - </dd> - <dt> - <fork href= "../PropertyConsts.html#initialValueTypes" - ><code >int[] initialValueTypes</code ></fork> - </dt> - <dd> - <fork href= "../PropertyConsts.html#getInitialValueTypes" - ><code >int getInitialValueTypes(int)</code ></fork> - </dd> - <dt> - <fork href= "../PropertyConsts.html#inherited" ><code >int[] - inherited</code ></fork> - </dt> - <dd> - <fork href= "../PropertyConsts.html#inheritance" ><code >int - inheritance(int)</code ></fork> - </dd> - </dl> - </section> - </body> -</document> |