Browse Source

Added documentation for the new embedding examples.

Adjusted documentation for new directory structure.
Improved documentation a bit.


git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@195858 13f79535-47bb-0310-9956-ffa450edef68
tags/Alt-Design-integration-base
Jeremias Maerki 21 years ago
parent
commit
4a3e8582e7

+ 45
- 37
src/documentation/content/xdocs/configuration.xml View File

@@ -3,56 +3,64 @@
"http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">

<document>
<header>
<title>Configuration</title>
</header>
<header>
<title>Configuration</title>
</header>

<body>
<section>
<title>Configuration</title>
<body>
<section>
<title>How to configure Fop</title>
<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
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 ;-)
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.
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
<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 &lt;hyphenation-dir>.
</p>
<ol>
<li>
Get the TeX hyphenation pattern file and turn it into an xml file which
conforms to the hyphenation.dtd in the subdirectory /src/hyph.
</li>
<li>
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.
</li>
<li>
If you have build your new hyphenation pattern file successfully there are
two ways to make it accessible to FOP.
<ul>
<li>
Put this new file into the directory /src/hyph and rebuild FOP. The file will
be picked up and added to the fop.jar.
</li>
<li>
Put the file into a directory of your choice and specify this directory
in the userconfig.xml in the entry &lt;hyphenation-dir>.
</li>
</ul>
</li>
</ol>
</section>
</section>
</body>
</body>
</document>


+ 158
- 37
src/documentation/content/xdocs/embedding.xml View File

@@ -27,7 +27,7 @@
</p>
</section>
<section>
<title>Examples</title>
<title>Basics</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.
@@ -35,26 +35,42 @@
<p>Here is an example use of Driver which outputs PDF:
</p>
<source><![CDATA[
Driver driver = new Driver(new InputSource (args[0]),
import org.apache.fop.apps.Driver;
/*..*/
Driver driver = new Driver(new InputSource(args[0]),
new FileOutputStream(args[1]));
driver.setRenderer(Driver.RENDER_PDF);
driver.run();]]></source>
<p>
In the example above, args[0] contains the path to an XSL-FO file, while
args[1] contains a path for the target PDF file.
</p>

<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.
of org.apache.avalon.framework.logger.Logger. See
<jump href="#logging">below</jump> for more information.
</p>
<source><![CDATA[
Logger logger = new ConsoleLogger(ConsoleLogger.LEVEL_INFO);
MessageHandler.setScreenLogger(logger);
driver.setLogger(logger);]]></source>
import org.apache.avalon.framework.logger.Logger;
import org.apache.avalon.framework.logger.ConsoleLogger;
/*..*/
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[
import org.apache.fop.apps.Options;
/*..*/
userConfigFile = new File(userConfig);
options = new Options(userConfigFile);]]></source>
<note>
@@ -63,12 +79,12 @@

<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.
invocation of the method is either <code>render(Document)</code> or
<code>render(Parser, InputSource)</code> respectively.
</p>
<p>
<strong>Another possibility may be used to build the FO Tree. You can
call getContentHandler() and fire the SAX events yourself.
call <code>getContentHandler()</code> and fire the SAX events yourself.
</strong>
</p>
<p>Once the FO Tree is built, the format() and render() methods may be
@@ -91,23 +107,25 @@
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>
<p>Have a look at the classes CommandLineStarter or FopServlet for complete
examples. Also, have a look at the examples at the bottom of this page.
</p>

<note>If your FO files contain SVG then batik will be used. When batik is
<note>If your XSL-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
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>
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 JDK 1.4</note>

