Special Settings for the PDF Renderer

- To embed Apache FOP in your application, instantiate org.apache.fop.apps.Fop. - You'll tell FOP in the constructor which output format (i.e. Renderer) to use. - Afterwards, you'll set the OutputStream to use to output the results of the - rendering (where applicable). You can customize FOP's behaviour by supplying - your own FOUserAgent instance. The FOUserAgent can, for example, be used to - set your own Renderer instance (details below). Finally, you retrieve a SAX - DefaultHandler instance from the Fop instance to which you can send your - FO file. + To embed Apache FOP in your application, first create a new + org.apache.fop.apps.FopFactory instance. This object can be used to launch multiple + rendering runs. For each run, create a new org.apache.fop.apps.Fop instance through + one of the factory methods of FopFactory. In the method call you specify which output + format (i.e. Renderer) to use and, if the selected renderer requires an OutputStream, + which OutputStream to use for the results of the rendering. You can customize FOP's + behaviour in a rendering run by supplying your own FOUserAgent instance. The + FOUserAgent can, for example, be used to set your own Renderer instance (details + below). Finally, you retrieve a SAX DefaultHandler instance from the Fop object and + use that as the SAXResult of your transformation.

Input Sources

- The input XSL-FO document is always handled internally as SAX (see the + The input XSL-FO document is always received by FOP as a SAX stream (see the Parsing Design Document for the rationale).

@@ -229,19 +244,19 @@ try { File: Source src = new StreamSource(new File("C:/Temp/myinputfile.xml"));

- String: Source src = new StreamSource(new StringReader(myString)); //myString is a String + String: Source src = new StreamSource(new StringReader(myString)); // myString is a String

InputStream: Source src = new StreamSource(new MyInputStream(something));

- Byte Array: Source src = new StreamSource(new ByteArrayInputStream(myBuffer)); //myBuffer is a byte[] here + Byte Array: Source src = new StreamSource(new ByteArrayInputStream(myBuffer)); // myBuffer is a byte[] here

- DOM: Source src = new DOMSource(myDocument); //myDocument is a Document or a Node + DOM: Source src = new DOMSource(myDocument); // myDocument is a Document or a Node

- Java Objects: Please have a look at the Embedding examples which contains an example for this. + Java Objects: Please have a look at the Embedding examples which contain an example for this.

@@ -255,134 +270,176 @@ try {

Configuring Apache FOP Programmatically

- Apache FOP provides a class called FOUserAgent which is used to customize FOP's - behaviour. If you wish to do that, the first step is to create your own instance - of FOUserAgent and pass that to the Fop constructor: -

- -

- You can do all sorts of things on the user agent: + Apache FOP provides two levels on which you can customize FOP's + behaviour: the FopFactory and the user agent.

-
- The base URL to use when resolving relative URLs. Example: -
- userAgent.setBaseURL("file:///C:/Temp/"); -
-
- Disable strict validation. When disabled FOP is less strict about the rules established by the XSL-FO specification. Example: -
- userAgent.setStrictValidation(false); -
-
- Set the producer of the document. This is metadata information that can be used for certain output formats such as PDF. The default producer is "Apache FOP". Example: -
- userAgent.setProducer("MyKillerApplication"); -
-
- Set the creating user of the document. This is metadata information that can be used for certain output formats such as PDF. Example: -
- userAgent.setCreator("John Doe"); -
-
- Set the author of the document. This is metadata information that can be used for certain output formats such as PDF. Example: -
- userAgent.setAuthor("John Doe"); -
-
- Override the creation date and time of the document. This is metadata information that can be used for certain output formats such as PDF. Example: -
- userAgent.setCreationDate(new Date()); -
-
- Set the title of the document. This is metadata information that can be used for certain output formats such as PDF. Example: -
- userAgent.setTitle("Invoice No 138716847"); -
-
- Set the keywords of the document. This is metadata information that can be used for certain output formats such as PDF. Example: -
- userAgent.setKeywords("XML XSL-FO"); -
-
- Set the source resolution for the document. This is used internally to determine the pixel - size for SVG images and bitmap images without resolution information. Default: 72 dpi. Example: -
- userAgent.setSourceResolution(96); //=96dpi (dots/pixels per Inch) -
-
- Set the target resolution for the document. This is used to - specify the output resolution for bitmap images generated by bitmap renderers - (such as the TIFF renderer) and by bitmaps generated by Apache Batik for filter - effects and such. Default: 72 dpi. Example: -
- userAgent.setTargetResolution(300); //=300dpi (dots/pixels per Inch) -
-
- Set your own Renderer instance. If you want to supply your own renderer or - configure a Renderer in a special way you can give the instance to the FOUserAgent. Normally, - the Renderer instance is created by FOP. Example: -
- userAgent.setRendererOverride(myRenderer); //myRenderer is an org.apache.fop.render.Renderer -
-
- Set your own FOEventHandler instance. If you want to supply your own FOEventHandler or - configure an FOEventHandler subclass in a special way you can give the instance to the FOUserAgent. Normally, - the FOEventHandler instance is created by FOP. Example: -
- userAgent.setFOEventHandlerOverride(myFOEventHandler); //myFOEventHandler is an org.apache.fop.fo.FOEventHandler -
-
- Manually add a ElementMapping instance. If you want to supply a special FOP extension - you can give the instance to the FOUserAgent. Normally, the FOP extensions can be automatically detected - (see the documentation on extension for more info). -
- userAgent.addElementMapping(myElementMapping); //myElementMapping is a org.apache.fop.fo.ElementMapping -
-
- Set a URIResolver for custom URI resolution. By supplying a JAXP URIResolver you can add - custom URI resolution functionality to FOP. For example, you can use - Apache XML Commons Resolver to make use of XCatalogs. -
- userAgent.setURIResolver(myResolver); //myResolver is a javax.xml.transform.URIResolver -
-
- Set the parameters for PDF encryption for the document. If you create PDF files you can - instantiate and set an org.apache.fop.pdf.PDFEncryptionParams object. Example: -
- userAgent.setPDFEncryptionParams(new PDFEncryptionParams(null, "owner", false, false, true, true)); -
-
- Enable an alternative set of rules for text indents that tries to mimic the behaviour of many commercial - FO implementations that chose to break the specification in this aspect. The default of this option is - 'false' which causes Apache FOP to behave exactly as describes in the specification. To enable the - alternative behaviour, call: -
- userAgent.setBreakIndentInheritanceOnReferenceAreaBoundary(true); -

- - You should not reuse an FOUserAgent instance between FOP rendering runs although you can. Especially - in multi-threaded environment, this is a bad idea. - +

+ Customizing the FopFactory +

+ The FopFactory holds configuration data and references to objects which are reusable over + multiple rendering runs. It's important to instantiate it only once (except in special + environments) and reuse it every time to create new FOUserAgent and Fop instances. +

+ You can set all sorts of things on the FopFactory: +

+
+ The font base URL to use when resolving relative URLs for fonts. Example: +
+ fopFactory.setFontBaseURL("file:///C:/Temp/fonts"); +
+
+ Disable strict validation. When disabled FOP is less strict about the rules + established by the XSL-FO specification. Example: +
+ fopFactory.setStrictValidation(false); +
+
+ Enable an alternative set of rules for text indents that tries to mimic the behaviour of many commercial + FO implementations, that chose to break the specification in this respect. The default of this option is + 'false', which causes Apache FOP to behave exactly as described in the specification. To enable the + alternative behaviour, call: +
+ fopFactory.setBreakIndentInheritanceOnReferenceAreaBoundary(true); +
+
+ Set the source resolution for the document. This is used internally to determine the pixel + size for SVG images and bitmap images without resolution information. Default: 72 dpi. Example: +
+ fopFactory.setSourceResolution(96); // =96dpi (dots/pixels per Inch) +
+
+ Manually add an ElementMapping instance. If you want to supply a special FOP extension + you can give the instance to the FOUserAgent. Normally, the FOP extensions can be automatically detected + (see the documentation on extension for more info). Example: +
+ fopFactory.addElementMapping(myElementMapping); // myElementMapping is a org.apache.fop.fo.ElementMapping +
+
+ Set a URIResolver for custom URI resolution. By supplying a JAXP URIResolver you can add + custom URI resolution functionality to FOP. For example, you can use + Apache XML Commons Resolver to make use of XCatalogs. Example: +
+ fopFactory.setURIResolver(myResolver); // myResolver is a javax.xml.transform.URIResolver + + Both the FopFactory and the FOUserAgent have a method to set a URIResolver. The URIResolver on the FopFactory + is primarily used to resolve URIs on factory-level (hyphenation patterns, for example) and it is always used + if no other URIResolver (for example on the FOUserAgent) resolved the URI first. + +

+ Customizing the User Agent +

+ The user agent is the entity that allows you to interact with a single rendering run, i.e. the processing of a single + document. If you wish to customize the user agent's behaviour, the first step is to create your own instance + of FOUserAgent using the appropriate factory method on FopFactory and pass that + to the factory method that will create a new Fop instance: +

+ +

+ You can do all sorts of things on the user agent: +

+
+ The base URL to use when resolving relative URLs. Example: +
+ userAgent.setBaseURL("file:///C:/Temp/"); +
+
+ Set the producer of the document. This is metadata information that can be used for certain output formats such as PDF. The default producer is "Apache FOP". Example: +
+ userAgent.setProducer("MyKillerApplication"); +
+
+ Set the creating user of the document. This is metadata information that can be used for certain output formats such as PDF. Example: +
+ userAgent.setCreator("John Doe"); +
+
+ Set the author of the document. This is metadata information that can be used for certain output formats such as PDF. Example: +
+ userAgent.setAuthor("John Doe"); +
+
+ Override the creation date and time of the document. This is metadata information that can be used for certain output formats such as PDF. Example: +
+ userAgent.setCreationDate(new Date()); +
+
+ Set the title of the document. This is metadata information that can be used for certain output formats such as PDF. Example: +
+ userAgent.setTitle("Invoice No 138716847"); +
+
+ Set the keywords of the document. This is metadata information that can be used for certain output formats such as PDF. Example: +
+ userAgent.setKeywords("XML XSL-FO"); +
+
+ Set the target resolution for the document. This is used to + specify the output resolution for bitmap images generated by bitmap renderers + (such as the TIFF renderer) and by bitmaps generated by Apache Batik for filter + effects and such. Default: 72 dpi. Example: +
+ userAgent.setTargetResolution(300); // =300dpi (dots/pixels per Inch) +
+
+ Set your own Renderer instance. If you want to supply your own renderer or + configure a Renderer in a special way you can give the instance to the FOUserAgent. Normally, + the Renderer instance is created by FOP. Example: +
+ userAgent.setRendererOverride(myRenderer); // myRenderer is an org.apache.fop.render.Renderer +
+
+ Set your own FOEventHandler instance. If you want to supply your own FOEventHandler or + configure an FOEventHandler subclass in a special way you can give the instance to the FOUserAgent. Normally, + the FOEventHandler instance is created by FOP. Example: +
+ userAgent.setFOEventHandlerOverride(myFOEventHandler); // myFOEventHandler is an org.apache.fop.fo.FOEventHandler +
+
+ Set a URIResolver for custom URI resolution. By supplying a JAXP URIResolver you can add + custom URI resolution functionality to FOP. For example, you can use + Apache XML Commons Resolver to make use of XCatalogs. Example: +
+ userAgent.setURIResolver(myResolver); // myResolver is a javax.xml.transform.URIResolver + + Both the FopFactory and the FOUserAgent have a method to set a URIResolver. The URIResolver on the FOUserAgent is + used for resolving URIs which are document-related. If it's not set or cannot resolve a URI, the URIResolver + from the FopFactory is used. + +

+ + You should not reuse an FOUserAgent instance between FOP rendering runs although you can. Especially + in multi-threaded environment, this is a bad idea. + +

Using a Configuration File @@ -398,7 +455,11 @@ import org.apache.avalon.framework.configuration.DefaultConfigurationBuilder; DefaultConfigurationBuilder cfgBuilder = new DefaultConfigurationBuilder(); Configuration cfg = cfgBuilder.buildFromFile(new File("C:/Temp/mycfg.xml")); -userAgent.setUserConfig(cfg);]]> +fopFactory.setUserConfig(cfg); + +/* ..or.. */ + +fopFactory.setUserConfig(new File("C:/Temp/mycfg.xml"));]]>

