CVS: jfor/docs/website/www.jfor.org jfor-readme.html,NONE,1.1 index.html,1.3,1.4
Bertrand Delacretaz <[email protected]> Fri, 12 Jul 2002 01:04:34 -0700
| Newsgroups | gmane.text.xml.jfor.cvs |
|---|---|
| Message-ID | <[email protected]> |
Update of /cvsroot/jfor/jfor/docs/website/www.jfor.org
In directory usw-pr-cvs1:/tmp/cvs-serv10671
Modified Files:
index.html
Added Files:
jfor-readme.html
Log Message:
jfor-readme.html added
--- NEW FILE: jfor-readme.html ---
<html>
<head>
<title>jfor - Open-Source Java XSL-FO to RTF converter - XML to RTF publishing</title>
<meta name="keywords" content="jfor xsl-fo xsl:fo rtf java xml xsl fop pdf winword word codeconsult Bertrand Delacrétaz www.jfor.org www.codeconsult.org">
<style type="text/css">
BODY,TD,H1,H2,H3,H4
{
font-family: arial, verdana, sans-serif;
color: black;
background: white;
}
pre
{
padding-top:1em;
padding-bottom: 1em;
margin-left: 2em;
margin-right: 2em;
border: solid blue 1px;
}
.mainTitle
{
font-size:140%;
background: rgb(220,220,220);
padding:2mm;
}
.news
{
font-size:90%;
}
</style>
</head>
<body bgcolor="white">
<h3 class="mainTitle">
jfor README
</h3>
<p class="note">
Last revised July 12th 2002 by Bertrand Delacrétaz.
<br/>
See also the <a href="http://www.jfor.org">jfor homepage</a>.
</p>
<h3>INTRO</h3>
<p>
jfor was initially written by Bertrand Delacretaz ([email protected]), and
is released under its own Apache-style license, see
<a href="http://www.jfor.org/jfor-license.html">http://www.jfor.org/jfor-license.html</a>.
<br/>
Please note what the license says in more detail:
<font color="red"><b>
jfor comes without any warranty of any kind - use at your own risk (no guts, no glory...).
</b>
</font>
</p>
<h3>WHAT IS JFOR?</h3>
<p>
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.
</p>
<p>
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.).
</p>
<p>
jfor releases are tested with:
</p>
<ul>
<li>XSL:FO documents found in the <em>samples</em> directory of the jfor source code distribution</li>
<li>Microsoft Word 97 to check the output RTF documents</li>
</ul>
<p>
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
<a href="jfor-cocoon-howto.html">jfor/Cocoon 2 HOWTO</a> for more info).
</p>
<p>
jfor also includes a general-purpose RTF generation library, see
package org.jfor.jfor.rtflib.testdocs for usage examples.
</p>
<h3>STATUS</h3>
<p>
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.
</p>
<p>
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.
</p>
<h3>KNOWN BUGS</h3>
<p>
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.
</p>
<h3>HOW TO RUN JFOR?</h3>
<li>
1) Generate test RTF documents
<br/>
The following command should generate a few test RTF documents in directory "outdir"
(the "testdocs" target of the ant build does the same):
<pre>
java -cp $JFOR_HOME/dist/lib/jfor.jar ch.codeconsult.jfor.rtflib.testdocs.CreateTestDocuments outdir
</pre>
The output of this command should be like:
<pre>
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.
</pre>
You should then be able to open the generated documents with your favorite word processor. The contents are
meant to be self-describing.
</li>
<li>
2) Command-line conversion
<br/>
jfor releases are tested with the sample XSL-FO files provided with the source distribution.
<br/>
To convert file $JFOR_HOME/samples/cocoon/minimal.fo.xml to x.rtf, for example, use the following command:
<pre>
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
</pre>
The output of which should be like:
<pre>
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'.
</pre>
</li>
<li>
3) Cocoon 1.8 integration (<b>not needed for Cocoon 2, see the <a href="index.html">jfor homepage</a> for
Cocoon 2 info</b>).
<br/>
These (minimal) instructions assume a working knowledge of Cocoon configuration and usage.
<br/>
Briefly, assuming you're running Cocoon under tomcat on port 8080:
<br/>
-copy jfor.jar to the tomcat lib directory
<br/>
-add the following to file cocoon.properties:
<pre>
formatter.type.xslfo/rtf = ch.codeconsult.jfor.cocoon.cocoon18.Cocoon18FoToRtfFormatter
formatter.xslfo/rtf.MIME-type = application/msword
</pre>
-restart tomcat
<br/>
-check http://localhost:8080/cocoon/Cocoon.xml (or your equivalent), where the formatters list should include:
<pre>
xslfo/rtf: RTF Formatter using jfor V0.1
[ MIME type: application/msword ]
</pre>
-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.
</li>
</ul>
<h3>HOW TO COMPILE JFOR?</h3>
<p>
Binaries are available for download on our SourceForge project page.
</p>
<p>
If you want to build jfor yourself, you need the following libraries and tools, which are
NOT currently included in the jfor downloads:
</p>
<ul>
<li>ANT build tool, <a href="http://jakarta.apache.org/ant/">http://jakarta.apache.org/ant/</a></li>
<li>Xerces parser, <a href="http://xml.apache.org/xerces-j/">http://xml.apache.org/xerces-j/</a></li>
<li>Cocoon 1.x (optional, for Cocoon 2 you do not need this), <a href="http://xml.apache.org/cocoon/">http://xml.apache.org/cocoon/</a></li>
</ul>
<p>
The instructions below apply to a linux system.
Contributions of instructions for other systems are welcome.
</p>
<ul>
<li>
1) get jfor
<br/>
Get the jfor source from SourceForge and copy it to a local directory (called JFOR_HOME below).
<br/>
Replace $JFOR_HOME with the name of this directory in the instructions below.
<br/>
Running "ls $JFOR_HOME" must give a listing that includes README.TXT, the "src" and "lib"
directories, among other files and directories.
</li>
<li>
2) check that ant is working
<br/>
Download ant and install it according to the instructions in the package.
<br/>
Running "ant -version" must say "Ant version 1.3" at least, later version should work ok too.
</li>
<li>
3) install required libraries
<br/>
Copy the following files to the $JFOR_HOME/lib directory:
<br/>
-xerces.jar (we use xerces 1.2.3 to compile and test jfor)
<br/>
-cocoon.jar (needed for Cocoon 1.x only, not for Cocoon 2)
</li>
<li>
4) build jfor
<br/>
Change directory to $JFOR_HOME and run "ant".
<br/>
If all goes well, you should see something like:
<pre>
$ ant
Buildfile: build.xml
init:
[mkdir] Created dir: /home/bert/work/jfor/build
compile:
[javac] Compiling 57 source files to /home/bert/work/jfor/build
dist:
[mkdir] Created dir: /home/bert/work/jfor/dist/lib
[jar] Building jar: /home/bert/work/jfor/dist/lib/jfor.jar
BUILD SUCCESSFUL
Total time: 5 seconds
$
</pre>
</li>
</ul>
<h3>CODA</h3>
That's all, folks. Thanks for your interest in jfor!
</body>
</html>
Index: index.html
===================================================================
RCS file: /cvsroot/jfor/jfor/docs/website/www.jfor.org/index.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** index.html 12 Jul 2002 07:11:09 -0000 1.3
--- index.html 12 Jul 2002 08:04:31 -0000 1.4
***************
*** 43,52 ****
<h3>WHAT IS JFOR?</h3>
<b>jfor</b> <a href="#jfor-explain">(*)</a> converts XML documents conforming to the XSL-FO specification to RTF
format, the goal being to use the same XSL-FO documents (as often generated using XSLT transforms) to generate PDF (using
<a href="http://xml.apache.org/fop">FOP</a>
or similar) and RTF (using jfor) documents.
! <p>jfor is licensed under the <a target="_top" href="http://www.mozilla.org/MPL/MPL-1.1.html">Mozilla Public License V1.1</a>.</p>
<p>Through an intermediate transformation to XSL-FO, jfor can be used to convert any raw or XML data to RTF format.
--- 43,59 ----
<h3>WHAT IS JFOR?</h3>
+ <p>
<b>jfor</b> <a href="#jfor-explain">(*)</a> converts XML documents conforming to the XSL-FO specification to RTF
format, the goal being to use the same XSL-FO documents (as often generated using XSLT transforms) to generate PDF (using
<a href="http://xml.apache.org/fop">FOP</a>
or similar) and RTF (using jfor) documents.
+ </p>
! <p>
! jfor is licensed under its own Apache-style license, found under
! <a href="http://www.jfor.org/jfor-license.html">http://www.jfor.org/jfor-license.html</a>.
! Releases prior to V0.7.0 used the Mozilla Public License V1.1, but this was changed to make it possible
! to distribute jfor with projects of the Apache Software Foundation.
! </p>
<p>Through an intermediate transformation to XSL-FO, jfor can be used to convert any raw or XML data to RTF format.
***************
*** 86,89 ****
--- 93,97 ----
<ul>
<li>jfor homepage <a href="http://www.jfor.org">http://www.jfor.org</a>
+ <li><a href="jfor-readme.html">jfor-readme.html</a> shows how to run and compile jfor</li>
<li><a href="http://lists.sourceforge.net/lists/listinfo/jfor-announce">jfor-announce</a> mailing list: announces new releases
and important events about jfor.
***************
*** 111,115 ****
<h3>HOW TO COMPILE, RUN, ETC.</h3>
! More information will be provided here shortly - in the meantime, see the README V0.1 in the "files" area of the SourceForge project (also included in the source distribution).
<h3>THE TEAM</h3>
--- 119,123 ----
<h3>HOW TO COMPILE, RUN, ETC.</h3>
! See <a href="readme.html">readme.html</a>.
<h3>THE TEAM</h3>
-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Gadgets, caffeine, t-shirts, fun stuff.
http://thinkgeek.com/sf