</section>
<section>
<section id="logging">
<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>
<fork href="http://jakarta.apache.org/avalon/api/org/apache/avalon/framework/logger/Logger.html">Logger</fork>
interface to do logging. See the <fork href="http://jakarta.apache.org/avalon/">Jakarta Avalon project</fork> 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>
@@ -125,7 +143,7 @@ issues should be fixed in the upcoming JDK1.4</note>

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>
More information on Jakarta LogKit can be found <fork href="http://jakarta.apache.org/avalon/logkit/index.html">here</fork>.</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>
@@ -141,8 +159,8 @@ issues should be fixed in the upcoming JDK1.4</note>
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
<fork href="http://xml.apache.org/xalan-j/usagepatterns.html">
http://xml.apache.org/xalan-j/usagepatterns.html</fork> describes
how you can do these things.
</p>
<p>
@@ -150,6 +168,9 @@ 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>
<p>
Examples showing this can be found at the bott
</p>
</section>
<section>
<title>Object reuse</title>
@@ -168,33 +189,133 @@ IntputStream and renderer.
<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.
To get the number of pages that were rendered by FOP you can call
<code>Driver.getResults()</code>. 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>
<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:
In the directory xml-fop/examples/servlet you can find a working example how
to use FOP in a servlet. After building the 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&amp;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>
<p>The source code for the servlet can be found under xml-fop/examples/servlet/src/FopServlet.java.</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.
differently. Having a ".pdf" on the end of the URL may help.
</note>
</section>
</section>
<section>
<title>Examples</title>
<p>
The directory "xml-fop/examples/embedding" contains several working examples.
In contrast of the examples above the examples here primarily use JAXP for
XML access. This may be easier to understand for people familiar with JAXP.
</p>
<section>
<title>ExampleFO2PDF.java</title>
<p>
This example demonstrates the basic usage pattern to transform an XSL-FO
file to PDF using FOP.
</p>
<figure src="images/EmbeddingExampleFO2PDF.png" alt="Example XSL-FO to PDF"/>
</section>
<section>
<title>ExampleXML2FO.java</title>
<p>
This example has nothing to do with FOP. It is there to show you how an XML
file can be converted to XSL-FO using XSLT. The JAXP API is used to do the
transformation. Make sure you've got a JAXP-compliant XSLT processor in your
classpath (ex. <fork href="http://xml.apache.org/xalan-j">Xalan</fork>).
</p>
<figure src="images/EmbeddingExampleXML2FO.png" alt="Example XML to XSL-FO"/>
</section>
<section>
<title>ExampleXML2PDF.java</title>
<p>
This example demonstrates how you can convert an arbitrary XML file to PDF
using XSLT and XSL-FO/FOP. It is a combination of the first two examples
above. The example uses JAXP to transform the XML file to XSL-FO and FOP to
transform the XSL-FO to PDF.
</p>
<figure src="images/EmbeddingExampleXML2PDF.png" alt="Example XML to PDF (via XSL-FO)"/>
<p>
The output (XSL-FO) from the XSL transformation is piped through to FOP using
SAX events. This is the most efficient way to do this because the
intermediate result doesn't have to be saved somewhere. Often, novice users
save the intermediate result in a file, a byte array or a DOM tree. We
strongly discourage you to do this if it isn't absolutely necessary. The
performance is significantly higher with SAX.
</p>
</section>
<section>
<title>ExampleObj2XML.java</title>
<p>
This example is a preparatory example for the next one. It's an example that
shows how an arbitrary Java object can be converted to XML. It's an often
needed task to do this. Often people create a DOM tree from a Java object and
use that. This is pretty straightforward. The example here however shows how
to do this using SAX which will probably be faster and not even more
complicated once you know how this works.
</p>
<figure src="images/EmbeddingExampleObj2XML.png" alt="Example Java object to XML"/>
<p>
For this example we've created two classes: ProjectTeam and ProjectMember
(found in xml-fop/examples/embedding/java/embedding/model). They represent
the same data structure found in
xml-fop/examples/embedding/xml/xml/projectteam.xml. We want to serialize a
project team with several members which exist as Java objects to XML.
Therefore we created the two classes: ProjectTeamInputSource and
ProjectTeamXMLReader (in the same place as ProjectTeam above).
</p>
<p>
The XMLReader implementation (regard it as a special kind of XML parser)is
responsible for creating SAX events from the Java object. The InputSource
class is only used to hold the ProjectTeam object to be used.
</p>
<p>
Have a look at the source of ExampleObj2XML.java to find out how this is
used. For more detailed information see other resources on JAXP (ex.
<fork href="http://java.sun.com/xml/jaxp/dist/1.1/docs/tutorial/xslt/3_generate.html">An older JAXP tutorial</fork>).
</p>
</section>
<section>
<title>ExampleObj2PDF.java</title>
<p>
The last example here combines the previous and the third to demonstrate
how you can transform a Java object to a PDF directly in one smooth run
by generating SAX events from the Java object that get fed to an XSL
transformation. The result of the transformation is then converted to PDF
using FOP as before.
</p>
<figure src="images/EmbeddingExampleObj2PDF.png" alt="Example Java object to PDF (via XML and XSL-FO)"/>
</section>
<section>
<title>Final notes</title>
<p>
These examples should give you an idea of what's possible. It should be easy
to adjust these examples to your needs. For examples, you can use a DOMSource
instead of a StreamSource to feed a DOM tree as input for an XSL
transformation.
</p>
<p>
If you think you have a decent example that should be here, contact us via
one of the mailing lists and we'll see to it that it gets added. Also, if
you can't find the solution to your particular problem drop us a message on
the fop-user mailing list.
</p>
</section>
</section>
</body>
</document>