The layout of the configuration file is described on the Configuration page.

@@ -408,11 +469,10 @@ userAgent.setUserConfig(cfg);]]>

Object reuse

- At the moment, the Fop instances shouldn't be reused. Please recreate - Fop and FOUserAgent instances for each rendering run until further notice. - We will likely add an additional object which will carry information - and configuration which can be reused between rendering runs to further - optimize this. + Fop instances shouldn't (and can't) be reused. Please recreate + Fop and FOUserAgent instances for each rendering run using the FopFactory. + This is a cheap operation as all reusable information is held in the + FopFactory. That's why it's so important to reuse the FopFactory instance.

@@ -439,9 +499,9 @@ userAgent.setUserConfig(cfg);]]>

To get the number of pages that were rendered by FOP you can call Fop.getResults(). This returns a FormattingResults object - where you can lookup the number of pages produced. It also gives you the + where you can look up 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 + numbers 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.

@@ -458,16 +518,16 @@ userAgent.setUserConfig(cfg);]]> (parser, XSL transformer, SQL datasource etc.).

- Depending on the target OutputStream (in case of an FileOutputStream, but not + Depending on the target OutputStream (in case of a FileOutputStream, but not for a ByteArrayOutputStream, for example) it may improve performance considerably if you buffer the OutputStream using a BufferedOutputStream: - fop.setOutputStream(new java.io.BufferedOutputStream(out)); + out = new java.io.BufferedOutputStream(out);
Make sure you properly close the OutputStream when FOP is finished.

Cache the stylesheet. If you use the same stylesheet multiple times - you can setup a JAXP Templates object and reuse it each time you do + you can set up a JAXP Templates object and reuse it each time you do the XSL transformation. (More information can be found here.)

@@ -475,14 +535,18 @@ userAgent.setUserConfig(cfg);]]> Use an XSLT compiler like XSLTC that comes with Xalan-J. +

