diff options
| author | Keiron Liddle <keiron@apache.org> | 2002-11-11 09:23:48 +0000 |
|---|---|---|
| committer | Keiron Liddle <keiron@apache.org> | 2002-11-11 09:23:48 +0000 |
| commit | 05693a538b488336af0a83e402b6d7eb584c7a73 (patch) | |
| tree | d4a3b59ca54ea6cd99382f676a7581ee7f37811c /docs | |
| parent | a7a1db3511fd664f5906c8fb50b403528d43f1bb (diff) | |
| download | xmlgraphics-fop-05693a538b488336af0a83e402b6d7eb584c7a73.tar.gz xmlgraphics-fop-05693a538b488336af0a83e402b6d7eb584c7a73.zip | |
more to new docs
git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@195466 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/design/architecture.xml | 58 | ||||
| -rw-r--r-- | docs/design/areas.xml | 186 | ||||
| -rw-r--r-- | docs/design/book.xml | 27 | ||||
| -rw-r--r-- | docs/design/breakpos.xml | 289 | ||||
| -rw-r--r-- | docs/design/embedding.xml | 114 | ||||
| -rw-r--r-- | docs/design/extending.xml | 99 | ||||
| -rw-r--r-- | docs/design/fotree.xml | 92 | ||||
| -rw-r--r-- | docs/design/intro.xml | 51 | ||||
| -rw-r--r-- | docs/design/layout.xml | 438 | ||||
| -rw-r--r-- | docs/design/optimise.xml | 58 | ||||
| -rw-r--r-- | docs/design/properties.xml | 257 | ||||
| -rw-r--r-- | docs/design/renderers.xml | 30 | ||||
| -rw-r--r-- | docs/design/status.xml | 73 | ||||
| -rw-r--r-- | docs/design/useragent.xml | 176 |
14 files changed, 0 insertions, 1948 deletions
diff --git a/docs/design/architecture.xml b/docs/design/architecture.xml deleted file mode 100644 index a9a19e318..000000000 --- a/docs/design/architecture.xml +++ /dev/null @@ -1,58 +0,0 @@ -<?xml version="1.0" standalone="no"?> - -<document> - <header> - <title>Architecture</title> - <subtitle>Architecture information for FOP</subtitle> - <authors> - <person name="Arved Sandstrom"/> - </authors> - </header> - - <body> - -<s1 title="FOP Mechanics"> - -<s2 title="Introduction"> -<p> -The overall process is controlled by <em>org.apache.fop.apps.Driver</em>. -This class handles the FO Tree building, renderers, output and logging. -</p> -<p> -The process in general is that the FO document is sent to the tree -builder via SAX events. This creates an FO Tree. The FO Tree is then -handled by the layout processor which converts the FO Tree into an area -tree. This area tree is then given to the renderer and the renderer converts -the area tree into a stream of data containing the output document. -</p> -</s2> - -<s2 title="Formatting Object Tree"> -<p> -The class <em>org.apache.fop.fo.FOTreeBuilder</em> is responsible for -actually constructing the FO tree. The key SAX events used are </p> -<p><code>startElement()</code>,</p> -<p><code>endElement()</code> and <code>characters()</code>.</p> - -<p>All formatting objects derive from abstract class -<em>org.apache.fop.fo.FONode</em>. The other FO classes inherit from -<em>FONode</em> as follows:</p> - -</s2> - -<s2 title="Rendering"> -<p> -This is a separate process. The <code>render()</code> method in -<em>Driver</em> is invoked (say, -by <em>CommandLine</em>) with the laid-out <em>AreaTree</em> and a -<em>PrintWriter</em> as arguments. -This actually calls the <code>render()</code> method in a specific implementation of -the <em>Renderer</em> interface, typically <em>PDFRenderer</em> or -<em>AWTRenderer</em>. -</p> -</s2> - -</s1> - </body> -</document> - diff --git a/docs/design/areas.xml b/docs/design/areas.xml deleted file mode 100644 index d8b9c830f..000000000 --- a/docs/design/areas.xml +++ /dev/null @@ -1,186 +0,0 @@ -<?xml version="1.0" standalone="no"?> - -<!-- Overview --> - -<document> - <header> - <title>Area Tree</title> - <subtitle>Area Tree Design for FOP</subtitle> - <authors> - <person name="Keiron Liddle" email="keiron@aftexsw.com"/> - </authors> - </header> - - <body> -<s1 title="Area Tree"> -<p> -The code to implement the area tree will attempt to match the areas -defined in the specification. A number of optimisations may be possible -for similar areas and groups of areas. - </p> - <p> -Since the area tree will be used during the layout by the layout managers -it will need to store information that affects the layout. The information -such as spacing and keeps will be held in such a way that it can be -discarded once the layout is finalised. - </p> -<s2 title="Structure"> -<p> -The area tree is a root element that has a list of page-viewport-areas. -Each page viewport has a page-reference-area which holds the contents of -the page. To handle the processing better FOP does not maintain a list -at the root level but lets another class handle each page as it is added. - </p> - </s2> -<s2 title="Page"> -<p> -A page is made up of five area regions. These are before, start, body, -end and after. Each region has a viewport and contains the areas -produced from the children in the FO object heirarchy. - </p> - <p> -For the body area there are more subdivisions for before floats, -footnotes and the main reference area. The main reference area is -made from span areas which have normal flow reference areas as -children. The flow areas are then created inside these normal flow -reference areas. - </p> - <p> -Since the layout is done inside a page, the page is created from the -pagemaster with all the appropriate areas. The layout manager then -uses the page to add areas into the normal flow reference areas -and floats and footnotes. After the layout of the body region -is complete then the other regions can be done. - </p> - </s2> -<s2 title="Block Areas"> -<p> -Block areas are created and/or returned by all top level elements -in the flow. These areas have keep and spacing information that -needs to be retained until the page is finalised. A block area -is stacked with other block areas in a particular direction, it -has a size and it contains either line areas made from a group -of inline areas or block areas. - </p> - <p> -A block area can also be split into two block areas by splitting -between two line areas or splitting between two block areas (or -groups) that are stacked in the block progression direction of -the page. The split may also be in a child block area. - </p> - </s2> -<s2 title="Line Areas"> -<p> -A line areas is simply a collection of inline areas that are stacked -in the inline progression direction. A line area has a height and -width. It also contains information about floats and footnotes -that are associated with the inline areas. - </p> - <p> -A line area gets a set of inline areas added until complete then -it is justified and vertically aligned. If the line area contains -unresolved areas it will retain the justification information -until all areas are resolved. - </p> - </s2> -<s2 title="Inline Areas"> -<p> -There are a few different types of inline areas. All inline areas -have a height. Their width may be variable until the line is -finalised. - </p> - <p> -Unresolved areas can reserve some space to allow for possible -sizes once it is resolved. Then the line can be re-justified -and finalised. - </p> - </s2> -<s2 title="Cloning"> -<p> -Any subtree of the area tree should be cloneable so that for -areas that are repeated the area tree can simply be copied rather -than going through the layout again. This will only work if the -width is the same. - </p> - <p> -Resolveable areas may be converted into an unresolved form. - </p> - </s2> -<s2 title="Classes"> -<p> -The following class structure will be used to represent the area -tree. - </p> -<s3 title="Page Area Classes"> -<p> -The page area classes hold the top level layout of a page. The -areas are created by the page master and should be ready to have -flow areas added. - </p> - </s3> -<s3 title="Block Area Classes"> -<p> -The block areas typically hold either a set of line areas or a set of -block areas. The child areas are usually stacked in a particular -direction. - </p> - <p> -Areas for tables and lists have their child block areas stacked -in different ways. Lists also can have spacing between the block -areas. - </p> - </s3> -<s3 title="Inline Area Classes"> -<p> -The inline areas are used to make up a line area. An inline area -typically has a height, width and some content. The alignment is -used for block progression direction displacement and to determine -the height of a line. - </p> - </s3> - </s2> - -<s2 title="Rendering Area Tree"> -<p> -The rendering of an area tree is done by rendering each page -to a suitable output. The regions are rendered in order and each -region is contained by a viewport. - </p> - <p> -The relevent structures that will need to be rendered are: -Page -Viewport -Region -Span -Block -Line -Inline - </p> - <p> -The renderer will need to be able to: - <itemizedlist> - <listitem><para> -render each individual page - </para></listitem> - <listitem><para> -clip and align child areas to a viewport - </para></listitem> - <listitem><para> -handle all types of inline area, text, image etc. - </para></listitem> - <listitem><para> -draw various lines and rectangles - </para></listitem> - </itemizedlist> - </p> - <p> -An abstract renderer will be able to handle the generic positioning -of child areas, iterating through areas that have child areas. - </p> - </s2> - - </s1> - - </body> -</document> - diff --git a/docs/design/book.xml b/docs/design/book.xml deleted file mode 100644 index 315ed9cac..000000000 --- a/docs/design/book.xml +++ /dev/null @@ -1,27 +0,0 @@ -<?xml version="1.0"?> - -<book title="FOP Design" copyright="1999-2002 The Apache Software Foundation"> - <external href="http://xml.apache.org/fop/" label="About FOP"/> - <separator/> - <external href="understanding/index.html" label="Understanding" /> - <separator/> - <page id="index" label="Design" source="intro.xml"/> - <page id="architecture" label="Architecture" source="architecture.xml" /> - <page id="properties" label="Properties" source="properties.xml" /> - <page id="fotree" label="FO Tree" source="fotree.xml" /> - <page id="areatree" label="Area Tree" source="areas.xml" /> - <separator/> - <page id="layout" label="Layout" source="layout.xml" /> - <page id="breakpos" label="Break Possibility" source="breakpos.xml" /> - <page id="renderers" label="Renderers" source="renderers.xml" /> - <page id="useragent" label="User Agent" source="useragent.xml" /> - <page id="optimise" label="Optimisations" source="optimise.xml" /> - <separator/> - <page id="embedding" label="Embedding" source="embedding.xml" /> - <page id="extending" label="Extending" source="extending.xml" /> - <separator/> - <page id="status" label="Status" source="status.xml" /> - <separator/> - <external href="alt.design/index.html" label="ALT DESIGN" /> - <separator/> -</book> diff --git a/docs/design/breakpos.xml b/docs/design/breakpos.xml deleted file mode 100644 index 34df68d9f..000000000 --- a/docs/design/breakpos.xml +++ /dev/null @@ -1,289 +0,0 @@ -<?xml version="1.0" standalone="no"?> - -<!-- Overview --> - -<document> - <header> - <title>Layout Managers</title> - <subtitle>Break Possibility Proposal</subtitle> - <authors> - <person name="Karen Lease" email="klease@club-internet.fr"/> - </authors> - </header> - - <body> -<s1 title="Introduction"> -<p> -As explained in <link href="layout.html">Layout</link>, -the hierarchy of Layout Managers is responsible for building and placing -areas. Each Layout Manager is responsible for creating and filling -areas of a particular type, either inline or block. This document -explains one potential algorithm for this process. It is based on the -the generation of <em>break possibilities</em> (BP for short). The -Layout Managers (LM for short), will generate one or more BP and -choose the best one. The BP is then used to generate the corresponding -areas. -</p> -</s1><s1 title="Anatomy of a Break Possibility"> -<p>A break possibility is represented by the BreakPoss class. A -BreakPoss contains size information in the stacking direction and in -the -non-stacking direction (at least for inline areas, it must have both). Flags -indicating various conditions (ISFIRST, ISLAST, CAN_BREAK_AFTER, -FORCE_BREAK_AFTER, ANCHORS etc). A BreakPoss contains a reference to -the top-level LayoutManager which generated it. -</p> -<p>A BreakPoss contains an object implementing -the BreakPoss.Position interface. This object is specific to the layout -manager which created the BreakPoss. It should indicate where the -break occurs and allow the LM to -create an area corresponding to the BP. A higher level LM Position -must somehow reference or wrap the Position returned by its child LM in its -BreakPoss object. The layout manager modifies the flags and dimension -information in the BP to reflect its own requirements. For example an -inline FO layout manager might add space-start, space-end, border and -padding values to the stacking or non-stacking dimensions. It might also -modify the flags based its on keep properties.</p> -</s1> -<s1 title="Turning Break Possibilities into Areas"> -<p>Once break possibilities have been generated, the galley-level -layout manager selects the best one -and passes it back to the LayoutManager which generated it to create -the area. A LayoutManager is responsible for -storing enough information in its Position objects to be able to -create the corresponding areas.</p> - </s1> -<s1 title="A walk-through"> -<p>Layout Managers are created from the top down. First the -page sequence creates a PageLM and a FlowLM. The PageLM will manage -finding the right page model (with help from the PageSequenceMaster) -and managing the balancing act between before-floats, footnotes and -the normal text flow. The FlowLM will -manage the normal content in the main flow. We can think of it as a -<em>galley</em> manager. -</p> -<p>In general, each LM asks its child LMs to return sucessive -break possibilities. It passes some -information to the child in a flags object and it gets back -a break possibility which contains the size in -the stacking direction as well as information about such things as -anchors, break conditions and span conditions which can change the -reference area environment. This process continues down to the lowest -level of the layout manager hierarchy which corresponds to atomic -inline-level FOs such as characters or graphics. -</p> -<p> -Each layout manager will repeatedly call getNextBreakPoss on its current -child LM until the child returns a BP with the ISLAST -flag set. Then the layout manager moves on to its next child LM (ie, -it asks the next child FO to generate a layout manager.) Galley level -layout managers which are Line and Flow will return to their parent -layout managers either when they have finished their content or when -they encounter a a BP which will fill one of their areas. -</p> -<p>The break possibilities are generated from the bottom up. -All inline content must first be broken into -lines which are then stacked into block areas. This is done by the -LineLayoutManager, which creates line areas. -The LineLM asks its child LM to generate a break possibility, which -represents a place where the line can end. This -initially means each potential line-end (primarily spaces or forced -linefeeds and a few other potential line-end characters such as hard -hyphens.) The text LM returns an object which stores the size in the -stacking direction as a MinOptMax triplet -and a <em>cost</em>, which is based on how well this break -would satisfy the constraints. The Text LM keeps track of its position in -the text content and returns the total size of the text area it would -create if it were to break at a given point. The returned BP -object also contains information about whether the break is forced -(linefeed) or whether this is the last area which can be generated by -the LM (ISLAST flag). If a textFO ends on a non-break character, the -ISLAST flag is set, but the CAN_BREAK_AFTER flag isn't, since we don't -know if there is any following text in another inline object for -example. -</p> -<p>Variable size content is taken into account from -the bottom up. Each LM returns a range of sizes in the stacking -direction, based on property values. For text, this comes from -variable word-space values or letter-space values. For other inline -objects, it may include variable space-start and space-end values -(after calculation of the entire sequence of space specifiers at a -particular break possibility.)</p> -<p>The main constraint for laying out -lines is the available inline-progression-dimension (IPD) for the line -area to be created. This -depends on the IPD of the reference area ancestor, on the indents of the -containing fo:block, and on any side-floats which may be intruding on -this line.</p> -<note>See below <link href="#getRefIPD">Getting the Reference -IPD</link> -for discussion of how the reference area IPD is -transmitted to the Line LM.</note> -<p>For now, let's assume that only the LineLM knows about the IPD -available to it. Therefore only it can make a decision about which BP -is the best one; the lower level inline layout managers can only -return potential break points.</p> -<note>There are certainly optimizations to this model which can be -examined later.</note> -<p>So the Line LM will ask its child LM(s) for break possibilities until -it gets back a BP whose stacking dimension <em>could</em> fill the -line. This means that the BP.stackdim.max >= LineIPD.min. It can look -for further BP, perhaps one whose stackdim.opt is closer to the -LineIPD.opt. If it isn't happy with the choice of break possibilities, -it can go past the end of the line to the next one, and then try to -find a hyphenation point between the last one which fits and the first -one which doesn't. If no possibility is found whose min/max values -enclose the available IPD, some constraint will be violated (and -reported in the log.) The actual strategy is up to the Line LM and -should be able to be easily replaced without changing the architecture -(Strategy pattern). -</p> -<p>The definition of a good break possibility depends on the -properties at the block and inline level which govern things such as -wrapping behavior and justification mode. For example, if lines are -not to be wrapped, only an explicit linefeed can serve as a BP. If -lines are wrapped but not justified then there is no requirement to -completely fill the IPD on each line, but a sophisticated layout -manager will try to achieve "aesthetic rag". -</p> -<p>Note that no areas have actually been created yet. Once the LineLM -has found a potential break point for the inline content, it can -calculate the total size of the line area which would be created. The -size in the IPD is determined by the Line LM based on the chosen BP. -The size of the line area in the the block-progression-dimension -depends on the size of the text (or other inline content). These -values are set by the inline-level LM -in their returned BP (in terms of ascender and descender heights with -respect to the baseline). The LineLM adds spacing implied by the -current line-stacking strategy and line-height property values. It -stores a reference to the chosen inline BP and "wraps" that in its own -Position object which it stores in the BP it returns to its parent LM -(the block layout manager). -</p><p>The block LM now has a potential break position after its -first line. It assigns that possibility a cost, based on widow, orphan -and keep properties. It can also calculate the total size of the block -area it would create, were it to end the area after this line. It does -this by adding any padding and border (taking into account -conditionality). It also calculates space-before and space-after -values, or contributes to building up a sequence of such values. -With this information, the block LM creates a new BP (or -updates the existing one). It stores a Position object in this -BP which wraps the returned BP from its child Line LM. -It returns the new BP to its parent and so on, back up to the -FlowLM.</p> -<p>Obviously there is more complicated logic involved when dealing -with lists and tables. These cases need to be walked through in detail.</p> -<p>The FlowLM sees if the returned stacking dimension will still -fit in its available block-progression-dimension (BPD). It repeatedly calls -getNextBreakPoss on its -child LMs until it reaches the maximum BPD for the flow reference area -or until there is no more content to lay out. If one child LM is -finished, it moves on to the next until the last child LM has returned -a BP with the ISLAST flag set. If any child LM returns a -BP with a FORCE_BREAK_BEFORE or SPAN flag set, the FlowLM will -force layout of any pending break possibilities and return to its -parent (the PageLM) in order to handle the break or span condition.</p> -<p>If the returned BP has any new before-float or footnote anchors in -it (ANCHOR flag in the -BP), the FlowLM will also return to the PageLM. The PageLM must then -try to find space to place the floats, possibly asking the FlowLM for -help if the body contains multiple columns.</p> -</s1> -<s1 title="Some issues"> -<p>Following are a few remarks on specific issues.</p> -<s2 title="Where Line Layout Managers are created"> -<p>If the first child FO in a block FO is an inline-level FO -such as text, the block LM creates an intermediate level LineLM -to layout the -sequence of inline content into Lines. Note that the whole sequence of -inline FOs is managed by a single instance of LineLM. The LineLM -becomes the parent to the various inline-level LM created by each -individual inline FO. -Since an fo:block can have both block and inline content, its LM -may create a sequence of intermixed BlockLM and LineLM.</p> -</s2> -<anchor id="getRefIPD"/><s2 title="Getting the reference IPD"> -<p>When the layout process starts, with the FlowLM asking its first -child LM for a break possibility, the IPD isn't known, since we don't -know whether -the first FO might be spanning, or on which page it might start. (Of -course, if all page masters in the sequence have the same region-body IPD -and all have only a single column, the IPD will never change -and could already be calculated before starting layout.) -The FlowLM gets its -first child LM and calls its getNextBreakPoss method. That is a child LM for -some block-level FO. For now, suppose it's an fo:block. The BlockLM -will create its first child LM, which may be another block-level LM in -the case of nested blocks or a LineLM as explained above. (Question: -do we need a START flag for layout status?) -</p> -<p>We keep calling getNextBreakPoss on lower level layout managers until we -get down to the inline level or to a level which cannot have break-before -properties, such as a list-item-label. At that point, we assume we are -going to have to layout some actual content. But we can't do that yet -since we don't know the inline-progression-dimension. So we return a -BP object which has 0 size in the stacking dimension, but which -has flags set to signal to -higher-level layout managers what needs to be done. If it has a break-before -property or a span property, it stores these in the BP. If -no reference IPD is yet defined, it sets a flag to get that. It then -returns to its parent. The parent LM will inspect the BP object -returned. In general, it "wraps" it with information about its own -needs. If the returned BP is not actually returning any potential -areas, the LM can still add information about its own break or span -requirements. This return path continues back up to the PageLM. It -will then check break and span requirements and create a new page -if necessary using the appropriate page-master. At that point, the -reference IPD for the main -flow is known and is set in the flags object used for -the next getNextBreakPoss call to the lower level LM. -</p><p>Using this information, the BlockLM parent can now calculate -the available IPD for its LineLM child, based on its indents. -(If there are any -side-floats information about the intrusion must be passed down by the -FlowLM to lower level managers.) The LineLM can now generate a series -of BreakPoss objects, which it passes back to its parent LM. -</p> -</s2> -<s2 title="Hyphenation"> -<p> -The LineLM is responsible for initiating hyphenation if it is allowed -by the properties and if no satisfactory BP can be found without -hyphenating. The hyphenation manager is passed two break -possibilities, one whose IPD is less than the desired line area IPD -and one whose IPD is greater. These break possibilities might have -been generated by different inline-level layout managers (text + a -wrapper with a color change for example), though -frequently they represent two positions in a single text run. -If hyphenation is successful, a new BP is -returned. The LineLM may look for several intermediate BP -based on the "cost" of the returned possibilities. If no intermediate -BP is found, the line will be "short", the white-space stretch will be -exceeded, or perhaps the content will be overflowed or clipped, -depending on various property settings.</p> -</s2> -<s2 title="Optimizing"> -<p>It obviously seems inefficient to go down to the lowest level -LM and back up to the FlowLM for every possible line-break -decision. It seems like it would be possible to optimize by letting -the lower level layout managers run until they had exceeded the -current limit in -the stacking direction. They would then return control to the "galley" -level (LineLM or FlowLM) which would fine-tune the break decision by -asking the lower level LM to find a previous BP which would fit. At -the inline level, this means hyphenation as described above.</p> -<p>Another interesting question is at what point pending break -possibilities can be turned into areas.The idea is to wait until we -are sure we won't have to redo the breaking. This depends on the -sophistication of the layout strategy. For example, if a -linebreak can be considered final if the line is full and there are no -anchors on the line, we could create the LineArea at that point. But -if we are willing to change a previous line-end decision to get a -better overall composition of a whole group of lines (to prevent multiple -hyphens for example), we might wait until the LineLM had finished -laying out all its material and then make all the Lines at once.</p> -</s2> -</s1> - </body> -</document> - diff --git a/docs/design/embedding.xml b/docs/design/embedding.xml deleted file mode 100644 index a429dec59..000000000 --- a/docs/design/embedding.xml +++ /dev/null @@ -1,114 +0,0 @@ -<?xml version="1.0" standalone="no"?> - -<!-- Overview --> - -<document> - <header> - <title>FOP Design</title> - <subtitle>Design Approach to FOP</subtitle> - <authors> - <person name="Keiron Liddle" email="keiron@aftexsw.com"/> - </authors> - </header> - - <body> -<s1 title="Introduction"> -<p> -This is the design for the external interface when FOP is to be embedded -inside another java application. - </p> - <p> -Common places where FOP is embedded is in a report production application -of a server side application such as <jump href="http://xml.apache.org/cocoon/index.html">Cocoon</jump>. - </p> - </s1> -<s1 title="Settings"> -<s2 title="User Agent"> -<p> -The user agent is responsible for supplying user or context -specific information. The list of user agent values can be found on the -<jump href="useragent.html">User Agent</jump> page. - </p> - </s2> -<s2 title="Logging"> -<p> -<ul> -<li>logging level</li> -<li>logging messages of various levels</li> -<li>error handling</li> -<li>Logging setup (LogKit, Log4J, JDK14Logging)</li> -</ul> - </p> - </s2> -<s2 title="XML input"> -<p> -<ul> -<li>various ways to supply FOP with the xsl:fo file, fo, xml+xsl</li> -<li>sax handler</li> -</ul> - </p> - </s2> -<s2 title="general options"> -<p> -<ul> -<li>base directory</li> -<li>uri resolvers</li> -<li>which implementation of a particular</li> -<li>LayoutManager to use</li> -</ul> - </p> - </s2> -<s2 title="Rendering Options"> -<p> -<ul> -<li>embedding fonts</li> -<li>compression in pdf</li> -<li>image embedding</li> -</ul> -</p> -<p> -for the PS renderer (eventually): -<ul> -<li>PostScript Level</li> -<li>PPD to use</li> -<li>binary/ascii switch</li> -</ul> - </p> - </s2> -<s2 title="User Agent"> -<p> -Output from FOP: -- Generation statistics: Number of pages total, Number of pages of each - page-sequence, page-master used for each page (could be used to - control the paper bin to get paper from, important for me in - conjunction with PS Renderer). - </p> - </s2> -<s2 title="Setting Up"> -<p> -The Driver handles the XML input. -The user agent information is through the FOUserAgent. -We could handle logging through the user agent. -Options could also be handled through the user agent, using mime type -selection for renderer options. -</p> - </s2> -<s2 title="Others"> -<p> -render to more than one renderer at once (maybe not from the command line). -For example you could generate a PDF for the archive -and the PS for the printer in one run. It would probably be faster than -converting the PDF to PostScript afterwards. -</p> -<p> -Several code pieces for resolving URLs and/or -file locations are scattered all over FOP and Batik. These should -be replaced with an URIResolver invocation to unify behaviour and -remove redundancies. - </p> - </s2> -</s1> - - </body> -</document> - diff --git a/docs/design/extending.xml b/docs/design/extending.xml deleted file mode 100644 index a0b45f371..000000000 --- a/docs/design/extending.xml +++ /dev/null @@ -1,99 +0,0 @@ -<?xml version="1.0" standalone="no"?> - -<!-- Overview --> - -<document> - <header> - <title>FOP Extensions</title> - <subtitle>Adding extensions to FOP</subtitle> - <authors> - <person name="Keiron Liddle" email="keiron@aftexsw.com"/> - </authors> - </header> - - <body> -<s1 title="Extensions"> -<p> -FOP provides an extension mechanism to add extra functionality. There -are a number of different types of extensions that apply to different -steps when converting FO into the rendered output. - </p> -<s2 title="Extensions"> - <p> -SVG Graphic - This applies to svg and any other xml document that -can be converted into svg in the output. All that is required is -the element mapping for the xml and a converter that changes the -document into svg. This conversion is done in the FO Tree. The -conversion is done by the top level element of the namespace -or in the case of an external image a Converter. - </p> - <p> -XML Document - Instead of converting the document into svg it -can be passed directly to the renderer. The renderer will need -to have a handler for the xml document. This handler can add -information directly to the output document. - </p> - <p> -Output Document - This is used to add document level information -to the output result. Such an extension will set information that -is passed to the output document. There needs to be a handler for -the output information which creates a document level result. - </p> - <p> -FO Area - This is where an extension creates an normal area in -the Area Tree. This is useful when the normal FO objects -cannot create the area in the way that is needed. - </p> - <p> -Resolveable - In some cases it may require information to be -resolved for information such as page numbers. This can apply -to the XML Document, FO Area or output document extensions. - </p> - <p> -- Add a string ['(Continued)'] to a table header if the table spans -multiple pages. These tables are part of the content and can start -anywhere in the page. - </p> - <p> -- Separate page number display for a subsection. ie. - master document -is page 4 of 7, but subsection is page 2 of 3. - - </p> -</s2> -<s2 title="Examples"> - <p> -Plan - The plan extension is a simple SVG graphic extension. -Given a plan document either inside an InstreamForeignObject -or as an external graphic, it converts the plan document into -an svg graphic. The svg graphic is then passed through the -Area Tree to the Renderer. The Renderer then renders the svg -graphic as normal. - </p> - <p> -PDF Outline - This is output document extension. If rendering to -pdf and this extensionis used then the bookmark information is -passed to the pdf document. This information is then set on the -document. - </p> - <p> -PDF Additions - This can be done with an XML Document extension. -A simple xml document is defined that provides the appropriate -information. When the document is rendered a handler converts the -document into PDF markup. - </p> - <p> -eg. -<source><![CDATA[<my:script-link script="app.execMenuItem('AcroSrch:Query');">Search</my:script-link>]]></source> - -to result in a text box referencing the following PDF action: -<source><![CDATA[<< /S /JavaScript /JS (app.execMenuItem("AcroSrch:Query");) >>]]></source> - - </p> - -</s2> - - </s1> - - </body> -</document> - diff --git a/docs/design/fotree.xml b/docs/design/fotree.xml deleted file mode 100644 index 1f8ed6a3b..000000000 --- a/docs/design/fotree.xml +++ /dev/null @@ -1,92 +0,0 @@ -<?xml version="1.0" standalone="no"?> - -<!-- Overview --> - -<document> - <header> - <title>FO Tree</title> - <subtitle>Design of FO Tree Structure</subtitle> - <authors> - <person name="Keiron Liddle" email="keiron@aftexsw.com"/> - </authors> - </header> - - <body> -<s1 title="Introduction"> -<p> -The FO Tree is an internal representation of the input FO document. -The tree is created by building the elements and attributes from -the SAX events. - </p> - <p> -The FO Tree is used as an intermediatory structure which is converted -into the area tree. The complete FO tree should not be held in memory -since FOP should be able to handle FO documents of any size. - </p> - -<s2 title="FONode"> -<p> -The class inheritance described above only describes the nature of the -content. Every FO in FOP also has a parent, and a Vector of children. The -parent attribute (in the Java sense), in particular, is used to enforce -constraints required by the FO hierarchy. -</p> - -<p> -FONode, among other things, ensures that FO's have a parent, that they -have children, that they maintain a marker of where the layout was up to -(for FObj's it is the child number, and for FOText's it is the character -number), and that they have a <code>layout()</code> method. -</p> -</s2> - -<s2 title="Making FO's"> -<p> -An FO maker is read from a hashmap lookup using the namespace and -element name. This maker is then used to create a new class that -represents an FO element. This is then added to the FO tree as a child -of the current parent. -</p> - -<p> -Properties (recall that FO's have properties, areas have traits, and XML -nodes have attributes) are also a concern of <em>FOTreeBuilder</em>. It -accomplishes this by using a <em>PropertyListBuilder</em>. There is a -separate <em>PropertyListBuilder</em> for each namespace encountered -while building the FO tree. Each Builder object contains a hash of -property names and <ref>their</ref> respective makers. It may also -contain element-specific property maker hashes; these are based on the -<em>local name</em> of the flow object, ie. <em>table-row</em>, not -<em>fo:table-row</em>. If an element-specific property mapping exists, -it is preferred to the generic mapping.</p> -<p>The base class for all -properties is <em>Property</em>, and all the property makers extend -<em>Property.Maker</em>. A more complete discussion of the property -architecture may be found in <jump href="properties.html">Properties</jump>. -</p> -</s2> - -<s2 title="Foreign XML"> -<p> -FOP supports the handlingof foreign XML. -The XML is converted internally into a DOM, this is then available to -the FO tree to convert the DOM into another format which can be rendered. -In the case of SVG the DOM needs to be created with Batik, so an element -mapping is used to read all elements in the SVG namespace and pass them -into the Batik DOM. -</p> -</s2> - -<s2 title="Extensions"> -<p> -It is possible to add extensions to FOP so that you can extend the ability of -FOP with respect to render output, document specific information or extended -layout functionality. -</p> -</s2> - - </s1> - - </body> -</document> - diff --git a/docs/design/intro.xml b/docs/design/intro.xml deleted file mode 100644 index 101512ede..000000000 --- a/docs/design/intro.xml +++ /dev/null @@ -1,51 +0,0 @@ -<?xml version="1.0" standalone="no"?> - -<!-- Overview --> - -<document> - <header> - <title>FOP Design</title> - <subtitle>Design Approach to FOP</subtitle> - <authors> - <person name="Keiron Liddle" email="keiron@aftexsw.com"/> - </authors> - </header> - - <body> -<s1 title="Introduction"> -<p> -The information here describes the design and architecture details for FOP. -Currently this is part of a redesign process for some of the core parts of -FOP. - </p> - <p> -The redesign is mainly focusing on some particular process involved -with the layout process when converting the FO tree into the Area Tree. - </p> -<s2 title="Aims"> - <p> -The main aim for FOP is to comply with the spec and to be able to -process files of any size. - </p> - <p> -In achieving this aim we need to understand the problem and break it -into small problems that can be solved. - </p> - <p> -<ul> -<li>use SAX as input</li> -<li>process FO elements ASAP</li> -<li>dispose of unused memory, keep memory minimal</li> -<li>layout handles floats, footnotes and keeps in a simple straight forward way</li> -<li>id references are kept simple</li> -<li>pages are rendered ASAP, can be cached until resolved</li> -<li>renderers are totally responsible for their output format</li> -<li>output is sent to a stream</li> -</ul> - </p> -</s2> - </s1> - - </body> -</document> - diff --git a/docs/design/layout.xml b/docs/design/layout.xml deleted file mode 100644 index 8ee748b6b..000000000 --- a/docs/design/layout.xml +++ /dev/null @@ -1,438 +0,0 @@ -<?xml version="1.0" standalone="no"?> - -<!-- Overview --> - -<document> - <header> - <title>Layout</title> - <subtitle>Layout Process in FOP</subtitle> - <authors> - <person name="Keiron Liddle" email="keiron@aftexsw.com"/> - </authors> - </header> - - <body> -<s1 title="FO Layout"> -<p> -The aim of the layout system is to be self contained and allow for -easy changes or extensions for future development. For example the -line breaking should be decided at a particular point in the process -that makes it easier to handle other languages. - </p> - <p> -The layout begins once the hierarchy of FO objects has been constructed. -Note: it may be possible to start immediately after a block formatting -object has been added to the flow but this is not currently in the scope -of the layout. It is also possible to layout all pages in a page sequence -after each page sequence has been added from the xml. - </p> - <p> -The layout process is handled by a set of layout managers. The block -level layout managers are used to create the block areas which are -added to the region area of a page. - </p> -<s2 title="Layout Managers"> - <p> -The layout managers are set up from the hierarchy of the formatting -object tree. A manager represents a hierachy of area producing objects. -A manager is able to handle the block area(s) that it creates and -organise or split areas for page breaks. - </p> - <p> -Normally any object that creates a block area will have an associated -layout manager. Other cases are tables and lists, these objects will -also have layout managers that will manager the group of layout managers -that make up the object. - </p> - <p> -A layout manager is also able to determine height (min/max/optimum) -and keep status. This will be used when organising the layout on -a page. The manager will be able to determine the next place a break -can be made and then be able to organise the height. - </p> - <p> -A layout manager is essentially a bridge between the formatting objects -and the area tree. It will keep a list of line areas inside block areas. -Each line area will contain a list of inline areas that is able to be -adjusted if the need arises. - </p> - <p> -The objects in the area tree that are organised by the manager will mostly -contain the information about there layout such as spacing and keeps, this -information will be thrown away once the layout for a page is finalised. - </p> - </s2> -<s2 title="Creating Managers"> - <p> -The managers are created by the page sequence. The top level manager -is the Page manager. This asks the flow to add all managers in this -page sequence. - </p> - <p> -For block level objects they have a layout manager. Neutral objects -don't represent any areas but are used to contain a block level -area and as such these objects will ask the appropriate child to -create a layout manager. - </p> - <p> -Any nested block areas or inline areas may be handled by the layout -manager at a later stage. - </p> - </s2> -<s2 title="Using Managers"> - <p> -Block area layout managers are used to create a block area, other block -level managers may ask their child layout managers to create block areas -which are then added to the area tree (subset). - </p> - <p> -A manager is used to add areas to a page until the page is full, -then the manages contain all the information necessary to make -the decision about page break and spacing. A manager can split an -area that it has created will keep a status about what has been -added to the current area tree. - </p> - </s2> -<s2 title="Page Layout"> - <p> -Once the Page layout manager, belonging to the page sequence, is ready -then we can start laying out each page. The page sequence will create -the current page to put the page data, the next page and if it exists -a last page. - </p> - <p> -The current page will have the areas added to it from the block layout -managers. The next page will be used when splitting a block that goes -over the page break. Note: any page break overrides the layout decided -here. The last page will be necessary if the last block area is added -to this page. The size of the last page will be considered and the -areas will be added to the last page instead. - </p> - <p> -The first step is to add areas to the current page until the area is full -and the lines of the last block area contain at least n(orphans) and at least -n(orphans) + n(widows) in total. This will only be relevant for areas at -the start or end of a particular reference area. - </p> - <p> - <image src="page.svg"/> - </p> - <p> -The spacing between the areas (including spacing in block areas inside -an inline-container) will be set to the minimum values. This will allow -the page to have at least all the information it needs to organise the -page properly. - </p> - <p> -This should handle the situation where there are keeps on some -block areas that go over the end of the page better. It is possible that -fitting the blocks on the page using a spacing between min and optimum -would give a closer value to the optimum than putting the blocks on the -next page and the spacing being between optimum and max. So if the objects -are placed first at optimum then you will need to keep going to see if -there is a lower keep further on that has a spacing that is closer to the -optimum. - </p> - <p> -The spacing and keep information is stored so that the area positions -and sizes can be adjusted. - </p> - </s2> -<s2 title="Balancing Page"> - <p> -The page is vertically justified so that it distributes the areas -on the page for the best result when considering keeps and spacing. - </p> - </s2> -<s2 title="Finding Break"> - <p> -First the keeps are checked. The available space on the page may have -changed due to the presence of before floats or footnotes. The page break -will need to be at a height <= the available space on the page. - </p> - <p> -A page break should be made at the first available position that -has the lowest keep value when searching from the bottom. Once the first -possible break is found then the next possible break, with equally low -keep value, is considered. If the height of the page is closer to the -optimal spacing then this break will be used instead. - </p> - <p> -Keep values include implicit and explicit values when trying to -split a block area into more than one area. Implicit keeps may -be such things as widows/orphans. - </p> - <p> -If the page contains before floats or footnotes then as each area or line -area is removed the float/footnote should also be removed. This will -change the available space and is a one way operation. The footnote -should be removed first as a footnote may be placed on the next page. -The lowest keep value may need to be reassessed as each conditional -area is removed. - </p> - <p> -The before float and footnote regions are managed so that the separator -regions will be present if it contains at least one area. - </p> - </s2> -<s2 title="Optimising"> - <p> -Once the areas for the page are finalised then the spacing will -need to be adjusted. The available height on the page is compared -with the min and max spacing. All of the spacing in all the areas -on the page is then adjusted by the appropriate percentage value. - </p> - </s2> -<s2 title="Multi-Column Pages"> - <p> -In the case of multi-column pages the column breaks and eventually -the page break must be found in a slightly different way. - </p> - <p> -The columns need to be layed out completely from first to last but -this can only be done after a rough estimate of all the elements -on the page in case of before floats or footnotes. - </p> - <p> -So first the complete page is layed out with all columns filled -with areas and the spacing at a minimum. Then if there are any -before floats or footnotes then the availabe space is adjusted. -Then each the best break is found for each column starting from -the first column. If any before floats or footnotes are removed -as a result of the new breaks and optimised spacing then all the -columns should still be layed out for the same column height. - </p> - </s2> -<s2 title="Completing Page"> - <p> -After the region body has been finished the static areas can be -layed out. The width of the static area is set and the height is -inifinite, that is all block areas should be placed in the area -and their visibility is controlled be other factors. - </p> - <p> -The area tree for the region body will contain the information -about markers that may be necessary for the retrieve marker. - </p> - <p> -The ordering of the area tree must be adjusted so that the areas are -before, start, body, end and after in that order. The body region -should be in the order before float, main then footnote. - </p> - </s2> -<s2 title="Line Areas"> - <p> -Creating a line areas uses a similair concept. Each inline area -is placed across the available space until there is no room left. -The line is then split by considering all keeps and spacing. - </p> - <p> -Each word (group of adjacent character inline areas) will have keeps -based on hyphenation. The line break is at the lowest keep value -starting from the end of the line. - </p> - <p> -Once a line has been layed out for a particular width -then that line is fixed for the page (except for unresolved -page references). - </p> - </s2> -<s2 title="Before Floats and Footnotes"> - <p> -The before float region and footnote region are handled by the page -layoutmanger. These regions will handle the addition and removal -of the separator regions when before floats/footnotes area added -and removed. - </p> - </s2> -<s2 title="Side Floats"> - <p> -If a float anchor is present in a particular line area then the available -space for that line (and other in the block) will be reduced. The side float -adds to the height of the block area and this height also depends -on the clear value of subsequent blocks. The keep status of the block is -also effected as there must be enough space on the page to fit the -side float. - </p> - <p> -<image src="float.svg"/> - </p> - </s2> -<s2 title="Unresolved Areas"> - <p> -Once the layout of the page is complete there may be unresolved areas. - </p> - <p> -Page number citations and links may require following pages to be -layed out before they can be resolved. These will remain in the -area tree as unresolved areas. - </p> - <p> -As each page is completed the list of unresolved id's will be checked -and if the id can be resolved it will be. Once all id's are resolved -then the page can be rendered. - </p> - <p> -Each page contains a map of all unresolved id's and the corresponding -areas. - </p> - <p> -In the case of page number citations. The areas reserves the equivalent -of 3 number nines in the current font. When the area is resolved -then the area is adjusted to its proper size and the line area is -re-aligned to accomodate the change. - </p> - </s2> -<s2 title="ID and Link Areas"> - <p> -Any formatting object that has an ID or any inline link defines an area -that will be required when rendering and resolving id references. - </p> - <p> -This area is stored in the parent area and may be a shape that exists -in more than one page, for example over a page break. This shape consists -of the boundary of all inline (or block) areas that the shape is defined -for. - </p> - </s2> -<s2 title="Inline Areas"> - <p> -This is the definition of all inline areas that will exist in the -area. - </p> - </s2> -<s2 title="Fixed Areas"> - <p> -instream-foreign-object, external-graphic, inline-container - </p> - <p> -These areas have a fixed width and height. They also have a viewport. - </p> - </s2> -<s2 title="Stretch Areas"> - <p> -leader, inline space - </p> - <p> -These areas have a fixed height but the width may vary. - </p> - </s2> -<s2 title="Character Areas"> - <p> -character - </p> - <p> -This is an simple character that has fixed properties according to -the current font. There are implicit keeps with adjacent characters. - </p> - </s2> -<s2 title="Anchor Areas"> - <p> -float anchor, footnote anchor - </p> - <p> -This area has no size. It keeps the position for footnotes and floats -and has a keep with the associated inline area. - </p> - </s2> -<s2 title="Unresolved Page Numbers"> - <p> -page-number-citation - </p> - <p> -A page number area that needs resolving, behaves as a character and -has the space of 3 normal characters reserved. The size will adjust -when the value is resolved. - </p> - </s2> -<s2 title="Block Areas"> - <p> -The block area has info about the following: - <itemizedlist> - <listitem><para> -all anchors including which lines they are on - </para></listitem> - <listitem><para> -unresolved page references with line info - </para></listitem> - <listitem><para> -id and link areas - </para></listitem> - <listitem><para> -height (min/max/optimum) or area including floats - </para></listitem> - <listitem><para> -holds space before/after and keep information - </para></listitem> - <listitem><para> -widows and orphans - </para></listitem> - </itemizedlist> - </p> - <p> -Once the layout has been finalised then this information can be -discarded. - </p> - </s2> -<s2 title="Page Areas"> - <p> -Contains inforamtion about all the block areas in the body, -before area and footer area. - </p> - <p> -Has a list of the unresolved page references and a list of id refences -that can be used to obtain the area associated with that id. - </p> - </s2> -<s2 title="Test Cases"> - <p> -Here a few layout possibilities areas explored to determine how the -layout process will handle these situations. - </p> -<s3 title="Simple Pages"> - <p> -All blocks (including nested) are placed on the page with minimum spacing -and the last block has the minimum number of lines past the page end. -The lowest keep value is then found within the body area limits. Then the next -equally low keep is found to determine if the spacing will be closer to -the optimum values. - </p> - </s3> -<s3 title="Before Floats/Footnotes"> - <p> -After filling the page with the block areas then the new body height -is used to find the best position to break. Before each line area or block -area is remove any associated before floats and footnotes are removed. -This will then adjust the available space on the page and may allow -for a different breaking point. Areas are removed towards the new -breaking point until the areas fit on the page. When finding the -optimum spacing the removal of before floats and footnotes must also -be considered. - </p> - </s3> -<s3 title="Multicolumn"> - <p> -First the page is filled with all columns for the intial page area. -Then each column is adjusted for the new height starting from the -first column. The best break for the column is found then the next -column is considered, any left over areas a pre-pended to the next -column. Once all the columns are finished then all the columns are -adjusted to fit in the same height columns. This handles the situation -where before floats or footnotes may have been removed. - </p> - </s3> -<s3 title="Last Page"> - <p> -If in the process of adding areas to a page it is found that there -are no more areas in the flow then this page will need to be changed to -the last page (if applicable). The areas are then placed on a last -page. - </p> - </s3> - </s2> - - </s1> - - </body> -</document> - diff --git a/docs/design/optimise.xml b/docs/design/optimise.xml deleted file mode 100644 index 0b8fcd19e..000000000 --- a/docs/design/optimise.xml +++ /dev/null @@ -1,58 +0,0 @@ -<?xml version="1.0" standalone="no"?> - -<!-- Overview --> - -<document> - <header> - <title>FOP Optimisations</title> - <subtitle>Notes for Optimising FOP</subtitle> - <authors> - <person name="Keiron Liddle" email="keiron@aftexsw.com"/> - </authors> - </header> - - <body> -<s1 title="Process Optimisations"> -<p> -FOP should be able to handle very large documents. A document can be -supplied using SAX and the information should be passed entirely through -the system, from fo elements to rendered output as soon as possible. - </p> - <p> -A top level block area, immediately below the flow, can be added to the -page layout as soon as the element is complete. - </p> - <p> -The fo elements used to construct a page can be discarded as soon as the -layout for the page is complete. Some information may be stored in the -area tree of the page in order to handle unresolved page references -and links. - </p> - <p> -Once the layout of a page has been completed, all elements are fully -resolved, then the page can be rendered. Some renderers may support -out of order rendering of pages. - </p> - <p> -The main problem that will remain is that any page with forward -references will need to be stored until the refence is resolved. -This means that the information contained in the page should be -as minimal as possible. - </p> - <p> -Line areas can be optimised once the layout for the line has -been finalised. Consecutive characters with the same properties -can be combined into a "word" to hold the information with -limited overhead. - </p> - <p> -If there are a large number of pages where forward references -cannot be resolved the a method of writing a page onto disk -could be used to save memory. The easiest way to achieve this -is to make the page and all children serializable. - </p> - </s1> - - </body> -</document> - diff --git a/docs/design/properties.xml b/docs/design/properties.xml deleted file mode 100644 index 1d0744194..000000000 --- a/docs/design/properties.xml +++ /dev/null @@ -1,257 +0,0 @@ -<?xml version="1.0" encoding="ISO-8859-1"?> - -<!-- $Id$ --> - -<document> - <header> - <title>Properties</title> - <subtitle>Properties overview</subtitle> - <authors> - <person name="Karen Lease"/> - </authors> - </header> - - <body> - -<s1 title="Properties"> - <s2 title="Property datatypes"> -<p>The property datatypes are defined in the -org.apache.fop.datatypes package, except Number and String which are java -primitives. The FOP datatypes are:</p> -<ul> -<li>Number</li> -<li>String</li> -<li>ColorType</li> -<li>Length (has several subclasses)</li> -<li>CondLength (compound)</li> -<li>LengthRange (compound)</li> -<li>Space (compound)</li> -<li>Keep (compound)</li> -</ul> -<p>The <em>org.apache.fop.fo.Property</em> class is the superclass for all -Property subclasses. There is a subclass for each kind of property -datatype. These are named using the datatype name plus the word -Property, resulting in NumberProperty, StringProperty, and so -on. There is also a class EnumProperty which uses an <code>int</code> -primitive to hold enumerated values. There is no corresponding Enum -datatype class.</p> -<p>The Property class provides a "wrapper" around any possible -property value. Code manipulating property values (in layout for -example) usually knows what kind (or kinds) of datatypes are -acceptable for a given property and will use the appropriate accessor.</p> -<p>The base Property class defines accessor methods for all FO property -datatypes, such as getNumber(), getColorType(), getSpace(), getEnum(), -etc. It doesn't define -accessors for SVG types, since these are handled separately (at least -for now.) In the base Property class, all of these methods return -null, except getEnum which returns 0. Individual subclasses return a value of the appropriate type, -such as Length or ColorType. A subclass may also choose to return a -reasonable value for other accessor types. For example, a -SpaceProperty will return the optimum value if asked for a Length.</p> - </s2> - - <s2 title="Property Makers"> -<p>The Property class contains a nested class called -<em>Maker</em>. This is the base class for all other property Makers. It -provides basic framework functionality which is overridden by the -code generated by properties.xsl from the *properties.xml files. In -particular it provides basic expression evaluation, using -PropertyParser class in the org.apache.fop.fo.expr package.</p> -<p>Other Property subclasses such as LengthProperty define their own -nested Maker classes (subclasses of Property.Maker). These handle -conversion from the Property subclass returned from expression -evaluation into the appropriate subclass for the property.</p> -<p>For each generic or specific property definition in the -properties.xml files, a new subclass of one of the Maker classes is -created. Note that no new Property subclasses are created, only new -PropertyMaker subclasses. Once the property value has been parsed and -stored, it has no specific functionality. Only the Maker code is -specific. Maker subclasses define such aspects as keyword -substitutions, whether the property can be inherited or not, which -enumerated values are legal, default values, corresponding properties -and specific datatype conversions.</p> -</s2> - <s2 title="XML property specification format"> - <s3 title="Generic properties"> -<p>In the properties xml files, one can define generic property -definitions which can serve as a basis for individual property -definitions. There are currently several generic properties defined in -foproperties.xml. An example is GenericColor, which defines basic properties -for all ColorType properties. Since the generic specification doesn't include -the inherited or default elements, these should be set in each property -which is based on GenericColor. Here is an example:</p> -<p> -<code> - <property type='generic'> - <name>background-color</name> - <use-generic>GenericColor</use-generic> - <inherited>false</inherited> - <default>transparent</default> - </property> -</code></p> -<p>A generic property specification can include all of the elements -defined for the property element in the DTD, including the description -of components for compound properties, and the specification of -keyword shorthands.</p> - -<p>Generic property specifications can be based on other generic -specifications. -An example is GenericCondPadding template which is based on the -GenericCondLength definition but which extends it by adding an inherited -element and a default value for the length component.</p> -<p> -Generic properties can specify enumerated values, as in the -GenericBorderStyle template. This means that the list of values, which -is used by 8 properties (the "absolute" and "writing-mode-relative" -variants for each BorderStyle property) is only specified one time.</p> -<p> -When a property includes a "use-generic" element and includes no other -elements (except the "name" element), then no class is generated for the -property. Instead the generated mapping will associate this -property directly with an instance of the generic Maker.</p> -<p> -A generic class may also be hand-coded, rather than generated from the -properties file. -Properties based on such a generic class are indicated by the -attribute <code>ispropclass='true'</code> on the -<em>use-generic</em> element.</p> -<p> This is illustrated by the SVG properties, most of -which use one of the Property subclasses defined in the -<em>org.apache.fop.svg</em> -package. Although all of these properties are now declared in -svgproperties.xml, no specific classes are generated. Classes are only -generated for those SVG properties which are not based on generic -classes defined in svg.</p> - </s3> - <s3 title="Element-specific properties"> -<p>Properties may be defined for all flow objects or only for -particular flow objects. A PropertyListBuilder object will always look -first for a Property.Maker for the flow object before looking in the -general list. These are specified in the -<code>element-property-list</code> section of the properties.xml -files. The <code>localname</code> element children of this element specify for -which flow-object elements the property should be registered.</p> -<p><em>NOTE</em>: All the properties for an object or set of objects -must be specified in a single element-property-list element. If the -same localname appears in several element lists, the later set of -properties will hide the earlier ones! Use the <em>ref</em> -functionality if the same property is to be used in different sets of -element-specific mappings. -</p> - </s3> - <s3 title="Reference properties"> - <p>A property element may have a type attribute with the value - <code>ref</code>. The - content of the <em>name</em> child element is the name of the referenced - property (not its class-name!). This indicates that the property - specification has - already been given, either in this same specification file or in a - different one (indicated by the <code>family</code> attribute). The - value of the family attribute is <em>XX</em> where the file - <em>XXproperties.xml</em> defines the referenced property. For - example, some SVG objects may have properties defined for FO. Rather - than defining them again with a new name, the SVG properties simply - reference the defined FO properties. The generating mapping for the - SVG properties will use the FO Maker classes.</p> - </s3> - <s3 title="Corresponding properties"> -<p>Some properties have both <em>absolute</em> and -<em>writing-mode-relative</em> forms. In general, the absolute forms -are equivalent to CSS properties, and the writing-mode-relative forms -are based on DSSSL. FO files may use either or both forms. In -FOP code, a request for an absolute form will retrieve that value if it -was specified on the FO; otherwise the corresponding relative property -will be used if it was specified. However, a request for a relative -form will only use the specified relative value if the corresponding -absolute value was <em>not</em> specified for that FO. -</p> -<p>Corresponding properties are specified in the properties.xml files -using the element <code>corresponding</code>, which has at least one -<code>propval</code> child and may have a <code>propexpr</code> child, -if the corresponding -value is calculated based on several other properties, as for -<code>start-indent</code>. -</p> -<p><em>NOTE</em>: most current FOP code accesses the absolute variants -of these properties, notably for padding, border, height and width -attributes. However it does use start-indent and end-indent, rather -than the "absolute" margin properties. -</p> -</s3> - </s2> - - <s2 title="Mapping"> -<p>The XSL script <code>propmap.xsl</code> is used to generate -property mappings based on -both foproperties.xml and svgproperties.xml. The mapping classes -in the main fop packages simply load these automatically generated -mappings. The mapping code still uses the static -"maker" function of the generated object to obtain a Maker -object. However, for all generated classes, this method returns an -instance of the class itself (which is a subclass of Property.Maker) -and not an instance of a separate nested Maker class.</p> -<p>For most SVG properties which use the SVG Property classes directly, -the generated mapper code calls the "maker" method of the SVG Property -class, which returns an instance of its nested Maker class.</p> -<p>The property generation also handles element-specific property -mappings as specified in the properties XML files.</p> - </s2> - - <s2 title="Enumerated values"> -<p>For any property whose datatype is <code>Enum</code> or which -contains possible enumerated values, FOP code may need to access -enumeration constants. These are defined in the interfaces whose name -is the same as the generated class name for the property, -for example <code>BorderBeforeStyle.NONE</code>. These interface classes -are generated by the XSL script <code>enumgen.xsl</code>. A separate -interface defining the enumeration constants is always generated for -every property which uses the constants, even if the constants -themselves are defined in a generic class, as in BorderStyle.</p> -<p>If a subproperty or component of a compound property has enumerated -values, the constants are defined in a nested interface whose name is -the name of the subproperty (using appropriate capitalization -rules). For example, -the keep properties may have values of AUTO or FORCE or an integer -value. These are defined for each kind of keep property. For example, -the keep-together property is a compound property with the components -within-line, within-column and within-page. Since each component may -have the values AUTO or FORCE, the KeepTogether interface defines -three nested interfaces, one for each component, and each defines -these two constants. An example of a reference in code to the constant -is <code>KeepTogether.WithinPage.AUTO</code>.</p> - - </s2> - - <s2 title="Compound property types"> -<p>Some XSL FO properties are specified by compound datatypes. In the FO file, -these are defined by a group of attributes, each having a name of the -form <code>property.component</code>, for example -<code>space-before.minimum</code>. These are several compound -datatypes:</p> -<ul> -<li>LengthConditional, with components length and conditionality</li> -<li>LengthRange, with components minimum, optimum, and maximum</li> -<li>Space, with components minimum, optimum, maximum, precedence and -conditionality </li> -<li>Keep, with components within-line, within-column and within-page</li> -</ul> -<p>These are described in the properties.xml files using the element -<code>compound</code> which has <code>subproperty</code> children. A subproperty element is much -like a property element, although it may not have an <code>inherited</code> child -element, as only a complete property object may be inherited. -</p> -<p>Specific datatype classes exist for each compound property. Each -component of a compound datatype is itself stored as a Property -object. Individual components may be accessed either by directly -performing a get operation on the name, using the "dot" notation, -eg. <code>get("space-before.optimum")</code>; or by using an accessor on the compound -property, eg. <code>get("space-before").getOptimum()</code>. -In either case, -the result is a Property object, and the actual value may be accessed -(in this example) by using the "getLength()" accessor. -</p> - </s2> -</s1> - </body> -</document> - diff --git a/docs/design/renderers.xml b/docs/design/renderers.xml deleted file mode 100644 index 1fe18c32a..000000000 --- a/docs/design/renderers.xml +++ /dev/null @@ -1,30 +0,0 @@ -<?xml version="1.0" standalone="no"?> - -<!-- Overview --> - -<document> - <header> - <title>Renderers</title> - <subtitle>Design of Renderers</subtitle> - <authors> - <person name="Keiron Liddle" email="keiron@aftexsw.com"/> - </authors> - </header> - - <body> -<s1 title="Introduction"> -<p> -A render is primarily design to convert a given area tree into the output -document format. It should be able to produce pages and fill the pages -with the text and graphical content. Usually the output is sent to -an output stream. - </p> - <p> -Some output formats may support extra information that is not available -from the area tree or depends on the destination of the document. - </p> - </s1> - - </body> -</document> - diff --git a/docs/design/status.xml b/docs/design/status.xml deleted file mode 100644 index 93769ecc5..000000000 --- a/docs/design/status.xml +++ /dev/null @@ -1,73 +0,0 @@ -<?xml version="1.0" standalone="no"?> - -<!-- Status of Design/Rewrite --> - -<document> - <header> - <title>Design Status</title> - <subtitle>Current Status of FOP and Design</subtitle> - <authors> - <person name="Keiron Liddle" email="keiron@aftexsw.com"/> - </authors> - </header> - - <body> -<s1 title="Status"> -<p> -Currently some of FOP is being re-written so that the layout can be handled -properly without the problems that have been encountered and to make -it possible to handle keeps/breaks and spacing better. - </p> -<p> -A number of issues have been dealt with in the redesigned code. - </p> - </s1> -<s1 title="Features TODO"> -<p> -<ul> -<li>avalon integration - logging, configuration, component management, caching, uri resolver</li> -<li>improved interfaces -<ul> - <li>no threading/static problems</li> - <li>simpler to use</li> -</ul> -</li> -<li>better commandline handling</li> -</ul> - </p> - </s1> -<s1 title="Done/Started Features"> -<p> -Many of these changes will make FOP much better to use and develop. -So if you help out with the development you can get to use these -things sooner. -<ul> -<li><strong>better layout design</strong> - that can handle keeps and -spacing better</li> -<li><strong>better area tree handling</strong> - means it can run in -less memory</li> -<li><strong>better image handling</strong> - redone so it can use a -cache and synchronizes properly only on the current image while loading</li> -<li>svg now in an xml handler, FOP can be used without batik</li> -<li>bookmark extension improved a bit - changed bookmark extension, -now requires a wrapping element bookmark</li> -<li>new interface for structured documents, rtf and mif</li> -<li>better handling of unknown xml and xml from an unknown namespace</li> -<li>Changed extensions to allow for external xml</li> -<li>Can have a default element mapping for extensions</li> -<li>mathml extension</li> -<li>another xml -> svg extension</li> -<li>svg text normal text if that can be handled otherwise stroked -this is done automatically</li> -<li>new area tree model</li> -<li>new renderer model</li> -<li>added handlers for xml in renderer</li> -<li>changed area tree xml format to match the area tree hierarchy</li> -</ul> - - </p> - </s1> - - </body> -</document> - diff --git a/docs/design/useragent.xml b/docs/design/useragent.xml deleted file mode 100644 index cf3bea97c..000000000 --- a/docs/design/useragent.xml +++ /dev/null @@ -1,176 +0,0 @@ -<?xml version="1.0" standalone="no"?> - -<document> - <header> - <title>FO User Agent</title> - <subtitle>Design of FO User Agent</subtitle> - <authors> - <person name="Keiron Liddle" email="keiron@aftexsw.com"/> - </authors> - </header> - - <body> -<s1 title="Purpose"> -<p> -Technically the user agent is FOP in the role of determining the -output format and when resolving various attributes. The user -agent is represented by a class that is available to others to -specify how FOP should behave. - </p> - <p> -The user agent is used by the formatting process to determine -certain user definable values. - </p> - <p> -It will enable the customisation of values for generating and -rendering the document. - </p> - <p> -The user agent must be available to the layout processor and -the renderer. Users can supply their own user agent or use -the default one for a particular renderer. - </p> - <p> -The user agent needs to be made available to the property -resolution layout process and the renderer. - </p> - - <p> -Standard Features: - <ul> - <li><p> -error handling, what to do if fo markup is invalid - </p></li> - <li><p> -auto overflow value and handling error-if-overflow - </p></li> - <li><p> -adjusting length values (eg. for borders) to renderable values - </p></li> - <li><p> -available fonts - </p></li> - <li><p> -converting cm/in to pt (dpi) - </p></li> - <li><p> -active state for multi properties - </p></li> - <li><p> -title, used to identify a set of pages (in a page sequence) - </p></li> - <li><p> -the width (in inline-progression-dimension) of a character with -treat-word-as-space true - </p></li> - <li><p> -maximum space used by conditional areas from region-reference-area - </p></li> - <li><p> -if there should be "hot links" to before floats or footnotes - </p></li> - <li><p> -when to clear side floats if space in inline-progression-dimension -is not enough - </p></li> - <li><p> -placement of left over footnotes on a page with a region-body - </p></li> - <li><p> -using color property as border colour - </p></li> - <li><p> -interpretting all border styles (except outset) as solid - </p></li> - <li><p> -thin, medium and thick values for border width - </p></li> - <li><p> -initial font-family value - </p></li> - <li><p> -absolute font sizes (eg, xx-small, x-small etc.) - </p></li> - <li><p> -relative font sizes (eg. larger, smaller) - </p></li> - <li><p> -small caps simulation - </p></li> - <li><p> -font weight mapping - </p></li> - <li><p> -baseline info for a font if not available - </p></li> - <li><p> -determining sub/superscript when another baseline is dominant - </p></li> - <li><p> -scaling method for external-graphic and instream-foreign-object - </p></li> - <li><p> -the width of a replaced element - </p></li> - <li><p> -"normal" line height value - </p></li> - <li><p> -text alignment (stretching the line with letter and word spacing) - </p></li> - <li><p> -text transform - </p></li> - <li><p> -initial color - </p></li> - <li><p> -rendering intent of auto - </p></li> - <li><p> -dot character for leader - </p></li> - <li><p> -line breaking with leaders, use optimum length when breaking the line - </p></li> - <li><p> -page height/width of auto - </p></li> - <li><p> -left and right caption widths - </p></li> - <li><p> -glyph orientation vertical of auto - </p></li> - <li><p> -rendering processor of content-type (mime type) - </p></li> - </ul> - </p> - - <p> -Interactive Features: - <ul> - <li><p> -inline and block scroll amount - </p></li> - <li><p> -dynamic effects, links and property sets - </p></li> - <li><p> -initial "pause-after", "pause-before" and "voice-family" value - </p></li> - <li><p> -treating fixed as scroll on background attachement - </p></li> - <li><p> -media usage of auto - </p></li> - </ul> - </p> - - </s1> - - </body> -</document> - |