Differences between revisions 1 and 2
Revision 1 as of 2005-03-22 05:54:03
Size: 6869
Editor: anonymous
Comment: missing edit-log entry for this revision
Revision 2 as of 2009-09-20 23:52:18
Size: 6891
Editor: localhost
Comment: converted to 1.6 markup
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
Interested in working on the integration of [http://www.jfor.org jfor] into [http://xml.apache.org/fop FOP]? Interested in working on the integration of [[http://www.jfor.org|jfor]] into [[http://xml.apache.org/fop|FOP]]?
Line 3: Line 3:
You're most welcome, this page gives some background and starting points. --["BertrandDelacretaz"] You're most welcome, this page gives some background and starting points. --[[BertrandDelacretaz]]
Line 6: Line 6:
 * You're welcome to add comments or additional info to this page, but if you do please indicate your name in["square brackets"].
 * see also ["FOPProjectPages"]
 * [http://www.usemod.com/cgi-bin/wiki.pl?TextFormattingRules UseMod:TextFormattingRules] explains how to format text here.
 * Use the["SandBox"] to experiment with modifying wiki pages.
 * You're welcome to add comments or additional info to this page, but if you do please indicate your name in[[square brackets]].
 * see also [[FOPProjectPages]]
 * [[http://www.usemod.com/cgi-bin/wiki.pl?TextFormattingRules|UseMod:TextFormattingRules]] explains how to format text here.
 * Use the[[SandBox]] to experiment with modifying wiki pages.
Line 53: Line 53:
 * [http://marc.theaimsgroup.com/?l=fop-dev&m=103419780425734&w=2 this message] explains how the jfor integration can take place.  * [[http://marc.theaimsgroup.com/?l=fop-dev&m=103419780425734&w=2|this message]] explains how the jfor integration can take place.
Line 59: Line 59:
 * Jfor integration has been [http://marc.theaimsgroup.com/?l=fop-dev&m=103613363514120&w=2 jumpstarted], meaning there is minimal code in FOP that generates RTF documents. It's way incomplete, but this means you should be able to work in and below the org.apache.fop.rtf package without having to learn much about the rest of the code.  * Jfor integration has been [[http://marc.theaimsgroup.com/?l=fop-dev&m=103613363514120&w=2|jumpstarted]], meaning there is minimal code in FOP that generates RTF documents. It's way incomplete, but this means you should be able to work in and below the org.apache.fop.rtf package without having to learn much about the rest of the code.
Line 77: Line 77:
 * Release early, release often. As soon as you have some concrete part of the integration working, provide a patch for the FOP team to integrate into the FOP codebase. [http://xml.apache.org/cocoon/howto/howto-patch.html This document] explains how to create patches for the Cocoon projet, the steps for FOP are the same except that you must use the FOP project name when posting patches to bugzilla.  * Release early, release often. As soon as you have some concrete part of the integration working, provide a patch for the FOP team to integrate into the FOP codebase. [[http://xml.apache.org/cocoon/howto/howto-patch.html|This document]] explains how to create patches for the Cocoon projet, the steps for FOP are the same except that you must use the FOP project name when posting patches to bugzilla.
Line 91: Line 91:
 * Edit the build-local.properties file as described in [http://marc.theaimsgroup.com/?l=fop-dev&m=103613363514120&w=2 this message] and run "./build.sh examples" again.  * Edit the build-local.properties file as described in [[http://marc.theaimsgroup.com/?l=fop-dev&m=103613363514120&w=2|this message]] and run "./build.sh examples" again.
Line 97: Line 97:
 * Here's [http://marc.theaimsgroup.com/?l=fop-dev&w=2&r=1&s=jfor&q=b Everything] that's been said on jfor on the fop-devel mailing list.
 * [http://www.cafeconleche.org/books/bible2/chapters/ch18.html XSL Formatting Objects], Chapter 18 of the XML Bible, Second Edition.
 * CVS code repository browsing of [http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/jfor/ jfor] and [http://cvs.apache.org/viewcvs.cgi/xml-fop/ FOP] is available.
 * Here's [[http://marc.theaimsgroup.com/?l=fop-dev&w=2&r=1&s=jfor&q=b|Everything]] that's been said on jfor on the fop-devel mailing list.
 * [[http://www.cafeconleche.org/books/bible2/chapters/ch18.html|XSL Formatting Objects]], Chapter 18 of the XML Bible, Second Edition.
 * CVS code repository browsing of [[http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/jfor/|jfor]] and [[http://cvs.apache.org/viewcvs.cgi/xml-fop/|FOP]] is available.

Interested in working on the integration of jfor into FOP?

You're most welcome, this page gives some background and starting points. --BertrandDelacretaz

Please read this first:


Overview

== What is jfor =

Jfor takes XSL-FO documents as input (like FOP) and generates RTF documents as its output.

== Current status of jfor - what will we keep? =

Although heavily used in production and very stable, jfor is fairly limited in its handling of XSL-FO properties (the XSL-FO attributes that define text appearance and formatting options). Many properties are ignored or only partially implemented.

Codewise, jfor mostly consists of a "Converter" that interprets SAX events provided by and XML parser, and uses an "RTFLibrary" written for jfor, that is able to generate RTF documents based on the instructions of the Converter.

Only the RTFLibrary will be used by FOP, the Converter will be replaced by the FOP front-end.

== Why integrate jfor into FOP? =

FOP and jfor have many things in common, mostly at the front-end stages: XML parsing and interpretation of XSL-FO properties. It makes sense to use the same front-end for RTF and PDF generation, although the back-ends are very different.

Compared to jfor as it currently stands, an RTF-enabled FOP should be able to handle many more properties correctly, and improving this property handling will impact both RTF and PDF documents later on.

Also, jfor is currently weak in its handling of nested fo:block and fo:inline elements. Rewriting the front-end (based on FOP) is a good opportunity to improve this. I think moving from a "nested elements" model to a "linear text runs" model for fo:blocks and fo:inlines should help a lot with this.

For RTF documents, no layout computations (line and page breaks, etc.) need to be done, as the layout is done by the wordprocessor when opening the RTF document.

For PDF documents, on the other hand, the layout must be computed down to the smallest details in order to generate pages with all elements in the right places. This is a much more complicated backend than the RTF one.

The { { { StructureHandler } } } concept was introduced in FOP this year to facilitate integration of non-layout based "renderers" into FOP. The RTF renderer based on jfor code will be one of these.

So, in conclusion, it make sense to integrate the RTF generation capabilities of jfor in FOP, mostly to leverage the current FOP front-end for both PDF and RTF formats.

== How can you help? =

Although it already uses the existing jfor RTF library, the RTFHandler in FOP (as of December 2002) recognizes almost no useful XSL-FO constructs. It only shows that the integration is possible but needs to be expanded to produce useful documents.

I (BertrandDelacretaz) am available to help steer this in the (hopefully) right direction so you're not left in the dark.

Roadmap

== The plan =

  • this message explains how the jfor integration can take place.

The plan was to first use jfor in binary form, but now the RTF library of jfor has been donated to FOP and adapted so that basic RTF documents work without needing the jfor jar.

== Where we stand now =

  • Jfor integration has been jumpstarted, meaning there is minimal code in FOP that generates RTF documents. It's way incomplete, but this means you should be able to work in and below the org.apache.fop.rtf package without having to learn much about the rest of the code.

  • As mentioned above, the RTF library of jfor has been donated to FOP and integrated (thanks Victor!).
  • The latest changes to the jfor RTF library haven't been ported to FOP yet, some synchronization might be needed at some point.
  • Peter Herweg has started porting document generation code from jfor and is currently working on it.

== How to go on =

Here are a few suggestions:

  • The main goal is to improve org.apache.fop.rtf.renderer.RTFHandler by having it recognize and correctly process all { { { StructureRenderer } } } events and their attributes to generate RTF documents.

  • The final goal, of course, is having "build.sh examples" generate all examples correctly as RTF files.
  • Tackle one feature at a time. For example, try implementing fo:block, test it with reference documents (either the FOP or the jfor XSL-FO sample documents) and post a patch so the FOP team can integrate it.
  • Release early, release often. As soon as you have some concrete part of the integration working, provide a patch for the FOP team to integrate into the FOP codebase. This document explains how to create patches for the Cocoon projet, the steps for FOP are the same except that you must use the FOP project name when posting patches to bugzilla.

  • Use the org.jfor.jfor.converter package as an example of how to convert the { { { StructureRenderer } } } events.

  • Ask questions on the fop-dev mailing list. Please put the word "RTF" in the subject line so we can easily spot your messages.

== Testing the RTF generation =

Currently the easiest way to test is as follows:

  • Checkout the FOP code from CVS
  • Build and test using "./build.sh examples" from the directory that contains build.xml. This generates PDF test documents in directory build/examples. As the FOP codebase is still being heavily worked on, some sample documents might cause errors, this is not a problem at this stage. If you get several PDF documents in the output directory, it means your development environment is functional.
  • Edit the build-local.properties file as described in this message and run "./build.sh examples" again.

  • You should now find generated RTF documents in directory lib/examples.

References

  • Here's Everything that's been said on jfor on the fop-devel mailing list.

  • XSL Formatting Objects, Chapter 18 of the XML Bible, Second Edition.

  • CVS code repository browsing of jfor and FOP is available.

JforIntegrationInFop (last edited 2009-09-20 23:52:18 by localhost)