Configuration

From: Keiron Liddle Date: Mon, 28 Oct 2002 08:41:01 +0000 (+0000) Subject: updated docs for dev version X-Git-Tag: Alt-Design-integration-base~376 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=06a4ad36f67612273f489f1b6468805b9d5871c7;p=xmlgraphics-fop.git updated docs for dev version using new forrest docs git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@195365 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/forrest.properties b/forrest.properties new file mode 100644 index 000000000..e6839f1d9 --- /dev/null +++ b/forrest.properties @@ -0,0 +1,27 @@ +############## +# Properties used by forrest.build.xml for building the website +############## + +# Prints out a summary of Forrest settings for this project +#forrest.echo=true + +# Project name (used to name .war file) +project.name=fop-project + +# Specifies name of Forrest skin to use +#project.skin=forrest-site + +# Properties that must be set to override the default locations +#project.status=status.xml +project.content-dir=src/documentation +#project.conf-dir=${project.content-dir}/conf +project.sitemap=${project.content-dir}/sitemap.xmap +#project.xdocs-dir=${project.content-dir}/content/xdocs +#project.stylesheets-dir=${project.content-dir}/resources/stylesheets +#project.images-dir=${project.content-dir}/resources/images +#project.schema-dir=${project.content-dir}/resources/schema +#project.skins-dir=${project.content-dir}/skins +project.skinconf=${project.content-dir}/skinconf.xml +#project.lib-dir=${project.content-dir}/lib +#project.classes-dir=${project.content-dir}/classes + diff --git a/src/documentation/content/xdocs/book.xml b/src/documentation/content/xdocs/book.xml new file mode 100644 index 000000000..e1c2550be --- /dev/null +++ b/src/documentation/content/xdocs/book.xml @@ -0,0 +1,14 @@ + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/dev/book.xml b/src/documentation/content/xdocs/dev/book.xml new file mode 100644 index 000000000..e17c4895d --- /dev/null +++ b/src/documentation/content/xdocs/dev/book.xml @@ -0,0 +1,16 @@ + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/dev/configuration.xml b/src/documentation/content/xdocs/dev/configuration.xml new file mode 100644 index 000000000..894da78ca --- /dev/null +++ b/src/documentation/content/xdocs/dev/configuration.xml @@ -0,0 +1,45 @@ + + + +

+ Configuration +

+ +

+ Configuring FOP +

+In the directory xml-fop/conf you will find an example +configuration file. It contains the default values of various +configurable options available in FOP. +

The file fop.xconf is not read automatically, the user + must specify it on the command line or if embedding then + configure the appropriate classes. +

+ Setting up Hyphenation +

Fop comes already with some hyphenation patterns. If you + need a hyphenation pattern which isn't included in the + distribution, do the following: +

1. get the TeX hyphenation pattern file and turn it into an xml file which conforms + to the hyphenation.dtd in the sub directory /hyph +

2. name this new file following this schema: languageCode_countryCode.xml. If you don't need + a country code, leave it out, e.g the file name for an American english hyphenation pattern + would look like this: en_US.xml. For an Italian file: it.xml. Language and country codes must be + the same as in xsl:fo, that is follow + ISO 639 + and ISO 3166 + respectively. NOTE: The ISO 639/ISO 3166 convention is that language names are + written in lower case, while country codes are written in upper case. +

3. If you have build your new hyphenation pattern file + successfully you put the file into the /hyph directoy + and rebuild Fop. The file will be picked up and added + to the fop.jar. +

+ + diff --git a/src/documentation/content/xdocs/dev/examples.xml b/src/documentation/content/xdocs/dev/examples.xml new file mode 100644 index 000000000..89975a21d --- /dev/null +++ b/src/documentation/content/xdocs/dev/examples.xml @@ -0,0 +1,14 @@ + + + +

+ FO Examples +

+ +

+ + diff --git a/src/documentation/content/xdocs/dev/extensions.xml b/src/documentation/content/xdocs/dev/extensions.xml new file mode 100644 index 000000000..bc6ceeb5a --- /dev/null +++ b/src/documentation/content/xdocs/dev/extensions.xml @@ -0,0 +1,95 @@ + + + +

