jfor README

See also the jfor homepage.
Last revised September 3rd 2002 by Bertrand Delacrétaz. (CreateTestDocuments class name was wrong)

INTRO

jfor was initially written by Bertrand Delacretaz (bdelacretaz@codeconsult.ch), and is released under its own Apache-style license, see http://www.jfor.org/jfor-license.html.
Please note what the license says in more detail: jfor comes without any warranty of any kind - use at your own risk (no guts, no glory...).

WHAT IS JFOR?

jfor converts XML documents conforming to the XSL:FO specification to RTF format, the goal being to use common XSL stylesheets to generate PDF (using FOP or similar) and RTF (using jfor) documents.

Although there are PDF-to-RTF converters, the RTF that they generate usually loses too much structure to be easily editable. jfor attempts to preserve the structure of the document (a table is a table, a list is a list, etc.), which can cause some loss of presentation information (distances between elements, etc.).

jfor releases are tested with:

Both a command-line converter and an adapter for Cocoon 1.8 are provided, and Cocoon 2 includes an RTFSerializer that uses jfor (see the jfor/Cocoon 2 HOWTO for more info).

jfor also includes a general-purpose RTF generation library, see package org.jfor.jfor.rtflib.testdocs for usage examples.

STATUS

Despite serious limitations regarding the interpretation of XSL-FO constructs, jfor can be used productively to generate RTF documents, often with some adjustments to the XSL-FO documents to work around jfor's limitations.

In theory, jfor should not generate invalid RTF documents, but as the RTF spec is a moving target, word processor crashes upon opening documents created by jfor are fairly possible. Unfortunately, it is too late to uninvent RTF.

KNOWN BUGS

See the sample XSL-FO files provided in the samples directory of the source distribution for examples of what works and what doesn't work in the current version.

HOW TO RUN JFOR?

  • 1) Generate test RTF documents
    The following command should generate a few test RTF documents in directory "outdir" (the "testdocs" target of the ant build does the same):
            java -cp $JFOR_HOME/dist/lib/jfor.jar org.jfor.jfor.rtflib.testdocs.CreateTestDocuments outdir
    
    The output of this command should be like:
            CreateTestDocuments - using jfor V0.1 - see http://sourceforge.net/projects/jfor
            Generates documents to test the jfor RTF library.
            Generating document /tmp/rtfout/SimpleDocument.rtf...
            Generating document /tmp/rtfout/TextAttributes.rtf...
            Generating document /tmp/rtfout/SimpleTable.rtf...
            Generating document /tmp/rtfout/SimpleLists.rtf...
            Generating document /tmp/rtfout/ListInTable.rtf...
            CreateTestDocuments - all done.
    
    You should then be able to open the generated documents with your favorite word processor. The contents are meant to be self-describing.
  • 2) Command-line conversion
    jfor releases are tested with the sample XSL-FO files provided with the source distribution.
    To convert file $JFOR_HOME/samples/cocoon/minimal.fo.xml to x.rtf, for example, use the following command:
    
            java \
            -cp $JFOR_HOME/lib/xerces.jar:$JFOR_HOME/dist/lib/jfor.jar \
            ch.codeconsult.jfor.main.CmdLineConverter \
            $JFOR_HOME/samples/cocoon/minimal.fo.xml simple.rtf
    
    The output of which should be like:
            jfor V0.7 - see http://sourceforge.net/projects/jfor
            Converting XSL:FO file '/home/bert/work/jfor/samples/cocoon/minimal.fo.xml' to RTF output 'simple.rtf'...
            jfor.INFO:jfor V0.7 - setting up conversion...
            jfor.INFO:Parsing xsl:fo document...
            jfor.DEBUG:Element 'fo:layout-master-set' (including child elements) ignored due to NullBuilder ignore list
            jfor.DEBUG:Element 'fo:page-sequence' ignored due to default NullBuilder
            jfor.DEBUG:Element 'fo:flow' ignored due to default NullBuilder
            jfor.INFO:Writing out RTF...
            jfor.INFO:Done converting xsl:fo to RTF.
            jfor.DEBUG:conversion took 269 milliseconds.
            Done writing RTF output 'simple.rtf'.
    
  • 3) Cocoon 1.8 integration (not needed for Cocoon 2, see the jfor homepage for Cocoon 2 info).
    These (minimal) instructions assume a working knowledge of Cocoon configuration and usage.
    Briefly, assuming you're running Cocoon under tomcat on port 8080:
    -copy jfor.jar to the tomcat lib directory
    -add the following to file cocoon.properties:
            formatter.type.xslfo/rtf = ch.codeconsult.jfor.cocoon.cocoon18.Cocoon18FoToRtfFormatter
            formatter.xslfo/rtf.MIME-type = application/msword
    
    -restart tomcat
    -check http://localhost:8080/cocoon/Cocoon.xml (or your equivalent), where the formatters list should include:
            xslfo/rtf: RTF Formatter using jfor V0.1
            [ MIME type: application/msword ]
    
    -copy file $JFOR_HOME/samples/cocoon/minimal.fo.xml to a directory served by cocoon. Requesting this file through a browser should deliver an RTF version of this file. If using Internet Explorer, you might need to add ?dummy=file.rtf at the end of the URL so that is uses the correct file handler.
  • HOW TO COMPILE JFOR?

    Binaries are available for download on our SourceForge project page.

    If you want to build jfor yourself, you need the following libraries and tools, which are NOT currently included in the jfor downloads:

    The instructions below apply to a linux system. Contributions of instructions for other systems are welcome.

    CODA

    That's all, folks. Thanks for your interest in jfor!