Examples

From 1f91d6eb67457acc113b6adbe5436443a45ba150 Mon Sep 17 00:00:00 2001 From: fotis Date: Wed, 2 Aug 2000 07:59:01 +0000 Subject: [PATCH] updating documentation and moving it to html-docs git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@193576 13f79535-47bb-0310-9956-ffa450edef68 --- docs/examples.html | 60 ------ docs/html-docs/architecture.html | 276 ++++++++++++++++++++++++++ docs/{ => html-docs}/bugs.html | 34 ++-- docs/{ => html-docs}/compiling.html | 17 +- docs/{ => html-docs}/download.html | 6 +- docs/{ => html-docs}/embedding.html | 1 + docs/html-docs/examples.html | 48 +++++ docs/{ => html-docs}/faq-running.html | 25 ++- docs/{ => html-docs}/faqs.html | 3 +- docs/{ => html-docs}/implemented.html | 232 ++++++++++++++++------ docs/{ => html-docs}/index.html | 42 +++- docs/html-docs/involved.html | 70 +++++++ docs/{ => html-docs}/license.html | 1 + docs/{ => html-docs}/limitations.html | 27 +-- docs/{ => html-docs}/running.html | 30 +-- docs/{ => html-docs}/specs.html | 10 +- docs/involved.html | 97 --------- 17 files changed, 687 insertions(+), 292 deletions(-) delete mode 100644 docs/examples.html create mode 100644 docs/html-docs/architecture.html rename docs/{ => html-docs}/bugs.html (83%) rename docs/{ => html-docs}/compiling.html (89%) rename docs/{ => html-docs}/download.html (96%) rename docs/{ => html-docs}/embedding.html (99%) create mode 100644 docs/html-docs/examples.html rename docs/{ => html-docs}/faq-running.html (69%) rename docs/{ => html-docs}/faqs.html (91%) rename docs/{ => html-docs}/implemented.html (66%) rename docs/{ => html-docs}/index.html (50%) create mode 100644 docs/html-docs/involved.html rename docs/{ => html-docs}/license.html (99%) rename docs/{ => html-docs}/limitations.html (89%) rename docs/{ => html-docs}/running.html (87%) rename docs/{ => html-docs}/specs.html (94%) delete mode 100644 docs/involved.html diff --git a/docs/examples.html b/docs/examples.html deleted file mode 100644 index df81eae69..000000000 --- a/docs/examples.html +++ /dev/null @@ -1,60 +0,0 @@ -Examples

- -


	Warning

The following files show some simple examples, how formatting object files conforming to the xsl working - draft could look like to work with FOP. Please be warned: At the moment FOP only supports the - XSL Working Draft 21 April 1999 and the examples are also following this version. -

- -


	Normal text

xsl-fo-file
pdf-file


	Simple table

xsl-fo-file
pdf-file


	Simple list

xsl-fo-file
pdf-file


	All examples

jar file

You can unpack this jar file by using the java command line tool jar

jar xf fop-examples.jar

The jar file format is identical with the zip file format, so you can - can also use your normal unzip tools instead of jar -

- -

\ No newline at end of file diff --git a/docs/html-docs/architecture.html b/docs/html-docs/architecture.html new file mode 100644 index 000000000..f1f7472b8 --- /dev/null +++ b/docs/html-docs/architecture.html @@ -0,0 +1,276 @@ +FOP Mechanics

+ +


	Introduction

+ +

+The overall process is controlled by org.apache.fop.apps.Driver. In +this class, a typical sequence is:

+ +

Driver driver = new Driver();

driver.setRenderer("org.apache.fop.render.pdf.PDFRenderer", version);

driver.addElementMapping("org.apache.fop.fo.StandardElementMapping");

driver.addElementMapping("org.apache.fop.svg.SVGElementMapping");

driver.setWriter(new PrintWriter(new FileWriter(args[1])));

driver.buildFOTree(parser, fileInputSource(args[0]));

driver.format();

driver.render();

+ +


	Formatting Object Tree

The class org.apache.fop.fo.FOTreeBuilder is responsible for actually +constructing the FO tree. The key SAX events used are

startElement(),

endElement() and characters().

+ +

All formatting objects derive from abstract class +org.apache.fop.fo.FONode. The other FO classes inherit from +FONode as follows:

+ +

FONode

|

__________|________

| |

FObj FOText

|

|___________________

| |

FObjMixed SequenceSpecifier +

+ +

FO's extending FObj:

+ +

Package org.apache.fop.fo.pagination:

+ + +

LayoutMasterSet

PageSequence

RegionAfter

RegionBefore

RegionBody

Root

SequenceSpecification

SimplePageMaster

+ + +

Package org.apache.fop.fo.flow:

+ + +

BlockContainer

DisplayGraphic

DisplayRule

DisplaySequence

Flow

InlineGraphic

ListBlock

ListItem

ListItemBody

ListItemLabel

PageNumber

StaticContent

Table

TableBody

TableCell

TableColumn

