Prepare README for 0.90alpha1 release.

git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@344978 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 138 insertions, 33 deletions

diff --git a/README b/README
index 26df7a325..e803d34e5 100644
--- a/README
+++ b/README
@@ -1,39 +1,144 @@
-FOP README
-
-    What is FOP?
-    FOP is the world's first print formatter driven by XSL formatting
-    objects. It is a Java application that reads a formatting object
-    tree conforming to the XSL 1.0 Recommendation (15 October 2001) and
-    then turns it into a PDF document or allows you to preview it
-    directly on screen.
-
-    FOP is part of Apache's XML Graphics project. The homepage of FOP is
-    http://xml.apache.org/fop.  Our resources page is at 
-    http://xml.apache.org/fop/resources.html.
-    
-    Please report bugs to bugzilla at http://issues.apache.org/bugzilla/
+$Id$
+
+==============================================================================
+  APACHE FOP  -  README
+==============================================================================
+
++----------------------------------------------------------------------------+
+|                                                                            |
+|                      **** IMPORTANT! ****                                  |
+|                                                                            |
+| This release is the first after a big redesign effort on the whole FOP     |
+| codebase. This release is to be considered ALPHA quality and it is         |
+| intended as a preview release encouraging people to take a look at the new |
+| version and to provide feedback to the developers. Please not only report  |
+| to us problems you might experience but also tell us if it works for you.  |
+| If you find out that this version works fine for you, you're welcome to    |
+| use it but please test it thoroughly as we don't consider this release     |
+| ready for every production environment. Please read the following page for |
+| more detailed information:                                                 |
+| http://xmlgraphics.apache.org/fop/0.90/upgrading.html                      |
+|                                                                            |
++----------------------------------------------------------------------------+
+
+Contents of this file:
+ - What is FOP?
+ - Where to get help?
+ - How do I build FOP?
+ - How do I run FOP?
+ - Release Notes
 
-    A mailing list for how to use FOP is at fop-users@xmlgraphics.apache.org
-    (subscribe by sending an empty mail to 
-    fop-users-subscribe@xmlgraphics.apache.org)
+==============================================================================
 
-    Before you post any questions, please have a look at the FAQ at
-    http://xml.apache.org/fop/fo.html.
 
+What is FOP?
+---------------
 
-Instructions for building FOP from source code:
+Apache FOP is the world's first print formatter driven by XSL formatting 
+objects. It is a Java application that reads a formatting object tree 
+conforming to the XSL 1.0 Recommendation (15 October 2001) and then turns it 
+into a PDF document, certain other output formats or allows you to preview it 
+directly on screen.
 
-    FOP uses Apache Ant as its build system.  You can download Apache Ant
-    from http://ant.apache.org.
+Apache FOP is part of Apache's XML Graphics project. The homepage of Apache 
+FOP is http://xml.apache.org/fop/.
+    
+    
+Where to get help?
+---------------------    
+    
+http://xmlgraphics.apache.org/fop/gethelp.html
     
-    Ant installation instructions:
-    1. Download and install Ant
-    2. Set the ANT_HOME environment variable to the directory where you've
-       placed Ant.
-    3. Add "%%ANT_HOME%%\bin" to your PATH so the "ant.bat" batch file
-       can be executed from wherever needed.
-    4. (optional) Download JUnit and place junit-*.jar in %%ANT_HOME%%\lib.
-       This enables the JUnit test cases.
-	
-    After Ant is installed, you can build FOP simply by navigating to
-    the FOP base directory and typing "ant".
+A mailing list where you can get all your questions about FOP answered is at 
+fop-users@xmlgraphics.apache.org. You can subscribe by sending an empty mail 
+to fop-users-subscribe@xmlgraphics.apache.org.
+
+Before you post any questions, please have a look at the FAQ at 
+http://xmlgraphics.apache.org/fop/faq.html and FO help page at 
+http://xml.apache.org/fop/fo.html.
+
+Please report bugs to bugzilla at http://issues.apache.org/bugzilla/
+
+
+How do I build FOP?
+----------------------
+
+If you've downloaded a binary distribution, you don't need to build FOP.
+
+Otherwise, please follow the instructions found here:
+http://xmlgraphics.apache.org/fop/0.90/compiling.html
+
+
+How do I run FOP?
+--------------------
+
+Simply by typing "fop" on the command-line. Without any parameters you
+will receive a screen with instruction on how to call FOP from the
+command-line.
+
+For more details, see: http://xmlgraphics.apache.org/fop/0.90/running.html
+
+==============================================================================
+  RELEASE NOTES
+==============================================================================
+
+Version 0.90alpha1
+---------------------
+
+We don't list all the changes since the 0.20.5 release, since this release 
+represents the first after a complete redesign of the FOP codebase. This 
+is basically a new software.
+
+Upgrading from 0.20.5:
+Please read http://xmlgraphics.apache.org/fop/0.90/upgrading.html
+
+Caveats:
+
+    - This release is a preview release and not intended for use in a
+      production environment. Use at your own risk!
+    - The API is not to be considered stable, yet. Please be prepared 
+      for the API to be changed in a backwards-incompatible way.
+    - You may experience different behaviour compared to version 0.20.5.
+      Please consult the "Upgrading" page indicated above for details.
+
+Known issues:
+
+    - PCL, MIF and SVG support have not been restored, yet.
+    - Java2D/AWT support contains some problems, for example with 
+      block-containers.
+    - Support for kerning has not been restored, yet.
+    - Auto table layout is not implemented, yet.
+    - The collapsing border model on tables is not implemented, yet. Please 
+      use border-collapse="separate" for now.
+    - Footnotes may overlap with text of the region-body in multi-column 
+      documents.
+    - Space resolution does not work between footnote regions.
+    - There's a problem involving nested block-containers and 
+      reference-orientation 180/-180 (Bugzilla #36391)
+    - block-containers with no height currently don't create a fence for
+      spaces as they should (they behave like a normal block).
+    - Preserved linefeeds in fo:character are not handled correctly.
+    - Zero-width spaces are not handled correctly.
+    - An empty block currently produces a fence for stacking constraints
+      which it shouldn't.
+    - There are several small problems around white space handling.
+    - Images currently don't shrink so they fit on a page when they are 
+      too big and shrinking is allowed to happen.
+    - Block-level content in fo:inlines may produce unwelcome results.
+    - inline-container may not work as expected.
+    - letter-spacing and work-spacing may not work as expected.
+    - leaders with leader-pattern="use-content" may not work as expected.
+    - keep-with-previous doesn't work inside tables and lists, yet.
+    - White space on direct inline-level children of a marker are not 
+      handled correctly.
+    - If two consecutive pages don't have the same available width, the 
+      content currently isn't properly fit into the available space on
+      the new page.
+    - background-images on page-number-citations are not placed correctly.
+    - Not all FO elements can be referenced by their "id", most notably:
+      table-body, table-header, table-footer and table-row.
+    - The backgrounds of table-body, table-header, table-footer and 
+      table-column are not painted, yet.
+    - Border and padding conditionality are not supported on table-cells, yet.
+    - Copy/Paste from PDF content in Acrobat Reader is not supported for
+      text using embedded TrueType fonts.