+ Fine-tune your stylesheet to make the XSLT process more efficient and to create XSL-FO that can + be processed by FOP more efficiently. Less is more: Try to make use of property inheritance where possible. +

Multithreading FOP

Apache FOP may currently not be completely thread safe. - FOP uses some static variables (for example for the image cache). This code - has not been fully tested for multi-threading issues, yet. + The code has not been fully tested for multi-threading issues, yet. + If you encounter any suspicious behaviour, please notify us.

There is also a known issue with fonts being jumbled between threads when using @@ -494,13 +558,11 @@ userAgent.setUserConfig(cfg);]]> Examples

The directory "{fop-dir}/examples/embedding" contains several working examples. - In contrast to the examples above the examples here primarily use JAXP for - XML access. This may be easier to understand for people familiar with JAXP.

ExampleFO2PDF.java

This - + example demonstrates the basic usage pattern to transform an XSL-FO file to PDF using FOP. @@ -510,7 +572,7 @@ file to PDF using FOP.

ExampleXML2FO.java

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 @@ -522,7 +584,7 @@ classpath (ex. Xalan).

ExampleXML2PDF.java

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 @@ -542,13 +604,13 @@ performance is significantly higher with SAX.

ExampleObj2XML.java

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

@@ -556,13 +618,13 @@ complicated once you know how this works. 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. +xml-fop/examples/embedding/xml/xml/projectteam.xml. We want to serialize to XML a +project team with several members which exist as Java objects. Therefore we created the two classes: ProjectTeamInputSource and ProjectTeamXMLReader (in the same place as ProjectTeam above).