TableRow

+ +

FO's extending SequenceSpecifier:

+ +

Package org.apache.fop.fo.pagination:

+ + +

SequenceSpecifierAlternating

SequenceSpecifierRepeating

SequenceSpecifierSingle

+ +

FO's extending FObjMixed:

+ +

Package org.apache.fop.fo.flow:

+ + +

Block

InlineSequence

SimpleLink

+ +


	FONode

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

+ +

+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 layout() method. +

+ +


	Making FO's

+ +

+Every FO class has code that looks something like this: +

+ +

public static class Maker extends FObj.Maker {

public FObj make(FObj parent, PropertyList propertyList)

throws FOPException

{

return new SimplePageMaster(parent, propertyList);

}

+ + +

+The class also has a static method that resembles +

+ +

public static FObj.Maker maker()

{

return new PageSequence.Maker();

}

+ +

+A hash 'fobjTable' exists in FOTreeBuilder, and maps the FO names (such as +'fo:table') to object references to the appropriate factories +(such as Table.Maker). +

+ +

+Properties (recall that FO's have properties, areas have traits, and XML +nodes have attributes) are also a concern of FOTreeBuilder. It +accomplishes this by using PropertyListBuilder, which contains a hash of +property names and their respective makers. The base class for +properties is Property, and the property makers extend +Property.Maker. +


	FO Formatting

+ +

+FOTreeBuilder calls format() on the root FO, passing +it the AreaTree +reference. In turn, Root calls format() on each +PageSequence, passing it +the AreaTree reference. +

+ +

+The PageSequence format() method does the following things: +

+ +

Makes a Page, using PageMasterFactory to produce a +PageMaster, and +using makePage() in the latter class. In the simplest picture, +a Page has +5 areas represented by AreaContainers;
Handles layout for StaticContent objects in the 'before' and 'after' +regions, if set. This uses the layout() method in +StaticContent;
If a page break is not forced, it will continue to layout the flow into +the body area (AreaContainer) of the current page;
It continues with (1) when layout into the current page is done, but +the flow is not empty.

+ +


	Area Layout

+ +

+FO's that represent actual areas, starting with Flow and +StaticContent, have +a layout() method, with the following signature: +

+ +

++ public Status layout(Area area) + +

+ +

+The fundamental role of the layout() method is to manage the layout of +children and/or to generate new areas. +

+ +

+Example: the layout() method for Flow generates no new areas - it manages the +layout of the flow children. +

+ +

+Example: the layout() method for Block +generates a new BlockArea in and of +itself, and also manages the layout of the block children, which are added +to the BlockArea before that is itself added to its parent +Area. +

+ +

+Layout() methods are subject to the general constraint that possibly not +all of their children can be accommodated, and they report back accordingly +with an appropriate Status. +

+ +


	Rendering

+ +

+This is a separate process. The render() method in +Driver is invoked (say, +by CommandLine) with the laid-out AreaTree and a +PrintWriter as arguments. +This actually calls the render() method in a specific implementation of +the Renderer interface, typically PDFRenderer or +AWTRenderer. +

+ +

+At the highest level PDFRenderer, for example, begins by rendering each +Page. The render() method in Page (as is the case for other areas), +invokes a particular method in the renderer of choice, e.g. +renderPage(). +NOTE: this system is bypassed for Page, incidentally. +

+ +

+Rendering will not be discussed further in this document, as most of our +current effort must concentrate on layout. Section 4.12 in the XSL WD +discusses some issues applicable to rendering. +

+ +

\ No newline at end of file diff --git a/docs/bugs.html b/docs/html-docs/bugs.html similarity index 83% rename from docs/bugs.html rename to docs/html-docs/bugs.html index 97e82882c..516b2ac69 100644 --- a/docs/bugs.html +++ b/docs/html-docs/bugs.html @@ -12,6 +12,7 @@

@@ -19,21 +20,26 @@


	How to report bugs

Please use the bug reporting system bugzilla - , which is part of xml.apache.org.

Please report bugs to the discussion list fop-dev@xml.apache.org and put + the word [BUG] in the subject line.

Please make sure, before you report a bug, that it is not mentioned in the FAQ or + in the list of open bugs in the file STATUS in the start directory of the Fop + distribution.

Please make your description as concise as possible and send an example fo + file with your report, which just demonstrates the problem. Thanks for your help!


	Some bugs

In release version 0.12.0 you cannot use FOP with the commandline XTCommandLine. - This results always in the fatal error "Root element must be root". If you need - XTCommandLine please use the cvs version, where the bug is fixed, or a newer version - of FOP. -

The page count (/Count tag) in the Pages dictionary is 0 in PDF files produced by - FOP. Most of the time this doesn't do any harm, but it has been reported to be a - problem with xpdf. -

Colour not continued onto subsequent pages, if coloured block goes over page. -


	Known bugs

Colour not continued onto subsequent pages, if coloured block goes over page.
SVG linearGradients don't appear the same as in other SVG Viewers
colour not continued onto subsequent pages if coloured block goes over page
no SVG support in AWTCommandLine
keep-next doesn't work and doubles the text lines which should be moved to the next page
pdf files created with Fop don't print correctly on postscript printers
lists containing list do not keep their indentation correctly over a page boundary
id references are marked as illegally doubled, if they are first layouted at the bottom of a page + and then moved to the next page

Copyright © 1999 The Apache Software Foundation. diff --git a/docs/compiling.html b/docs/html-docs/compiling.html similarity index 89% rename from docs/compiling.html rename to docs/html-docs/compiling.html index b4dbd6dd1..82aa9ed93 100644 --- a/docs/compiling.html +++ b/docs/html-docs/compiling.html @@ -12,6 +12,7 @@

+

@@ -35,7 +36,7 @@
Some of the Java source code in FOP is generated from XML using XSLT. Xalan must be used to generate this code.

Xalan is an XSL stylesheet processor written in java. At the moment you - can't use any other processor, because the make file makes use of some + can't use any other processor, because the make process makes use of some proprietary features of Xalan which allow to write output in more then one document. You can find Xalan also at xml.apache.org. You have to use Xalan version 0.19.5 or later. @@ -46,11 +47,21 @@ root directory. This is true, even if you use JDK 1.2 or above, which don't need this setting. It is used by the compilation software.


	Settings in your classpath

If you want Fop to use the image library jimi, it should be in your classpath during + compilation. +

A CLASSPATH for a complete compilation of Fop could look like this, if all these jar files are in + a directory called jars (example uses windows syntax): +

set CLASSPATH=\jars\xalan.jar;\jars\xerces.jar;\jars\bsf.jar;\jars\jimi.jar; +


	Compiling

Compilation is started by executing build, a batch file on win32 or a shell script on unix. The compilation uses Ant, +

Compilation is started by executing build, either as a batch file on win32 (build.bat) or as a shell script on unix. The compilation uses Ant, a replacement of make (you can find more information about Ant at - jakarte.apache.org). + jakarte.apache.org). build.xml is the replacement of makefile. Look there for further information.

A help screen is shown by calling "build usage".

diff --git a/docs/download.html b/docs/html-docs/download.html similarity index 96% rename from docs/download.html rename to docs/html-docs/download.html index 8eab67490..08b4ee89d 100644 --- a/docs/download.html +++ b/docs/html-docs/download.html @@ -12,6 +12,7 @@

@@ -19,9 +20,8 @@

You can download the latest release version FOP 0.12.1.

Note: This jar file must be unpacked. It contains the binary fop_bin_0_12_1.jar, - the documentation (including some example fo files) and the source.

You can download the latest release version from the distribution directory.

The file contains also the documentation (including some example fo files) and the source.

To run FOP from the command line, see Running FOP. If you are interested in embedding FOP in a Java application of your own, see Embedding FOP. diff --git a/docs/embedding.html b/docs/html-docs/embedding.html similarity index 99% rename from docs/embedding.html rename to docs/html-docs/embedding.html index 5605049c5..86f023e5d 100644 --- a/docs/embedding.html +++ b/docs/html-docs/embedding.html @@ -12,6 +12,7 @@

+

diff --git a/docs/html-docs/examples.html b/docs/html-docs/examples.html new file mode 100644 index 000000000..38ac499c1 --- /dev/null +++ b/docs/html-docs/examples.html @@ -0,0 +1,48 @@ +Examples

+
+
+
+
+
+
+
+
+
+
+
+
+
+ +
+
+
+
+ +
+
Examples for the use of xsl:fo can be found in the Fop distribution in + the subdirectory xml-fop/docs/examples/fo. You can start transformation of all fo files into pdf + files by starting xml-fop/docs/examples/runtests. +
+
At the moment the following files are part of the distribution:
+
+
normal.fo - a very simple file showing the use of a 2 level of headings, normal text and a header. +
+
table.fo - a simple table +
+
list.fo - a simple list +
+
images.fo - shows how to embed gif and jpg images into the xsl:fo file using inline-graphic. +
+
border.fo - a not so simple example how to use borders in tables +
+
extensive.fo - a longer test file containing a lot of different flow objects and properties. + A good candidate to test your bugfix or new Fop code. +
+
+
Developers will find the first steps to a test suite for all implemented formatting objects and + properties in xml-fop/docs/bugtests.
+ +

+ Copyright © 1999 The Apache Software Foundation. + All Rights Reserved. +
\ No newline at end of file diff --git a/docs/faq-running.html b/docs/html-docs/faq-running.html similarity index 69% rename from docs/faq-running.html rename to docs/html-docs/faq-running.html index 002f546ee..633f698c8 100644 --- a/docs/faq-running.html +++ b/docs/html-docs/faq-running.html @@ -12,39 +12,46 @@

+

-