+ Extensions to FOP +

+ +

+ Overview +

+If the default funtionality of FOP needs to be extended for +some reason then you can write an extensions. +

+There are three types of extensions possible. An output document +extensions such as the PDF bookmarks, an instream-foreign-object +extensions such as SVG and an fo extension that creates an +area in the area tree where normal xsl:fo is not possible. +

+ Default Extensions +

+These extension are available by default. They are automatically loaded +and you only need to provide the correct namespace for your embedded +xml markup. +

+ SVG +

+Please see the SVG page for more details. +

+The SVG extensions gets all the xml elements in the SVG namespace +and builds an SVG DOM with batik. The SVG DOM is then rendered +to the output format using a handler for the XML content of +the instream-foreign-object. +

+ PDF Bookmarks +

+To use this standard Fop extension, you need to add a namespace entry for + http://xml.apache.org/fop/extensions on the root element.

+ +

You can provide outlines inside the root object (but outside + any page-sequences or + other formatting objects). Here's an example of an outline entry:

+ + + + + Running FOP + + + Prerequisites + + + +]]> +

It works similarly to a basic-link. There is also an external-destination + property, but it isn't supported currently. See the pdfoutline.pdf for a more complete example. +

+ Adding Your Own +

+To add your own extension you need to do the following things. +

+Write code that implements your extension functionality. +There are some examples in the contrib/ directory. +

+Create a jar file with your classes, it must also include the +following file "/META-INF/services/org.apache.fop.fo.ElementMapping". +In this file you need to put the fully qualified classname of +your element mappings class. This class must implement the +"org.apache.fop.fo.ElementMapping" interface. +

+Create your fo file with the extra xml data embedded in the file +with the correct name space. The examples for svg and +pdfoutline.pdf +show how this can be done. +

+Put your jar file in the classpath and then run fop over the fo file. +

+ + + diff --git a/src/documentation/content/xdocs/dev/fo/embedding.fo b/src/documentation/content/xdocs/dev/fo/embedding.fo new file mode 100644 index 000000000..4570ad057 --- /dev/null +++ b/src/documentation/content/xdocs/dev/fo/embedding.fo @@ -0,0 +1,1106 @@ + + + + + + + + + + + + + Embedding SVG examples + + + Page + + + + + + Embedding SVG + + + + + + +A less cute tiger + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Some examples of how to embed an SVG image inside your FO documents + + + +Introduction + + + +This document shows some examples of how an SVG document can be embedded directly in +an fo document and how FOP will render it. + + + +There are a couple of ways to specify the XML for embedding. +There are a number of factors which specify exactly how the SVG image will be rendered, such as size, clipping etc. + + + +Note: if you want to know about SVG itself you should consult the appropriate SVG resource. The

Batik Project

is a good resource for information about SVG and samples etc. + + + +XML Syntax + + + +Here we have some examples of how the XML can be specified in the fo document. + + + + + + + + +This first example specifies the name space on the instream-foreign-object using the xmlns:svg attribute. +Then all the svg elements start with the svg: namespace prefix. It can be specified on any element +above where the svg:svg tag appears (eg. fo:root). + + + + + + + + + + + + + + + +]]> + + + + + + + + + + + + + + + + + + + + +This example specifies the name space on the svg:svg element using the xmlns:svg attribute. +Then all the svg elements start with the svg: namespace prefix. +It is able to determine the namespace for the current element. + + + + + + + + + + + + + + + +]]> + + + + + + + + + + + + + + + + + + + + +This example specifies the namespace for the current element, rather than for the svg: prefix. +This means that all elements under this one are assumed to have the same namespace. + + + + + + + + + + +]]> + + + + + + + + + + + + + + + + + + + + +Sizing + + + + The size of the instream-foreign-object is obtained in a number of ways. + + + + + + + + + +Specify the size on the instream-foreign-object element. + + + + + + + + + + + + + + + +]]> + + + + + + + + + + + + + + + + + + + + + + +Specify the size on the svg document element. + + + + + + + + + + + + + + + +]]> + + + + + + + + + + + + + + + + + + + + +Specify the size on the svg document element and for the content size on the instream-foreign-object. + + + + + + + + + + + + + + + +]]> + + + + + + + + + + + + + + + + + + + + + + + + + + +Clipping + + + + + + + +Interesting Functionality + + + + + + + + + + diff --git a/src/documentation/content/xdocs/dev/index.xml b/src/documentation/content/xdocs/dev/index.xml new file mode 100644 index 000000000..73aa550f9 --- /dev/null +++ b/src/documentation/content/xdocs/dev/index.xml @@ -0,0 +1,92 @@ + + + +