+ 35
- 35
src/documentation/content/xdocs/examples.xml View File

@@ -6,31 +6,31 @@
<header>
<title>Examples</title>
</header>
<body>
<section>
<title>Examples</title>
<table>
<caption>Generated examples</caption>
<tr>
<th>description</th>
<th>fo file</th>
<th>pdf result</th>
</tr>
<tr>
<td>default font characters</td>
<td><link href="fo/fonts.fo">fonts.fo</link></td>
<td><link href="fo/fonts.fo.pdf">fonts.fo.pdf</link></td>
</tr>
</table>
<body>
<table>
<caption>Generated examples</caption>
<tr>
<th>Description</th>
<th>XSL-FO file</th>
<th>PDF result</th>
</tr>
<tr>
<td>default font characters</td>
<td><link href="fo/fonts.fo">fonts.fo</link></td>
<td><link href="fo/fonts.fo.pdf">fonts.fo.pdf</link></td>
</tr>
</table>

<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
<section>
<title>Examples in the distribution</title>
<p>Examples for the use of XSL-FO can be found in the FOP distribution in
the subdirectory xml-fop/examples/fo. You can start transformation of all fo files into pdf
files by starting xml-fop/examples/fo/runtests (only source distribution). The resulting test
files can be found in xml-fop/examples/fo/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>simple.fo - a very simple file which gives use a first impression of the structure of an XSL-FO file
</li>
<li>normal.fo - a simple file showing the use of a 2 level of headings, normal text and a header.
</li>
@@ -38,12 +38,12 @@
</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>images.fo - shows how to embed GIF and JPEG 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.
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>
@@ -51,24 +51,24 @@
</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>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>textdeko.fo - shows the use of the property text-decoration
</li>
<li>readme.fo - uses an old version of Fop documentation for a longer example
<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>Look also into the directory examples/fo/svg. There you find some very extensive SVG examples.
</li>
<li>In the directory examples/pagination you find a suite of examples showing the use
of xsl:fo pagination.
<li>In the directory examples/fo/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>
<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>


+ 61
- 51
src/documentation/content/xdocs/extensions.xml View File

@@ -4,36 +4,39 @@

<document>
<header>
<title>FOP</title>
<title>Extensions</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>
<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>
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>
</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">
@@ -44,32 +47,39 @@ Please see the <link href="svg.html">SVG page</link> for more details.
</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>
<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
examples/fo/basic 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>
</p>
<ol>
<li>
Write code that implements your extension functionality. The easiest place to
start is by looking at the code in org.apache.fop.extension.
</li>
<li>
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.
</li>
<li>
Create your XSL-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.
</li>
<li>
Put your jar file in the classpath and then run fop over the XSL-FO file.
</li>
</ol>
</section>
</body>
</document>


Loading…
Cancel
Save