	Questions

Formatting object xxx doesn't work as expected
Fatal error: Root element must be root
Char '>' inserted into page number
Are font properties allowed here
Embedding fonts


	Answers


	Q: Feature xxx of the XSL Working Draft 12 January 2000 does not work as it should. Why?

A: First: Only a small subset of formatting objects and properties is +


	Questions

Source files for the formatting properties are missing
Formatting object xxx doesn't work as expected
Supporting the latest XSL working draft
Fatal error: Root element must be root
Char '>' inserted into page number
Are font properties allowed here
Supported fonts


	Answers


	Q: I can't find the source files for the formatting properties. The directories + where they should be are empty. Where can I find them?

A: They are generated during the build process. So you should use the build script coming + with Fop at least once to generate these files. +


	Q: Feature xxx of the XSL Working Draft 27 March 2000 does not work as it should. Why?

A: First: Only a small subset of formatting objects and properties is implemented at the moment. Please have a look at the section "Features", which lists the supported fo and properties. Second: At the moment only - Working Draft 21 Apr 1999 is supported. + Working Draft 21 Apr 1999 is supported. +


	Q: When will the latest version of the XSL working draft be supported?

Basic conformance to the latest XSL working draft is scheduled for fall 2000.


	Q: Running FOP I get the following messages or something similar: +


