From 46f47c3095c086d88ff7d652aee40303a9ed9601 Mon Sep 17 00:00:00 2001 From: Simon Pepping Date: Thu, 30 Mar 2006 19:33:25 +0000 Subject: A few small changes to these two documentation pages git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@390222 13f79535-47bb-0310-9956-ffa450edef68 --- .../content/xdocs/trunk/embedding.xml | 95 +++++++++++----------- src/documentation/content/xdocs/trunk/output.xml | 11 +-- 2 files changed, 54 insertions(+), 52 deletions(-) (limited to 'src/documentation') diff --git a/src/documentation/content/xdocs/trunk/embedding.xml b/src/documentation/content/xdocs/trunk/embedding.xml index 98f1518a4..06b241eb4 100644 --- a/src/documentation/content/xdocs/trunk/embedding.xml +++ b/src/documentation/content/xdocs/trunk/embedding.xml @@ -32,15 +32,16 @@ to embedded applications as well as command-line use, such as options and performance.

- To embed Apache FOP in your application, instantiate a new org.apache.fop.apps.FopFactory - instance and create a new org.apache.fop.apps.Fop instance through one of the factory - methods of FopFactory. There, you can specify which output format (i.e. Renderer) to use - and you can optionally set the OutputStream to use to output the results of the - rendering. 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.

We recently changed FOP's outer API to what we consider the final API. This might require @@ -69,7 +70,7 @@ import org.apache.fop.apps.MimeConstants; // (reuse if you plan to render multiple documents!) FopFactory fopFactory = FopFactory.newInstance(); -// Step 2: Setup output stream. +// Step 2: Set up output stream. // Note: Using BufferedOutputStream for performance reasons (helpful with FileOutputStreams). OutputStream out = new BufferedOutputStream(new FileOutputStream(new File("C:/Temp/myfile.pdf"))); @@ -100,7 +101,7 @@ try {

@@ -299,8 +300,8 @@ try {

  • 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 + 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); @@ -310,23 +311,23 @@ try { 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) + fopFactory.setSourceResolution(96); // =96dpi (dots/pixels per Inch)

  • - Manually add a ElementMapping instance. If you want to supply a special FOP extension + 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). + (see the documentation on extension for more info). Example:

    - fopFactory.addElementMapping(myElementMapping); //myElementMapping is a org.apache.fop.fo.ElementMapping + 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. + Apache XML Commons Resolver to make use of XCatalogs. Example:

    - fopFactory.setURIResolver(myResolver); //myResolver is a javax.xml.transform.URIResolver + 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 @@ -340,12 +341,14 @@ try {

    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 respective factory method on FopFactory and pass that + 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: @@ -400,7 +403,7 @@ try { (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) + userAgent.setTargetResolution(300); // =300dpi (dots/pixels per Inch)

  • @@ -408,7 +411,7 @@ try { 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 + userAgent.setRendererOverride(myRenderer); // myRenderer is an org.apache.fop.render.Renderer

  • @@ -416,15 +419,15 @@ try { 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 + 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. + Apache XML Commons Resolver to make use of XCatalogs. Example:

    - userAgent.setURIResolver(myResolver); //myResolver is a javax.xml.transform.URIResolver + 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 @@ -496,9 +499,9 @@ fopFactory.setUserConfig(new File("C:/Temp/mycfg.xml"));]]>

    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.

    @@ -515,16 +518,16 @@ fopFactory.setUserConfig(new File("C:/Temp/mycfg.xml"));]]> (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.)
    • @@ -555,8 +558,6 @@ fopFactory.setUserConfig(new File("C:/Temp/mycfg.xml"));]]> 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 @@ -608,8 +609,8 @@ performance is significantly higher with SAX. 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.

    @@ -617,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.

    @@ -660,7 +661,7 @@ use a DOM tree as input for an XSL transformation.

    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/trunk/output.xml b/src/documentation/content/xdocs/trunk/output.xml index 8880aca21..22f5c6e49 100644 --- a/src/documentation/content/xdocs/trunk/output.xml +++ b/src/documentation/content/xdocs/trunk/output.xml @@ -88,7 +88,7 @@ out = proc.getOutputStream();]]>
    Fonts

    - PDF has a set of fonts that are always available to all PDF viewers, + PDF has a set of fonts that are always available to all PDF viewers; to quote from the PDF Specification: "PDF prescribes a set of 14 standard fonts that can be used without prior @@ -201,7 +201,7 @@ out = proc.getOutputStream();]]>

    Limitations
      -
    • Images and SVG may not be display correctly. SVG support is far from being complete. No image transparency is available.
      • +
    • Images and SVG may not be displayed correctly. SVG support is far from being complete. No image transparency is available.
    • Only Type 1 fonts are supported.
    • Multibyte characters are not supported.
    • PPD support is still missing.
      • @@ -364,11 +364,12 @@ out = proc.getOutputStream();]]> 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 + an 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 may appear wrong. + same way as for the AWT viewer. If the SVG is viewed on a + system where the fonts are different, such as another platform, + then the page may look wrong.

    -- cgit v1.2.3