+ FOP 1.0 development +

+ +

+ Introduction +

+These pages contain information that is relevant to the +current development of FOP. +

FOP is the world's first print formatter driven by XSL formatting + objects and the world's first output independent formatter. It is a + Java application that reads a formatting object tree and then + renders the resulting pages to a specified output. Output formats + currently supported are PDF, PCL, PS, SVG, XML (area tree representation), + Print, AWT, MIF and TXT. + The primary output target is PDF. +

+ +FOP - someone who is overly concerned with style, also conveniently +can mean Formatting Object Processor. + +

The latest version of Fop is 0.20.4 and it supports the + XSL-FO Version 1.0 + W3C Recommendation. + You can download + Fop including a precompiled version, the source code and many example files to + get you started. Pointers to introductions into xsl:fo can be found in the + resources section. Please be aware, that + Fop is at the moment not a full implementation of the basic conformance level + of the xsl:fo standard. You can find a list of supported flow objects and properties + in the section Features and in section + Limitations in what way this support is + limited. +

FOP is part of Apache's XML project. The homepage of FOP is + http://xml.apache.org/fop. + Here you can find information about using and developing with FOP. +

Users can subscribe to fop-user@xml.apache.org by sending an email + to fop-user-subscribe@xml.apache.org + this is where user specific topics are discussed. +

+ Formatting +

+This image is a demonstration of a two page document. The xml data on the left +is formatted into the two pages on the right. The document contains static areasthat appear on every page, an external graphic in this case an svg document. +There is a footnote on the first page and a table that goes across both pages. +

+The advantage of XSL is the ability to take an XML document and to format +the information into a page layout. The XML document can be generated +in any way, the most common would be to use XSLT. FOP takes the XML +and formats the data into pages. The pages are then rendered to the +requested output. +

+This is a real document. The image was created by rendering the document +to the svg renderer then putting the rendered pages into an svg document +along with the xml. +

+ 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 W3C Recommendation from 15 October 2001, 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. +

+ +

To reach this aim currently the layout system is being redesigned to +better handle the formatting of all different types of formatting objects. +

+ + diff --git a/src/documentation/content/xdocs/dev/svg.xml b/src/documentation/content/xdocs/dev/svg.xml new file mode 100644 index 000000000..9205cc5bc --- /dev/null +++ b/src/documentation/content/xdocs/dev/svg.xml @@ -0,0 +1,234 @@ + + + +

+ SVG in FOP +

+ +

+ Introduction +

+FOP uses the SVG library from +Batik to handle SVG. +This format can be handled as an fo:instream-foreign-object +or in a separate file referenced with fo:external-graphic. +Either way the SVG document will be read in and converted into a +DOM in Batik. This DOM will then be used by the renderer to +create the graphical image. +

+The AWT and Print renderers simply use batik to draw the SVG into a graphic. +

+In the case of the PDF renderer there is a PDFGraphics2D class that Batik uses +to render the image into. This class converts the drawing instructions into +PDF markup which is placed into the current PDF document. +

+ Converting SVG to a PDF Document +

+It is possible to convert a standalone SVG document directly +into a simple page PDF document. +This is possible through the use of Batik's transcoder mechanism.
+java org.apache.batik.apps.rasterizer.Main -m application/pdf document.svg +
+This will output the svg document as "document.pdf" containing +a PDF rendering of the SVG file. +

+It is also possible to specify the width and/or height +of the PDF document on the command line with -w and -h or if +you are using the transcoder api you can use the transcoding hints. +