	Q: Running FOP I get the following messages or something similar: "WARNING: Unknown formatting object http://www.w3.org/XSL/Format/1.0^root" and then a FATAL Error "Root element must be root, not default FO".

A: Make sure that you have specified as the namespace for fo the following string: "http://www.w3.org/1999/XSL/Format". It is analogous to the xslt namespace "http://www.w3.org/1999/XSL/Transform"


	Q: The char ">" is inserted into the page number display like this +


	Q: The char ">" is inserted into the page number display like this "formatting FOs into areas [1] [2] [3>>>>]". Is this a bug?

A: No, a feature. It simply means that on that page an area - overflowed (ie there was not enough room to fit the text in).


	Q: It looks like FOP must be honoring font properties when it shouldn't be? + overflowed (ie there was not enough room to fit the text in).


	Q: It looks like FOP must be honoring font properties when it shouldn't be? Example: According to the dtd coming with the xsl-fo spec inline-sequence shouldn't have any attributes, but FOP doesn't reject them.

Font properties are inherited down to individual characters. You can +

A: Font properties are inherited down to individual characters. You can specify font properties on any formatting object you like and any textual content will inherit those properties (unless overriden by a closer ancestor).

The dtd coming with the xsl-fo spec isn't correct in this respect.


	I need some additional fonts in FOP. How I can set embedding fonts? +


	Q: I need some additional fonts in FOP. How I can set embedding fonts?

At present, FOP does not support any fonts other than the in-built fonts - Times, Helvetica and Courier. +

A: At present, FOP does not support any fonts other than the built-in fonts + Times, Helvetica, Courier, Symbol and ZapfDingbats.

Copyright © 1999 The Apache Software Foundation. diff --git a/docs/faqs.html b/docs/html-docs/faqs.html similarity index 91% rename from docs/faqs.html rename to docs/html-docs/faqs.html index a3c96f426..447ebbba9 100644 --- a/docs/faqs.html +++ b/docs/html-docs/faqs.html @@ -12,6 +12,7 @@

+

@@ -20,7 +21,7 @@


	FAQ Running FOP

Read the FAQ Running FOP document or jump directly to: -

+
Source files for the formatting properties are missing
Formatting object xxx doesn't work as expected
Supporting the latest XSL working draft
Fatal error: Root element must be root
Char '>' inserted into page number
Are font properties allowed here
Supported fonts

\ No newline at end of file diff --git a/docs/implemented.html b/docs/html-docs/implemented.html similarity index 66% rename from docs/implemented.html rename to docs/html-docs/implemented.html index 244de36b1..abfa4357e 100644 --- a/docs/implemented.html +++ b/docs/html-docs/implemented.html @@ -12,6 +12,7 @@

@@ -20,91 +21,208 @@


	What's Implemented?

The following formatting objects and properties of the xsl-fo - working draft (21 Apr 1999) are implemented. Please have also a look at the + working draft (27 March 2000) are implemented. Please have also a look at the section on limitations


	1) Formatting Objects

root
layout-master-set
simple-page-master
region-body
region-before
region-after
page-sequence
sequence-specification
sequence-specifier-single
sequence-specifier-repeating
sequence-specifier-alternating
flow
static-content
block
conditional-page-master-reference
display-rule
display-sequence
external-graphic
flow
inline-sequence
layout-master-set
list-block
list-item
list-item-label
list-item-body
list-item-label
page-number
display-sequence
inline-sequence
display-rule
display-graphic
page-number-citation, see limitations
page-sequence
page-sequence-master
region-after
region-before
region-body
repeatable-page-master-alternatives
repeatable-page-master-reference
root
simple-page-master
simple-link (internal and external)
single-page-master-reference
static-content
table (minimal support)
table-column (minimal support)
table-body (minimal support)
table-row (minimal support)
table-cell (minimal support)

table-column (minimal support)

