Acknowledgement: Some content in this guide was adapted from other Apache projects such as Avalon, Cactus, Turbine and Velocity.
+Conventions in this section apply to Repository content, regardless of type:
+In order to facilitate the human reading of FOP source code, the FOP developers have agreed on a set of coding conventions. +The basis of these coding conventions is documented in the Apache XML Project Guidelines, which requires that all Java Language source code in the repository must be written in conformance to Sun's Code Conventions for the Java Programming Language. +In addition, the FOP developers have agreed to other conventions, which are summarized in the following table:
+| Convention | +Rationale | +Enforced By | +
|---|---|---|
| Every Java source file starts with the Apache licence header. | +Required by Apache. | +checkstyle | +
| No tabs in content | +Programmers should not have to adjust the tab settings in their editor to be able to read the source code. | +checkstyle | +
| Indentation of 4 spaces per level | +Maximize readability. | +Not enforced | +
| Comments must be in English | +To avoid the need for everyone to learn all languages, English has become the standard language for many technology projects, and is the only human language that all FOP developers are expected to know. | +Not enforced | +
| Fully qualify all import statements (no "import java.util.*") | +Clarity | +checkstyle | +
| No underscores in variable names except for static finals. | +Upper/lower case distinctions can be made in all other variable names, eliminating the need for artificial word boundaries. | +checkstyle | +
| Opening brace for a block should be on the same line as its control statement (if, while, etc.). | +Standardization, general preference. | +checkstyle | +
| Write appropriate javadoc entries for all public and protected classes, methods, and variables. | +Basic API documentation is needed. | +checkstyle | +
For developers that dislike these conventions, one workaround is to develop using their own style, then use a formatting tool like astyle (Artistic Style) before committing.
+The java syntax checker "
To use the "checkstyle" target in FOP's build process, download the source from the
Checkstyle is probably most useful when integrated into your IDE. See the Checkstyle web site for more information about IDE plugins.
+The following general principles are a distillation of best practice expectations on the FOP project.
+| Convention | +Rationale | +Enforced By | +
|---|---|---|
| XML files must always be well-formed. Validation is optional. | +Document integrity | +Not enforced | +
| No tabs in content. | +Users should not have to adjust tab settings in their editor to be able to read the content. | +Not enforced | +
| Indentation of 2 spaces per level | +Maximize readability | +Not enforced | +
This page documents the process of creating a FOP release. +FOP releases are coordinated by one member of the team (currently Christian Geisert), so others do not ordinarily need to use this information. +The purpose of documenting it here is to facilitate consistency, ensure that the process is captured, and to allow others to comment on the process.
+The checklist below was assembled from Christian Geisert's notes. It will be expanded in the future as he has time.
+cvs tag fop-0_20_5rc3cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic co -r
+fop-0_20_5rc3 xml-fopgpg -a -b --force-v3-sigs fop-0.20.5rc3-bin.tar.gz etc.scp fop-0.20.5rc3*.tar.gz*
+chrisg@www.apache.org:/www/www.apache.org/dist/xml/fop/chmod 664 ... ; chgrp xml ...md5 fop-0.20.5rc3-bin.tar.gz >
+ fop-0.20.5rc3-bin.tar.gz.md5The following is a sample of some other project release checlists, which might be consulted for ideas:
+Following are links with information about mirroring:
+The RTFLib package is an open-source, independent package suitable for writing RTF files in a java environment. +By independent we mean:
+The FOP development team intends to keep the RTFLib package independent so that it can be used for other purposes.
+RTFLib was originally developed by Bertrand Delacrétaz and the jfor team. jfor was written under an Apache-style license, and the jfor team contributed the code to the Apache Software Foundation in June, 2003. RTFLib is a subset of the original jfor project, which also includes an XSL-FO parsing mechanism for a complete XSL-FO to RTF solution.
+Although FOP's implementation of the RTFLib package is very incomplete, the RTFLib package itself is relatively mature. RTFLib is only available in the trunk line of FOP development.
+Perhaps the easiest way to see how to use RTFLib is by looking at an example. A set of test documents is part of the package, and can be viewed online. +A quick look at the Abstract TestDocument class, and one of the Concrete subclasses, SimpleDocument will provide the basics of how to use the package.
+There are two basic concepts you will need to understand in order to use RTFLib:
+RTFLib handles the process of converting to and writing the RTF content as the document is created. All you need to do is flush the document at the end to make sure that the last pieces get written.
+The documentation in this section is intended to provide a high-level view of the process of building an RTF document. For more detailed API documentation of the various methods, be sure to consult the Javadocs for RTFLib.
+The following table summarizes the various containers that can be created:
+| Name | +Class.Method where created | +Attribute Set(s) | +Valid children | +
|---|---|---|---|
| Document Area | +RtfFile.startDocumentArea() | +Information Group, Document Formatting | +Section | +
| Section | +RtfDocumentArea.newSection() | +Section Formatting | +Paragraph, ParagraphKeepTogether, Image, List, Before (Page Heading), After (Page Footer), JforCmd | +
| Paragraph | +RtfSection.newParagraph() | +Paragraph Formatting, Character Formatting | +Text | +
| ParagraphKeepTogether | +RtfSection.newParagraphKeepTogether | +. | +. | +
| Image | +RtfSection.newImage | +. | +. | +
| Table | +RtfSection.newTable | +. | +. | +
| List | +RtfSection.newList | +. | +. | +
| Before (Page Heading) | +RtfSection.newBefore | +. | +. | +
| After (Page Footer) | +RtfSection.newAfter | +. | +. | +
| JforCmd | +RtfSection.newJforCmd | +. | +. | +
| Text | +RtfParagraph.newText() | +Character Formatting | +N/A | +
Attributes can be set for each container and piece of content in the document. The general approach is to build an RtfAttributes object containing the various attributes, then pass that RtfAttributes object to the method that creates the new container or content. See the Javadoc API documentation for RtfAttributes for details on the syntax for creating an RtfAttributes object. The following information lists the various attributes that can be set for each type of container.
+These attributes are set when creating a Document.
+These attributes are set when creating a Document.
+These attributes are set when creating a Section.
+These attributes are set when creating a Paragraph.
+| Description | +Attribute Name | +Attribute Value | +RTF Control Word | +
|---|---|---|---|
| . | +|||
| Alignment | +. | +||
| Align Left | +RtfText.ALIGN_LEFT | +N/A (boolean) | +\ql | +
| Align Right | +RtfText.ALIGN_RIGHT | +N/A (boolean) | +\qr | +
| Align Centered | +RtfText.ALIGN_CENTER | +N/A (boolean) | +\qc | +
| Align Justified | +RtfText.ALIGN_JUSTIFIED | +N/A (boolean) | +\qj | +
| Align Distributed | +RtfText.ALIGN_DISTRIBUTED | +N/A (boolean) | +\qd | +
| Kashida justification | +not implemented | +0-20 (integer) | +\qkN | +
| Thai Distributed justification | +not implemented | +N/A (boolean) | +\qt | +
| Indentation | +. | +||
| Left indent body | +RtfText.LEFT_INDENT_BODY | +(int) "hundredths of a character unit" (?) | +\li | +
| Left indent first | +RtfText.LEFT_INDENT_FIRST | +(int) "hundredths of a character unit" (?) | +\fi | +
| Borders | +. | +||
| Bottom single border | +RtfText.BDR_BOTTOM_SINGLE | +Boolean? | +brdrb\\brsp40\\brdrs | +
| Bottom double border | +RtfText.BDR_BOTTOM_DOUBLE | +Boolean? | +brdrb\\brsp40\\brdrdb | +
| Bottom embossed border | +RtfText.BDR_BOTTOM_EMBOSS | +Boolean? | +brdrb\\brsp40\\brdremboss | +
| bottom dotted border | +RtfText.BDR_BOTTOM_DOTTED | +Boolean? | +brdrb\\brsp40\\brdrdot | +
| bottom dashed border | +RtfText.BDR_BOTTOM_DASH | +Boolean? | +brdrb\\brsp40\\brdrdash | +
These attributes are set when creating a Paragraph, or Text.
+| Description | +Attribute Name | +Attribute Value | +RTF Control Word | +
|---|---|---|---|
| Bold | +RtfText.ATTR_BOLD | +N/A (boolean) | +\b | +
| Italic | +RtfText.ATTR_ITALIC | +N/A (boolean) | +\i | +
| Underline | +RtfText.ATTR_UNDERLINE | +N/A (boolean), or (int) 0 to turn underlining off | +\ul | +
| Font Size | +RtfText.ATTR_FONT_SIZE | +(int) font size in half-points | +\fs | +
| Font Family | +RtfText.ATTR_FONT_FAMILY | +(int) entry in document font-table | +\f | +
| Font Color | +RtfText.ATTR_FONT_COLOR | +(int) entry in document color-table | +\cf | +
| Background Color | +RtfText.ATTR_BACKGROUND_COLOR | +(int) entry in document color-table | +\chcbpat | +
FOP uses an XML-based TeX-like hyphenation pattern scheme. +Hyphenation pattern files for many languages are included in the standard FOP distribution. +However, because of licensing issues, there are currently some significant holes in FOP's hyphenation support. +The information on this page is intended to help you work around these limitations, if possible, add support for other languages, or enhance FOP's support of current languages.
+Many of the hyphenation files distributed with TeX and its offspring are licenced under the
The most important source of hyphenation pattern files is the
To install custom a custom hyphenation pattern for use with FOP:
+{fop-dir}/src/hyph/hyphenation.dtd.languageCode_countryCode.xml.
+The country code is optional, and should be used only if needed. For example:
+ en_US.xml would be the file name for an American English hyphenation pattern.it.xml would be the file name for an Italian hyphenation pattern.Before posting questions to any list:
+For help in understanding email acronyms, see the
Use this forum to discuss topics of interest to FOP users.
+To review the archives, you have several options:
+FOP support is primarily self-service. The FOP User Mailing List serves as a backup to the self-service documentation for cases where either the documentation is deficient or where users have unusual circumstances. FOP developers and users are happy to help answer questions that are appropriate to the forum (i.e. FOP-specific), and that are submitted after appropriate preparation. To ensure that your question is not abusive of this policy, please use the following checklist:
+Use this forum to ask general XSL-FO questions.
+Use this forum to ask general XSL-FO questions.
++ This page discusses topic all around using FOP in a servlet environment. +
++ In the directory {fop-dir}/examples/servlet, you'll find a working example + of a FOP-enabled servlet. +
++ You can build the servlet easily by using the supplied Ant script. After building + the servlet, drop fop.war into the webapps directory of Tomcat. Then, you can use + URLs like the following to generate PDF files: +
+The source code for the servlet can be found under {fop-dir}/examples/servlet/src/FopServlet.java.
++ Here is a minimal code snippet to demonstrate the basics: +
++ A common requirement is the to transform an XML source to + XSLFO using an XSL transformation. It is recommended to use + JAXP for this task. The following snippet shows the basic + code: +
+
+ The Source instance used above is simply an
+ example. If you have to read the XML from a string, supply
+ a new StreamSource(new
+ StringReader(xmlstring)). Constructing and reparsing
+ an XML string is generally less desirable than using a
+ SAXSource if you generate your XML. You can alternatively
+ supply a DOMSource as well. You may also use dynamically
+ generated XSL if you like.
+
+ Because you have an explicit Transformer object, you can also use it to
+ explicitly set parameters for the transformation run.
+
+ If you need to supply a special configuration do this in the init()
+ method so it will only be done once and to avoid multithreading problems.
+
+ There are several options to consider: +
++ Of course, the + performance hints from the Embedding page + apply here, too. +
++ 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: +
+.pdf, like
+ http://myserver/servlet/stuff.pdf. Yes, the servlet can
+ be configured to handle this. If the URL has to contain parameters,
+ try to have both the base URL as well as the last parameter end in
+ .pdf, if necessary append a dummy parameter, like
+ http://myserver/servlet/stuff.pdf?par1=a&par2=b&d=.pdf. The
+ effect may depend on IEx version.
+ Expires header entry may help in
+ this case:response.setDateHeader("Expires",
+ System.currentTimeMillis() + cacheExpiringDuration *
+ 1000);+ When using a servlet engine, there are potential CLASSPATH issues, and potential conflicts + with existing XML/XSLT libraries. Servlet containers also often use their own classloaders + for loading webapps, which can cause bugs and security problems. +
++ Check Tomcat's documentation for detailed instructions about installing FOP and Cocoon. + There are known bugs that must be addressed, particularly for Tomcat 4.0.3. +
++ Put a copy of a working parser in some directory where WebSphere can access it. + For example, if /usr/webapps/yourapp/servlets is the CLASSPATH for your servlets, + copy the Xerces jar into it (any other directory would also be fine). + Do not add the jar to the servlet CLASSPATH, but add it to the CLASSPATH of the + application server which contains your web application. + In the WebSphere administration console, click on the "environment" button in the + "general" tab. In the "variable name" box, enter "CLASSPATH". + In the "value" box, enter the correct path to the parser jar file + (/usr/webapps/yourapp/servlets/Xerces.jar in our example here). + Press "OK", then apply the change and restart the application server. +
+
+ Sometimes the requirements for a servlet get quite sophisticated: SQL data sources,
+ multiple XSL transformations, merging of several datasources etc. In such a case
+ consider using
All lists on this page are in alphabetical order. Some of them may be incomplete. If you know of an error or omission, please send a message to the fop-dev mailing list.
+FOP was originally created and donated to the Apache Software Foundation by James Tauber. Information about him can be found at
| + | BD | +CG | +KL | +KLL | +JM | +GM | +WVM | +JP | +AS | +OT | +PBW | +
|---|---|---|---|---|---|---|---|---|---|---|---|
| PMC representation | ++ | + | + | + | X | ++ | + | + | + | + | X | +
| Release manager | ++ | X | ++ | + | + | + | + | + | + | + | + |
| XSL-FO tree | ++ | + | + | X | ++ | + | + | + | + | + | X | +
| Layout | ++ | + | X | +X | ++ | + | + | X | +X | ++ | + |
| Fonts | ++ | + | + | + | X | ++ | + | + | + | + | + |
| SVG | ++ | + | + | X | +X | ++ | + | + | + | + | + |
| Java2D (AWT) | ++ | + | + | X | +X | ++ | + | + | + | + | + |
| + | + | + | X | +X | ++ | + | + | + | + | + | |
| PostScript | ++ | + | + | + | X | ++ | + | + | + | + | + |
| PCL | ++ | + | + | + | + | + | + | + | + | + | + |
| RTF | +X | ++ | + | + | + | + | + | + | + | + | + |
| MIF | ++ | + | + | + | + | + | + | + | + | + | + |