-The XMLReader implementation (regard it as a special kind of XML parser)is +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.

@@ -575,7 +637,7 @@ used. For more detailed information see other resources on JAXP (ex.

ExampleObj2PDF.java

This - + example combines the previous and the third to demonstrate how you can transform a Java object to a PDF directly in one smooth run @@ -588,7 +650,7 @@ using FOP as before.

ExampleDOM2PDF.java

This - + example has FOP use a DOMSource instead of a StreamSource in order to use a DOM tree as input for an XSL transformation. @@ -597,9 +659,9 @@ use a DOM tree as input for an XSL transformation.

ExampleSVG2PDF.java (PDF Transcoder example)

This - + example -shows use of the PDF Transcoder, a sub-application within FOP. +shows the usage of the PDF Transcoder, a sub-application within FOP. It is used to generate a PDF document from an SVG file.

diff --git a/src/documentation/content/xdocs/0.92/fonts.xml b/src/documentation/content/xdocs/0.92/fonts.xml index 993fa047e..5c1fc0c6f 100644 --- a/src/documentation/content/xdocs/0.92/fonts.xml +++ b/src/documentation/content/xdocs/0.92/fonts.xml @@ -1,6 +1,6 @@ + Relative URLs are resolved relative to the font-base property (or base) if available. See FOP: Configuration for more information. - Relative font URLs are currently not possible. You need to specify absolute URLs. Patches are welcome! :-)

