diff options
Diffstat (limited to 'src/documentation')
29 files changed, 2242 insertions, 43 deletions
diff --git a/src/documentation/content/xdocs/book.xml b/src/documentation/content/xdocs/book.xml index 257c61ae0..a9427bcd7 100644 --- a/src/documentation/content/xdocs/book.xml +++ b/src/documentation/content/xdocs/book.xml @@ -8,9 +8,37 @@ <menu label="About"> <menu-item label="Index" href="index.html"/> + <menu-item label="News" href="news.html"/> <menu-item label="FAQs" href="faq.html"/> + <menu-item label="Download" href="download.html"/> + <menu-item label="Release Notes" href="relnotes.html"/> + <menu-item label="Getting Help" href="gethelp.html"/> + + <menu-item label="Status" href="status.html"/> <menu-item label="Changes" href="changes.html"/> <menu-item label="Todo" href="todo.html"/> + + <menu-item label="Running" href="running.html"/> + <menu-item label="Embedding" href="embedding.html"/> + <menu-item label="Output Formats" href="output.html"/> + <menu-item label="Implemented" href="implemented.html"/> + <menu-item label="Limitations" href="limitations.html"/> + + <menu-item label="SVG" href="svg.html"/> + <menu-item label="Extensions" href="extensions.html"/> + <menu-item label="Fonts" href="fonts.html"/> + <menu-item label="Configuration" href="configuration.html"/> + + <menu-item label="Getting Involved" href="involved.html"/> + <menu-item label="Compiling" href="compiling.html"/> + <menu-item label="Testing" href="testing.html"/> + + <menu-item label="Bugs" href="bugs.html"/> + <menu-item label="Resources" href="resources.html"/> + <menu-item label="License" href="license.html"/> + + <menu-item label="Examples" href="examples.html"/> + <external label="Patch queue" href="http://nagoya.apache.org/bugzilla/buglist.cgi?bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&email1=&emailtype1=substring&emailassigned_to1=1&email2=&emailtype2=substring&emailreporter2=1&bugidtype=include&bug_id=&changedin=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&product=Fop&short_desc=%5BPATCH%5D&short_desc_type=allwordssubstr&long_desc=&long_desc_type=allwordssubstr&bug_file_loc=&bug_file_loc_type=allwordssubstr&keywords=&keywords_type=anywords&field0-0-0=noop&type0-0-0=noop&value0-0-0=&namedcmd=Fop+all&newqueryname=fop+patch+queue&tofooter=1&order=Reuse+same+sort+as+last+time"/> </menu> </book> diff --git a/src/documentation/content/xdocs/bugs.xml b/src/documentation/content/xdocs/bugs.xml new file mode 100644 index 000000000..81005d814 --- /dev/null +++ b/src/documentation/content/xdocs/bugs.xml @@ -0,0 +1,26 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + +<document> + <header> + <title>Bugs</title> + </header> + <body> + <section> + <title>How to report bugs</title> + <p>Please report bugs to <link href="http://nagoya.apache.org/bugzilla/">bugzilla</link>, the Apache bug + database. A copy of your bug report is sent automatically to the discussion list fop-dev@xml.apache.org. </p> + <p>Please make sure, before you report a bug, that it is not mentioned in the FAQ or + in the list of open bugs at bugzilla.</p> + <p>Please make your description as concise as possible and add an example fo + file with your report, which just demonstrates the problem. Thanks for your help!</p> + </section> + <section> + <title>Known bugs</title> + <p>A list of known bugs can be found at + <link href="http://nagoya.apache.org/bugzilla/">bugzilla</link>.</p> + </section> +</body> +</document> + + diff --git a/src/documentation/content/xdocs/compiling.xml b/src/documentation/content/xdocs/compiling.xml new file mode 100644 index 000000000..61baf4c12 --- /dev/null +++ b/src/documentation/content/xdocs/compiling.xml @@ -0,0 +1,46 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + +<document> + <header> + <title>Compiling FOP</title> + </header> + <body> + <section> + <title>Compiling FOP</title> + <p>Compilation is started by executing build, either as a batch file on win32 (build.bat) or as a shell script on unix. Before you + can start one of these scripts, you have to setup your classpath and the environment variable JAVA_HOME (see below).</p> + <p> The compilation uses Ant, + a replacement of make (you can find more information about Ant at + <link href="http://jakarta.apache.org/ant/">jakarta.apache.org</link>). + build.xml is the replacement of makefile. Look there for detailed information on the build + process and different targets. </p> + <p>A help screen is shown by calling "build usage".</p> + <p>If you only want to use Fop, you don't need to build it. A fop.jar comes with the distribution.</p> + <section> + <title>Setting up your classpath</title> + <note>You don't have to setup your classpath; all libraries needed to compile Fop are coming with + the distribution and are referenced by the build script, so you only need to care about them, + if you build Fop in any other way. See build.bat/build.sh for details. </note> + </section> + <section> + <title>Setting of JAVA_HOME</title> + <p>You have to set the enviroment variable JAVA_HOME. It must point to your local JDK + root directory. This is true, even if you use JDK 1.2 or above, which normally don't need this + setting. It is used by Ant, the compilation software.</p> + </section> + <section> + <title>Problems</title> + <p>If you have problems compiling Fop, please try this first: </p> + <ul> + <li>delete the build directory completely and try a new build from scratch</li> + <li>check, whether you have an older version of xerces.jar, xalan.jar, batik.jar somewhere in + you classpath.</li> + </ul> + <p>If you still have problems, please look at the + page <link href="bugs.html">bugs</link>, for further help.</p> + </section> +</section> +</body> +</document> + diff --git a/src/documentation/content/xdocs/configuration.xml b/src/documentation/content/xdocs/configuration.xml new file mode 100644 index 000000000..eddf1ea18 --- /dev/null +++ b/src/documentation/content/xdocs/configuration.xml @@ -0,0 +1,57 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + +<document> + <header> + <title>Configuration</title> + </header> + + <body> +<section> + <title>Configuration</title> + <section> + <title>How to configure Fop</title> + <p>In the directory xml-fop/conf you will find two configuration files. One of them, + config.xml, is only intended for Fop developers, who want to add new default values + to some Fop feature. Don't change this file. For user configuration there is a file called + userconfig.xml. It contains templates for all settings a user can change. Most of them are + commented out. Uncomment the entry you want to set and change the value according to + your wishes. Please regard any comments which specify the value range. And, well, the + configuration files are xml files, so keep them at least well-formed ;-) + </p> + <p>The file userconfig.xml is not read automatically, but the user must specify its use on + the command line. See <link href="running.html">Running Fop</link> + or <link href="embedding.html">Embedding Fop</link> for details. + </p> + </section> + <section> + <title>setting up hyphenation</title> + <p>Fop comes already with some hyphenation pattern. If you need a hyphenation pattern + which isn't included in the distribution, do the following: + </p> + <p>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 + </p> + <p>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 + <link href="http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt">ISO 639</link> + and <link href="http://www.ics.uci.edu/pub/ietf/http/related/iso3166.txt">ISO 3166</link> + 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. + </p> + <p>3. If you have build your new hyphenation pattern file successfully there are + two ways to make it accessible to Fop. + </p> + <p> a) Put this new file into the directory /hyph and rebuild Fop. The file will + be picked up and added to the fop.jar. + </p> + <p> b) Put the file into a directory of your choice and specify this directory + in the userconfig.xml in the entry <hyphenation-dir>. + </p> + </section> +</section> + </body> +</document> + diff --git a/src/documentation/content/xdocs/dev/index.xml b/src/documentation/content/xdocs/dev/index.xml index 73aa550f9..1ed024917 100644 --- a/src/documentation/content/xdocs/dev/index.xml +++ b/src/documentation/content/xdocs/dev/index.xml @@ -24,7 +24,7 @@ FOP - someone who is overly concerned with style, also conveniently can mean Formatting Object Processor. </note> <p> - <figure width="480" height="260" src="document.jpg" alt="Render Diagram" /> + <figure width="480" height="260" src="../images/document.jpg" alt="Render Diagram" /> </p> <p>The latest version of Fop is 0.20.4 and it supports the <jump href="http://www.w3.org/TR/2001/REC-xsl-20011015/">XSL-FO Version 1.0 @@ -51,7 +51,7 @@ can mean Formatting Object Processor. <section> <title>Formatting</title> <p> - <figure width="480" height="260" src="layout.jpg" alt="Formatting Diagram" /> + <figure width="480" height="260" src="../images/layout.jpg" alt="Formatting Diagram" /> </p> <p> This image is a demonstration of a two page document. The xml data on the left diff --git a/src/documentation/content/xdocs/dev/svg.xml b/src/documentation/content/xdocs/dev/svg.xml index 9205cc5bc..08f59e2f8 100644 --- a/src/documentation/content/xdocs/dev/svg.xml +++ b/src/documentation/content/xdocs/dev/svg.xml @@ -58,6 +58,7 @@ For more information see <link href="http://xml.apache.org/batik/">Batik</link> for how transcoders work. </p> </section> +<!-- <section> <title>Examples</title> <p> @@ -101,9 +102,15 @@ to PDF: <td><link href="svg/transparency.png">transparency.png</link></td> <td><link href="svg/transparency.pdf">transparency.pdf</link></td> </tr> - </table> -As can be seen most of the specific issues are handled. - + </table> + <p> + As can be seen most of the specific issues are handled. + </p> + <p> +<note> +You will need Acrobat 5.0 to see transparency. +</note> + </p> <table> <caption>XSL:FO to PDF examples</caption> <tr> @@ -119,6 +126,7 @@ As can be seen most of the specific issues are handled. </table> </p> </section> +--> <section> <title>Important Notes</title> <p> diff --git a/src/documentation/content/xdocs/download.xml b/src/documentation/content/xdocs/download.xml new file mode 100644 index 000000000..10d002bf5 --- /dev/null +++ b/src/documentation/content/xdocs/download.xml @@ -0,0 +1,32 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + +<document> + <header> + <title>Download</title> + </header> + + <body> +<section> + <title>Downloading FOP</title> + <p>You can download the latest release version from the <link + href="http://xml.apache.org/dist/fop/">distribution directory</link>. </p> + <p>The file contains also the documentation (including some example fo files) and the source. </p> + <p>If you want to work with the latest and nicest code, you can use the cvs version. See the section + on AnonCVS in the <link href="http://xml.apache.org/cvs.html">xml.apache.org documentation</link> for details. + Sometimes people have difficulties to access the cvs server; in this case you can download + a snapshot from the cvs files <link href="http://xml.apache.org/from-cvs/xml-fop/">here</link>. + In both cases you have to build Fop yourself - see <link href="compiling.html">Compiling Fop</link> for details. + </p> + <note> + Important: Currently, releases of FOP are coming out of the "fop-0_20_2-maintain" branch. The "MAIN" branch is + used for the redesign. See <link href="design/index.html">NEW DESIGN</link> for more information. + </note> + <p>To run FOP from the command line, see <link href="running.html">Running FOP</link>.</p> + <p>If you are interested in embedding FOP in a Java application of your own, see + <link href="embedding.html">Embedding FOP</link>. + </p> +</section> + </body> +</document> + diff --git a/src/documentation/content/xdocs/embedding.xml b/src/documentation/content/xdocs/embedding.xml new file mode 100644 index 000000000..47a94129a --- /dev/null +++ b/src/documentation/content/xdocs/embedding.xml @@ -0,0 +1,200 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + + +<!-- Embedding FOP --> +<document> + <header> + <title>Embedding FOP</title> + <subtitle>Notes about embedding FOP in your Java application</subtitle> + </header> + + <body> +<section> + <title>Embedding FOP</title> + <section> + <title>Overview</title> + <p>Instantiate org.apache.fop.apps.Driver. Once this class is + instantiated, methods are called to set the + Renderer to use + and the OutputStream to use to output the results of the + rendering (where applicable). In the case of the Renderer and + ElementMapping(s), the Driver may be supplied either with the + object itself, or the name of the class, in which case Driver will + instantiate the class itself. The advantage of the latter is it + enables runtime determination of Renderer and ElementMapping(s). + </p> + </section> + <section> + <title>Examples</title> + <p>The simplest way to use Driver is to instantiate it with the + InputSource and OutputStream, then set the renderer desired and + call the run method. + </p> + <p>Here is an example use of Driver which outputs PDF: + </p> + <source><![CDATA[ + Driver driver = new Driver(new InputSource (args[0]), + new FileOutputStream(args[1])); + driver.setRenderer(Driver.RENDER_PDF); + driver.run();]]></source> + + <p>You also need to set up logging. Global logging for all FOP + processes is managed by MessageHandler. Per-instance logging + is handled by Driver. You want to set both using an implementation + of org.apache.avalon.framework.logger.Logger. See + <link href="http://jakarta.apache.org/avalon/framework/">Jakarta + Avalon Framework</link> for more information. + </p> + <source><![CDATA[ + Logger logger = new ConsoleLogger(ConsoleLogger.LEVEL_INFO); + MessageHandler.setScreenLogger(logger); + driver.setLogger(logger);]]></source> + + <p>To setup the user config file you can do the following + </p> + <source><![CDATA[ + userConfigFile = new File(userConfig); + options = new Options(userConfigFile);]]></source> + <note> + This is all you need to do, it sets up a static configuration class. + </note> + + <p>Once the Driver is set up, the render method + is called. Depending on whether DOM or SAX is being used, the + invocation of the method is either render(Document) or + render(Parser, InputSource) respectively. + </p> + <p> + <strong>Another possibility may be used to build the FO Tree. You can + call getContentHandler() and fire the SAX events yourself. + </strong> + </p> + <p>Once the FO Tree is built, the format() and render() methods may be + called in that order. + </p> + <p>Here is an example use of Driver:</p> + <source><![CDATA[ + Driver driver = new Driver(); + driver.setRenderer(Driver.RENDER_PDF); + driver.setInputSource(new FileInputSource(args[0])); + driver.setOutputStream(new FileOutputStream(args[1])); + driver.run();]]></source> + <p>You can also specify an xml and xsl file for the input. + </p> + <p>Here is an example use of Driver with the XSLTInputHandler:</p> + <source><![CDATA[ + Driver driver = new Driver(); + driver.setRenderer(Driver.RENDER_PDF); + InputHandler inputHandler = new XSLTInputHandler(xmlFile, xslFile); + XMLReader parser = inputHandler.getParser(); + driver.setOutputStream(new FileOutputStream(outFile)); + driver.render(parser, inputHandler.getInputSource());]]></source> + <p>Have a look at the classes CommandLineStarter or FopServlet for complete examples.</p> + +<note>If your FO files contain SVG then batik will be used. When batik is +initialised it uses certain classes in <code>java.awt</code> that +intialises the java AWT classes. This means that a daemon thread +is created by the jvm and on unix it will need to connect to a +DISPLAY. +The thread means that the java application will not automatically quit +when finished, you will need to call <code>System.exit</code>. These +issues should be fixed in the upcoming JDK1.4</note> + + </section> + <section> + <title>Controlling logging</title> + <p>FOP uses Jakarta Avalon's + <link href="http://jakarta.apache.org/avalon/api/org/apache/avalon/framework/logger/Logger.html">Logger</link> + interface to do logging. See the <link href="http://jakarta.apache.org/avalon/">Jakarta Avalon project</link> for more information.</p> + <p>Per default FOP uses the ConsoleLogger which logs to System.out. If you want to do logging using a + logging framework (such as LogKit, Log4J or JDK 1.4 Logging) you can set a + different Logger implementation on the Driver object. Here's an example how you would use LogKit:</p> + <source><![CDATA[ + Hierarchy hierarchy = Hierarchy.getDefaultHierarchy(); + PatternFormatter formatter = new PatternFormatter( + "[%{priority}]: %{message}\n%{throwable}" ); + + LogTarget target = null; + target = new StreamTarget(System.out, formatter); + + hierarchy.setDefaultLogTarget(target); + log = hierarchy.getLoggerFor("fop"); + log.setPriority(Priority.INFO); + + driver.setLogger(new org.apache.avalon.framework.logger.LogKitLogger(log));]]></source> + <p>The LogKitLogger class implements the Logger interface so all logging calls are being redirected to LogKit. + More information on Jakarta LogKit can be found <link href="http://jakarta.apache.org/avalon/logkit/index.html">here</link>.</p> + <p>Similar implementations exist for Log4J (org.apache.avalon.framework.logger.Log4JLogger) and + JDK 1.4 logging (org.apache.avalon.framework.logger.Jdk14Logger).</p> + <p>If you want FOP to be totally silent you can also set an org.apache.avalon.framework.logger.NullLogger instance.</p> + <p>If you want to use yet another logging facility you simply have to create a class that implements org.apache.avalon.framework.logging.Logger + and set it on the Driver object. See the existing implementations in Avalon Framework for examples.</p> + + </section> + <section> + <title>Hints</title> + <section> + <title>XML/XSL/DOM Inputs</title> + <p> +You may want to supply you input to FOP from different data sources. +For example you may have a DOM and XSL stylesheet or you may want to +set variables in the stylesheet. The page here: +<link href="http://xml.apache.org/xalan-j/usagepatterns.html"> +http://xml.apache.org/xalan-j/usagepatterns.html</link> describes +how you can do these things. + </p> + <p> +You can use the content handler from the driver to create a SAXResult. +The transformer then can fire SAX events on the content handler which +will in turn create the rendered output. + </p> + </section> + <section> + <title>Object reuse</title> + <p> +If FOP is going to be used multiple times within your application +it may be useful to reuse certain objects to save time. + </p> + <p> +The renderers and the driver can both be reused. A renderer is reusable +once the previous render has been completed. The driver is reuseable +after the rendering is complete and the reset method is called. +You will need to setup the driver again with a new OutputStream, +IntputStream and renderer. + </p> + </section> + <section> + <title>Getting information on the rendering process</title> + <p> + To get the number of pages that were rendered by FOP you can call Driver.getResults(). This returns a + FormattingResults object where you can lookup the number of pages produced. It also gives you the + page-sequences that were produced along with their id attribute and their number of pages. This is particularly useful if you + render multiple documents (each enclosed by a page-sequence) and have to know the number of pages + of each document. + </p> + </section> + </section> + <section> + <title>Using Fop in a servlet</title> + <p> +In the directory xml-fop/docs/examples/embedding you can find a working +example how to use Fop in a servlet. You can drop the fop.war into the +webapps directory of Tomcat, then go to a URL like this: + </p> + <p>http://localhost:8080/fop/fop?fo=/home/path/to/fofile.fo</p> + <p>http://localhost:8080/fop/fop?xml=/home/path/to/xmlfile.xml&xsl=/home/path/to/xslfile.xsl</p> + <p>You can also find the source code there in the file FopServlet.java</p> + <p> + To compile this code you will need servlet_2_2.jar (or compatible), fop.jar and the sax api in your classpath. + </p> + <note> + Some browsers have problems handling the PDF result sent back to + the browser. IE is particularly bad and different versions behave + differently. Having a ".pdf" on the end of the url may help. + </note> + </section> +</section> + </body> +</document> + diff --git a/src/documentation/content/xdocs/examples.xml b/src/documentation/content/xdocs/examples.xml new file mode 100644 index 000000000..476c66bf4 --- /dev/null +++ b/src/documentation/content/xdocs/examples.xml @@ -0,0 +1,59 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + +<document> + <header> + <title>Examples</title> + </header> +<body> +<section> + <title>Examples</title> + <p>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 (only source distribution). The resulting test + files can be found in xml-fop/docs/examples/tests + </p> + <p>At the moment the following files are part of the distribution:</p> + <ul> + <li>simple.fo - a very simple file which gives use a first impression of the structure of an fo file + </li> + <li>normal.fo - a simple file showing the use of a 2 level of headings, normal text and a header. + </li> + <li>table.fo - some table examples + </li> + <li>list.fo - a short tutorial how to use list fo's and properties + </li> + <li>images.fo - shows how to embed gif and jpg images into the xsl:fo file using external-graphic. + </li> + <li>border.fo - a not so simple example how to use borders in tables + </li> + <li>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. + </li> + <li>leader.fo - shows different uses of fo:leader, p.e. as rule or in a table of content + </li> + <li>normalex.fo - shows the use of computed property values + </li> + <li>inhprop.fo - shows the use of inherited property values + </li> + <li>instream.fo - shows the use of fo:instream-foreign-object together with svg + </li> + <li>textdeko.fo - shows the use of the property textdecoration + </li> + <li>readme.fo - uses an old version of Fop documentation for a longer example + </li> + + <li>Look also into the directory examples/svg. There you find some very extensive svg examples. + Just start makedoc. + </li> + <li>In the directory examples/pagination you find a suite of examples showing the use + of xsl:fo pagination. + </li> + </ul> + <p>Developers will find the first steps to a test suite for all implemented formatting objects and + properties in xml-fop/test/xml/.</p> + +</section> +</body> +</document> + diff --git a/src/documentation/content/xdocs/extensions.xml b/src/documentation/content/xdocs/extensions.xml new file mode 100644 index 000000000..1c4a873df --- /dev/null +++ b/src/documentation/content/xdocs/extensions.xml @@ -0,0 +1,74 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + +<document> + <header> + <title>FOP</title> + </header> + <body> +<section> + <title>Extensions to FOP</title> + <p>Sometimes it is desirable to have extensions to xsl:fo in order to support some feature of the + output format which isn't covered by the xsl:fo specification. + </p> + <section> + <title>Default Extensions</title> +<p> +These extension are available by default. They are automatically loaded +and you only need to provide the correct namespace for your embedded +xml markup. +</p> + <section> + <title>SVG</title> +<p> +Please see the <link href="svg.html">SVG page</link> for more details. +</p> + </section> + <section> + <title>Bookmarks</title> + <p>To use this standard Fop extension, you need to add a namespace entry for + http://xml.apache.org/fop/extensions on the root element. </p> + + <p>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:</p> + <source> +<![CDATA[<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format" + xmlns:fox="http://xml.apache.org/fop/extensions"> + <fox:outline internal-destination="sec3"> + <fox:label>Running FOP</fox:label> + + <fox:outline internal-destination="sec3-1"> + <fox:label>Prerequisites</fox:label> + </fox:outline> + <fox:outline> +</fo:root>]]></source> + <p>It works similarly to a basic-link. There is also an external-destination + property, but it isn't supported currently. See the pdfoutline.fo file in + docs/examples/fo for a more complete example.</p> + </section> + </section> + <section> + <title>Adding Your Own</title> +<p> +To add your own extension you need to do the following things. +</p> +<p> +Write code that implements your extension functionality. +The easiest place to start is by looking at the code in org.apache.fop.extension. +</p> +<p> +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. +</p> +<p> +Create your fo file with the extra xml data embedded in the file with the correct name space. The examples for svg and pdfoutline.fo show how this can be done. +</p> +<p> +Put your jar file in the classpath and then run fop over the fo file. +</p> + + </section> +</section> +</body> +</document> + diff --git a/src/documentation/content/xdocs/fonts.xml b/src/documentation/content/xdocs/fonts.xml new file mode 100644 index 000000000..91e5d45c7 --- /dev/null +++ b/src/documentation/content/xdocs/fonts.xml @@ -0,0 +1,143 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + +<document> + <header> + <title>Fonts</title> + <authors> + <person name="Jeremias Maerki" email=""/> + <person name="Tore Engvig" email=""/> + </authors> + </header> +<body> +<section> + <title>Font Support</title> + <section> + <title>Status</title> + <p>FOP (building PDF files) normally supports only the base 14 font package defined in the Adobe PDF specification. + That includes the following fonts: Helvetica, Times, Courier, Symbol and ZapfDingbats. + </p> + <p>Font support in FOP can be extended by the addition of font metric files (written in XML) created from Adobe + Type 1 fonts and Truetype fonts. No other font types (Type 3, etc.) are supported at this time. + </p> + <note> + The Font is simply embedded into the PDF file, it is not converted. + </note> + </section> + <section> + <title>Adding additional Type 1 fonts</title> + <p>As mentioned above you need an XML file containing font metrics to be able to use an additional font. FOP + contains a tool that can generate such a font metrics file from a PFM file, which normally comes with the font file. + </p> + <section> + <title>Generating a font metrics file</title> + <p> Run the class org.apache.fop.fonts.apps.PFMReader to generate the XML file. + </p> + <p>Windows:</p> + <p> + <code>java -cp build\fop.jar;lib\xercesImpl-2.0.1.jar;lib\xml-apis.jar;lib\xalan-2.3.1.jar;lib\batik.jar + org.apache.fop.fonts.apps.PFMReader pfm-file xml-file</code> + </p> + <p>Unix:</p> + <p> + <code>java -cp build/fop.jar:lib/xercesImpl-2.0.1.jar:lib/xml-apis.jar:lib/xalan-2.3.1.jar:lib/batik.jar + org.apache.fop.fonts.apps.PFMReader pfm-file xml-file</code> + </p> + <note>The tool will construct some values (FontBBox, StemV and ItalicAngle) based on assumptions and + calculations which are only an approximation to the real values. FontBBox and Italic Angle can be found in + the human-readable part of the PFB file. The PFMReader tool does not yet interpret PFB files, so if you want + to be correct, you may have to adjust the values in the XML file manually. The constructed values however + appear to have no visible influence. + </note> + </section> + <section> + <title>Register the fonts within FOP</title> + <p> + Edit conf/userconfig.xml and add entries for the font + if the fonts section, + ie: + </p> + <p> + <code><![CDATA[ +<font metrics-file="cyberbit.xml" kerning="yes" embed-file="C:\WINNT\Fonts\Cyberbit.ttf"> + <font-triplet name="Cyberbit" style="normal" weight="normal"> +</font>]]> +</code> +</p> + <note> + If you do not want the font embedded in the PDF then remove the + "embed-file" attribute. The PDF will then contain text using + the font with the font metrics and to view it properly the + font will need to be installed where it is being viewed. + </note> + <note> + Cocoon users will need to setup the config, see FOPSerializer + for more information. + </note> + </section> + </section> + <section> + <title>Adding additional TrueType</title> + <p>Adding Truetype fonts is almost identical to the process of + adding type 1 fonts. The main difference is in the first + step.</p> + + <section> + <title>Generating a font metrics file</title> + <p>As mentioned above you need an XML file containing font + metrics to be able to use an additional font. FOP contains + a tool that can generate such a font metrics file from + your truetype font file. + </p> + <p> + Create metrics for the fontfile (we assume the file has + the name cmr10.ttf and exists in c:\myfonts\): + </p> + <p> + <code>java -cp build\fop.jar;lib\xercesImpl-2.0.1.jar;lib\xml-apis.jar;lib\xalan-2.3.1.jar;lib\batik.jar org.apache.fop.fonts.apps.TTFReader C:\myfonts\cmr10.ttf C:\myfonts\cmr10.ttf ttfcm.xml</code></p> + </section> + <section> + <title>TrueType collections</title> + <p> + TrueType collections (.ttc files) contains more than one + font. To create metrics for a ttc file you must specify + the font in the collection with the -ttcname option to + TTFReader. + </p> + <p> + To get a list of the fonts in a collection, just start the + TTFReader as if it were a normal truetype file (without + the -ttcname option). It will then display all the font + names and exit with an Exception... + </p> + <p> + Example on generating metrics for a .ttc file: + </p> + <p> + <code> + java -cp build\fop.jar;lib\xercesImpl-2.0.1.jar;lib\xml-apis.jar;lib\xalan-2.3.1.jar;lib\batik.jar org.apache.fop.fonts.apps.TTFReader -ttcname "MS Mincho" msmincho.ttc msminch.xml + </code> + </p> + </section> + + <section> + <title>Register the fonts within FOP</title> + <p> + Same as for Type 1 fonts. + </p> + </section> + + <section> + <title>Embedding fonts</title> + <p> + Font embedding is enabled in the userconfig.xml file. + </p> + </section> + </section> + <p> + Remember to start fop with -c conf/userconfig.xml + </p> +</section> +</body> +</document> + diff --git a/src/documentation/content/xdocs/gethelp.xml b/src/documentation/content/xdocs/gethelp.xml new file mode 100644 index 000000000..3634fec51 --- /dev/null +++ b/src/documentation/content/xdocs/gethelp.xml @@ -0,0 +1,49 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + + +<!-- How to get Help --> +<document> + <header> + <title>How to Get Help</title> + <subtitle>Solving problems</subtitle> + </header> + + <body> +<section> + <title>How to get Help</title> + <ol> + <li> + Have a look at the documentation pages on this site. You can find information on how to run FOP, + how to embed it, how to add custom fonts etc. + </li> + <li> + Consult the <link href="faq.html">FAQ</link> to see if your question has already been answered before. + </li> + <li> + If you have a question concerning XSL:FO that is not related to FOP directly, please consult the various + resources on the net. See <link href="resources.html">Resources</link> for some interesting links. + </li> + <li> + Before you post your questions to one of the mailing lists, please search the mailing list archives, since it's + possible that your question has already been answered but it may not have found its way into the FAQ. You'll + find links to the mailing list archive in the <link href="resources.html">Resources</link>. + </li> + <li> + If you still can't solve your problem subscribe to FOP's user mailing list and post your question there. Please + don't forget to supply the version you're using, detailed error messages etc. This makes it easier to help you. + The instructions on how to subscribe can be found in the <link href="resources.html">Resources</link> + </li> + <li> +You should probably read ESR's +<link href="http://www.tuxedo.org/~esr/faqs/smart-questions.html">"How to Ask Questions the Smart Way"</link> + </li> + </ol> + <note> + Please don't use Bugzilla to post questions and please ask on the user mailing list first, if you think you've + found a bug. + </note> +</section> + </body> +</document> + diff --git a/src/documentation/content/xdocs/implemented.xml b/src/documentation/content/xdocs/implemented.xml new file mode 100644 index 000000000..9262a322b --- /dev/null +++ b/src/documentation/content/xdocs/implemented.xml @@ -0,0 +1,255 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + +<document> +<header> +<title>Implemented</title> +</header> +<body> +<section> + <title>Features</title> + <section> + <title>What's Implemented?</title> + <p>The following formatting objects and properties of the XSL-FO 1.0 + W3C Recommandation are implemented. Please have also a look at the + section on <jump href="limitations.html">limitations</jump>. + </p> + </section> + <section> + <title>1) Formatting Objects</title> + <p>This section follows the table "B Formatting Object Summary" in the xsl:fo specification. At the + end of each sub-section you find listed what is not implemented.</p> + + <section> + <title>B.1 Declaration and Pagination and Layout Formatting Objects</title> + <ul> + <li>root</li> + <li>page-sequence</li> + <li>page-sequence-master</li> + <li>single-page-master-reference</li> + <li>repeatable-page-master-reference</li> + <li>repeatable-page-master-alternatives</li> + <li>conditional-page-master-reference</li> + <li>layout-master-set</li> + <li>simple-page-master</li> + <li>region-body</li> + <li>region-before</li> + <li>region-after</li> + <li>region-start</li> + <li>region-end</li> + <li>flow</li> + <li>static-content</li> + </ul> + <p>Not implemented: declarations, color-profile, title</p> + </section> + + <section> + <title>B.2 Block Formatting Objects</title> + <ul> + <li>block</li> + <li>block-container (limited)</li> + </ul> + </section> + + <section> + <title>B.3 Inline Formatting Objects</title> + <ul> + <li>character</li> + <li>external-graphic</li> + <li>inline</li> + <li>instream-foreign-object</li> + <li>leader</li> + <li>page-number </li> + <li>page-number-citation, see <jump href="limitations.html">limitations</jump></li> + </ul> + <p>Not implemented: bidi-override, initial-property-set, inline-container</p> + </section> + + <section> + <title>B.4 Table Formatting Objects</title> + <ul> + <li>table</li> + <li>table-body</li> + <li>table-cell</li> + <li>table-column</li> + <li>table-footer</li> + <li>table-header</li> + <li>table-row</li> + </ul> + <p>Not implemented: table-and-caption, table-caption </p> + </section> + + <section> + <title>B.5 List Formatting Objects</title> + <ul> + <li>list-block </li> + <li>list-item </li> + <li>list-item-body </li> + <li>list-item-label </li> + </ul> + </section> + + <section> + <title>B.6 Link and Multi Formatting Objects</title> + <ul> + <li>basic-link (internal and external)</li> + </ul> + <p>Not implemented: multi-switch, multi-case, multi-toggle, + multi-properties, multi-property-set</p> + </section> + + <section> + <title>B.7 Out-of-line Formatting Objects</title> + <ul> + <li>footnote</li> + <li>footnote-body</li> + </ul> + <p>Not implemented: float</p> + </section> + + <section> + <title>B.8 Other Formatting Objects</title> + <ul> + <li>wrapper</li> + <li>marker, retrieve marker</li> + </ul> + </section> + </section> + + <section> + <title>2) Properties</title> + <p>Property values can be computed. Compound properties are also understood by Fop.</p> + <ul> + <li>background-color </li> + <li>background-image </li> + <li>blank-or-not-blank</li> + <li>border-after-color</li> + <li>border-after-style</li> + <li>border-after-width</li> + <li>border-before-color</li> + <li>border-before-style</li> + <li>border-before-width</li> + <li>border-bottom</li> + <li>border-bottom-color</li> + <li>border-bottom-style</li> + <li>border-bottom-width</li> + <li>border-color (only one value allowed) </li> + <li>border-end-color</li> + <li>border-end-style</li> + <li>border-end-width</li> + <li>border-left</li> + <li>border-left-color</li> + <li>border-left-style</li> + <li>border-left-width</li> + <li>border-right</li> + <li>border-right-color</li> + <li>border-right-style</li> + <li>border-right-width</li> + <li>border-start-color</li> + <li>border-start-style</li> + <li>border-start-width</li> + <li>border-style</li> + <li>border-top</li> + <li>border-top-color</li> + <li>border-top-style</li> + <li>border-top-width</li> + <li>border-width</li> + <li>bottom</li> + <li>break-after </li> + <li>break-before </li> + <li>character</li> + <li>color </li> + <li>column-count</li> + <li>column-gap</li> + <li>column-width </li> + <li>country</li> + <li>end-indent </li> + <li>extent </li> + <li>external-destination</li> + <li>flow-name </li> + <li>font-family </li> + <li>font-size </li> + <li>font-style </li> + <li>font-weight </li> + <li>height</li> + <li>hyphenate</li> + <li>hyphenation-character</li> + <li>hyphenation-push-character-count</li> + <li>hyphenation-remain-character-count</li> + <li>id</li> + <li>initial-page-number</li> + <li>internal-destination</li> + <li>keep-with-next (broken)</li> + <li>language</li> + <li>leader-alignment (not value "page")</li> + <li>leader-length (see limitations)</li> + <li>leader-pattern (not value "use-content")</li> + <li>leader-pattern-width</li> + <li>left</li> + <li>letter-spacing</li> + <li>line-height </li> + <li>margin (only on pages and regions) </li> + <li>margin-bottom (only on pages and regions) </li> + <li>margin-left (only on pages and regions) </li> + <li>margin-right (only on pages and regions) </li> + <li>margin-top (only on pages and regions) </li> + <li>master-name </li> + <li>master-reference </li> + <li>maximum-repeats</li> + <li>number-columns-spanned</li> + <li>odd-or-even</li> + <li>padding (only one value allowed) </li> + <li>padding-after</li> + <li>padding-before</li> + <li>padding-bottom </li> + <li>padding-end</li> + <li>padding-left </li> + <li>padding-right </li> + <li>padding-start</li> + <li>padding-top </li> + <li>page-height </li> + <li>page-position</li> + <li>page-width </li> + <li>position (allowed values: "static" (default),"relative", "absolute", fixed ) </li> + <li>provisional-distance-between-starts </li> + <li>provisional-label-separation </li> + <li>ref-id </li> + <li>region-name</li> + <li>right</li> + <li>rule-style</li> + <li>rule-thickness </li> + <li>space-after.optimum </li> + <li>space-before.optimum </li> + <li>span</li> + <li>src </li> + <li>start-indent </li> + <li>table-omit-footer-at-break</li> + <li>table-omit-header-at-break</li> + <li>text-align </li> + <li>text-align-last </li> + <li>text-decoration</li> + <li>text-indent </li> + <li>top</li> + <li>white-space-collapse</li> + <li>width</li> + <li>wrap-option</li> + </ul> + <p>All other properties are not implemented.</p> + </section> + + <section> + <title>3)SVG Support</title> +<p> +FOP uses <jump href="http://xml.apache.org/batik/">Batik</jump> directly for its SVG support. Therefore FOP supports the same +elements and properties as are supported by Batik. As FOP is designed for +rendering to a static medium then only static SVG is rendered. +</p> +<p> +Due to some limitations in PDF some SVG images, particularly ones with effects +or transparency, may not come out correctly. The images should still be renderedcorrectly for the AWT and Print renderers. +</p> + </section> +</section> +</body> +</document> + diff --git a/src/documentation/content/xdocs/index.xml b/src/documentation/content/xdocs/index.xml index 4c10c9510..6e2a6f72d 100644 --- a/src/documentation/content/xdocs/index.xml +++ b/src/documentation/content/xdocs/index.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> - <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> <document> <header> <title>FOP</title> @@ -7,8 +7,74 @@ <body> <section> <title>Introduction</title> - <p> - </p> + <p>FOP (Formatting Objects Processor) 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. <link href="output.html">Output formats</link> + currently supported are PDF, PCL, PS, SVG, XML (area tree representation), + Print, AWT, MIF and TXT. + The primary output target is PDF. + </p> + <figure width="480" height="260" src="images/document.jpg" alt="Render Diagram" /> + <p>The latest version of Fop is 0.20.4 and it supports the + <link href="http://www.w3.org/TR/2001/REC-xsl-20011015/">XSL-FO Version 1.0 + W3C Recommendation</link>. + You can <link href="download.html">download</link> + 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 + <link href="resources.html">resources</link> 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 <link href="implemented.html">Features</link> and in section + <link href="limitations.html">Limitations</link> in what way this support is + limited. + </p> + <p>FOP is part of Apache's XML project. The homepage of FOP is + <link href="http://xml.apache.org/fop">http://xml.apache.org/fop</link>. + Here you can find information about using and developing with FOP. + </p> + <p>Users can subscribe to fop-user@xml.apache.org by sending an email + to <link href="mailto:fop-user-subscribe@xml.apache.org">fop-user-subscribe@xml.apache.org</link> + this is where user specific topics are discussed. + </p> </section> + + <section> + <title>Formatting</title> + <figure width="480" height="260" src="images/layout.jpg" alt="Formatting Diagram" /> +<p> +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. +</p> +<p> +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. +</p> +<p> +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. +</p> + </section> + <section> + <title>FOP Objectives</title> + <p>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. + </p> + + <p>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. + </p> + + <p>To reach this aim currently the layout system is being redesigned to +better handle the formatting of all different types of formatting objects. + </p> + </section> </body> </document> diff --git a/src/documentation/content/xdocs/involved.xml b/src/documentation/content/xdocs/involved.xml new file mode 100644 index 000000000..995313877 --- /dev/null +++ b/src/documentation/content/xdocs/involved.xml @@ -0,0 +1,89 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + +<document> + <header> + <title>Getting Involved</title> + <subtitle>How to Get Involved in FOP</subtitle> + </header> + + <body> +<section> + <title>Getting involved</title> + <p> +There are many different levels where people can get involved. The +development of FOP and the related plans and tasks are discussed on +the dev mailing list. Users can help or get issues resolved by +contributing information and examples to the developers. +</p> + + <section> + <title>Get familiar with the Fop related standards</title> + <p> +At the moment Fop is mainly a tool 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 links under +<link href="resources.html">Resources</link>. +</p> + </section> + <section> + <title>Fop's Design</title> + <p> +The design for FOP is specified under the +<link href="design/index.html">Design</link> section. + </p> + <p> +This is where the information on how FOP is developed and designed +internally will be kept. + </p> + </section> + + <section> + <title>Subscribe to the fop developers list</title> + <p>You can subscribe to fop-dev@xml.apache.org by sending an email + to <link href="mailto:fop-dev-subscribe@xml.apache.org">fop-dev-subscribe@xml.apache.org</link></p> + <p>Sending bug reports and feature requests to the list is a welcome and important contribution to + developing Fop. </p> + <p>Read also the <link href="http://marc.theaimsgroup.com/?l=fop-dev&r=1&w=2">archive</link> + of the discussion list fop-dev to get an idea of the issues being discussed. </p> + </section> + <section> + <title>Look at the developer's code using cvs</title> + <p>Between releases the newest code can be accessed via cvs. To do this you need to install a cvs + client on your computer, if it is not already there. An explanation how to connect to the + Fop source repository can be found at <link href="http://xml.apache.org/cvs.html">http://xml.apache.org/cvs.html</link>. + An introduction into cvs and the cvs manual can be found in the + <link href="http://xml.apache.org/library.html">reference library</link>.</p> + <p>All changes to the code repository are sent to a special mailing list. After a cvs commit the diffs are automatically sent to this list. You can subscribe + to fop-cvs@xml.apache.org by sending an email to <link href="mailto:fop-cvs-subscribe@xml.apache.org"> + fop-cvs-subscribe@xml.apache.org</link>. If you want to contribute to the development of Fop you should subscribe, + because it is important that you follow changes being made. </p> + </section> + <section> + <title>Contributing code, tests and documentation</title> + <p>If you want to contribute code (p.e. a bugfix), a test or documentation (p.e. an additional example), please do the following: </p> + <p>1) Make sure your code doesn't break the existing one and that Fop still compiles.</p> + <p>2) Create a file which shows the differences to the existing code.</p> + <p>3) Send this file as an <strong>Attachment</strong> to <link href="mailto:fop-dev@xml.apache.org">fop-dev@xml.apache.org.</link></p> + <p>One of the committers will test your code and commit it to the code repository.</p> + <p>If you have a test or useful bug test you should <link href="testing.html">read this page</link>.</p> + <p>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 <link href="http://xml.apache.org/roles.html">here</link>).</p> + </section> + + <section> + <title>Coding Conventions</title> + <p>As mentioned in <link href="http://xml.apache.org/source.html">Apache XML Project Guidelines</link>, + <strong>all Java Language source code in the repository must be written in conformance to the</strong> + <link href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">Code Conventions + for the Java Programming Language</link> as published by Sun. Additionally we agreed on 4 + spaces (no tabs) for indenting.</p> + <p>If you don't like those conventions, just use your own standards while developing and reformat the source before + committing with a tool like <link href="http://astyle.sourceforge.net/">astyle</link> (Artistic Style). + </p> + </section> + +</section> + </body> +</document> + diff --git a/src/documentation/content/xdocs/license.xml b/src/documentation/content/xdocs/license.xml new file mode 100644 index 000000000..a89f295ec --- /dev/null +++ b/src/documentation/content/xdocs/license.xml @@ -0,0 +1,63 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + +<document> +<header> + <title>FOP License</title> +</header> +<body> +<section> + <title>License</title> + <section> + <title>The Apache Software License, Version 1.1</title> + <p> Copyright (C) 1999-2001 The Apache Software Foundation. All rights reserved.</p> + <p> Redistribution and use in source and binary forms, with or without modification, + are permitted provided that the following conditions are met:</p> + <p>1. Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + </p> + + <p>2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + </p> + + <p>3. The end-user documentation included with the redistribution, if any, must + include the following acknowledgment: "This product includes software + developed by the Apache Software Foundation (http://www.apache.org/)." + Alternately, this acknowledgment may appear in the software itself, if + and wherever such third-party acknowledgments normally appear. + </p> + + <p>4. The names "FOP" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior + written permission. For written permission, please contact + apache@apache.org. + </p> + + <p>5. Products derived from this software may not be called "Apache", nor may + "Apache" appear in their name, without prior written permission of the + Apache Software Foundation. + </p> + <p>THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE + APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLU- + DING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS + OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON + ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF + THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + </p> + + <p> + This software consists of voluntary contributions made by many individuals + on behalf of the Apache Software Foundation and was originally created by + James Tauber <jtauber@jtauber.com>. For more information on the Apache + Software Foundation, please see <link href="http://www.apache.org/">http://www.apache.org/</link>. + </p> + </section> +</section> +</body> +</document> + diff --git a/src/documentation/content/xdocs/limitations.xml b/src/documentation/content/xdocs/limitations.xml new file mode 100644 index 000000000..c6bf9ee27 --- /dev/null +++ b/src/documentation/content/xdocs/limitations.xml @@ -0,0 +1,78 @@ +<?xml version="1.0"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + +<document> + <header> + <title>Limitations</title> + </header> + + <body> +<section> + <title>Limitations</title> + <p>FOP implements the fo objects and properties listed + in <jump href="implemented.html">features</jump>, sometimes it does so only in a limited way. + </p> + + <section> + <title>fo:leader</title> + <p>leader-length.minimum is not used at all</p> + </section> + + <section> + <title>page-number-citation</title> + <p>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. + </p> + </section> + + <section> + <title>Padding</title> + <p>Padding works in conjunction with indents and spaces. It is only implemented + for blocks. At the moment padding can't be used to make extra space (indents+spaces + must be used), but only to control how much the background-color extends beyond + the content rectangle. + </p> + </section> + <section> + <title>Tables</title> + <p>There two limitations for tables: 1) FOP needs you to explicitly specify column widths + 2) Cells have to contain block-level FOs. They can't contain straight character data. + </p> + <p>A working basic example of a table looks like this: </p> + <source><![CDATA[ +<fo:table> + <fo:table-column column-width="150pt"/> + <fo:table-column column-width="150pt"/> + <fo:table-body font-size="10pt" font-family="sans-serif"> + <fo:table-row> + <fo:table-cell> + <fo:block>text</fo:block> + </fo:table-cell> + <fo:table-cell> + <fo:block>text</fo:block> + </fo:table-cell> + </fo:table-row> + <fo:table-row> + <fo:table-cell> + <fo:block>text</fo:block> + </fo:table-cell> + <fo:table-cell> + <fo:block>text</fo:block> + </fo:table-cell> + </fo:table-row> + <fo:table-row> + <fo:table-cell> + <fo:block>text</fo:block> + </fo:table-cell> + <fo:table-cell> + <fo:block>text</fo:block> + </fo:table-cell> + </fo:table-row> + </fo:table-body> +</fo:table>]]></source> + </section> +</section> +</body> +</document> + diff --git a/src/documentation/content/xdocs/news.xml b/src/documentation/content/xdocs/news.xml new file mode 100644 index 000000000..81f152ce7 --- /dev/null +++ b/src/documentation/content/xdocs/news.xml @@ -0,0 +1,69 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + +<document> + <header> + <title>News</title> + </header> + <body> + <section> + <title>7 Jul 2002 FOP 0.20.4 released</title> + <p> + Changes since 0.20.3 include: + </p> + <ul> + <li>Support for background-image</li> + <li> + FOP should now work with any JAXP1.1 compliant + parser/transformer + </li> + <li> + The following JARs have been updated: Xerces to version + 2.0.1, Xalan to version 2.3.1 and Batik to version 1.5beta2. + </li> + <li>Fop has been compiled with Jimi support</li> + <li> + Logging has been changed from LogKit to Avalon's Logger + Interface + </li> + <li>New hyphenation patterns: turkish, portuguese and czech</li> + <li>FOP should now work on a EBCDIC machine</li> + <li> + Support for comma-separated values for the font-family + property + </li> + <li>Russian and Czech messages for AWTViewer</li> + </ul> + <p>For details see CHANGES file:<br/><link href= + "http://cvs.apache.org/viewcvs.cgi/xml-fop/CHANGES?rev=1.10.2.21" + >http://cvs.apache.org/viewcvs.cgi/xml-fop/CHANGES?rev=1.10.2.21</link> + </p> + <p> + See also the full text of the <link href= + "http://marc.theaimsgroup.com/?l=fop-dev&m=102607087326357&w=4" + >announcement</link>. + </p> + </section> + <section> + <title>13 Jun 2002 FOP 0.20.4 Release Candidate available</title> + <p> + See the full text of the <link href= + "http://marc.theaimsgroup.com/?l=fop-dev&m=102398470424177&w=4" + >announcement</link>. + </p> + </section> + <section> + <title>19 April 2002 - New Committers</title> + <p>Welcome Jeremias Maerki, Joerg Pietschmann and Peter B. West!</p> + </section> +<section> + <title>11 March 2002 - Fop 0.20.3 released</title> + <p>This is a maintenance release, the first version which supports the XSL-FO + Recommendation syntax. See the + <link href="http://marc.theaimsgroup.com/?l=xml-apache-announce&m=101588818821794"> + announcement</link> for more information.</p> + </section> + + </body> +</document> + diff --git a/src/documentation/content/xdocs/output.xml b/src/documentation/content/xdocs/output.xml new file mode 100644 index 000000000..6383dac07 --- /dev/null +++ b/src/documentation/content/xdocs/output.xml @@ -0,0 +1,238 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + +<!-- Output Formats: Renderers --> +<document> + <header> + <title>Output</title> + <subtitle>Notes about Output Formats: Renderers</subtitle> + <authors> + <person name="Keiron Liddle" email="keiron@aftexsw.com"/> + <person name="Art Welch" email=""/> + </authors> + </header> + + <body> +<section> + <title>Output Formats</title> + <p> +FOP supports a number of different output formats. This is achieved by +using different renderers that create the output. + </p> + <p> +Here we will explain some information for uses to be able to understand +what the renderers are doing and what difference there may be between +different renderers. + </p> +<section> + <title>Common Information</title> + <p> +Each renderer is given an area tree to render to its output format. +The area tree is simply a representation of the pages and the placement +of text and graphical objects on those pages. + </p> + <p> +The renderer will be given each page as it is ready and an output stream +to write the data out. The renderer is responsible for managing the +output format and associated data and flow. + </p> + <p> +Fonts and Layout - some formats (eg. PDF and AWT) rely on different +font information. The fonts for these outputs have different sizes +for the same point size. This means that the layout can be quite +different for the same fo document. + </p> + <p> +DPI - This is an important issue when creating output for printing. +The dpi is used to convert measurements into points. For example 1in += 2.54cm = 72 points. It is also used when determining the size of +images and the rendering of certain graphics in the output. Currently +FOP uses a value of 72dpi. + </p> + <p> +You may want to send your output directly to a printer. The Print +renderer uses the java api to print the document or you might be +able to send the output stream directly to a printer. If your printer +supports postscript you could send the postscript to the printer. If +you have a printer that supports PCL you could stream the PCL document +to your printer. +On Windows: + </p> +<source><![CDATA[fop ... -ps \\computername\printer or fop ... -pcl \\computername\printer]]></source> + <p> +On UNIX: + </p> +<source><![CDATA[proc = Runtime.getRuntime().exec("lp -d" + print_queue + " -o -dp -"); +out = proc.getOutputStream();]]></source> + <p> +And give the OutputStream (out) to the PCLRenderer and it happily sends the +PCL to the AIX print queue. + </p> +</section> +<section> + <title>PDF</title> + <p> +PDF is the best supported output format. It is also the most accurate +with text and layout. This creates a PDF document that is streamed out +as each page is rendered. This means that the internal page index +information is stored near the end of the document. +The PDF version supported is 1.3 which is currently the most popular +version for Acrobat Reader (4.0), PDF versions are forwards/backwards +compatible. + </p> +</section> +<section> + <title>PCL</title> + <p> +This format is for the Hewlett-Packard PCL printers. +It should produce output as close to identical as possible to the +printed output of the PDFRenderer within the limitations of the +renderer, and output device. + </p> + <p> +The output created by the PCLRenderer is generic PCL 5 as documented +in the "HP PCL 5 Printer Language Technical Reference Manual" (copyright 1990). +This should allow any device fully supporting PCL 5 to be able to +print the output generated by the PCLRenderer. + </p> + <section> + <title>Limitations</title> + <ul> + <li>Text or graphics outside the left or top of the printable area are not rendered properly. In general things that should print to the left of the printable area are shifted to the right so that they start at the left edge of the printable area and an error message is generated.</li> + <li>The Helvetica and Times fonts are not well supported among PCL printers so Helvetica is mapped to Arial and Times is mapped to Times New. This is done in the PCLRenderer, no changes are required in the FO's. The metrics and appearance for Helvetica/Arial and Times/Times New are nearly identical, so this has not been a problem so far.</li> + <li>Only the original fonts built into FOP are supported.</li> + <li>For the non-symbol fonts, the ISO 8859/1 symbol set is used (PCL set "0N").</li> + <li>Multibyte characters are not supported.</li> + <li>SVG support is limited. Currently only lines, rectangles (may be rounded), circles, ellipses, text, simple paths, and images are supported. Colors are supported (dithered black and white) but not gradients.</li> + <li>Images print black and white only (not dithered). When the renderer prints a color image it uses a threshold value, colors above the threshold are printed as white and below are black. If you need to print a non-monochrome image you should dither it first.</li> + <li>Image scaling is accomplished by modifying the effective resolution of the image data. The available resolutions are 75, 100, 150, 300, and 600 DPI.</li> + <li>Color printing is not supported. Colors are rendered by mapping the color intensity to one of the PCL fill shades (from white to black in 9 steps).</li> + <li>SVG clipping is not supported.</li> + </ul> + </section> + + <section> + <title>Additional Features</title> + <p>There are some special features that are controlled by some public variables on the PCLRenderer class.</p> + + <dl> + <dt>orientation</dt> + <dd>The logical page orientation is controlled by the public orientation variable. Legal values are: + <!--ul> + <li>0 Portrait</li> + <li>1 Landscape</li> + <li>2 Reverse Portrait</li> + <li>3 Reverse Landscape</li> + </ul--> + </dd> + <dt>curdiv, paperheight</dt> + <dd>The curdiv and paperheight variables allow multiple virtual pages to be printed on a piece of paper. This allows a standard laser printer to use perforated paper where every perforation will represent an individual page. The paperheight sets the height of a piece of paper in decipoints. This will be divided by the page.getHeight() to determine the number of equal sized divisions (pages) that will fit on the paper. The curdiv variable may be read/written to get/set the current division on the page (to set the starting division and read the ending division for multiple invocations).</dd> + <dt>topmargin, leftmargin</dt> + <dd>The topmargin and leftmargin may be used to increase the top and left margins for printing.</dd> + </dl> + </section> +</section> +<section> + <title>PostScript</title> + <p> +The PostScript renderer is still in its early stages and therefore still +missing some features. It provides good support for most text and layout. +Images and SVG are not fully supported, yet. Currently, the PostScript +renderer generates PostScript Level 3 with most DSC comments. Actually, +the only Level 3 feature used is FlateDecode, everthing else is Level 2. + </p> + <section> + <title>Limitations</title> + <ul> + <li>Images and SVG may not be display correctly. SVG support is far from being complete. No image transparency is available.</li> + <li>Character spacing may be wrong.</li> + <li>No font embedding is supported.</li> + <li>Multibyte characters are not supported.</li> + <li>PPD support is still missing.</li> + <li>The renderer is not yet configurable.</li> + </ul> + </section> +</section> +<section> + <title>RTF</title> + <p> +This is currently not integrated with FOP but it will soon. +This will create an rtf (rich text format) document that will +attempt to contain as much information from the fo document as +possible. + </p> +</section> +<section> + <title>SVG</title> + <p> +This format creates an SVG document that has links between the pages. +This is primarily for slides and creating svg images of pages. +Large documents will create SVG files that are far too large for +and SVG viewer to handle. Since fo documents usually have text the +SVG document will have a large number of text elements. +The font information for the text is obtained from the jvm in the +same way as the AWT viewer, if the svg is view where the fonts are +different, such as another platform, then the page will appear wrong. + </p> +</section> +<section> + <title>XML</title> + <p> +This is for testing and verification. The XML created is simply +a representation of the internal area tree put into XML. It does +not perform any other purpose. + </p> +</section> +<section> + <title>Print</title> + <p> +It is possible to directly print the document from the command line. +This is done with the same code that renders to the AWT renderer. + </p> +</section> +<section> + <title>AWT</title> + <p> +The AWT viewer shows a window with the pages displayed inside a +java graphic. It displays one page at a time. +The fonts used for the formatting and viewing depend on the fonts +available to your JRE. + </p> +</section> +<section> + <title>MIF</title> + <p> +This format is the Maker Interchange Format which is used by +Adobe Framemaker. This is currently not fully implemented. + </p> +</section> +<section> + <title>TXT</title> + <p> +Text as you could imagine does not work very well. It is an output format +that you should expect bad results. The main purpose of this is to get +a quick and dirty view of the document and the text inside it. + </p> + <p> +The TXTRenderer is a FOP renderer that produces plain ASCII text output +that attempts to match the output of the PDFRenderer as closely as +possible. This was originally developed to accommodate an archive system +that could only accept plain text files. Of course when limited to plain +fixed pitch text the output does not always look very good. + </p> + <p> +The TXTRenderer works with a fixed size page buffer. The size of this +buffer is controlled with the textCPI and textLPI public variables. +The textCPI is the effective horizontal characters per inch to use. +The textLPI is the vertical lines per inch to use. From these values +and the page width and height the size of the buffer is calculated. +The formatting objects to be rendered are then mapped to this grid. +Graphic elements (lines, borders, etc) are assigned a lower priority +than text, so text will overwrite any graphic element representations. + </p> +</section> + +</section> + </body> +</document> + diff --git a/src/documentation/content/xdocs/relnotes.xml b/src/documentation/content/xdocs/relnotes.xml new file mode 100644 index 000000000..2022de1e3 --- /dev/null +++ b/src/documentation/content/xdocs/relnotes.xml @@ -0,0 +1,85 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + +<document> + <header> + <title>Release Notes</title> + <subtitle>Fop 0.20.4</subtitle> + <authors> + <person name="Christian Geisert" email=""/> + </authors> + </header> + + <body> +<section> + <title>FOP 0.20.4</title> + <p>Important changes since 0.20.3:</p> + <ul> + <li>FOP should now work with any JAXP1.1 compliant parser/transformer. + It has been successfully tested with Xerces/Xalan, Saxon and JDK1.4 + (which includes Crimson and Xalan). + </li> + <li>The following JARs have been updated: + Xerces to version 2.0.1, Xalan to version 2.3.1 and Batik to version 1.5beta2. + </li> + <li>Fop has been compiled with Jimi support this time + but you still have to download + <link href="http://java.sun.com/products/jimi/">Jimi</link> + and copy it to lib/ to get PNG support (no need to build FOP yourself though). + </li> + <li>Building FOP with JDK1.2 does not work. Running is ok except + support for additional truetype fonts in AWT Viewer. + </li> + <li>Logging has been changed from LogKit to Avalon's Logger Interface. + (see <link href="embedding.html">Embedding</link> for details). + </li> + <li>Building under JDK 1.4: + You need to add a method in + <code>src/org/apache/fop/svg/PDFGraphics2D.java</code> + (search for jdk1.4 and remove the comments) + </li> + <li>To decrease the size of the distributions, ant, xml-docs, design-docs + and the hyphenation sources have been removed from the binary distribution. + Javadocs have been removed from the source distribution (use + <code>build javadocs</code> to generate them). + </li> + <li>Documentaion generation is broken in the maintenance branch at the moment + (Stylebook needs xerces1). The docs for this release are generated from the trunk. + </li> + <li> + For a more detailed list of changes, see the CHANGES file in the root of the FOP distribution. + </li> + </ul> + </section> + +<section> + <title>FOP 0.20.3</title> + <p>Important Information:</p> + <ul> + <li>This version supports the + <link href="http://www.w3.org/TR/2001/REC-xsl-20011015/">XSL-FO Version 1.0 + W3C Recommendation</link> syntax. So don't forget to update your + Stylesheets: + <br/>Just rename the <code>master-name</code> property to <code>master-reference</code> + on <code>fo:page-sequence</code>, <code>fo:single-page-master-reference</code>, + <code>fo:repeatable-page-master-reference</code> and + <code>fo:conditional-page-master-reference</code>.</li> + <li>JDK 1.2 (or later) is required</li> + <li>Jimi has been removed for licensing reasons + <br/>If you need PNG support you have to download + <link href="http://java.sun.com/products/jimi/">Jimi</link>, + copy it to lib/ and build FOP yourself</li> + <li>Building under JDK 1.4: + <br/>You need to add a method in + <code>src/org/apache/fop/svg/PDFGraphics2D.java</code> + (search for jdk1.4 and remove the comments) + </li> + <li> + For a more detailed list of changes, see the CHANGES file in the root of the FOP distribution. + </li> + </ul> + </section> + + </body> +</document> + diff --git a/src/documentation/content/xdocs/resources.xml b/src/documentation/content/xdocs/resources.xml new file mode 100644 index 000000000..64e98f065 --- /dev/null +++ b/src/documentation/content/xdocs/resources.xml @@ -0,0 +1,96 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + +<!-- FOP Relevant Specifications and links --> +<document> + <header> + <title>Resources</title> + <subtitle>Resources useful for developing and using FOP</subtitle> + </header> + + <body> + +<section> + <title>FOP Relevant Specifications and Links</title> + <section> + <title>Mailing Lists (and archives)</title> + <section> + <title>FOP User Mailing List</title> + <ul> + <li>Send a mail to <link href="mailto:fop-user-subscribe@xml.apache.org">fop-user-subscribe@xml.apache.org</link> + to subscribe (use <link href="mailto:fop-user-digest-subscribe@xml.apache.org"> + fop-user-digest-subscribe@xml.apache.org</link> for digest). + This is where user specific topics are discussed. For detailed instructions on the subscription, see + <link href="http://xml.apache.org/mail.html">Apache XML Mailing Lists</link>.</li> + <li>The Mailing list ARChives (MARC) at the AIMS group: + <link href="http://marc.theaimsgroup.com/?l=fop-user&r=1&w=2">fop-user</link> + (searchable)</li> + <li><link href="http://xml.apache.org/mail/fop-user/">Apache archive of fop-user@apache.org</link></li> + </ul> + </section> + <section> + <title>FOP Developer Mailing List</title> + <ul> + <li>Send a mail to <link href="mailto:fop-dev-subscribe@xml.apache.org">fop-dev-subscribe@xml.apache.org</link> + to subscribe. (use <link href="mailto:fop-dev-digest-subscribe@xml.apache.org"> + fop-dev-digest-subscribe@xml.apache.org</link> for digest). + For detailed instructions on the subscription, see + <link href="http://xml.apache.org/mail.html">Apache XML Mailing Lists</link>.</li> + <li>The Mailing list ARChives (MARC) at the AIMS group: + <link href="http://marc.theaimsgroup.com/?l=fop-dev&r=1&w=2">fop-dev</link> (searchable) + </li> + <li><link href="http://xml.apache.org/mail/fop-dev/">Apache archive of fop-dev@apache.org</link></li> + </ul> + </section> + <section> + <title>XSL:FO Mailing List (at W3C)</title> + <ul> + <li>There is an XSL:FO mailing list: www-xsl-fo@w3.org. Subscription info can be found here: <link href="http://www.w3.org/Mail/Request"> + http://www.w3.org/Mail/Request</link>.</li> + <li>The archive can be found here: + <link href="http://lists.w3.org/Archives/Public/www-xsl-fo/">http://lists.w3.org/Archives/Public/www-xsl-fo/</link></li> + </ul> + </section> + </section> + <section> + <title>Specifications</title> + <ul> + <li><link href="http://www.w3.org/TR/2001/REC-xsl-20011015/">XSL-FO Recommendation (15 October 2001)</link></li> + <li><link href="http://www.renderx.com/Tests/validator/fo.dtd.html">A dtd for the XSL-FO Recommendation provided by N. Grigoriev from RenderX</link></li> + <li><link href="http://www.w3.org/TR/SVG/">Supported SVG Recommendation (04 September 2001)</link></li> + <li><link href="http://www.w3.org/TR/REC-xml">XML Recommendation</link></li> + <li><link href="http://www.w3.org/TR/xslt">XSLT Recommendation</link></li> + <li><link href="http://partners.adobe.com/asn/developer/acrosdk/docs/filefmtspecs/PDFReference.pdf">Portable Document Format (PDF) 1.4 Reference Manual </link></li> + <li><link href="http://sax.sourceforge.net/">Simple API for XML (SAX)</link></li> + <li><link href="http://www.w3.org/TR/REC-DOM-Level-1">Document Object Model (DOM)</link></li> + <li><link href="http://www.w3.org/TR/REC-xml-names/">Namespaces in XML Recommendation</link></li> + <li><link href="http://java.sun.com/j2se/1.3/docs/api/index.html">Java JDK 1.3 Documentation</link></li> + </ul> + </section> + <section> + <title>Tutorials/Articles</title> + <ul> + <li><link href="http://www.ibiblio.org/xml/books/bible2/chapters/ch18.html">Elliotte Rusty Harold: Chapter 18 on xsl:fo from his excellent book XML Bible, Second Edition</link></li> + <li><link href="http://www.sun.com/software/xml/developers/slides-dtd/">Paul Sandoz: Using formatting objects with the slides dtd</link></li> + <li><link href="http://www.xml.com/pub/a/2001/01/17/xsl-fo/index.html">J. David Eisenberg: Using XSL Formatting Objects</link></li> + <li><link href="http://zvon.org/xxl/xslfoReference/Output/index.html">Miloslav Nic: XSL FO reference</link></li> + <li><link href="http://www.dpawson.co.uk/xsl/sect3/bk/index.html">Dave Pawson: An introduction to XSL Formatting Objects</link></li> + </ul> + </section> + <section> + <title>Related/Useful Products</title> + <ul> + <li> +PJ is an open source product that can be used to modify PDF documents: +<link href="http://www.etymon.com/pj/index.html">http://www.etymon.com/pj/index.html</link> + </li> + <li> +iText is a library that can edit PDF files, it is possible to do +post processing of the generated PDF files: <link href="http://www.lowagie.com/iText/">http://www.lowagie.com/iText/</link>. + </li> + </ul> + </section> +</section> + </body> +</document> + diff --git a/src/documentation/content/xdocs/running.xml b/src/documentation/content/xdocs/running.xml new file mode 100644 index 000000000..9539db620 --- /dev/null +++ b/src/documentation/content/xdocs/running.xml @@ -0,0 +1,76 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + +<document> + <header> + <title>Running FOP</title> + </header> + + <body> +<section> + <title>Running FOP</title> + <section> + <title>Prerequisites</title> + <p>Following software must be installed:</p> + <p>a) Java 1.2.x or later</p> + <p>b) All libraries you need are part of the Fop distribution and + can be found in the xml-fop/lib directory. Look at the batch/shell script fop.bat/fop.sh + to see, how Fop can be invoked easily. These libraries are included: + </p> + <ul> + <li>An XML parser which supports SAX and DOM like + <jump href="http://xml.apache.org/xerces-j/index.html">Xerces-J</jump>. + (Xerces is the default xml parser) + </li> + <li>An XSLT processor (Xalan is included) + </li> + <li>The SVG library batik.jar is the library from the <jump href="http://xml.apache.org/batik/">batik project</jump> at xml.apache.org. + </li> + </ul> + </section> + + <section> + <title>Starting FOP as an standalone application</title> + <p><code>Fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-pcl|-txt|-svg|-at|-print] <outfile></code></p> + <p>[OPTIONS]</p> + <source> + -d debug mode<br/> + -x dump configuration settings<br/> + -q quiet mode<br/> + -c cfg.xml use additional configuration file cfg.xml<br/> + -l lang the language to use for user information<br/></source> + <p>[INPUT]</p> + <source> + infile xsl:fo input file (the same as the next)<br/> + -fo infile xsl:fo input file<br/> + -xml infile xml input file, must be used together with -xsl<br/> + -xsl stylesheet xslt stylesheet<br/></source> + + <p>[OUTPUT]</p> + <source> + outfile input will be rendered as pdf file into outfile<br/> + -pdf outfile input will be rendered as pdf file (outfile req'd)<br/> + -awt input will be displayed on screen<br/> + -mif outfile input will be rendered as mif file (outfile req'd)<br/> + -pcl outfile input will be rendered as pcl file (outfile req'd)<br/> + -txt outfile input will be rendered as text file (outfile req'd)<br/> -svg outfile input will be rendered as an svg slides file (outfile req'd) + -at outfile representation of area tree as XML (outfile req'd) + -print input file will be rendered and sent to the printer<br/> see options with "-print help"<br/></source> + + <p>[Examples]</p> + <source> + Fop foo.fo foo.pdf<br/> + Fop -fo foo.fo -pdf foo.pdf (does the same as the previous line)<br/> + Fop -xsl foo.xsl -xml foo.xml -pdf foo.pdf<br/> + Fop foo.fo -mif foo.mif<br/> + Fop foo.fo -print or Fop -print foo.fo<br/> + Fop foo.fo -awt<br/></source> + </section> + + <section> + <title>Problems</title> + <p>If you have problems running FOP, please have a look at the <jump href="gethelp.html">"How to get Help" page</jump>.</p> + </section> +</section> +</body> +</document> diff --git a/src/documentation/content/xdocs/status.xml b/src/documentation/content/xdocs/status.xml new file mode 100644 index 000000000..76bf06f72 --- /dev/null +++ b/src/documentation/content/xdocs/status.xml @@ -0,0 +1,128 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + +<!-- Status --> + +<document> + <header> + <title>FOP Status</title> + <subtitle>Current Status of FOP</subtitle> + </header> + + <body> + <section> + <title>Status</title> +<p>[last updated 10th June 2002]</p> + <figure width="585" height="175" src="images/track.png" alt="Planning and branches of FOP development" /> +<p> +This is the development status of FOP. A branch has been created for +maintenance releases while the development is done to address various +performance and design issues. +</p> + </section> + + <section> + <title>Development Status</title> +<p> +Volunteers needed for:</p> +<ul> +<li>configuration implementation</li> +<li>implement formatting objects and properties</li> +<li>AWT/Swing viewer design and implementation</li> +<li>documentation</li> +<li>MIF output</li> +</ul> +<p> +... and plenty of other areas. See the <link href="todo.html">todo</link> +list for more details. +See this <link href="design/status.html">Status</link> for more information. +</p> +<p> +Development for 1.0DR1 is addressing the design issues for layout and +performance. The new design focusing on making it possible to be conformant +to the spec and be able to handle large documents. The development effort +is roughly 50% towards a developers release. +</p> +<p> +The developers release should have the following: similar functionality +to previous FOP releases, a rough API and a suitable design for +developers to work on more functionality. +</p> +<p> +The timing of these events depends on progress made so it is not possible +to predict any dates. +</p> +<p><strong>Binaries</strong></p> + <table> + <tr><td>fop.jar</td><td>1,966 kb</td></tr> + <tr><td>hyphention (in fop.jar)</td><td>717 kb</td></tr> + <tr><td>batik.jar</td><td>2,164 kb</td></tr> + <tr><td>bsf.jar</td><td>106 kb</td></tr> + <tr><td>xalan.jar</td><td>883 kb</td></tr> + <tr><td>xerces.jar</td><td>1,809 kb</td></tr> + </table> + +<p><strong>Lines of code</strong> using "find . -iname "*.java" | xargs cat | wc -l"</p> + <table> + <tr><td>org.apache.fop.*</td><td>67076</td></tr> + <tr><td>org.apache.fop.fo.*</td><td>15257 (23%)</td></tr> + <tr><td>org.apache.fop.layoutmgr.*</td><td>4537 (7%)</td></tr> + <tr><td>org.apache.fop.area.*</td><td>2314 (3.5%)</td></tr> + <tr><td>org.apache.fop.render.*</td><td>6474 (10%)</td></tr> + <tr><td>org.apache.fop.pdf.*</td><td>8113 (12%)</td></tr> + </table> + +<p><strong>Files</strong> using "find . -iname "*.java" | wc -l"</p> + <table> + <tr><td>org.apache.fop.*</td><td>462</td></tr> + <tr><td>org.apache.fop.fo.*</td><td>127 (27%)</td></tr> + <tr><td>org.apache.fop.layoutmgr.*</td><td>28 (6%)</td></tr> + <tr><td>org.apache.fop.area.*</td><td>36 (8%)</td></tr> + <tr><td>org.apache.fop.render.*</td><td>35 (8%)</td></tr> + </table> + + + </section> + + <section> + <title>Maintenance Status</title> +<p> +Latest maintenance release was FOP 0.20.3 on 4th March 2002. +See <link href="relnotes.html">release notes</link> for more +details. Releases will be made periodically to address minor bugs +and compatibility. +</p> + +<p><strong>Binaries</strong></p> + <table> + <tr><td>fop.jar</td><td>1,695 kb</td></tr> + <tr><td>hyphention (in fop.jar)</td><td>746 kb</td></tr> + <tr><td>batik.jar</td><td>2,164 kb</td></tr> + <tr><td>bsf.jar</td><td>106 kb</td></tr> + <tr><td>xalan.jar</td><td>906 kb</td></tr> + <tr><td>xercesImpl.jar</td><td>1,729 kb</td></tr> + <tr><td>xml-apis.jar</td><td>108 kb</td></tr> + </table> + +<p><strong>Lines of code</strong> using "find . -iname "*.java" | xargs cat | wc -l"</p> + <table> + <tr><td>org.apache.fop.*</td><td>69131</td></tr> + <tr><td>org.apache.fop.fo.*</td><td>14916 (22%)</td></tr> + <tr><td>org.apache.fop.layout.*</td><td>7108 (10%)</td></tr> + <tr><td>org.apache.fop.render.*</td><td>15840 (23%)</td></tr> + <tr><td>org.apache.fop.pdf.*</td><td>7883 (11%)</td></tr> + </table> + +<p><strong>Files</strong> using "find . -iname "*.java" | wc -l"</p> + <table> + <tr><td>org.apache.fop.*</td><td>391</td></tr> + <tr><td>org.apache.fop.fo.*</td><td>119 (30%)</td></tr> + <tr><td>org.apache.fop.layout.*</td><td>49 (13%)</td></tr> + <tr><td>org.apache.fop.render.*</td><td>48 (12%)</td></tr> + <tr><td>org.apache.fop.pdf.*</td><td>49 (13%)</td></tr> + </table> + + </section> + </body> +</document> + diff --git a/src/documentation/content/xdocs/svg.xml b/src/documentation/content/xdocs/svg.xml new file mode 100644 index 000000000..94580a310 --- /dev/null +++ b/src/documentation/content/xdocs/svg.xml @@ -0,0 +1,135 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + +<!-- SVG in FOP --> + +<document> + <header> + <title>SVG</title> + <subtitle>Embedding SVG in FOP</subtitle> + </header> + + <body> + +<section> + <title>SVG in FOP</title> + <section> + <title>Introduction</title> + <p> +FOP uses the SVG library from <link href="http://xml.apache.org/batik/">Batik</link> to handle SVG. +This format can be handled as an <code>fo:instream-foreign-object</code> or in a separate +file referenced with <code>fo:external-graphic</code>. 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. + </p> + <p> +The AWT and Print renderers simply use batik to draw the SVG into a graphic. + </p> + <p> +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. + </p> + </section> + + <section> + <title>Converting SVG to a PDF Document</title> + <p> +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.<br/> +<code>java org.apache.batik.apps.rasterizer.Main -m application/pdf document.svg</code> +<br/> +This will output the svg document as "document.pdf" containing a PDF rendering of +the SVG file. + </p> + <p> +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. + </p> + <p> +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. +</p> + <p> +The size of the pdf file will also remain the same regardless of what size the page is. + </p> + <p> +For more information see <link href="http://xml.apache.org/batik/">Batik</link> for +how transcoders work. + </p> + </section> + + <section> + <title>Important Notes</title> + <p> +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. + </p> + <p> +There are a number of SVG things that cannot be converted directly into +PDF. Parts of the graphic such as effects, patterns 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. +This needs to be improved. + </p> + <p> +Another important note is that text is converted and drawn as a +set of shapes by batik. 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. + </p> + <p> +It is possible to make sure that all text is drawn into PDF using the +PDF text commands by adding the following to the user config: + </p> +<source><![CDATA[<entry> + <key>strokeSVGText</key> + <value>false</value> +</entry>]]></source> + <p> +The drawback from this is that all text will be confined to text that is +possible for PDF fonts (including embedded fonts) and implemented with +this workaround. The fonts available are the standard pdf fonts and any +fonts that you have embedded using FOP. The font sizes will be rounded +to an integer value. In future this will be improved. + </p> + <p> +Currently transparency is not supported in PDF so many svg images that +contain effects or graphics with transparent areas will not be displayed +correctly. + </p> + </section> + + <section> + <title>Classes</title> + <p> +These are the relevant classes, found in the package org.apache.fop.svg : + </p> +<ul> +<li><em>PDFGraphics2D</em> +<br/> +used for drawing onto a Graphics2D into an existing pdf document, used +internally to draw the svg. +</li> +<li><em>PDFDocumentGraphics2D</em> +<br/> +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. +</li> +<li><em>PDFTranscoder</em> +<br/> +used by Batik to transcode an svg document into a standalone pdf, via +PDFDocumentGraphics2D. +</li> +</ul> + + </section> + +</section> + </body> +</document> + diff --git a/src/documentation/content/xdocs/testing.xml b/src/documentation/content/xdocs/testing.xml new file mode 100644 index 000000000..c43f9e7f2 --- /dev/null +++ b/src/documentation/content/xdocs/testing.xml @@ -0,0 +1,111 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"> + +<document> + <header> + <title>SVG</title> + <subtitle>Embedding SVG in FOP</subtitle> + </header> + + <body> +<section> + <title>Testing FOP</title> + <section> + <title>Running and Using Tests</title> + <p> +Testing is an important part of getting FOP to operate correctly and conform to the +necessary standards. + </p> + <p> +A testing system has been set up that works with as a build target when developing +with FOP. A developer can run the tests after making changes to the code, the aim +is to have the tests run to verfiy that nothing working has been broken. + </p> + <p> +To setup the testing the developer must place a reference fop.jar in the +"<cvs_repository>/test/reference/" directory. This jar will be dynamically +loaded to create the reference output. + </p> + </section> + + <section> + <title>W3C TestSuite</title> + <p> +The testing is set up so that you can download the testsuite from +<jump href="http://www.w3.org/Style/XSL/TestSuite/">http://www.w3.org/Style/XSL/TestSuite/</jump>, +unzip the file into the base directory of FOP. +Then you can uncomment the lines in the build.xml file in the test target and itwill run through all the tests in the testsuite distribution. + </p> + </section> + + <section> + <title>Writing a Test</title> + <p> +A test belongs to one of a few catagories. A basic test should excercise one +element in a number of situations such as changing a property. This should have +at least one normal value, one border value and one invalid value. If the property +can be of different types then this should also be included. + </p> + <p> +A bug test is a test that is specifically aimed at a problem with FOP. That is, the test +is not excercising the specification but rather a problem with FOP in handling a particular +situation that is not exposed with the other testing. + </p> + <p> +A system test is one that tests the abitlity of FOP to handle a number of different +elements together. + </p> + <p> +A test can consist of a complete fo document or a part of the document such as +some elements that will be placed into the flow of a standard document. + </p> + + </section> + <section> + <title>Submitting a Test</title> + <p> +If you have a test which you think would be useful you should supply the +test and a diff to the appropriate test suite xml file. Make sure that the +test works as would be expected against the current build. + </p> + </section> + + <section> + <title>How Testing Works</title> + <p> +The tests are stored in the "<cvs_repository>/test" directory. + </p> + <p> +You can run the tests by specifying the build target "test" ie: <br/> +<code>build.sh test</code> + </p> + <p> +This will then compare the current code in the local src directory to a specified +release of FOP. Any differences between the current code and the output from +the reference version will be reported. If the test previously passed then the +test run will have failed. + </p> + <p> +The testing is done by reading a test suite xml file, which corresponds to the +standard testsuite.dtd supplied from w3c. This xml file contains a test xml +file and an xsl file (which may simply copy the file). It also contains information +such as if the test has passed and any comments. + </p> + <p> +For FOP the testing is done by rendering all the testing documents using the +XML renderer. The XML files are then compared to see if there are any differences. + </p> + </section> + + <section> + <title>SVG Testing</title> + <p> +The testing of SVG is not part of this testing system. SVG is tested for its rendering +accuracy by using the transcoding mechanism via Batik. So that the only part that needs +testing is how the SVG image is embedded inside the flow of the fo document. + </p> + </section> +</section> +</body> +</document> + diff --git a/src/documentation/resources/images/document.jpg b/src/documentation/resources/images/document.jpg Binary files differnew file mode 100644 index 000000000..e441833d8 --- /dev/null +++ b/src/documentation/resources/images/document.jpg diff --git a/src/documentation/resources/images/layout.jpg b/src/documentation/resources/images/layout.jpg Binary files differnew file mode 100644 index 000000000..3c519baa2 --- /dev/null +++ b/src/documentation/resources/images/layout.jpg diff --git a/src/documentation/resources/images/track.png b/src/documentation/resources/images/track.png Binary files differnew file mode 100644 index 000000000..1d413334c --- /dev/null +++ b/src/documentation/resources/images/track.png diff --git a/src/documentation/sitemap.xmap b/src/documentation/sitemap.xmap index 06da4d18d..a96ad16bf 100644 --- a/src/documentation/sitemap.xmap +++ b/src/documentation/sitemap.xmap @@ -122,8 +122,8 @@ <map:resource name="skinit"> <map:transform src="skins/{defaults:skin}/xslt/html/{type}.xsl"> <map:parameter name="isfaq" value="{isfaq}"/> - <map:parameter name="dir" value="{dir}"/> - <map:parameter name="resource" value="{resource}"/> + <map:parameter name="nopdf" value="{nopdf}"/> + <map:parameter name="path" value="{path}"/> <!-- Can set an alternative project skinconfig here <map:parameter name="config-file" value="../../../../skinconf.xml"/> --> @@ -135,7 +135,7 @@ <map:generate src="content/xdocs/{../1}book.xml"/> <map:call resource="skinit"> <map:parameter name="type" value="book2menu"/> - <map:parameter name="resource" value="{resource}.html"/> + <map:parameter name="path" value="{path}"/> </map:call> </map:resource> @@ -192,20 +192,19 @@ <map:generate src="content/xdocs/tabs.xml"/> <map:call resource="skinit"> <map:parameter name="type" value="tab2menu"/> - <map:parameter name="resource" value="{1}"/> - <map:parameter name="dir" value="{1}/"/> + <map:parameter name="path" value="{2}.html"/> </map:call> </map:match> <map:match pattern="**book-**/*.xml"> <map:call resource="book"> - <map:parameter name="resource" value="{3}"/> + <map:parameter name="path" value="{2}/{3}"/> </map:call> </map:match> <map:match pattern="**book-**.xml"> <map:call resource="book"> - <map:parameter name="resource" value="{2}"/> + <map:parameter name="path" value="{2}"/> </map:call> </map:match> @@ -214,8 +213,7 @@ <map:transform src="library/xslt/todo2document.xsl" label="content"/> <map:call resource="skinit"> <map:parameter name="type" value="document2html"/> - <map:parameter name="resource" value="todo"/> - <map:parameter name="dir" value=""/> + <map:parameter name="path" value="/todo.xml"/> </map:call> </map:match> @@ -224,8 +222,7 @@ <map:transform src="library/xslt/changes2document.xsl" label="content"/> <map:call resource="skinit"> <map:parameter name="type" value="document2html"/> - <map:parameter name="resource" value="changes"/> - <map:parameter name="dir" value=""/> + <map:parameter name="path" value="/changes"/> </map:call> </map:match> @@ -234,8 +231,7 @@ <map:transform src="library/xslt/faq2document.xsl" label="content"/> <map:call resource="skinit"> <map:parameter name="type" value="document2html"/> - <map:parameter name="resource" value="faq"/> - <map:parameter name="dir" value=""/> + <map:parameter name="path" value="{1}/faq"/> <map:parameter name="isfaq" value="true"/> </map:call> @@ -246,8 +242,7 @@ <map:transform src="library/xslt/faq2document.xsl" label="content"/> <map:call resource="skinit"> <map:parameter name="type" value="document2html"/> - <map:parameter name="resource" value="faq"/> - <map:parameter name="dir" value=""/> + <map:parameter name="path" value="faq"/> <map:parameter name="isfaq" value="true"/> </map:call> @@ -264,8 +259,7 @@ <map:generate src="content/xdocs/community/{1}/index.xml"/> <map:call resource="skinit"> <map:parameter name="type" value="document2html"/> - <map:parameter name="resource" value="{1}"/> - <map:parameter name="dir" value="community/{1}/"/> + <map:parameter name="path" value="community/{1}/index"/> </map:call> </map:match> @@ -274,8 +268,7 @@ <map:generate src="content/xdocs/community{1}revision-{2}.xml"/> <map:call resource="skinit"> <map:parameter name="type" value="document2html"/> - <map:parameter name="resource" value="{1}"/> - <map:parameter name="dir" value="community/{1}/"/> + <map:parameter name="path" value="community/{1}/revision-{2}"/> </map:call> </map:match> @@ -288,8 +281,7 @@ <map:transform src="library/xslt/{1}2document.xsl" label="content"/> <map:call resource="skinit"> <map:parameter name="type" value="document2html"/> - <map:parameter name="resource" value="{3}"/> - <map:parameter name="dir" value="community/{1}/{2}/"/> + <map:parameter name="path" value="community/{1}/{2}/{3}"/> </map:call> </map:match> @@ -311,8 +303,7 @@ <map:transform src="library/xslt/howto2document.xsl" label="content"/> <map:call resource="skinit"> <map:parameter name="type" value="document2html"/> - <map:parameter name="resource" value="{3}"/> - <map:parameter name="dir" value="{1}howto/"/> + <map:parameter name="path" value="{1}howto/{2}"/> </map:call> </map:match> @@ -328,7 +319,8 @@ <map:parameter name="uri" value="{1}"/> </map:transform> <map:serialize type="xml"/> - </map:match> + </map:match> + <map:match pattern="body-doclist.xml"> <map:aggregate element="doclist"> <map:part src="cocoon:/doclist/content/xdocs/book.xml"/> @@ -337,7 +329,8 @@ <map:transform src="library/xslt/doclist2document.xsl"/> <map:call resource="skinit"> <map:parameter name="type" value="document2html"/> - <map:parameter name="dir" value="community/{1}/{2}/"/> + <map:parameter name="path" value="doclist"/> + <map:parameter name="nopdf" value="true"/> </map:call> </map:match> @@ -352,8 +345,7 @@ <map:call resource="skinit"> <map:parameter name="type" value="document2html"/> <map:parameter name="isfaq" value="true"/> - <map:parameter name="resource" value="{1}.dtdx"/> - <map:parameter name="dir" value="{1}"/> + <map:parameter name="path" value="{1}.dtdx.html"/> </map:call> </map:match> @@ -362,8 +354,7 @@ <map:generate src="content/xdocs/{1}/{2}.xml"/> <map:call resource="skinit"> <map:parameter name="type" value="document2html"/> - <map:parameter name="dir" value="{1}/"/> - <map:parameter name="resource" value="{2}"/> + <map:parameter name="path" value="{1}/{2}"/> </map:call> </map:match> @@ -372,8 +363,7 @@ <map:generate src="content/xdocs/{1}.xml"/> <map:call resource="skinit"> <map:parameter name="type" value="document2html"/> - <map:parameter name="dir" value="/"/> - <map:parameter name="resource" value="{1}"/> + <map:parameter name="path" value="{1}"/> </map:call> </map:match> @@ -385,8 +375,7 @@ </map:aggregate> <map:call resource="skinit"> <map:parameter name="type" value="site2xhtml"/> - <map:parameter name="dir" value=""/> - <map:parameter name="resource" value="{0}"/> + <map:parameter name="path" value="{1}"/> </map:call> </map:match> @@ -398,8 +387,7 @@ </map:aggregate> <map:call resource="skinit"> <map:parameter name="type" value="site2xhtml"/> - <map:parameter name="dir" value="{1}/"/> - <map:parameter name="resource" value="{0}"/> + <map:parameter name="path" value="{1}/{2}"/> </map:call> </map:match> |