table-row (minimal support)


	2) Properties

background-color
blank-or-not-blank
border-after-color
border-after-style
border-after-width
border-before-color
border-before-style
border-before-width
border-bottom
border-bottom-color
border-bottom-style
border-bottom-width
border-color (only one value allowed)
border-end-color
border-end-style
border-end-width
border-left
border-left-color
border-left-style
border-left-width
border-right
border-right-color
border-right-style
border-right-width
border-start-color
border-start-style
border-start-width
border-style
border-top
border-top-color
border-top-style
border-top-width
border-width
bottom
break-after
break-before
color
column-width
end-indent
page-master-name
page-master-first
page-master-repeating
page-master-odd
page-master-even
margin-top (only on pages and regions)
margin-bottom (only on pages and regions)
margin-left (only on pages and regions)
margin-right (only on pages and regions)
extent
page-width
page-height
external-destination
flow-name
font-family
font-size
font-style
font-weight
font-size
height
id
initial-page-number
internal-destination
keep-with-next
left
line-height
text-align
text-align-last
space-before.optimum
space-after.optimum
start-indent
end-indent
margin-bottom (only on pages and regions)
margin-left (only on pages and regions)
margin-right (only on pages and regions)
margin-top (only on pages and regions)
master-name
maximum-repeats
odd-or-even
padding (only one value allowed)
padding-after
padding-before
padding-bottom (only in conjunction with background color)
padding-end
padding-left (only in conjunction with background color)
padding-right (only in conjunction with background color)
padding-start
padding-top (only in conjunction with background color)
page-height
page-position
page-width
position (allowed values: "static" (default),"relative", "absolute", fixed )
provisional-distance-between-starts
provisional-label-separation
ref-id
right
rule-thickness
color
wrap-option
white-space-treatment
break-before
break-after
space-after.optimum
space-before.optimum
src
start-indent
text-align
text-align-last
text-indent
href
column-width
background-color
padding-top (only in conjunction with background color)
padding-left (only in conjunction with background color)
padding-bottom (only in conjunction with background color)
padding-right (only in conjunction with background color)
border-color (only one value allowed)
border-style (allowed value: "solid")
border-width (only one value allowed)
position (allowed values: "static" (default), "relative", "absolute", fixed )
padding (only one value allowed)
top
white-space-treatment
width
wrap-option

+ +


	3) SVG elements supported

rect
circle
line
text - tref, tspan
path
polygon
ellipse
g
svg (inside)
image
use
defs (including referenced items not in defs element)
linearGradient
radialGradient
stop


	4) SVG properties supported

style
fill (style)
stroke (style)
stroke-width (style)
stroke-dasharray (style)
stroke-offset (style)
stroke-linecap (style)
stroke-linejoin (style)
stroke-miterlimit (style)
stop-color (style)
color (style)
font (style)
font-size (style)
font-family (style)
font-weight (style)
font-style (style)
x
y
x1
y1
x2
y2
r
cx
cy
x (list)
y (list)
dx
dy
transform
rotate (transform)
translate (transform)
scale (transform)
matrix (transform)
skewX (transform)
skewY (transform)
d
id
width
height
xlink:href
refX
refY
offset
points
fx
fy

diff --git a/docs/index.html b/docs/html-docs/index.html similarity index 50% rename from docs/index.html rename to docs/html-docs/index.html index fcece4c80..cb35cbeea 100644 --- a/docs/index.html +++ b/docs/html-docs/index.html @@ -1,4 +1,4 @@ -What is FOP?

+Fop

@@ -12,24 +12,58 @@

+

-
+
What is FOP?

FOP is the world's first print formatter driven by XSL formatting - objects. It is a Java 1.1 application that reads a formatting object + objects. It is a Java application that reads a formatting object tree and then turns it into a PDF document. The formatting object tree, can be in the form of an XML document (output by an XSLT engine like XT or Xalan) or can be passed in memory as a DOM Document or (in the case of XT) SAX events.

FOP is part of Apache's XML project. The homepage of FOP is - http://xml.apache.org/fop. + http://xml.apache.org/fop. A list + of the committers to this project and the tasks they are working on can be found + in the file Status

+ +
FOP Objectives
+
The goals of the Apache XML FOP Project are to deliver an XSL FO->PDF formatter that is compliant to at least the Basic + conformance level described in the 27 March 2000 XSL WD, and that complies with the 11 March 1999 Portable Document + Format Specification (Version 1.3) from Adobe Systems. +
+ +
Conformance to the XML 1.0 Recommendation, XSLT 1.0 Recommendation and the XML Namespaces Recommendation is + understood. Other relevant documents, such as the XPath and XLink Working Drafts, are referenced as necessary. The FOP + Project will attempt to use the latest version of evolving specifications. +
+ +
Secondary goals of the FOP Project (also, "FOP") are desirable requirements that also have a high priority. +
+ +
One secondary goal of the FOP Project is to deliver a follow-on version of the formatter that is compliant to the Extended + conformance level described in the XSL FO. Any formatting objects that cannot be translated into PDF will be explicitly + identified as such. +
+ +
Another secondary goal is to promote the conversion of SVG into PDF. The most natural mechanism for doing so is within + fo:instream-foreign-object FO's. The powerful graphics offered by both SVG and PDF are a natural fit, and it is + desirable that FOP natively supports an SVG content processor for the fo:instream-foreign-object. +
+ +
A final secondary goal is the continued refinement of the FOP design and implementation. In particular, maintaining the + separation between formatting and rendering, continuing to support the AWT Viewer renderer (backend), and providing + new renderers, are all desirable objectives. +
+