The "kerning" and "embed-url" attributes are optional. Kerning is currently not used at all. If embedding is off, the output will position the text correctly (from the metrics file), but it will not be displayed or printed correctly unless the viewer has the applicable font available to their local system.

When setting the embed-url attribute for Type 1 fonts, be sure to specify the PFB (actual font data), not PFM (font metrics) file that you used to generate the XML font metrics file.

@@ -256,6 +257,11 @@ It will display all of the font names and exit with an Exception.

The font is simply embedded into the PDF file, it is not converted.

Font embedding is enabled in the userconfig.xml file and controlled by the embed-url attribute. If you don't specify the embed-url attribute the font will not be embedded, but will only be referenced.

+ + Omitting the embed-url attribute for CID-encoded TrueType fonts will currently produce invalid + PDF files! If you create the XML font metric file using the "-enc ansi" option, you can omit + the embed-url attribute for TrueType fonts but you're restricted to the WinAnsi character set. +

When FOP embeds a font, it adds a prefix to the fontname to ensure that the name will not match the fontname of an installed font. This is helpful with older versions of Acrobat Reader that preferred installed fonts over embedded fonts.

When embedding PostScript fonts, the entire font is always embedded.

@@ -268,6 +274,30 @@ This will cause the whole font to be embedded in the pdf document. Characters will be WinAnsi encoded (as specified in the PDF spec), so you lose the ability to use characters from other character sets. See Table of TTF Encoding Options for more details.

+ Explicitely embedding the base 14 fonts +

+ There are cases where you might want to force the embedding of one or more of the base 14 fonts that + can normally be considered available on the target platform (viewer, printer). One of these cases is + PDF/A which mandates the embedding of even the base 14 fonts. Embedding a font such as Helvetica or + Courier is straight-forward. The "Symbol" and "ZapfDingbats" fonts, however, currently present a + problem because FOP cannot correctly determine the encoding of these two single-byte fonts through + the PFM file. FOP now correctly interprets the "encoding" value in the XML font metrics file, but the + PFMReader application writes "UnknownEncoding" to the generated XML file. In order to embed "Symbol" + and "ZapfDingbats" you have to manually change the XML font metrics file and specify "SymbolEncoding" + or "ZapfdingbatsEncoding" encoding respectively as the value for the "encoding" element. +

Example:

+ + + Symbol +

+ SymbolEncoding + 673 + 766 + [..]]]> +

diff --git a/src/documentation/content/xdocs/0.92/hyphenation.xml b/src/documentation/content/xdocs/0.92/hyphenation.xml index 3340f9c4f..6b21dd951 100644 --- a/src/documentation/content/xdocs/0.92/hyphenation.xml +++ b/src/documentation/content/xdocs/0.92/hyphenation.xml @@ -113,7 +113,7 @@ be created from the supplied pattern(s)).

Put the pattern source file(s) into a directory of your choice and configure FOP to look for custom patterns in this directory, by setting the - <hyphenation-dir> + <hyphenation-base> configuration option.

