123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888 |
- <?xml version="1.0" standalone="no"?>
- <!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to You under the Apache License, Version 2.0
- (the "License"); you may not use this file except in compliance with
- the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
- -->
- <!-- $Id$ -->
- <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
- <!-- Output Formats: Renderers -->
- <document>
- <header>
- <title>Apache FOP Output Formats</title>
- <version>$Revision$</version>
- <authors>
- <person name="Keiron Liddle" email="keiron@aftexsw.com"/>
- <person name="Art Welch" email=""/>
- </authors>
- </header>
-
- <body>
- <p>
- FOP supports multiple output formats by using a different renderer for each format.
- The renderers do not all have the same set of capabilities, sometimes because of
- the output format itself, sometimes because some renderers get more development
- attention than others.
- </p>
- <section id="general">
- <title>General Information</title>
- <section id="general-fonts">
- <title>Fonts</title>
- <p>
- Most FOP renderers use a FOP-specific system for font registration.
- However, the Java2D/AWT and print renderers use the Java AWT package, which gets its
- font information from the operating system registration.
- This can result in several differences, including actually using different fonts,
- and having different font metrics for the same font.
- The net effect is that the layout of a given FO document can be quite different between
- renderers that do not use the same font information.
- </p>
- <p>
- Theoretically, there's some potential to make the output of the PDF/PS renderers match
- the output of the Java2D-based renderers. If FOP used the font metrics from its own
- font subsystem but still used Java2D for text painting in the Java2D-based renderers,
- this could probably be achieved. However, this approach hasn't been implemented, yet.
- </p>
- <p>
- With a work-around, it is possible to match the PDF/PS output in a Java2D-based
- renderer pretty closely. The clue is to use the
- <a href="intermediate.html">intermediate format</a>. The trick is to layout the
- document using FOP's own font subsystem but then render the document using Java2D.
- Here are the necessary steps (using the command-line):
- </p>
- <ol>
- <li>
- Produce an IF file: <code>fop -fo myfile.fo -at application/pdf myfile.at.xml</code><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.
- </li>
- <li>Render to a PDF file: <code>fop -atin myfile.at.xml -pdf myfile.pdf</code></li>
- <li>Render to a Java2D-based renderer:
- <ul>
- <li><code>fop -atin myfile.at.xml -print</code></li>
- <li><code>fop -atin myfile.at.xml -awt</code></li>
- <li><code>fop -atin myfile.at.xml -tiff myfile.tiff</code></li>
- </ul>
- </li>
- </ol>
- </section>
- <section id="general-direct-output">
- <title>Output to a Printer or Other Device</title>
- <p>
- The most obvious way to print your document is to use the FOP
- <a href="#print">print renderer</a>, which uses the Java2D API (AWT).
- However, you can also send output from the Postscript renderer directly to a Postscript
- device, or output from the PCL renderer directly to a PCL device.
- </p>
- <p>
- Here are Windows command-line examples for Postscript and PCL:
- </p>
- <source><![CDATA[fop ... -ps \\computername\printer]]></source>
- <source><![CDATA[fop ... -pcl \\computername\printer]]></source>
- <p>
- Here is some Java code to accomplish the task in UNIX:
- </p>
- <source><![CDATA[proc = Runtime.getRuntime().exec("lp -d" + print_queue + " -o -dp -");
- out = proc.getOutputStream();]]></source>
- <p>
- Set the output MIME type to "application/x-pcl" (MimeConstants.MIME_PCL) and
- it happily sends the PCL to the UNIX printer queue.
- </p>
- </section>
- </section>
- <section id="pdf">
- <title>PDF</title>
- <p>
- PDF is the best supported output format. It is also the most accurate
- with text and layout. This creates a PDF document that is streamed out
- as each page is rendered. This means that the internal page index
- information is stored near the end of the document.
- The PDF version supported is 1.4. PDF versions are forwards/backwards
- compatible.
- </p>
- <p>
- Note that FOP does not currently support "tagged PDF" or PDF/A-1a.
- Support for <a href="pdfa.html">PDF/A-1b</a> and <a
- href="pdfx.html">PDF/X</a> has recently been added, however.
- </p>
- <section id="pdf-fonts">
- <title>Fonts</title>
- <p>
- PDF has a set of fonts that are always available to all PDF viewers;
- to quote from the PDF Specification:
-
- <em>"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."</em>
- </p>
- </section>
- <section id="pdf-postprocess">
- <title>Post-processing</title>
- <p>
- FOP does not currently support several desirable PDF features: watermarks and signatures.
- One workaround is to use Adobe Acrobat (the full version, not the Reader) to process
- the file manually or with scripting that it supports.
- </p>
- <p>
- Another popular post-processing tool is <a href="http://www.lowagie.com/iText">iText</a>,
- which has tools for adding security features, document properties, watermarks, and many
- other features to PDF files.
- </p>
- <warning>
- Caveat: iText may swallow PDF bookmarks. But
- <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=37589">Jens Stavnstrup tells us</a>
- that this doesn't happen if you use iText's PDFStamper.
- </warning>
- <p>
- Here is some sample code that uses iText to encrypt a FOP-generated PDF. (Note that FOP now
- supports <a href="pdfencryption.html">PDF encryption</a>. However the principles for using
- iText for other PDF features are similar.)
- </p>
- <source><![CDATA[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);
- }
- document.close();
- } catch( Exception e) {
- e.printStackTrace();
- }
- }]]></source>
- <p>
- Check the iText tutorial and documentation for setting access flags, password,
- encryption strength and other parameters.
- </p>
- </section>
- <section id="pdf-watermark">
- <title>Watermarks</title>
- <p>
- In addition to the <a href="#pdf-postprocess">PDF Post-processing</a> options, consider the following workarounds:
- </p>
- <ul>
- <li>
- Use a background image for the body region.
- </li>
- <li>
- (submitted by Trevor Campbell) Place an image in a
- region that overlaps the flowing text. For example, make
- region-before large enough to contain your image. Then include a
- block (if necessary, use an absolutely positioned block-container)
- containing the watermark image in the static-content for the
- region-before. Note that the image will be drawn on top of the
- normal content.
- </li>
- </ul>
- </section>
- </section>
- <section id="ps">
- <title>PostScript</title>
- <p>
- The PostScript renderer has been brought up to a similar quality as the
- PDF renderer, but may still be missing certain features. It provides good
- support for most text and layout.
- Images and SVG are not fully supported, yet. Currently, the PostScript
- renderer generates PostScript Level 3 with most DSC comments. Actually,
- the only Level 3 features used are the FlateDecode and DCTDecode
- filter (the latter is used for 1:1 embedding of JPEG images), everything
- else is Level 2.
- </p>
- <section id="ps-configuration">
- <title>Configuration</title>
- <p>
- The PostScript renderer configuration currently allows the following settings:
- </p>
- <source><![CDATA[<renderer mime="application/postscript">
- <auto-rotate-landscape>false</auto-rotate-landscape>
- <language-level>3</language-level>
- <optimize-resources>false</optimize-resources>
- <safe-set-page-device>false</safe-set-page-device>
- <dsc-compliant>true</dsc-compliant>
- </renderer>]]></source>
- <p>
- The default value for the "auto-rotate-landscape" setting is "false". Setting it
- to "true" will automatically rotate landscape pages and will mark them as landscape.
- </p>
- <p>
- The default value for the "language-level" setting is "3". This setting specifies
- the PostScript language level which should be used by FOP. Set this to "2"
- only if you don't have a Level 3 capable interpreter.
- </p>
- <p>
- The default value for the "optimize-resources" setting is "false". Setting it
- to "true" will produce the PostScript file in two steps. A temporary file will be
- written first which will then be processed to add only the fonts which were really
- used and images are added to the stream only once as PostScript forms. This will
- reduce file size but can potentially increase the memory needed in the interpreter
- to process.
- </p>
- <p>
- The default value for the "safe-set-page-device" setting is "false". Setting it
- to "true" will cause the renderer to invoke a postscript macro which guards against
- the possibility of invalid/unsupported postscript key/values being issued to the
- implementing postscript page device.
- </p>
- <p>
- The default value for the "dsc-compliant" setting is "true". Setting it
- to "false" will break DSC compliance by minimizing the number of setpagedevice
- calls in the postscript document output. This feature may be useful when unwanted
- blank pages are experienced in your postscript output. This problem is caused by
- the particular postscript implementation issuing unwanted postscript subsystem
- initgraphics/erasepage calls on each setpagedevice call.
- </p>
- </section>
- <section id="ps-limitations">
- <title>Limitations</title>
- <ul>
- <li>Images and SVG may not be displayed correctly. SVG support is far from being complete. No image transparency is available.</li>
- <li>Only Type 1 fonts are supported.</li>
- <li>Multibyte characters are not supported.</li>
- <li>PPD support is still missing.</li>
- </ul>
- </section>
- </section>
- <section id="pcl">
- <title>PCL</title>
- <p>
- This format is for the Hewlett-Packard PCL printers and other printers
- supporting PCL. It should produce output as close to identical as possible
- to the printed output of the PDFRenderer within the limitations of the
- renderer, and output device.
- </p>
- <p>
- The output created by the PCLRenderer is generic PCL 5, HP GL/2 and PJL.
- This should allow any device fully supporting PCL 5 to be able to
- print the output generated by the PCLRenderer. PJL is used to control the
- print job and switch to the PCL language. PCL 5 is used for text, raster
- graphics and rectangular fill graphics. HP GL/2 is used for more complex
- painting operations. Certain painting operations are done off-screen and
- rendered to PCL as bitmaps because of limitations in PCL 5.
- </p>
- <section id="pcl-references">
- <title>References</title>
- <ul>
- <li><a href="http://en.wikipedia.org/wiki/Printer_Control_Language">WikiPedia entry on PCL</a></li>
- <li><a href="http://h20000.www2.hp.com/bizsupport/TechSupport/Document.jsp?objectID=bpl04568">Technical reference documents on PCL from Hewlett-Packard</a></li>
- </ul>
- </section>
- <section id="pcl-limitations">
- <title>Limitations</title>
- <ul>
- <li>
- Text or graphics outside the left or top of the printable area are not
- rendered properly. This is a limitation of PCL, not FOP. In general,
- things that should print to the left of the printable area are shifted
- to the right so that they start at the left edge of the printable area.
- </li>
- <li>
- The Helvetica and Times fonts are not well supported among PCL printers
- so Helvetica is mapped to Arial and Times is mapped to Times New. This
- is done in the PCLRenderer, no changes are required in the FO's. The
- metrics and appearance for Helvetica/Arial and Times/Times New are
- nearly identical, so this has not been a problem so far.
- </li>
- <li>For the non-symbol fonts, the ISO 8859-1 symbol set is used (PCL set "0N").</li>
- <li>
- All fonts available to the Java2D subsystem are usable. The texts are
- painted as bitmap much like the Windows PCL drivers do.
- </li>
- <li>Multibyte characters are not supported.</li>
- <li>
- At the moment, only monochrome output is supported. PCL5c color extensions
- will only be implemented on demand. Color and grayscale images are converted
- to monochrome bitmaps (1-bit). Dithering only occurs if the JAI image library
- is available.
- </li>
- <li>
- Images are scaled up to the next resolution level supported by PCL (75,
- 100, 150, 200, 300, 600 dpi). For color and grayscale images an even
- higher PCL resolution is selected to give the dithering algorithm a chance
- to improve the bitmap quality.
- </li>
- <li>
- Currently, there's no support for clipping and image transparency, largely
- because PCL 5 has certain limitations.
- </li>
- </ul>
- </section>
- <section id="pcl-configuration">
- <title>Configuration</title>
- <p>
- The PCL renderer configuration currently allows the following settings:
- </p>
- <source><![CDATA[<renderer mime="application/vnd.hp-PCL">
- <rendering>quality</rendering>
- <text-rendering>bitmap</text-rendering>
- <disable-pjl>false</disable-pjl>
- </renderer>]]></source>
- <p>
- The default value for the "rendering" setting is "speed" which causes borders
- to be painted as plain rectangles. In this mode, no special borders (dotted,
- dashed etc.) are available. If you want support for all border modes, set the
- value to "quality" as indicated above. This will cause the borders to be painted
- as bitmaps.
- </p>
- <p>
- The default value for the "text-rendering" setting is "auto" which paints the
- base fonts using PCL fonts. Non-base fonts are painted as bitmaps through Java2D.
- If the mix of painting methods results in unwelcome output, you can set this
- to "bitmap" which causes all text to be rendered as bitmaps.
- </p>
- <p>
- The default value for the "disable-pjl" setting is "false". This means that
- the PCL renderer usually generates PJL commands before and after the document
- in order to switch a printer into PCL language. PJL commands can be disabled
- if you set this value to "true".
- </p>
- <p>
- You can control the output resolution for the PCL using the "target resolution"
- setting on the FOUserAgent. The actual value will be rounded up to the next
- supported PCL resolution. Currently, only 300 and 600 dpi are supported which
- should be enough for most use cases. Note that this setting directly affects
- the size of the output file and the print quality.
- </p>
- </section>
- <section id="pcl-extensions">
- <title>Extensions</title>
- <p>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:</p>
- <source><![CDATA[
- <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
- xmlns:pcl="http://xmlgraphics.apache.org/fop/extensions/pcl">
- ]]></source>
- <section id="pcl-page-source">
- <title>Page Source (Tray selection)</title>
- <p>
- 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:
- </p>
- <source><![CDATA[
- <fo:layout-master-set>
- <fo:simple-page-master master-name="simple" pcl:paper-source="2">
- ...
- </fo:simple-page-master>
- </fo:layout-master-set>
- ]]></source>
- <p>
- Note: the tray number is a positive integer and the value depends on
- the target printer. Not all PCL printers support the same paper trays.
- Usually,
- "1" is the default tray,
- "2" is the manual paper feed,
- "3" is the manual envelope feed,
- "4" is the "lower" tray and
- "7" is "auto-select".
- Consult the technical reference for your printer for all available values.
- </p>
- </section>
- </section>
- </section>
- <section id="afp">
- <title>AFP</title>
- <warning>The AFP Renderer is a new addition (27-Apr-2006) to the sandbox and as such not yet fully tested or feature complete.</warning>
- <p>
- The FOP AFP Renderer deals with creating documents conforming to the IBM AFP document architecture
- also refered to as MO:DCA (Mixed Object Document Content Architecture).
- </p>
- <section id="afp-references">
- <title>References</title>
- <ul>
- <li><a href="http://en.wikipedia.org/wiki/Advanced_Function_Presentation">AFP (Advanced Function Presentation)</a></li>
- <li><a href="http://wiki.apache.org/xmlgraphics-fop/AFPResources">AFP Resources on the FOP WIKI</a></li>
- </ul>
- </section>
- <section id="afp-limitations">
- <title>Limitations</title>
- <p>This list is most likely badly incomplete.</p>
- <ul>
- <li>
- Clipping of text and graphics is not supported.
- </li>
- <li>
- Only IBM outline and raster fonts and to a limited extend the original fonts built into FOP are supported.
- Support for TrueType fonts may be added later.
- </li>
- </ul>
- </section>
- <section id="afp-configuration">
- <title>Configuration</title>
- <section id="afp-font-config">
- <title>Fonts</title>
- <p>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:</p>
- <source><![CDATA[<renderer mime="application/x-afp">
- <!-- AFP Renderer -->
- ...
- </renderer>]]></source>
- <p>There are 3 font configuration variants supported:</p>
- <ol>
- <li>IBM Raster fonts</li>
- <li>IBM Outline fonts</li>
- <li>FOP built-in Base14 fonts</li>
- </ol>
- <p>A typical raster font configuration looks like:</p>
- <source><![CDATA[ <!-- This is an example of mapping actual IBM raster fonts / code pages to a FOP font -->
- <font>
- <!-- The afp-font element defines the IBM code page, the matching Java encoding and the
- path to the font -->
- <afp-font type="raster" codepage="T1V10500" encoding="Cp500" path="fonts/ibm">
- <!-- For a raster font a separate element for each font size is required providing
- the font size and the corresponding IBM Character set name -->
- <afp-raster-font size="7" characterset="C0N20070"/>
- <afp-raster-font size="8" characterset="C0N20080"/>
- <afp-raster-font size="10" characterset="C0N20000"/>
- <afp-raster-font size="11" characterset="C0N200A0"/>
- <afp-raster-font size="12" characterset="C0N200B0"/>
- <afp-raster-font size="14" characterset="C0N200D0"/>
- <afp-raster-font size="16" characterset="C0N200F0"/>
- <afp-raster-font size="18" characterset="C0N200H0"/>
- <afp-raster-font size="20" characterset="C0N200J0"/>
- <afp-raster-font size="24" characterset="C0N200N0"/>
- <afp-raster-font size="30" characterset="C0N200T0"/>
- <afp-raster-font size="36" characterset="C0N200Z0"/>
- </afp-font>
- <!-- These are the usual FOP font triplets as they apply to this font -->
- <font-triplet name="serif" style="normal" weight="normal"/>
- <font-triplet name="Times" style="normal" weight="normal"/>
- <font-triplet name="Times-Roman" style="normal" weight="normal"/>
- <font-triplet name="TimesNewRoman" style="normal" weight="normal"/>
- </font>]]></source>
- <p>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.</p>
- <source><![CDATA[ <font>
- <afp-font type="outline" codepage="T1V10500" encoding="Cp500" characterset="CZH200 "
- path="fonts/ibm" />
- <font-triplet name="sans-serif" style="normal" weight="normal"/>
- <font-triplet name="Helvetica" style="normal" weight="normal"/>
- <font-triplet name="any" style="normal" weight="normal"/>
- </font>
- ]]></source>
- <p>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 path 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.</p>
- <source><![CDATA[ <!-- 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 -->
- <font>
- <afp-font type="outline" codepage="T1V10500" encoding="Cp500" characterset="CZH200 "
- base14-font="Helvetica" />
- <font-triplet name="sans-serif" style="normal" weight="normal"/>
- <font-triplet name="Helvetica" style="normal" weight="normal"/>
- <font-triplet name="any" style="normal" weight="normal"/>
- </font>
- <font>
- <afp-font type="outline" codepage="T1V10500" encoding="Cp500" characterset="CZH300 "
- base14-font="HelveticaOblique" />
- <font-triplet name="sans-serif" style="italic" weight="normal"/>
- <font-triplet name="Helvetica" style="italic" weight="normal"/>
- <font-triplet name="any" style="italic" weight="normal"/>
- </font>
- <font>
- <afp-font type="outline" codepage="T1V10500" encoding="Cp500" characterset="CZH400 "
- base14-font="HelveticaBold" />
- <font-triplet name="sans-serif" style="normal" weight="bold"/>
- <font-triplet name="Helvetica" style="normal" weight="bold"/>
- <font-triplet name="any" style="normal" weight="bold"/>
- </font>
- <font>
- <afp-font type="outline" codepage="T1V10500" encoding="Cp500" characterset="CZH500 "
- base14-font="HelveticaBoldOblique" />
- <font-triplet name="sans-serif" style="italic" weight="bold"/>
- <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 "
- base14-font="TimesRoman" />
- <font-triplet name="serif" style="normal" weight="normal"/>
- <font-triplet name="Times" style="normal" weight="normal"/>
- <font-triplet name="Times-Roman" style="normal" weight="normal"/>
- </font>
-
- <!-- The following are examples of defining raster fonts based on FOP built-in
- font metrics for the Adobe Base14 fonts -->
- <!-- monospaced fonts based on Courier -->
- <font>
- <afp-font type="raster" codepage="T1V10500" encoding="Cp500">
- <afp-raster-font size="7" characterset="C0420070" base14-font="Courier"/>
- <afp-raster-font size="8" characterset="C0420080" base14-font="Courier"/>
- <afp-raster-font size="10" characterset="C0420000" base14-font="Courier"/>
- <afp-raster-font size="12" characterset="C04200B0" base14-font="Courier"/>
- <afp-raster-font size="14" characterset="C04200D0" base14-font="Courier"/>
- <afp-raster-font size="20" characterset="C04200J0" base14-font="Courier"/>
- </afp-font>
- <font-triplet name="monospace" style="normal" weight="normal"/>
- <font-triplet name="Courier" style="normal" weight="normal"/>
- </font>
- <font>
- <afp-font type="raster" codepage="T1V10500" encoding="Cp500">
- <afp-raster-font size="7" characterset="C0440070" base14-font="CourierBold"/>
- <afp-raster-font size="8" characterset="C0440080" base14-font="CourierBold"/>
- <afp-raster-font size="10" characterset="C0440000" base14-font="CourierBold"/>
- <afp-raster-font size="12" characterset="C04400B0" base14-font="CourierBold"/>
- <afp-raster-font size="14" characterset="C04400D0" base14-font="CourierBold"/>
- <afp-raster-font size="20" characterset="C04400J0" base14-font="CourierBold"/>
- </afp-font>
- <font-triplet name="monospace" style="normal" weight="bold"/>
- <font-triplet name="Courier" style="normal" weight="bold"/>
- </font>]]></source>
- </section>
- <section id="afp-renderer-resolution-config">
- <title>Output Resolution</title>
- <p>By default the AFP Renderer creates output with a resolution of 240 dpi.
- This can be overridden by the <renderer-resolution/> configuration element. Example:</p>
- <source><![CDATA[
- <renderer-resolution>240</renderer-resolution>]]></source>
- </section>
- <section id="afp-image-config">
- <title>Images</title>
- <p>By default the AFP Renderer converts all images to 8 bit grey level.
- This can be overridden by the <images> configuration element. Example:</p>
- <source><![CDATA[
- <images mode="color" />
- ]]></source>
- <p>This will put images as RGB images into the AFP output stream. The default setting is:</p>
- <source><![CDATA[
- <images mode="b+w" bits-per-pixel="8" />
- ]]></source>
- <p>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.</p>
- </section>
- </section>
- <section id="afp-extensions">
- <title>Extensions</title>
- <p>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:</p>
- <source><![CDATA[
- <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
- xmlns:afp="http://xmlgraphics.apache.org/fop/extensions/afp">
- ]]></source>
- <section id="afp-page-overlay">
- <title>Page Overlay Extension</title>
- <p>The include-page-overlay extension element allows to define on a per simple-page-master basis a page overlay resource. Example:</p>
- <source><![CDATA[
- <fo:layout-master-set>
- <fo:simple-page-master master-name="simple">
- <afp:include-page-overlay name="O1SAMP1 " />
- ...
- </fo:simple-page-master>
- </fo:layout-master-set>
- ]]></source>
- <p>The mandatory name attribute must refer to an 8 character (space padded) resource name that
- must be known in the AFP processing environment.</p>
- </section>
- <section id="afp-page-segment">
- <title>Page Segment Extension</title>
- <p>The include-page-segment extension element allows to define resource substitution for fo:external-graphics elements.
- Example:</p>
- <source><![CDATA[
- <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
- xmlns:afp="http://xmlgraphics.apache.org/fop/extensions/afp">
- <fo:layout-master-set>
- <fo:simple-page-master master-name="simple">
- <afp:include-page-segment name="S1ISLOGO" src="../../resources/images/bgimg300dpi.jpg" />
- <fo:region-body/>
- </fo:simple-page-master>
- </fo:layout-master-set>
- ]]></source>
- <p>The include-page-segment extension element can only occur within a simple-page-master.
- Multiple include-page-segment extension elements within a simple-page-master are allowed.
- The mandatory name attribute must refer to an 8 character
- (space padded) resource name that must be known in the AFP processing environment.
- The value of the mandatory src attribute is compared against the value of the src attribute in
- fo:external-graphic elements and if it is identical (string matching is used) in the generated
- AFP the external graphic is replaced by a reference to the given resource.
- </p>
- </section>
- <section id="afp-tag-logical-element">
- <title>Tag Logical Element Extension</title>
- <p>The tag-logical-element extension element allows to injects TLEs into the AFP output stream. Example:</p>
- <source><![CDATA[
- <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
- xmlns:afp="http://xmlgraphics.apache.org/fop/extensions/afp">
- <fo:layout-master-set>
- <fo:simple-page-master master-name="simple">
- <afp:tag-logical-element name="The TLE Name" value="The TLE Value" />
- <fo:region-body/>
- </fo:simple-page-master>
- </fo:layout-master-set>
- ]]></source>
- <p>The tag-logical-element extension element can only occur within a simple-page-master.
- Multiple tag-logical-element extension elements within a simple-page-master are allowed.
- The name and value attributes are mandatory.
- </p>
- </section>
- <section id="afp-no-operation">
- <title>No Operation Extension</title>
- <p>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:</p>
- <source><![CDATA[
- <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
- xmlns:afp="http://xmlgraphics.apache.org/fop/extensions/afp">
- <fo:layout-master-set>
- <fo:simple-page-master master-name="simple">
- <afp:no-operation name="My NOP">insert up to 32k of character data here!</afp:no-operation>
- </fo:simple-page-master>
- </fo:layout-master-set>
- ]]></source>
- <p>The no-operation extension element can only occur within a simple-page-master.
- Multiple no-operation extension elements within a simple-page-master are allowed.
- The name attribute is mandatory.
- </p>
- </section>
- </section>
- </section>
- <section id="rtf">
- <title>RTF</title>
- <p>
- JFOR, an open source XSL-FO to RTF converter has been integrated into Apache FOP.
- This will create an RTF (rich text format) document that will
- attempt to contain as much information from the XSL-FO document as
- possible. It should be noted that is not possible (due to RTF's limitations) to map all
- XSL-FO features to RTF. For complex documents, the RTF output will never reach the feature
- level from PDF, for example. Thus, using RTF output is only recommended for simple documents
- such as letters.
- </p>
- <p>
- The RTF output follows Microsoft's RTF specifications
- and produces best results on Microsoft Word.
- </p>
- <note>RTF output is currently unmaintained and lacks many features compared to other output
- formats. Using other editable formats like Open Document Format, instead of producing XSL-FO
- then RTF through FOP, might give better results.</note>
- </section>
- <section id="xml">
- <title>XML (Area Tree XML)</title>
- <p>
- This is primarily for testing and verification. The XML created is simply
- a representation of the internal area tree put into XML. We use that to verify
- the functionality of FOP's layout engine.
- </p>
- <p>
- The other use case of the Area Tree XML is as FOP's "intermediate format". More information
- on that can be found on the page dedicated to the <a href="intermediate.html">Intermediate Format</a>.
- </p>
- </section>
- <section id="awt">
- <title>Java2D/AWT</title>
- <p>
- The Java2DRenderer provides the basic functionality for all
- Java2D-based output formats (AWT viewer, direct print, PNG, TIFF).
- </p>
- <p>
- The AWT viewer shows a window with the pages displayed inside a
- Java graphic. It displays one page at a time.
- The fonts used for the formatting and viewing depend on the fonts
- available to your JRE.
- </p>
- </section>
- <section id="print">
- <title>Print</title>
- <p>
- It is possible to directly print the document from the command line.
- This is done with the same code that renders to the Java2D/AWT renderer.
- </p>
- </section>
- <section id="bitmap">
- <title>Bitmap (TIFF/PNG)</title>
- <p>
- It is possible to directly create bitmap images from the individual
- pages generated by the layout engine.
- This is done with the same code that renders to the Java2D/AWT renderer.
- </p>
- <p>
- Currently, two output formats are supported: PNG and TIFF. TIFF produces
- one file with multiple pages, while PNG output produces one file per
- page. The quality of the bitmap depends on the target resolution setting
- on the FOUserAgent.
- </p>
- <section id="bitmap-configuration">
- <title>Configuration</title>
- <p>
- The TIFF and PNG renderer configuration currently allows the following settings:
- </p>
- <source><![CDATA[<renderer mime="image/png">
- <transparent-page-background>true</transparent-page-background>
- <fonts><!-- described elsewhere --></fonts>
- </renderer>]]></source>
- <p>
- The default value for the "transparent-page-background" setting is "false" which
- paints an opaque, white background for the whole image. If you set this to true,
- no such background will be painted and you will get a transparent image if
- an alpha channel is available in the output format.
- </p>
- </section>
- <section id="tiff-configuration">
- <title>TIFF-specific Configuration</title>
- <p>
- In addition to the above values the TIFF renderer configuration allows some additional
- settings:
- </p>
- <source><![CDATA[<renderer mime="image/tiff">
- <transparent-page-background>true</transparent-page-background>
- <compression>CCITT T.6</compression>
- <fonts><!-- described elsewhere --></fonts>
- </renderer>]]></source>
- <p>
- The default value for the "compression" setting is "PackBits" which
- which is a widely supported RLE compression scheme for TIFF. The set of compression
- names to be used here matches the set that the Image I/O API uses. Note that
- not all compression schemes may be available during runtime. This depends on the
- actual codecs being available. Here is a list of possible values:
- </p>
- <ul>
- <li>NONE (no compression)</li>
- <li>PackBits (RLE, run-length encoding)</li>
- <li>JPEG</li>
- <li>Deflate</li>
- <li>LZW</li>
- <li>ZLib</li>
- <li>CCITT T.4 (Fax Group 3)</li>
- <li>CCITT T.6 (Fax Group 4)</li>
- </ul>
- <note>
- If you want to use CCITT compression, please make sure you've got a J2SE 1.4 or later and
- <a href="http://java.sun.com/products/java-media/jai/current.html">
- Java Advanced Imaging Image I/O Tools
- </a>
- in your classpath. The Sun JRE doesn't come with a TIFF codec built in, so it has to be
- added separately. The internal TIFF codec from XML Graphics Commons only supports PackBits,
- Deflate and JPEG compression for writing.
- </note>
- </section>
- </section>
- <section id="txt">
- <title>TXT</title>
- <p>
- The text renderer produces plain ASCII text output
- that attempts to match the output of the PDFRenderer as closely as
- possible. This was originally developed to accommodate an archive system
- that could only accept plain text files, and is primarily useful for getting
- a quick-and-dirty view of the document text. The renderer is very limited,
- so do not be surprised if it gives unsatisfactory results.
- </p>
- <p>
- The Text renderer works with a fixed size page buffer. The size of this
- buffer is controlled with the textCPI and textLPI public variables.
- The textCPI is the effective horizontal characters per inch to use.
- The textLPI is the vertical lines per inch to use. From these values
- and the page width and height the size of the buffer is calculated.
- The formatting objects to be rendered are then mapped to this grid.
- Graphic elements (lines, borders, etc) are assigned a lower priority
- than text, so text will overwrite any graphic element representations.
- </p>
- <p>
- Because FOP lays the text onto a grid during layout, there are frequently
- extra or missing spaces between characters and lines, which is generally
- unsatisfactory.
- Users have reported that the optimal settings to avoid such spacing problems are:
- </p>
- <ul>
- <li>font-family="Courier"</li>
- <li>font-size="7.3pt"</li>
- <li>line-height="10.5pt"</li>
- </ul>
- </section>
- <section id="sandbox">
- <title>Output Formats in the Sandbox</title>
- <p>
- Due to the state of certain renderers we moved some of them to a "sandbox" area until
- they are ready for more serious use. The renderers and FOEventHandlers in the sandbox
- can be found under src/sandbox and are compiled into build/fop-sandbox.jar during the
- main build. The output formats in the sandbox are marked as such below.
- </p>
- <section id="mif">
- <title>MIF</title>
- <warning>The MIF handler is in the sandbox and not yet functional in FOP Trunk!!! Please help us ressurrect this feature.</warning>
- <p>
- This format is the Maker Interchange Format which is used by
- Adobe Framemaker.
- </p>
- </section>
- <section id="svg">
- <title>SVG</title>
- <warning>The SVG renderer is in the sandbox and may not work as expected in FOP Trunk!!! Please help us improve this feature.</warning>
- <p>
- This format creates an SVG document that has links between the pages.
- This is primarily for slides and creating svg images of pages.
- Large documents will create SVG files that are far too large for
- 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 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.
- </p>
- </section>
- </section>
- <section id="wishlist">
- <title>Wish list</title>
- <p>
- Apache FOP is easily extensible and allows you to add new output formats to enhance FOP's functionality. There's a number of output formats
- which are on our wish list. We're looking for volunteers to help us implement them.
- </p>
- <ul>
- <li>
- <a href="http://en.wikipedia.org/wiki/OpenDocument">ODF (Open Document Format)</a>:
- The standardized successor to OpenOffice's file format.
- </li>
- </ul>
- </section>
-
- </body>
- </document>
-
|