+

Copyright © 1999 The Apache Software Foundation. All Rights Reserved. diff --git a/docs/html-docs/involved.html b/docs/html-docs/involved.html new file mode 100644 index 000000000..917e1958f --- /dev/null +++ b/docs/html-docs/involved.html @@ -0,0 +1,70 @@ +Getting involved

+
+
+
+
+
+
+
+
+
+
+
+
+
+ +
+
+
+
+ +
+ +
Read the Status file
+
The Status file contains the list of features people are working on at the moment. + And an outline what steps are next.
+

+
Subscribe to the fop discussion list
+
You can subscribe to fop-dev@xml.apache.org by sending an email + to fop-dev-subscribe@xml.apache.org
+
Sending bug reports and feature requests to the list is a welcome and important contribution to + developing Fop.
+
Read also the archive + of the discussion list fop-dev to get an idea of the issues being discussed.
+

+
Look at the developer's code using cvs
+
Between releases the newest code can be accessed via cvs. To do this you need to install a cvs + client on your computer if it is not already there. An explanation how to connect to the + Fop source repository can be found at http://xml.apache.org/cvs.html. + An introduction into cvs and the cvs manual can be found in the + reference library.
+
All changes to the code repository are annonced in a special discussion group. You can subscribe + to fop-cvs@xml.apache.org by sending an email to + fop-cvs-subscribe@xml.apache.org. If you want to contribute to the development of Fop you should subscribe, + because it is important that you follow changes being made.
+

+
Contributing code and documentation
+
If you want to contribute code (p.e. a bugfix) or documentation (p.e. an additional example), please do the following:
+
1) Make sure your code doesn't break the existing one and that Fop still compiles.
+
2) Create a file which shows the differences to the existing code.
+
3) Send this file to fop-dev@xml.apache.org.
+
One of the committers will test your code and commit it to the code repository.
+
BTW: The Apache project knows different roles for contributors, namely 'users', 'developers', 'committers' and the 'Project + Management Committee' (An explanation of these roles can be found here).
+

+
Get familiar with the Fop related standards
+
At the moment Fop is mainly a tools to render XSL:FO files to pdf. Therefore if you want to contribute to Fop you should become + familiar with these standards. You can find their internet addresses on our website.
+

+
Fop's architecture
+
A bird's eye view on the way Fop operates can be found in the document FOP Mechanics
+
If you want to extend the functionality of FOP by adding new formatting objects, you should do the following:
+
1. FO Object: Write a class which contains the description of your formatting object and put it into the package fop.fo.flow, fop.fo.pagination (if it is a property it goes to fop.fo.properties. The classes in this package are generated via an xslt stylesheet located in codegen/properties.xml)
+
2. Element Mapping: Add it to the list in fop.fo.StandardElementMapping (if it is a property you need to add it to fop.fo.PropertyListBuilder)
+
3. Area: Either your need can be fulfilled within one of the existing classes in fop.layout, then just add the code to handle the new fo/property or you must write a new one.
+
4. Renderer: Choose the renderer you are interested in. If you worked on an existing layout class you must add code to handle the new features to the already existing area specific method in the renderer class. Otherwise you have to add a new method.
+

+

+ Copyright © 1999 The Apache Software Foundation. + All Rights Reserved. +
\ No newline at end of file diff --git a/docs/license.html b/docs/html-docs/license.html similarity index 99% rename from docs/license.html rename to docs/html-docs/license.html index 901e19da2..e9218ccec 100644 --- a/docs/license.html +++ b/docs/html-docs/license.html @@ -12,6 +12,7 @@

+

diff --git a/docs/limitations.html b/docs/html-docs/limitations.html similarity index 89% rename from docs/limitations.html rename to docs/html-docs/limitations.html index 868f85ec6..2cbe76235 100644 --- a/docs/limitations.html +++ b/docs/html-docs/limitations.html @@ -12,6 +12,7 @@

+

@@ -19,29 +20,15 @@