diff --git a/src/documentation/content/xdocs/0.92/intermediate.xml b/src/documentation/content/xdocs/0.92/intermediate.xml new file mode 100644 index 000000000..ad42f2645 --- /dev/null +++ b/src/documentation/content/xdocs/0.92/intermediate.xml @@ -0,0 +1,145 @@ + + + + + +

+ Intermediate Format + $Revision$ +

+ + + Please note that the intermediate format is an advanced feature and can be ignored by most + users of Apache FOP. + +

+ Introduction +

+ The intermediate format (IF) is a proprietary XML format that represents the area tree + generated by the layout engine. The area tree is conceptually defined in the + XSL-FO specification in chapter 1.1.2. + The IF can be generated through the area tree XML Renderer (the XMLRenderer). +

+ The intermediate format can be used to generate intermediate documents that are modified + before they are finally rendered to their ultimate output format. Modifications include + adjusting and changing trait values, adding or modifying area objects, inserting prefabricated + pages, overlays, imposition (n-up, rotation, scaling etc.). Multiple IF files can be combined + to a single output file. +

+ Usage of the Intermediate Format +

+ As already mentioned, the IF is generated by using the XMLRenderer (MIME type: + application/X-fop-areatree). So, you basically set the right MIME type for + the output format and process your FO files as if you would create a PDF file. However, there + is an important detail to consider: The various Renderers don't all use the same font sources. + To be able to create the right area tree for the ultimate output file, you need to create + the IF file using the right font setup. This is achieved by telling the XMLRenderer to mimic + another renderer. This is done by calling the XMLRenderer's mimicRenderer() method with an + instance of the ultimate target renderer as the single parameter. This has a consequence: An + IF file rendered with the Java2DRenderer may not look as expected when it was actually generated + for the PDF renderer. For renderers that use the same font setup, this restriction does not + apply (PDF and PS, for example). Generating the intermediate format file is the first step. +

+ The second step is to reparse the IF file using the AreaTreeParser which is + found in the org.apache.fop.area package. The pages retrieved from the IF file are added to an + AreaTreeModel instance from where they are normally rendered using one of the available Renderer + implementations. You can find examples for the IF processing in the + examples/embedding + directory in the FOP distribution +

+ The basic pattern to parse the IF format looks like this: +

+ +

+ This example simply reads an IF file and renders it to a PDF file. Please note, that in normal + FOP operation you're shielded from having to instantiate the FontInfo object yourself. This + is normally a task of the AreaTreeHandler which is not present in this scenario. The same + applies to the AreaTreeModel instance, in this case an instance of a subclass called + RenderPagesModel. RenderPagesModel is ideal in this case as it has very little overhead + processing the individual pages. An important line in the example is the call to + endDocument() on the AreaTreeModel. This lets the Renderer know that the processing + is now finished. +

+ The intermediate format can also be used from the command-line + by using the "-atin" parameter for specifying the area tree XML as input file. You can also + specify a "mimic renderer" by inserting a MIME type between "-at" and the output file. +

+ Concatenating Documents +

+ This initial example is obviously not very useful. It would be faster to create the PDF file + directly. As the ExampleConcat.java + example shows you can easily parse multiple IF files in a row and add the parsed pages to the + same AreaTreeModel instance which essentially concatenates all the input document to one single + output document. +

+ Modifying Documents +

+ One of the most important use cases for the intermediate format is obviously modifying the area + tree XML before finally rendering it to the target format. You can easily use XSLT to process + the IF file according to your needs. Please note, that we will currently not formally describe + the intermediate format. You need to have a good understanding its structure so you don't + create any non-parseable files. We may add an XML Schema and more detailed documentation at a + later time. You're invited to help us with that. +

+ Advanced Use +

+ The generation of the intermediate format as well as it parsing process has been designed to allow + for maximum flexibility and optimization. Please note that you can call setTransformerHandler() on + XMLRenderer to give the XMLRenderer your own TransformerHandler instance in case you would like to + do custom serialization (to a W3C DOM, for example) and/or to directly modify the area tree using + XSLT. The AreaTreeParser on the other side allows you to retrieve a ContentHandler instance where + you can manually send SAX events to to start the parsing process (see getContentHandler()). +

