You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xmlgraphics.apache.org by ps...@apache.org on 2012/12/04 16:58:33 UTC
svn commit: r1417008 [6/6] - in /xmlgraphics/site/trunk/content: batik/
batik/dev/ batik/tools/ batik/using/ batik/using/scripting/ commons/ fop/
fop/0.95/ fop/1.0/ fop/1.1/ fop/dev/design/ fop/trunk/
Modified: xmlgraphics/site/trunk/content/fop/trunk/fonts.mdtext
URL: http://svn.apache.org/viewvc/xmlgraphics/site/trunk/content/fop/trunk/fonts.mdtext?rev=1417008&r1=1417007&r2=1417008&view=diff
==============================================================================
--- xmlgraphics/site/trunk/content/fop/trunk/fonts.mdtext (original)
+++ xmlgraphics/site/trunk/content/fop/trunk/fonts.mdtext Tue Dec 4 15:58:21 2012
@@ -58,25 +58,26 @@ In earlier FOP versions, it was always n
Basic information about fonts can be found at:
-- [Adobe font types](http://partners.adobe.com/asn/developer/type/ftypes.html)
+- [Adobe font types](http://partners.adobe.com/asn/developer/type/ftypes.html)
-- [Adobe Font Technote](http://partners.adobe.com/asn/developer/technotes/fonts.html)
+- [Adobe Font Technote](http://partners.adobe.com/asn/developer/technotes/fonts.html)
## Bulk Font Configuration <a id="bulk"></a>
If you want FOP to use custom fonts, you need to tell it where to find them. This is done in the configuration file and once per renderer (because each output format is a little different). For convenience, FOP allows bulk registering of fonts; you can either tell FOP to find your operating system fonts or you can specify directories that it will search for support fonts. These fonts will then automatically be registered.
+ :::xml
<renderers>
<renderer mime="application/pdf">
<fonts>
<!-- register all the fonts found in a directory -->
<directory>C:\MyFonts1</directory>
-
+
<!-- register all the fonts found in a directory and all of its sub directories (use with care) -->
<directory recursive="true">C:\MyFonts2</directory>
<!-- automatically detect operating system installed fonts -->
- <auto-detect/>
+ <auto-detect/>
</fonts>
</renderer>
</renderers>
@@ -87,6 +88,7 @@ Review the documentation for [FOP Config
You must tell FOP how to find and use the font files by registering them in the [FOP Configuration](configuration.html) . Add entries for your custom fonts, regardless of font type, to the configuration file in a manner similar to the following:
+ :::xml
<renderers>
<renderer mime="application/pdf">
<fonts>
@@ -138,11 +140,14 @@ TrueType collections (.ttc files) contai
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 display all of the font names and exit with an Exception.
Here is an example of generating a metrics file for a .ttc file:
+
java -cp build\fop.jar;lib\avalon-framework.jar;lib\commons-logging.jar;lib\commons-io.jar
org.apache.fop.fonts.apps.TTFReader -ttcname "MS Mincho"
msmincho.ttc msminch.xml
+
Alternatively, the individual sub-fonts of a TrueType Collections can be selected using the "sub-font" attribute on the "font" element. That means that generating an XML font metrics file for TrueType collections is not necessary anymore. Example:
+ :::xml
<font embed-url="gulim.ttc" sub-font="GulimChe">
<font-triplet name="GulimChe" style="normal" weight="normal"/>
</font>
@@ -154,9 +159,9 @@ When the "auto-detect" flag is set in th
FOP will also auto-detect fonts which are available in the classpath, if they are described as "application/x-font" in the MANIFEST.MF file. For example, if your .jar file contains font/myfont.ttf:
Manifest-Version: 1.0
-
- Name: font/myfont.ttf
- Content-Type: application/x-font
+
+ Name: font/myfont.ttf
+ Content-Type: application/x-font
This feature allows you to create JAR files containing fonts. The JAR files can be added to fop by providem them in the classpath, e.g. copying them into the lib/ directory.
@@ -221,14 +226,14 @@ There are two different ways how you can
1. For automatically configured fonts there's a different mechanism to specify which fonts should be referenced rather than embedded. This is done in the "referenced-fonts" element in the configuration. Here's an example:
- <fop version="1.0">
- <fonts>
- <referenced-fonts>
- <match font-family="Helvetica"/>
- <match font-family="DejaVu.*"/>
- </referenced-fonts>
- </fonts>
- </fop>
+ <fop version="1.0">
+ <fonts>
+ <referenced-fonts>
+ <match font-family="Helvetica"/>
+ <match font-family="DejaVu.*"/>
+ </referenced-fonts>
+ </fonts>
+ </fop>
At the moment, you can only match fonts against their font-family. It is possible to use regular expressions as is shown in the second example above ("DejaVu.*"). The syntax for the regular expressions used here are the one used by the [package](http://java.sun.com/j2se/1.4/docs/api/java/util/regex/package-summary.html) . So, in the above snippet "Helvetica" and all variants of the "DejaVu" font family are referenced. If you want to reference all fonts, just specify `font-family=".*"` .
@@ -258,20 +263,20 @@ When a `<substitutions/>` section is def
For example you could make all FO font-family references to 'Arial' with weights between 700 and 900 reference the normal 'Arial Black' font.
- <fop version="1.0">
- <fonts>
- <substitutions>
- <substitution>
- <from font-family="Arial" font-weight="700..900"/>
- <to font-family="Arial Black"/>
- </substitution>
- <substitution>
- <from font-family="FrutigerLight"/>
- <to font-family="Times" font-weight="bold" font-style="italic"/>
- </substitution>
- </substitutions>
- </fonts>
- </fop>
+ <fop version="1.0">
+ <fonts>
+ <substitutions>
+ <substitution>
+ <from font-family="Arial" font-weight="700..900"/>
+ <to font-family="Arial Black"/>
+ </substitution>
+ <substitution>
+ <from font-family="FrutigerLight"/>
+ <to font-family="Times" font-weight="bold" font-style="italic"/>
+ </substitution>
+ </substitutions>
+ </fonts>
+ </fop>
## Font Selection Strategies <a id="selection"></a>
Modified: xmlgraphics/site/trunk/content/fop/trunk/intermediate.mdtext
URL: http://svn.apache.org/viewvc/xmlgraphics/site/trunk/content/fop/trunk/intermediate.mdtext?rev=1417008&r1=1417007&r2=1417008&view=diff
==============================================================================
--- xmlgraphics/site/trunk/content/fop/trunk/intermediate.mdtext (original)
+++ xmlgraphics/site/trunk/content/fop/trunk/intermediate.mdtext Tue Dec 4 15:58:21 2012
@@ -53,8 +53,9 @@ The second step is to reparse the file u
The basic pattern to parse the area tree XML format looks like this:
- FopFactory fopFactory = FopFactory.newInstance();
-
+ :::java
+ FopFactory fopFactory = FopFactory.newInstance();
+
// Setup output
OutputStream out = new java.io.FileOutputStream(pdffile);
out = new java.io.BufferedOutputStream(out);
@@ -62,16 +63,16 @@ The basic pattern to parse the area tree
//Setup fonts and user agent
FontInfo fontInfo = new FontInfo();
FOUserAgent userAgent = fopFactory.newFOUserAgent();
-
+
//Construct the AreaTreeModel that will received the individual pages
- AreaTreeModel treeModel = new RenderPagesModel(userAgent,
+ AreaTreeModel treeModel = new RenderPagesModel(userAgent,
MimeConstants.MIME_PDF, fontInfo, out);
-
+
//Parse the area tree file into the area tree
AreaTreeParser parser = new AreaTreeParser();
Source src = new StreamSource(myIFFile);
parser.parse(src, treeModel, userAgent);
-
+
//Signal the end of the processing. The renderer can finalize the target document.
treeModel.endDocument();
} finally {
@@ -111,32 +112,33 @@ The second step is to reparse the file u
The basic pattern to parse the intermediate format looks like this:
+ :::java
FopFactory fopFactory = FopFactory.newInstance();
-
+
// Setup output
OutputStream out = new java.io.FileOutputStream(pdffile);
out = new java.io.BufferedOutputStream(out);
try {
//Setup user agent
FOUserAgent userAgent = fopFactory.newFOUserAgent();
-
+
//Create IFDocumentHandler instance
IFDocumentHandler targetHandler;
String mime = MimeConstants.MIME_PDF;
targetHandler = fopFactory.getRendererFactory().createDocumentHandler(
userAgent, mime);
-
+
//Setup fonts
IFUtil.setupFonts(targetHandler);
-
+
//Tell the target handler where to write the PDF to
targetHandler.setResult(new StreamResult(pdffile));
-
+
//Parse the IF file
IFParser parser = new IFParser();
Source src = new StreamSource(myIFFile);
parser.parse(src, targetHandler, userAgent);
-
+
} finally {
out.close();
}
Modified: xmlgraphics/site/trunk/content/fop/trunk/output.mdtext
URL: http://svn.apache.org/viewvc/xmlgraphics/site/trunk/content/fop/trunk/output.mdtext?rev=1417008&r1=1417007&r2=1417008&view=diff
==============================================================================
--- xmlgraphics/site/trunk/content/fop/trunk/output.mdtext (original)
+++ xmlgraphics/site/trunk/content/fop/trunk/output.mdtext Tue Dec 4 15:58:21 2012
@@ -18,15 +18,15 @@ With a work-around, it is possible to ma
1. Produce an IF file: `fop -fo myfile.fo -at application/pdf myfile.at.xml` <br></br>Specifying "application/pdf" for the "-at" parameter causes FOP to use FOP's own font subsystem (which is used by the PDF renderer). Note that no PDF file is created in this step.
-1. Render to a PDF file: `fop -atin myfile.at.xml -pdf myfile.pdf`
+1. Render to a PDF file: `fop -atin myfile.at.xml -pdf myfile.pdf`
1. Render to a Java2D-based renderer:
-- `fop -atin myfile.at.xml -print`
+- `fop -atin myfile.at.xml -print`
-- `fop -atin myfile.at.xml -awt`
+- `fop -atin myfile.at.xml -awt`
-- `fop -atin myfile.at.xml -tiff myfile.tiff`
+- `fop -atin myfile.at.xml -tiff myfile.tiff`
### Output to a Printer or Other Device <a id="general-direct-output"></a>
@@ -48,7 +48,7 @@ Note that FOP does not currently support
### Fonts <a id="pdf-fonts"></a>
-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 definition. These include four faces each of three Latin text typefaces (Courier, Helvetica, and Times), as well as two symbolic fonts (Symbol and ITC Zapf Dingbats). These fonts, or suitable substitute fonts with the same metrics, are guaranteed to be available in all PDF viewer applications."*
+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 definition. These include four faces each of three Latin text typefaces (Courier, Helvetica, and Times), as well as two symbolic fonts (Symbol and ITC Zapf Dingbats). These fonts, or suitable substitute fonts with the same metrics, are guaranteed to be available in all PDF viewer applications."*
### Post-processing <a id="pdf-postprocess"></a>
@@ -58,46 +58,47 @@ Another popular post-processing tool is
<warning>Caveat: iText may swallow PDF bookmarks. But [Jens Stavnstrup tells us](http://issues.apache.org/bugzilla/show_bug.cgi?id=37589) that this doesn't happen if you use iText's PDFStamper.</warning>
Here is some sample code that uses iText to encrypt a FOP-generated PDF. (Note that FOP now supports [PDF encryption](pdfencryption.html) . However the principles for using iText for other PDF features are similar.)
+ :::java
public static void main(String args[]) {
- try {
- ByteArrayOutputStream fopout = new ByteArrayOutputStream();
- FileOutputStream outfile = new FileOutputStream(args[2]);
- FopFactory fopFactory = FopFactory.newInstance();
- Fop fop = fopFactory.newFop(MimeConstants.MIME_PDF, fopout);
-
- Transformer transformer = TransformerFactory.newInstance().newTransformer(
- new StreamSource(new File(args[1])));
- transformer.transform(new StreamSource(new File(args[0])),
- new SAXResult(fop.getDefaultHandler()));
- PdfReader reader = new PdfReader(fopout.toByteArray());
- int n = reader.getNumberOfPages();
- Document document = new Document(reader.getPageSizeWithRotation(1));
- PdfWriter writer = PdfWriter.getInstance(document, outfile);
- writer.setEncryption(PdfWriter.STRENGTH40BITS, "pdf", null,
- PdfWriter.AllowCopy);
- document.open();
- PdfContentByte cb = writer.getDirectContent();
- PdfImportedPage page;
- int rotation;
- int i = 0;
- while (i < n) {
- i++;
- document.setPageSize(reader.getPageSizeWithRotation(i));
- document.newPage();
- page = writer.getImportedPage(reader, i);
- rotation = reader.getPageRotation(i);
- if (rotation == 90 || rotation == 270) {
- cb.addTemplate(page, 0, -1f, 1f, 0, 0,
- reader.getPageSizeWithRotation(i).height());
- } else {
- cb.addTemplate(page, 1f, 0, 0, 1f, 0, 0);
- }
- System.out.println("Processed page " + i);
+ try {
+ ByteArrayOutputStream fopout = new ByteArrayOutputStream();
+ FileOutputStream outfile = new FileOutputStream(args[2]);
+ FopFactory fopFactory = FopFactory.newInstance();
+ Fop fop = fopFactory.newFop(MimeConstants.MIME_PDF, fopout);
+
+ Transformer transformer = TransformerFactory.newInstance().newTransformer(
+ new StreamSource(new File(args[1])));
+ transformer.transform(new StreamSource(new File(args[0])),
+ new SAXResult(fop.getDefaultHandler()));
+ PdfReader reader = new PdfReader(fopout.toByteArray());
+ int n = reader.getNumberOfPages();
+ Document document = new Document(reader.getPageSizeWithRotation(1));
+ PdfWriter writer = PdfWriter.getInstance(document, outfile);
+ writer.setEncryption(PdfWriter.STRENGTH40BITS, "pdf", null,
+ PdfWriter.AllowCopy);
+ document.open();
+ PdfContentByte cb = writer.getDirectContent();
+ PdfImportedPage page;
+ int rotation;
+ int i = 0;
+ while (i < n) {
+ i++;
+ document.setPageSize(reader.getPageSizeWithRotation(i));
+ document.newPage();
+ page = writer.getImportedPage(reader, i);
+ rotation = reader.getPageRotation(i);
+ if (rotation == 90 || rotation == 270) {
+ cb.addTemplate(page, 0, -1f, 1f, 0, 0,
+ reader.getPageSizeWithRotation(i).height());
+ } else {
+ cb.addTemplate(page, 1f, 0, 0, 1f, 0, 0);
+ }
+ System.out.println("Processed page " + i);
+ }
+ document.close();
+ } catch( Exception e) {
+ e.printStackTrace();
}
- document.close();
- } catch( Exception e) {
- e.printStackTrace();
- }
}
Check the iText tutorial and documentation for setting access flags, password, encryption strength and other parameters.
@@ -115,22 +116,25 @@ In addition to the [PDF Post-processing]
The PDF Renderer supports some PDF specific extensions which can be embedded into the input FO document. To use the extensions the appropriate namespace must be declared in the fo:root element like this:
+ :::xml
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
xmlns:pdf="http://xmlgraphics.apache.org/fop/extensions/pdf">
-
+
#### Embedded Files<a id="pdf-embedded-file"></a>
It is possible to attach/embed arbitrary files into a PDF file. You can give a name and a description of the file. Example:
+ :::xml
<fo:declarations>
<pdf:embedded-file filename="image.jpg" src="url(file:///C:/Temp/myimage.jpg)" description="My image"/>
<pdf:embedded-file src="url(file:///C:/Temp/MyTextDoc.odt)"/>
</fo:declarations>
-
+
`pdf:embedded-file` must be a child of `fo:declarations` . The "src" property is used to reference the file that is to be embedded. This property uses the "uri-specification" datatype from the XSL-FO specification. The "filename" property is optional. If it is missing the filename is automatically set from the URI/IRI of the "src" property. An optional description can also be added to further describe the file attachment.
It is also possible to reference an embedded file from an `fo:basic-link` . Use the special "embedded-file:" URI scheme with the filename as single argument after the URI scheme. Example:
+ :::xml
<fo:basic-link external-destination="url(embedded-file:image.jpg)">Attached Image</fo:basic-link>
Note: Not all PDF Viewers (including some Acrobat Versions) will open the embedded file when clicking on the link. In that case, the user will have to open he attachment via the separate list of file attachments.
@@ -143,6 +147,7 @@ The PostScript renderer has been brought
The PostScript renderer configuration currently allows the following settings:
+ :::xml
<renderer mime="application/postscript">
<auto-rotate-landscape>false</auto-rotate-landscape>
<language-level>3</language-level>
@@ -184,9 +189,9 @@ The output created by the PCLRenderer is
### References <a id="pcl-references"></a>
-- [WikiPedia entry on PCL](http://en.wikipedia.org/wiki/Printer_Control_Language)
+- [WikiPedia entry on PCL](http://en.wikipedia.org/wiki/Printer_Control_Language)
-- [Technical reference documents on PCL from Hewlett-Packard](http://h20000.www2.hp.com/bizsupport/TechSupport/Document.jsp?objectID=bpl04568)
+- [Technical reference documents on PCL from Hewlett-Packard](http://h20000.www2.hp.com/bizsupport/TechSupport/Document.jsp?objectID=bpl04568)
### Limitations <a id="pcl-limitations"></a>
@@ -211,6 +216,7 @@ The output created by the PCLRenderer is
The PCL renderer configuration currently allows the following settings:
+ :::xml
<renderer mime="application/vnd.hp-PCL">
<rendering>quality</rendering>
<text-rendering>bitmap</text-rendering>
@@ -229,6 +235,7 @@ You can control the output resolution fo
The PCL Renderer supports some PCL specific extensions which can be embedded into the input FO document. To use the extensions the appropriate namespace must be declared in the fo:root element like this:
+ :::xml
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
xmlns:pcl="http://xmlgraphics.apache.org/fop/extensions/pcl">
@@ -236,6 +243,7 @@ The PCL Renderer supports some PCL speci
The page-source extension attribute on fo:simple-page-master allows to select the paper tray the sheet for a particular simple-page-master is to be taken from. Example:
+ :::xml
<fo:layout-master-set>
<fo:simple-page-master master-name="simple" pcl:paper-source="2">
...
@@ -248,6 +256,7 @@ Note: the tray number is a positive inte
The `output-bin` extension attribute on fo:simple-page-master allows to select the output bin into which the printed output should be fed. Example:
+ :::xml
<fo:layout-master-set>
<fo:simple-page-master master-name="simple" pcl:output-bin="2">
...
@@ -260,6 +269,7 @@ Note: the output bin number is a positiv
The duplex-mode extension attribute on fo:simple-page-master allows to select the duplex mode to be used for a particular simple-page-master. Example:
+ :::xml
<fo:layout-master-set>
<fo:simple-page-master master-name="simple" pcl:duplex-mode="0">
...
@@ -285,11 +295,11 @@ FOP creates exactly one Document per Pri
### References <a id="afp-references"></a>
-- [AFP (Advanced Function Presentation)](http://en.wikipedia.org/wiki/Advanced_Function_Presentation)
+- [AFP (Advanced Function Presentation)](http://en.wikipedia.org/wiki/Advanced_Function_Presentation)
-- [AFP Resources on the FOP WIKI](http://wiki.apache.org/xmlgraphics-fop/AFPResources)
+- [AFP Resources on the FOP WIKI](http://wiki.apache.org/xmlgraphics-fop/AFPResources)
-- [Technical notes on AFP output in FOP](http://wiki.apache.org/xmlgraphics-fop/AFPOutput)
+- [Technical notes on AFP output in FOP](http://wiki.apache.org/xmlgraphics-fop/AFPOutput)
### Limitations <a id="afp-limitations"></a>
@@ -310,6 +320,7 @@ There are still a big number of older (o
The AFP Renderer requires special configuration particularly related to fonts. AFP Render configuration is done through the normal FOP configuration file. The MIME type for the AFP Renderer is application/x-afp which means the AFP Renderer section in the FOP configuration file looks like:
+ :::xml
<renderer mime="application/x-afp">
<!-- AFP Renderer -->
...
@@ -328,8 +339,9 @@ There are 4 font configuration variants
A typical raster font configuration looks like:
+ :::xml
<!-- This is an example of mapping actual IBM raster fonts / code pages to a FOP font -->
- <font>
+ <font>
<!-- The afp-font element defines the IBM code page, the matching Java encoding and the
base URI for the font -->
<afp-font type="raster" codepage="T1V10500" encoding="Cp500" base-uri="fonts/ibm/">
@@ -357,6 +369,7 @@ A typical raster font configuration look
An outline font configuration is simpler as the individual font size entries are not required. However, the characterset definition is now required within the afp-font element.
+ :::xml
<font>
<afp-font type="outline" codepage="T1V10500" encoding="Cp500" characterset="CZH200 "
base-uri="file:/fonts/ibm" />
@@ -369,8 +382,9 @@ If "base-uri" is missing or a relative U
Previously, the location of the font files was given by the "path" attribute. This is still supported for the time being, but you should move to using the more flexible "base-uri" attribute so you can profit from the power of URI resolvers.
A CID-keyed font (Type 0, double-byte outline font) configuration is much the same as an outline font. However, the characterset definition is now required within the afp-font element.
+ :::xml
<font>
- <afp-font type="CIDKeyed" characterset="CZJHMNU"
+ <afp-font type="CIDKeyed" characterset="CZJHMNU"
codepage="T1120000" encoding="UnicodeBigUnmarked"
base-uri="file:/fonts/ibm" />
<font-triplet name="J-Heisei Mincho" style="normal" weight="normal" />
@@ -380,6 +394,7 @@ Note that the value of the encoding attr
Experimentation has shown that the font metrics for the FOP built-in Base14 fonts are actually very similar to some of the IBM outline and raster fonts. In cases were the IBM font files are not available the base-uri attribute in the afp-font element can be replaced by a base14-font attribute giving the name of the matching Base14 font. In this case the AFP Renderer will take the font metrics from the built-in font.
+ :::xml
<!-- The following are examples of defining outline fonts based on FOP built-in
font metrics for the Adobe Base14 fonts -->
<!-- sans-serif fonts based on Helvetica -->
@@ -411,7 +426,7 @@ Experimentation has shown that the font
<font-triplet name="Helvetica" style="italic" weight="bold"/>
<font-triplet name="any" style="italic" weight="bold"/>
</font>
-
+
<!-- serif fonts based on Times Roman -->
<font>
<afp-font type="outline" codepage="T1V10500" encoding="Cp500" characterset="CZN200 "
@@ -453,49 +468,60 @@ By default, all manually configured font
For double byte EBCDIC encoded character sets, there is an optional tag that must be set to prevent characters from being miscoded. This defaults to "false" if not specified.
+ :::xml
<afp-font type="CIDKeyed" codepage="T10835 " encoding="Cp937" characterset="CZTKAI" ebcdic-dbcs="true"/>
-
+
#### Output Resolution<a id="afp-renderer-resolution-config"></a>
By default the AFP Renderer creates output with a resolution of 240 dpi. This can be overridden by the <renderer-resolution/> configuration element. Example:
+ :::xml
<renderer-resolution>240</renderer-resolution>
#### Images<a id="afp-image-config"></a>
By default the AFP Renderer converts all images to 8 bit grey level. This can be overridden by the <images/> configuration element. Example:
+ :::xml
<images mode="color" />
This will put images as RGB images into the AFP output stream. The default setting is:
+ :::xml
<images mode="b+w" bits-per-pixel="8" native="true"/>
Only the values "color" and "b+w" are allowed for the mode attribute.
The bits-per-pixel attribute is ignored if mode is "color". For "b+w" mode is must be 1, 4, or 8.
+ :::xml
<images native="true"/>
When the native attribute is specified and set to "true", all image resources will be natively injected into the datastream using an object container rather than being converted into an IOCA FS45 image. Support for native image formats (e.g. JPEG, TIFF, GIF) is not always available on printer implementations so by default this configuration option is set to "false".
Setting `cmyk="true"` on the `images` element will enable CMYK colors. This will only have an effect if the color mode is set to "color". Example:
+ :::xml
<images mode="color" cmyk="true"/>
+
When the color mode is set to 1 bit (bi-level), the "dithering-quality" attribute can be used to select the level of quality to use when converting images to bi-level images. Valid values for this attribute are floating point numbers from 0.0 (fastest) to 1.0 (best), or special values: "minimum" (=0.0), "maximum" (1.0), "medium" (0.5, the default). For the higher settings to work as expected, JAI needs to be present in the classpath. If JAI is present, 0.0 results in a minimal darkness-level switching between white and black. 0.5 does bayer-based dithering and 1.0 will use error-diffusion dithering. The higher the value, the higher the quality and the slower the processing of the images.
+ :::xml
<images mode="b+w" bits-per-pixel="1" dithering-quality="maximum"/>
When the boolean attribute pseg (default false) is set to true, non-inline FS11 and FS45 IOCA images are wrapped in page segment. This option is provided to support printers/print servers that require this MO:DCA structure.
+ :::xml
<images mode="b+w" bits-per-pixel="8" pseg="true"/>
Setting the boolean attribute fs45 to true (default false) will force all images to FS45.
+ :::xml
<images mode="b+w" bits-per-pixel="8" fs45="true"/>
By default, JPEG images are rasterized to a bitmap and the bitmap is included in the AFP doc. However it is possible to encode in a lossless way to maintain maximum quality. But due to lack of support for compression schemes like LZW (patent concerns), bitmap data is currently not compressed resulting in large AFP files. Using the "allow-embedding" attribute on jpeg child element allows the user to pass the JPEG as is in the document. The default is set to "false" since there are compatibility concerns as some AFP printers don't support JPEG decoding. Using the "bitmap-encoding-quality" attribute it is possible to enable lossy compression (JPEG baseline DCT). The default is "1.0" which means lossless encoding. Setting a value lower than 1.0, JPEG compression is enabled and the setting is used as the quality setting when encoding bitmap data. Note that this setting does not always have an effect. Bi-level (1 bit) bitmaps are not compressed using JPEG. Example:
+ :::xml
<images mode="color" cmyk="true">
<jpeg allow-embedding="false" bitmap-encoding-quality="0.8"/>
</images>
@@ -508,10 +534,12 @@ Not all AFP implementations support GOCA
GOCA is enabled by default. You can disable GOCA entirely in which case the AFP support falls back to generating bitmaps for vector graphics. Example:
+ :::xml
<goca enabled="false"/>
Some AFP implementations have trouble rendering text in GOCA. You can instruct the AFP support to render text as shapes (i.e. use vector graphics to paint text). Example:
+ :::xml
<goca enabled="true" text="shapes"/>
If you disable GOCA or let text render as shapes, the size of the generated AFP usually increases considerably.
@@ -520,12 +548,14 @@ If you disable GOCA or let text render a
By default, filled rectangles are painted using their given color using a PTOCA I-axis rule (DIR). But not all environments handle these colors correctly. That's why a setting is supported that paints the rectangles using an ordered dither pattern (bi-level) with an inline IOCA FS10 image that is used together with the "replicate and trim" mapping. The optional "shading" element can be used to control the shading mode. Its default value is "color". To enable the dithered mode, use "dithered". Example:
+ :::xml
<shading>dithered</shading>
#### Resource Group File<a id="afp-resource-group-file"></a>
By default the AFP Renderer will place all data resource objects such as images within the document of the main output datastream. An external resource group file where document resources may be specified with the <resource-group-file/> configuration element. Example:
+ :::xml
<resource-group-file>external_resources.afp</resource-group-file>
Be careful when using this option not to overwrite existing resource files from previous rendering runs.
@@ -535,6 +565,7 @@ By default, bitmap image objects (or pag
It is possible to override these defaults, either per image (see the [afp:resource-level](#afp-foreign-attributes-resource) extension attribute below) or by specifying different defaults in the configuration:
+ :::xml
<default-resource-levels goca="print-file" bitmap="inline"/>
"goca" refers to GOCA graphics and "bitmap" refers to IOCA images. The possible values for the attributes are "inline" and "print-file". In the future, additional possibilities may be added.
@@ -543,6 +574,7 @@ It is possible to override these default
The AFP Renderer supports some AFP specific extensions which can be embedded into the input fo document. To use the extensions the appropriate namespace must be declared in the fo:root element like this:
+ :::xml
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
xmlns:afp="http://xmlgraphics.apache.org/fop/extensions/afp">
@@ -550,6 +582,7 @@ The AFP Renderer supports some AFP speci
The include-page-overlay extension element allows to define on a per simple-page-master basis a page overlay resource. Example:
+ :::xml
<fo:layout-master-set>
<fo:simple-page-master master-name="simple">
<afp:include-page-overlay name="O1SAMP1 " x="20mm" y="30mm" />
@@ -563,6 +596,7 @@ The mandatory name attribute must refer
The include-page-segment extension element allows to define resource substitution for fo:external-graphics elements. Example:
+ :::xml
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
xmlns:afp="http://xmlgraphics.apache.org/fop/extensions/afp">
<fo:layout-master-set>
@@ -582,6 +616,7 @@ The include-page-segment extension eleme
The tag-logical-element extension element allows to injects TLEs into the AFP output stream. Example:
+ :::xml
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
xmlns:afp="http://xmlgraphics.apache.org/fop/extensions/afp">
<fo:layout-master-set>
@@ -602,6 +637,7 @@ The tag-logical-element extension elemen
The no-operation extension provides the ability to carry up to 32K of comments or any other type of unarchitected data into the AFP output stream. Example:
+ :::xml
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
xmlns:afp="http://xmlgraphics.apache.org/fop/extensions/afp">
<fo:layout-master-set>
@@ -616,6 +652,7 @@ The no-operation extension element can a
The invoke-medium-map extension allows to generate IMM fields (Invoke Medium Map) in the generated AFP output. Example:
+ :::xml
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
xmlns:afp="http://xmlgraphics.apache.org/fop/extensions/afp">
[..]
@@ -630,6 +667,7 @@ The invoke-medium-map element is allowed
Apache FOP supports embedding an external form map resource in the generated AFP output. This is done using the `afp:include-form-map` extension. An example:
+ :::xml
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
xmlns:afp="http://xmlgraphics.apache.org/fop/extensions/afp">
[..]
@@ -645,6 +683,7 @@ Apache FOP doesn't support a way to defi
The resource foreign attributes provides the ability to name and control where data object resources (e.g. images/scalable vector graphics) will reside in the AFP output. The afp foreign attributes are only used in conjuntion with <fo:external-graphic/> and <instream-foreign-object/>. Example:
+ :::xml
<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
xmlns:afp="http://xmlgraphics.apache.org/fop/extensions/afp">
...
@@ -730,6 +769,7 @@ The quality of the bitmap depends on the
The TIFF and PNG renderer configuration currently allows the following settings:
+ :::xml
<renderer mime="image/png">
<color-mode>rgba</color-mode>
<transparent-page-background>true</transparent-page-background>
@@ -764,6 +804,7 @@ The default value for the `"rendering"`
In addition to the above values the TIFF renderer configuration allows some additional settings:
+ :::xml
<renderer mime="image/tiff">
<transparent-page-background>true</transparent-page-background>
<compression>CCITT T.6</compression>
@@ -777,13 +818,13 @@ The default value for the "compression"
- `PackBits` (RLE, run-length encoding)
-- `JPEG`
+- `JPEG`
-- `Deflate`
+- `Deflate`
-- `LZW`
+- `LZW`
-- `ZLib`
+- `ZLib`
- `CCITT T.4` (Fax Group 3)
@@ -795,6 +836,7 @@ If you want to use CCITT compression, pl
The IF-based bitmap output implementations support a rendering option with the key "target-bitmap-size" (value: java.awt.Dimension) that allows to force the pages to be proportionally fit into a bitmap of a given size. This can be used to produce thumbnails or little preview images of the individual pages. An example:
+ :::java
userAgent.getRenderingOptions().put(
"target-bitmap-size", new Dimension(320, 200));
Modified: xmlgraphics/site/trunk/content/fop/trunk/pdfencryption.mdtext
URL: http://svn.apache.org/viewvc/xmlgraphics/site/trunk/content/fop/trunk/pdfencryption.mdtext?rev=1417008&r1=1417007&r2=1417008&view=diff
==============================================================================
--- xmlgraphics/site/trunk/content/fop/trunk/pdfencryption.mdtext (original)
+++ xmlgraphics/site/trunk/content/fop/trunk/pdfencryption.mdtext Tue Dec 4 15:58:21 2012
@@ -53,15 +53,17 @@ When FOP is embedded in another Java app
Encryption is enabled as soon as one of these options is set.
An example to enable PDF encryption in Java code:
+ :::java
import org.apache.fop.pdf.PDFEncryptionParams;
-
+
[..]
-
+
FOUserAgent userAgent = fopFactory.newFOUserAgent();
useragent.getRendererOptions().put("encryption-params", new PDFEncryptionParams(
null, "password", false, false, true, true));
Fop fop = fopFactory.newFop(MimeConstants.MIME_PDF, userAgent);
[..]
+
The parameters for the constructor of PDFEncryptionParams are:
Modified: xmlgraphics/site/trunk/content/fop/trunk/running.mdtext
URL: http://svn.apache.org/viewvc/xmlgraphics/site/trunk/content/fop/trunk/running.mdtext?rev=1417008&r1=1417007&r2=1417008&view=diff
==============================================================================
--- xmlgraphics/site/trunk/content/fop/trunk/running.mdtext (original)
+++ xmlgraphics/site/trunk/content/fop/trunk/running.mdtext Tue Dec 4 15:58:21 2012
@@ -68,7 +68,7 @@ The usual and recommended practice for s
-dpi xxx target resolution in dots per inch (dpi) where xxx is a number
-s for area tree XML, down to block areas only
-v run in verbose mode (currently simply print FOP version and continue)
-
+
-o [password] PDF file will be encrypted with option owner password
-u [password] PDF file will be encrypted with option user password
-noprint PDF file will be encrypted without printing permission
@@ -82,13 +82,13 @@ The usual and recommended practice for s
-a enables accessibility features (Tagged PDF etc., default off)
-pdfprofile prof PDF file will be generated with the specified profile
(Examples for prof: PDF/A-1b or PDF/X-3:2003)
-
+
-conserve enable memory-conservation policy (trades memory-consumption for disk I/O)
(Note: currently only influences whether the area tree is serialized.)
-
+
-cache specifies a file/directory path location
-flush flushes the current font cache file
-
+
[INPUT]
infile xsl:fo input file (the same as the next)
(use '-' for infile to pipe input from stdin)
@@ -98,10 +98,10 @@ The usual and recommended practice for s
-ifin infile intermediate format input file
-imagein infile image input file (piping through stdin not supported)
-xsl stylesheet xslt stylesheet
-
+
-param name value <value> to use for parameter <name> in xslt stylesheet
(repeat '-param name value' for each parameter)
-
+
-catalog use catalog resolver for input XML and XSLT files
[OUTPUT]
outfile input will be rendered as PDF into outfile
@@ -130,12 +130,12 @@ The usual and recommended practice for s
(Tip: "-out list" prints the list of supported MIME types)
-svg outfile input will be rendered as an SVG slides file (outfile req'd)
Experimental feature - requires additional fop-sandbox.jar.
-
+
-foout outfile input will only be XSL transformed. The intermediate
XSL-FO file is saved and no rendering is performed.
(Only available if you use -xml and -xsl parameters)
-
-
+
+
[Examples]
fop foo.fo foo.pdf
fop -fo foo.fo -pdf foo.pdf (does the same as the previous line)
@@ -146,6 +146,7 @@ The usual and recommended practice for s
fop foo.fo -rtf foo.rtf
fop foo.fo -print
fop foo.fo -awt
+
PDF encryption is only available if FOP was compiled with encryption support **and** if compatible encryption support is available at run time. Currently, only the JCE is supported. Check the [Details](pdfencryption.html) .
### Writing your own script <a id="your-own-script"></a>
@@ -179,7 +180,7 @@ In the case of using -xml and -xsl input
When asking for help on the FOP mailing lists, *never* attach XML and XSL to illustrate the issue. Always run the XSLT step (-foout) and send the resulting XSL-FO file instead. Of course, be sure that the XSL-FO file is correct before sending it.
The -foout option works the same way as if you would call the [Xalan command-line](http://xml.apache.org/xalan-j/commandline.html) :
- `java org.apache.xalan.xslt.Process -IN xmlfile -XSL file -OUT outfile`
+ `java org.apache.xalan.xslt.Process -IN xmlfile -XSL file -OUT outfile`
Note that there are some subtle differences between the FOP and Xalan command-lines.
Modified: xmlgraphics/site/trunk/content/fop/trunk/servlets.mdtext
URL: http://svn.apache.org/viewvc/xmlgraphics/site/trunk/content/fop/trunk/servlets.mdtext?rev=1417008&r1=1417007&r2=1417008&view=diff
==============================================================================
--- xmlgraphics/site/trunk/content/fop/trunk/servlets.mdtext (original)
+++ xmlgraphics/site/trunk/content/fop/trunk/servlets.mdtext Tue Dec 4 15:58:21 2012
@@ -28,9 +28,10 @@ This section assumes you are familiar wi
Here is a minimal code snippet to demonstrate the basics:
+ :::java
private FopFactory fopFactory = FopFactory.newInstance();
private TransformerFactory tFactory = TransformerFactory.newInstance();
-
+
public void doGet(HttpServletRequest request,
HttpServletResponse response) throws ServletException {
try {
@@ -51,9 +52,10 @@ There are numerous problems with the cod
A common requirement is to transform an XML source to XSL-FO using an XSL transformation. It is recommended to use JAXP for this task. The following snippet shows the basic code:
+ :::java
private FopFactory fopFactory = FopFactory.newInstance();
private TransformerFactory tFactory = TransformerFactory.newInstance();
-
+
public void init() throws ServletException {
//Optionally customize the FopFactory and TransformerFactory here
}
@@ -82,7 +84,7 @@ A common requirement is to transform an
//Prepare response
response.setContentType("application/pdf");
response.setContentLength(out.size());
-
+
//Send content to Browser
response.getOutputStream().write(out.toByteArray());
response.getOutputStream().flush();
@@ -102,7 +104,7 @@ You can easily set up your own FOUserAge
There are several options to consider:
-- Instead of java.io.ByteArrayOutputStream consider using the ByteArrayOutputStream implementation from the [Jakarta Commons IO project](http://commons.apache.org/io/) which allocates less memory. The full class name is: `org.apache.commons.io.output.ByteArrayOutputStream`
+- Instead of java.io.ByteArrayOutputStream consider using the ByteArrayOutputStream implementation from the [Jakarta Commons IO project](http://commons.apache.org/io/) which allocates less memory. The full class name is: `org.apache.commons.io.output.ByteArrayOutputStream`
- In certain cases it can help to write the generated PDF to a temporary file so you can quickly reuse the file. This is especially useful, if Internet Explorer calls the servlet multiple times with the same request or if you often generate equal PDFs.
@@ -114,8 +116,9 @@ Often, you will want to use resources (s
Here's how to set it up in your servlet. Instantiate a new instance in the servlet's init() method:
+ :::java
/** URIResolver for use by this servlet */
- protected URIResolver uriResolver;
+ protected URIResolver uriResolver;
public void init() throws ServletException {
this.uriResolver = new ServletContextURIResolver(getServletContext());
@@ -135,23 +138,25 @@ Further down, you can use the URIResolve
Here are some example snippets:
+ :::java
//Setting up the JAXP TransformerFactory
this.transFactory = TransformerFactory.newInstance();
this.transFactory.setURIResolver(this.uriResolver);
-
+
[..]
-
+
//Setting up the FOP factory
this.fopFactory = FopFactory.newInstance();
this.fopFactory.setURIResolver(this.uriResolver);
-
+
[..]
-
+
//The stylesheet for the JAXP Transfomer
Source xsltSrc = this.uriResolver.resolve(
"servlet-context:/xslt/mystylesheet.xsl", null);
Transformer transformer = this.transFactory.newTransformer(xsltSrc);
transformer.setURIResolver(this.uriResolver);
+
## Notes on Microsoft Internet Explorer <a id="ie"></a>
Some versions of Internet Explorer will not automatically show the PDF or call the servlet multiple times. These are well-known limitations of Internet Explorer and are not a problem of the servlet. However, Internet Explorer can still be used to download the PDF so that it can be viewed later. Here are some suggestions in this context:
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: commits-help@xmlgraphics.apache.org