The main limitation at the moment is: FOP only supports the XSL working draft 21 Apr 1999, - not the latest from 12 January 2000. FOP implements the fo objects and properties listed - in 'features', sometimes it does so only in a limited way. + not the latest from 27 March 2000. FOP implements the fo objects and properties listed + in features, sometimes it does so only in a limited way.
-
differences between XSL WD 1999 and 2000
-
The following formatting objects (supported by FOP) have changed between - XSL wd 1999 and wd 2000: -
-
<sequence-specification> changed to <page-sequence-master>
-
<sequence-specifier-single> changed to <single-page-master-reference>
-
<sequence-specifier-repeating> changed to <repeatable-page-master-reference>
-
<sequence-specifier-alternating> changed to <repeatable-page-master-alternatives>
-
<display-sequence> changed to <block-container>
-
<inline-sequence> <inline-container>
-
<display-rule> nuked
-
<display-graphic> changed to two tags: <external-graphic> <instream-graphic>
-
The following properties have changed between XSL wd 1999 and wd 2000: +
page-number-citation
+
Only works for table of contents without any problems. The case where the page number doesn't + fit on a line isn't handled, and any text on the same line and after the page-number might not + appear exactly where you want it to.
-
page-master-name nuked replaced with master-name
-
page-master-first implemented using conditional page reference object
-
page-master-repeating do
-
page-master-odd do
-
page-master-even do

list-block
diff --git a/docs/running.html b/docs/html-docs/running.html similarity index 87% rename from docs/running.html rename to docs/html-docs/running.html index 9568e2b10..e1f87e482 100644 --- a/docs/running.html +++ b/docs/html-docs/running.html @@ -12,6 +12,7 @@

+

@@ -20,7 +21,7 @@

Prerequisites

Following software must be installed:
-
a) Java 1.1.x or later
+
a) Java 1.1.x or later (If you want to use AWTCommandLine, you need Swing)

b) An XML parser which supports SAX and DOM like Xerces-J. (Xerces is the default xml parser)
@@ -32,12 +33,11 @@

Starting FOP as an standalone application
-
There are three ways to run FOP from the command line.
+
There are two ways to run FOP from the command line.

a) Batch processing formatting objects (fo) files:

java org.apache.fop.apps.CommandLine fo-file pdf-file
-
b) Batch processing xml files (includes production of the fo-files):
-
java org.apache.fop.apps.XTCommandLine xml-file xsl-file pdf-file
-
c) Previewing the fo-file:
+ +
b) Previewing the fo-file:

java org.apache.fop.apps.AWTCommandLine fo-file

Each method uses next to the fop classes other packages. The following describes each method in detail.
@@ -50,36 +50,24 @@
Classpath settings: You will need to include FOP and your XML Parser in your classpath and so you might invoke FOP, if Xerces-J is your xml parser:
-
java -cp fop_bin_0_12_1.jar;xerces.jar
+
java -cp fop.jar;xerces.jar;w3c.jar

org.apache.fop.apps.CommandLine fo-file pdf-file

If you want to use another sax parser, you will need to set the property org.xml.sax.parser to any other SAX Parser class to use. The following example shows the command line, if you use XP from James Clark:

java -Dorg.xml.sax.parser=com.jclark.xml.sax.Driver
-
-cp fop_bin_0_12_1.jar;xerces.jar;xp.jar
+
-cp fop.jar;xerces.jar;xp.jar;w3c.jar

org.apache.fop.apps.CommandLine fo-file pdf-file

Note: The xerces jar file must be included, because xp has no dom support.

+
Method Two
-
Rather than performing transformation with an XSLT before invoking FOP, it is - possible, if you use XT as your XSLT engine, to just call FOP and have it call - XT for you. To do this, run the class org.apache.fop.apps.CommandLine with the - source XML file name, XSL file name and PDF file name as arguments. You will - need to include XT in your classpath and so you might invoke -
-
java -cp fop_bin_0_12_1.jar;xt.jar;xerces.jar
-
org.apache.fop.apps.XTCommandLine xml-file xsl-file pdf-file
-
Again, if your SAX Parser is other than Xerces, you will need to set the property - org.xml.sax.parser to the SAX Parser class to use. -
-

-
Method Three

If you already produced the FO file, you can preview the results of your transformation without using any pdf viewer by invoking FOP with the viewer application. You will need to include FOP and your XML Parser in your classpath
-
java -cp fop_bin_0_12_1.jar;xerces.jar
+
java -cp fop.jar;xerces.jar;w3c.jar

org.apache.fop.apps.AWTCommandLine fo-file

The viewer uses the swing classes.

Note: If you are using java 2 or later (i.e. jdk 1.2. or later) you can put all diff --git a/docs/specs.html b/docs/html-docs/specs.html similarity index 94% rename from docs/specs.html rename to docs/html-docs/specs.html index dfebaa96f..2c32dc099 100644 --- a/docs/specs.html +++ b/docs/html-docs/specs.html @@ -12,6 +12,7 @@

+

@@ -19,11 +20,14 @@

-
XML Recommendation
-
Latest XSL-FO Working Draft (12 January 2000)
+
Latest XSL-FO Working Draft (27 March 2000)
+
A dtd for the XSL-FO Working Draft (27 March 2000) provided by N. Grigoriev from RenderX