+ + diff --git a/src/documentation/content/xdocs/0.92/output.xml b/src/documentation/content/xdocs/0.92/output.xml index 8402a9075..89b5ee233 100644 --- a/src/documentation/content/xdocs/0.92/output.xml +++ b/src/documentation/content/xdocs/0.92/output.xml @@ -1,6 +1,6 @@ + + + +

+ PDF/A (ISO 19005) + $Revision: 389563 $ + + + +

+ +

+ Overview + + Support for PDF/A is available beginning with version 0.92. + +

+ PDF/A is a standard which turns PDF into an "electronic document file + format for long-term preservation". PDF/A-1 is the first part of the + standard and is documented in + ISO 19005-1:2005(E). + Work on PDF/A-2 is in progress at + AIIM. +

+ Design documentation on PDF/A can be found on FOP's Wiki on the + PDFA1ConformanceNotes page. +

+ Implementation Status +

+ PDF/A-1b is implemented to the degree that FOP supports + the creation of the elements described in ISO 19005-1. +

+ There is a restriction with + XMP metadata. If an XMP metadata packet is present in the fo:declarations + element of an FO file, the values from the XMP packet are not synchronized + with the Info PDF object as is mandated by chapter 6.7.3 of the ISO document. + However, if no XMP packet is supplied FOP automatically generates an XMP + packet from the values in the Info PDF object. +

+ Tests have been performed against jHove and Adobe Acrobat 7.0.7 (Preflight function). +

+ PDF/A-1a is not implemented, yet. This is mostly because of the requirement + for tagged PDF which is not available in FOP, yet. +

+ Usage (command line) +

+ If you specify "-pdfa1b" instead of "-pdf" for the output format on the + command line, support for PDF/A-1b is activated. If there is a violation of + one of the validation rules for PDF/A, an error message is presented and the + processing stops. +

+ Usage (embedded) +

+ When FOP is embedded in another Java application you can set a special option + on the renderer options in the user agent to activate the PDF/A-1b profile. + Here's an example: +

+ +

+ If one of the validation rules of PDF/A is violated, an PDFConformanceException + (descendant of RuntimeException) is thrown. +

+ PDF/A in Action +

+ There are a number of things that must be looked after if you activate a PDF/A + profile. If you receive a PDFConformanceException, have a look at the following + list (not necessarily comprehensive): +

+ Make sure all (!) fonts are embedded. If you use base 14 fonts (like Helvetica) + you need to obtain a license for them and embed them like any other font. +
+ Don't use PDF encryption. PDF/A doesn't allow it. +
+ Don't use CMYK images without an ICC color profile. PDF/A doesn't allow mixing + color spaces and FOP currently only properly supports the sRGB color space. Please + note that FOP embeds a standard sRGB ICC profile (sRGB IEC61966-2.1) as the + primary output intent for the PDF. +
+ Don't use non-RGB colors in SVG images. Same issue as with CMYK images. +
+ Don't use EPS graphics with fo:external-graphic. Embedding EPS graphics in PDF + is deprecated since PDF 1.4 and prohibited by PDF/A. +
+ PDF is forced to version 1.4 if PDF/A-1 is activated. +
+ No filter must be specified explicitely for metadata objects. Metadata must be + embedded in clear text so non-PDF-aware applications can extract the XMP metadata. +

+ + diff --git a/src/documentation/content/xdocs/0.92/pdfencryption.xml b/src/documentation/content/xdocs/0.92/pdfencryption.xml index 2c7742d8d..aca98135a 100755 --- a/src/documentation/content/xdocs/0.92/pdfencryption.xml +++ b/src/documentation/content/xdocs/0.92/pdfencryption.xml @@ -1,6 +1,6 @@ + \ No newline at end of file diff --git a/src/documentation/content/xdocs/0.92/upgrading.xml b/src/documentation/content/xdocs/0.92/upgrading.xml index e1a812f83..abfb3b939 100644 --- a/src/documentation/content/xdocs/0.92/upgrading.xml +++ b/src/documentation/content/xdocs/0.92/upgrading.xml @@ -1,6 +1,6 @@