+Currently the SVG image is drawn at the SVG document size and +simply scaled in PDF to the new size. So the result may not be +the best possible. For example if you have any images or effects +it will draw them at the original resolution of the svg document. +When this is viewed in the pdf it will have an incorrect resolution +for the size of the pdf. +

+The size of the pdf file will also remain the same regardless of +what size the page is. +

+For more information see Batik +for how transcoders work. +

+ Examples +

+These examples illustrate a number of issues relating to conversion +to PDF: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SVG to PDF examples
svg file png file pdf result
images images.svg images.png images.pdf
svg linking link.svg link.png link.pdf
gradients and patterns paints.svg paints.png paints.pdf
various text and effects on text text.svg text.png text.pdf
transparent objects transparency.svg transparency.png transparency.pdf
+As can be seen most of the specific issues are handled. + + + + + + + + + + + + + +
XSL:FO to PDF examples
fo file pdf result
embedding svg embedding.fo embedding.fo.pdf
+

SVG to PDF examples
	svg file	png file	pdf result
images	images.svg	images.png	images.pdf
svg linking	link.svg	link.png	link.pdf
gradients and patterns	paints.svg	paints.png	paints.pdf
various text and effects on text	text.svg	text.png	text.pdf
transparent objects	transparency.svg	transparency.png	transparency.pdf

XSL:FO to PDF examples
	fo file	pdf result
embedding svg	embedding.fo	embedding.fo.pdf

+ Important Notes +

+The svg is inserted into PDF by using PDF commands to draw and fill +lines and curves. This means that the graphical objects created with +this remain as vector graphics. +

+There are a number of SVG things that cannot be converted directly into +PDF. Parts of the graphic such as effects and images are inserted +into the PDF as a raster graphic. The resolution of this graphic may not +be ideal depending on the FOP dpi (72dpi) and the scaling for that graphic. +

+Another important note is that text may be converted and drawn as a +set of shapes by batik. +If possible it will use normal PDF text when inserting text. It does +this by checking if the text can be drawn normally and the font is +supported. This example svg text.svg / +text.pdf +shows how various types and effects with text are handled. +

+If the text cannot be drawn normally then it uses shapes. +This means that a typical character will have about 10 curves +(each curve consists of at least 20 characters). +This can make the pdf files large and when the pdf is viewed the +viewer does not normally draw those fine curves very well (turning on +Smooth Line Art in the Acrobat preferences will fix this). +If the text is inserted into the PDF using the inbuilt text commands +for PDF it will use a single character. +

+ Known Problems +

+soft mask transparency is combined with white so that it looks better +on pdf 1.3 viewers but this causes the soft mask to be slightly lighter +or darker on pdf 1.4 viewers +
+there is some problem with a gradient inside a pattern causing a pdf +error when viewed in acrobat 5 +
+text is not always handled correctly, it may select the wrong font +especially if characters have multiple fonts in the font list +
+more pdf text handling could be implemented +It could draw the string using the attributed character iterator +to handle tspans and other simple changes of text. +
+JPEG images are not inserted directly into the pdf document +This area has not been implemented yet since the appropriate +method in batik is static +
+Uniform transparency for images and other svg elements that are converted +into a raster graphic are not drawn properly in PDF. The image is opaque. +

+ Developer Notes +

+For most output formats in FOP the SVG is simply drawn into +an image with Batik. +For PDF there are a set of classes to handle drawing the +GVT (Graphic Vector Toolkit) +into PDF markup. +

+ Classes +

+These are the relevant classes, found in the package org.apache.fop.svg : +

PDFGraphics2D +
+used for drawing onto a Graphics2D into an existing pdf document, used +internally to draw the svg. +
PDFDocumentGraphics2D +
+used to create a pdf document and inherits from PDFGraphics2D to do the +rest of the drawing. Used by the transcoder to create a standalone pdf +document from an svg. Can be used independantly the same as any Graphics2D. +
PDFTranscoder +
+used by Batik to transcode an svg document into a standalone pdf, via +PDFDocumentGraphics2D. +

+ Ideas +

+Batik can convert ttf to svg font. +This svg font could be converted into a pdf stroked font +(type 3 font). +