XSL-FO Working Draft 21 Apr 1999
+
Latest SVG Working draft
+
Supported SVG Working Draf
+
XML Recommendation

XSLT Recommendation
-
PDF Documentation
+
Portable Document Format (PDF) 1.3 Reference Manual

Simple API for XML (SAX)

Document Object Model (DOM)

Namespaces in XML Recommendation
diff --git a/docs/involved.html b/docs/involved.html deleted file mode 100644 index 69a189941..000000000 --- a/docs/involved.html +++ /dev/null @@ -1,97 +0,0 @@ -Getting involved

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- -
-
First steps
-
1. Subscribe to fop-dev@xml.apache.org by sending an email - to fop-dev-subscribe@xml.apache.org
-
2. Read the archives to fop-dev to get an idea of the issues being - discussed.
-
3. Subscribe to fop-cvs@xml.apache.org by sending an email to - fop-cvs-subscribe@xml.apache.org (it is important - that you follow changes being made).
-
4. Try :-) to wrap your head around the XSL working draft.
-
5. Get CVS working on your system.
-
6. Ask, on fop-dev, any questions you have at all about the code, design, etc.
-
7. When you feel comfortable modifying the code, send diffs to - fop-dev with your contributions.
-
8. Have fun!
-
xml.apache.org - has a more explicit description how to get involved.
-

-
The Ways of FOP
-
The following shows an example use of FOP from org.apache.fop.apps.CommandLine.java:
- -
1) Driver driver = new Driver();
-
2) driver.setRenderer ("org.apache.fop.render.pdf.PDFRenderer", version);
-
3) driver.addElementMapping ("org.apache.fop.fo.StandardElementMapping");
-
3) driver.addElementMapping ("org.apache.fop.svg.SVGElementMapping");
-
4) driver.setWriter (new PrintWriter(new FileWriter(args[1])));
-
5) driver.buildFOTree(parser, fileInputSource(args[0]));
-
6) driver.format();
-
7) driver.render();
- -
1. step: Initiate class Driver
-
Driver is the primary class that drives overall FOP process.
- -
2. step: Set Renderer
-
You set the renderer for the output format of your choice. At the moment 3 formats are supported: a) pdf (org.apache.fop.render.pdf.PDFRenderer)
-
b) awt (org.apache.fop.render.awt.AWTRenderer)
-
c) xml (org.apache.fop.render.xml.XMLRenderer)
- -
All renderers implement the interface Renderer which defines the methods an area needs to be laid out.
- -
The xml renderer is meant for debugging purposes.
- -
The interface Renderer takes a string as a version argument indicating the application that is producing the output. Many output formats like PDF allow the inclusion of a "Producer" string.
- - -
3. step: Set Element Mapping
-
By setting the element mapping you choose the dictionaries of elements which FOP can handle. At the moment two dictionaries are available:
-
a) Standard xsl elements (org.apache.fop.fo.StandardElementMapping)
-
b) Graphic elements described by SVG (org.apache.fop.svg.SVGElementMapping)
- -
All element mappings implement the interface ElementMapping.
- -
4. step: Set output destination
-
Normally this will be a Printwriter of some sort. If you are just displaying the output on screen you can skip this step.
- -
5. step: Build FO Tree
-
Builds the tree of formatting objects contained in the input source. Either walks the tree of the input document (DOM) or uses SAX events to build up the tree by looking up the definitions of the fo in the element mappings. Depending on whether DOM or SAX is being used, the invocation of the method is either buildFOTree(Document) or buildFOTree(Parser, InputSource) respectively.
- -
6. step: Build Area Tree from FO Tree
-
By calling format() of the driver class the fo tree is written/formatted into a area tree. Every formatting object knows how to layout itself, that is every formatting object has a an layout method which is now called to produce an area.
-
The setup of the font info for the renderer is also done in this step.
- -
7. step: Renderer renders Areas
-
The renderer, which has been set in step 2, is given the area tree. It uses the layout information to output it in its specific format. Example: For the PDF renderer there is a set of methods to create a pdf file containing the FOP supported kind of layout features.
- -
-------------------------------------
-
If you want to extend the functionality of FOP by adding new formatting objects, you should do the following:
- -
1. FO Object: Write a class which contains the description of your formatting object and put it into the package fop.fo.flow, fop.fo.pagination (if it is a property it goes to fop.fo.properties. The classes in this package are generated via an xslt stylesheet located in codegen/properties.xml)
-
2. Element Mapping: Add it to the list in fop.fo.StandardElementMapping (if it is a property you need to add it to fop.fo.PropertyListBuilder)
-
3. Area: Either your need can be fulfilled within one of the existing classes in fop.layout, then just add the code to handle the new fo/property or you must write a new one.
-
4. Renderer: Choose the renderer you are interested in. If you worked on an existing layout class you must add code to handle the new features to the already existing area specific method in the renderer class. Otherwise you have to add a new method.
- -

-

- Copyright © 1999 The Apache Software Foundation. - All Rights Reserved. -
\ No newline at end of file -- 2.39.5