+ + diff --git a/src/documentation/content/xdocs/dev/svg/images.svg b/src/documentation/content/xdocs/dev/svg/images.svg new file mode 100644 index 000000000..4337bfa87 --- /dev/null +++ b/src/documentation/content/xdocs/dev/svg/images.svg @@ -0,0 +1,41 @@ + + + diff --git a/src/documentation/content/xdocs/dev/svg/link.svg b/src/documentation/content/xdocs/dev/svg/link.svg new file mode 100644 index 000000000..5a6d28264 --- /dev/null +++ b/src/documentation/content/xdocs/dev/svg/link.svg @@ -0,0 +1,30 @@ + + + diff --git a/src/documentation/content/xdocs/dev/svg/paints.svg b/src/documentation/content/xdocs/dev/svg/paints.svg new file mode 100644 index 000000000..ee0122e3b --- /dev/null +++ b/src/documentation/content/xdocs/dev/svg/paints.svg @@ -0,0 +1,83 @@ + + + diff --git a/src/documentation/content/xdocs/dev/svg/text.svg b/src/documentation/content/xdocs/dev/svg/text.svg new file mode 100644 index 000000000..8ac73ec51 --- /dev/null +++ b/src/documentation/content/xdocs/dev/svg/text.svg @@ -0,0 +1,131 @@ + + + diff --git a/src/documentation/content/xdocs/dev/svg/transparency.svg b/src/documentation/content/xdocs/dev/svg/transparency.svg new file mode 100644 index 000000000..ec3753b02 --- /dev/null +++ b/src/documentation/content/xdocs/dev/svg/transparency.svg @@ -0,0 +1,48 @@ + + + diff --git a/src/documentation/content/xdocs/index.xml b/src/documentation/content/xdocs/index.xml new file mode 100644 index 000000000..4c10c9510 --- /dev/null +++ b/src/documentation/content/xdocs/index.xml @@ -0,0 +1,14 @@ + + + +

+ FOP +

+ +

+ Introduction +

+ + diff --git a/src/documentation/content/xdocs/tabs.xml b/src/documentation/content/xdocs/tabs.xml new file mode 100644 index 000000000..c431ae015 --- /dev/null +++ b/src/documentation/content/xdocs/tabs.xml @@ -0,0 +1,12 @@ + + + + + + + + + diff --git a/src/documentation/resources/images/group-logo.gif b/src/documentation/resources/images/group-logo.gif new file mode 100644 index 000000000..57e4b36a1 Binary files /dev/null and b/src/documentation/resources/images/group-logo.gif differ diff --git a/src/documentation/resources/images/logo.jpg b/src/documentation/resources/images/logo.jpg new file mode 100644 index 000000000..1e1ef8fa3 Binary files /dev/null and b/src/documentation/resources/images/logo.jpg differ diff --git a/src/documentation/sitemap.xmap b/src/documentation/sitemap.xmap new file mode 100644 index 000000000..bc739a905 --- /dev/null +++ b/src/documentation/sitemap.xmap @@ -0,0 +1,527 @@ + + + + + + + + + + + + + + + + + + + + + + false + false + false + + + + + + + + + + + + -//W3C//DTD HTML 4.01 Transitional//EN + ISO-8859-1 + + + + ISO-8859-1 + + + + + + + ISO-8859-1 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/skinconf.xml b/src/documentation/skinconf.xml new file mode 100644 index 000000000..82d35a62f --- /dev/null +++ b/src/documentation/skinconf.xml @@ -0,0 +1,93 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ]> + + + + false + xml.apache.org + Apache XML + + + FOP + http://xml.apache.org/fop/ + images/logo.jpg + + Apache XML + http://xml.apache.org/ + images/group-logo.gif + + + + + + 1999-2002 + The Apache Software Foundation. + + + + + + + + + + + + Built with Cocoon + http://xml.apache.org/cocoon/ + skin/images/built-with-cocoon.gif + 88 + 31 + + + Krysalis Centipede + http://www.krysalis.org/centipede/ + skin/images/centipede-logo-small.gif + 138 + 31 + + +