readme now points to html docs

status updated for 0.12.1


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

1 files changed, 3 insertions, 497 deletions

diff --git a/README b/README
index aead5893a..f5406a54e 100644
--- a/README
+++ b/README
@@ -1,18 +1,6 @@
 FOP readme
 
-	Content
-	1.  What is FOP?
-	2.  Downloading FOP
-	3.  Running FOP
-	4.  Features
-	5.  Limitations
-	6.  Compiling FOP
-	7.  Embedding FOP 
-	8.  Getting involved
-	9.  FOP Relevant Specifications
-	10.  License
-
-1.  What is FOP?
+    What is FOP?
     FOP is the world's first print formatter driven by XSL formatting
     objects. It is a Java 1.1 application that reads a formatting object
     tree and then turns it into a PDF document. The formatting object
@@ -21,490 +9,8 @@ FOP readme
     the case of XT) SAX events.
     
     FOP is part of Apache's XML project. The homepage of FOP is 
-    http:/xml.apache.org/fop (http:/xml.apache.org/fop). 
-
-
-2.  Downloading FOP
-
-  2.1. Downloading binaries
-    You can download the latest release version FOP 0.12.0 
-    (http://xml.apache.org/dist/fop_bin_0_12_0.jar). 
-    NOTE: you do not have to unjar or unzip this jar file.
-    To run FOP from the command line, see Running FOP. If you are 
-    interested in embedding FOP in a Java application of your own, see 
-    Embedding FOP.
-
-  2.2. Downloading source code
-    You can also download the source code v. 0.12.0 
-    (http://xml.apache.org/dist/fop_src_0_12_0.jar) as a jar file
-
-
-3.  Running FOP
-
-  3.1. Prerequisites
-    Following software must be installed:
-    a) Java 1.1.x or later
-    b) An XML parser which supports SAX and DOM like 
-       Xerces-J (http://xml.apache.org/xerces-j/index.html).
-    c) If you have to produce the flow objects files, which are the input for FOP, 
-       you need a transformation utility to create this files from your xml files. 
-       Normally this is an XSLT stylesheet processor like 
-       XT (http://www.jclark.com/xml/xt.html)
-       or XALAN (http://xml.apache.org/xalan/index.html). 
-
-  3.2. Starting FOP as an standalone application
-    There are three ways to run FOP from the command line.
-    a) Batch processing formatting objects (fo) files: 
-       java org.apache.fop.apps.CommandLine fo-file pdf-file
-    b) Batch processing xml files (includes production of the fo-files):
-       java org.apache.fop.apps.CommandLine xml-file xsl-file pdf-file
-    c) Previewing the fo-file:
-       java org.apache.fop.apps.AWTCommandLine fo-file
-    Each method uses next to the fop classes other packages. The following describes 
-       each method in detail.
-
-    3.2.1. Method One
-      One is to first use an XSLT engine to produce the formatting object tree as an 
-      XML document and then running the class org.apache.fop.apps.CommandLine with the
-      formatting object file name and PDF filename as arguments. You need to set classpath 
-      and set the used sax parser according to your enviroment
-      
-      Classpath settings: You will need to include FOP and your XML Parser 
-      in your classpath and so you might invoke FOP, if XP is your sax parser 
-      and Xerces-J your DOM parser: 
-      
-      java -cp fop_bin_0_12_0.jar;xp.jar;xerces.jar 
-           org.apache.fop.apps.CommandLine fo-file pdf-file
-
-      For historical reasons the standard sax parser for FOP is XP from James Clark. 
-      This will change in the future to Xerces-J, but at the moment you will need to 
-      set the property org.xml.sax.parser to any other SAX Parser class to use. 
-      The following example shows the command line, if you use Xerces-J: 
-      
-      java -Dorg.xml.sax.parser=org.apache.xerces.parsers.SAXParser
-         -cp fop_bin_0_12_0.jar;xerces.jar
-         org.apache.fop.apps.CommandLine fo-file pdf-file
-
-      PLEASE NOTE: Starting with v 0.12.1 [dev] the standard parser for FOP is xerces-J. 
-                   Therefore if you use xerces, you don't need to 
-                   set -Dorg.xml.sax.parser=org.apache.xerces.parsers.SAXParser
-
-    3.2.2. Method Two
-      Rather than performing transformation with an XSLT before invoking FOP, it is 
-      possible, if you use XT as your XSLT engine, to just call FOP and have it call 
-      XT for you. To do this, run the class org.apache.fop.apps.CommandLine with the 
-      source XML file name, XSL file name and PDF file name as arguments. You will 
-      need to include FOP, SAX, your SAX Parser and XT in your classpath and so you might 
-      invoke 
-      
-      java -cp fop_bin_0_12_0.jar;xt.jar;xp.jar;xerces.jar
-           org.apache.fop.apps.CommandLine xml-file xsl-file pdf-file
-
-      Again, if your SAX Parser is other than XP, you will need to set the property
-      org.xml.sax.parser to the SAX Parser class to use.
-
-      PLEASE NOTE: Starting with v 0.12.1 [dev] the standard parser for FOP is xerces-J. 
-                   Therefore the example will only work, if you use xerces. Otherwise
-                   you have to set the sax parser
+    http:/xml.apache.org/fop 
 
-    3.2.3. Method Three
-      If you already produced the FO file, you can preview the results of your 
-      transformation without using any pdf viewer by invoking FOP with the viewer 
-      application. You will need to include FOP and your XML Parser in your classpath 
-      
-      java -cp fop_bin_0_12_0.jar;xp.jar;xerces.jar
-           org.apache.fop.apps.AWTCommandLine fo-file 
-
-      The viewer uses the swing classes. 
-
-      Note: If you are using java 2 or later (i.e. jdk 1.2. or later) you can put all 
-            needed jar files into the subdirectory jdk1.2.x\jre\lib\ext (windows example). Then 
-            FOP can be started without classpath: 
-      
-            java org.apache.fop.apps.CommandLine fo-file pdf-file
-
-    
-  
-  3.3. Running FOP on MacOS  
-    Ensure that you have a recent MRJ, and that you have downloaded and
-    unpacked the XP and SAX distributions. The xp.jar and sax.jar files work
-    as is on MacOS.
-    
-    Drag the FOP jarfile onto the JBindery icon. When the first dialog
-    appears, type "org.apache.fop.apps.CommandLine" in the "Class name" field.
-    Using UNIX syntax, type the names of the input formatting-object file and
-    the output PDF in the "Optional parameters" field.
-    
-    Click on the Classpath icon. To add the xp.jar and sax.jar files, click
-    the "Add .zip file" button, navigate to the file in question, and click
-    Open.
-    
-    Once both are added (the FOP jarfile will already be in the list), click
-    Run. A "stdout" window will appear and display FOP runtime messages.
-      
-  
-  3.4. Problems
-    If you have problems running FOP, please have a look at the 
-    FOP FAQ (faq-running.html). If you don't find a solution there,
-    you can ask for help on the list fop-dev@xml.apache.org. Maybe it is a bug and 
-    maybe somebody is already working on it. 
-
-
-4.  Features
-
-  4.1. What's Implemented?
-      The following formatting objects and properties of the xsl-fo 
-      working draft are implemented. Please have also a look at the 
-      section on limitations (limitations.html)
-
-   1) Formatting Objects
-      root
-      layout-master-set 
-      simple-page-master 
-      region-body 
-      region-before 
-      region-after 
-      page-sequence 
-      sequence-specification 
-      sequence-specifier-single 
-      sequence-specifier-repeating 
-      sequence-specifier-alternating 
-      flow 
-      static-content 
-      block 
-      list-block 
-      list-item 
-      list-item-label 
-      list-item-body 
-      page-number 
-      display-sequence 
-      inline-sequence 
-      display-rule 
-      display-graphic 
-      table (minimal support)
-      table-column (minimal support)
-      table-body (minimal support)
-      table-row (minimal support)
-      table-cell (minimal support)
-
-   2) Properties
-      end-indent 
-      page-master-name 
-      page-master-first 
-      page-master-repeating 
-      page-master-odd 
-      page-master-even 
-      margin-top (only on pages and regions)
-      margin-bottom (only on pages and regions)
-      margin-left (only on pages and regions)
-      margin-right (only on pages and regions)
-      extent 
-      page-width 
-      page-height 
-      flow-name 
-      font-family 
-      font-style 
-      font-weight 
-      font-size 
-      line-height 
-      text-align 
-      text-align-last 
-      space-before.optimum 
-      space-after.optimum 
-      start-indent 
-      end-indent 
-      provisional-distance-between-starts 
-      provisional-label-separation 
-      rule-thickness 
-      color 
-      wrap-option 
-      white-space-treatment 
-      break-before 
-      break-after 
-      text-indent 
-      href
-      column-width
-      background-color
-      padding-top (only in conjunction with background color)
-      padding-left (only in conjunction with background color)
-      padding-bottom (only in conjunction with background color)
-      padding-right (only in conjunction with background color)
-
-
-5.  Limitations
-    Although FOP implements the above listed fo objects and properties, sometimes it does so 
-    only in a limited way. 
-  
-  5.1. list-block
-    The fo working draft allows describes two ways to markup lists.The list-block must 
-    have as children either: 1) pairs of fo:list-item-label and fo:list-item-body 
-    formatting objects, or 2) fo:list-item formatting objects.
-    At the moment FOP only implements the second way. Therefore a list has a basic 
-    structure like this: 
-    <fo:list-block>
-        <fo:list-item>
-           <fo:list-item-label><fo:block></fo:block></fo:list-item-label>
-           <fo:list-item-body><fo:block></fo:block></fo:list-item-body>
-        </fo:list-item>
-    </fo:list-block>
-  
-  5.2. Padding
-    Padding works in conjunction with indents and spaces. It is only implemented 
-    for blocks. At the moment padding can't be used to make extra space (indents+spaces
-    must be used), but only to control how much the background-color extends beyond
-    the content rectangle.
-  
-  5.3. Tables
-    There two limitations for tables: 1) FOP needs you to explicitly specify column widths 
-    2) Cells have to contain block-level FOs. They can't contain straight character data.
-    
-    A working basic example of a table looks like this:   
-    <fo:table>
-      <fo:table-column column-width="150pt"/>
-      <fo:table-column column-width="150pt"/>
-      <fo:table-body font-size="10pt" font-family="sans-serif">
-        <fo:table-row>
-          <fo:table-cell>
-            <fo:block>text</fo:block>
-          </fo:table-cell>
-          <fo:table-cell>
-            <fo:block>text</fo:block>
-          </fo:table-cell>
-        </fo:table-row>
-        <fo:table-row>
-          <fo:table-cell>
-            <fo:block>text</fo:block>
-          </fo:table-cell>
-          <fo:table-cell>
-            <fo:block>text</fo:block>
-          </fo:table-cell>
-        </fo:table-row>
-        <fo:table-row>
-          <fo:table-cell>
-            <fo:block>text</fo:block>
-          </fo:table-cell>
-          <fo:table-cell>
-            <fo:block>text</fo:block>
-          </fo:table-cell>
-        </fo:table-row>
-      </fo:table-body>
-    </fo:table>
+    HTML-Documentation can be found in the subdirectory /docs. 
 
-6.  Compiling FOP
 
-  6.1. Prerequisites
-    6.1.1. Java 1.1.x or later
-      If you use Java 1.1.x you must also seperately include the swing classes, which can
-      be found at the Sun website (http://java.sun.com/products/jfc/#download-swing). From 
-      Java 1.2 on (aka Java 2) they are part of the standard distribution. 
-    
-    6.1.2. An XML parser
-      An XML parser which supports DOM like Xerces-J 
-      (http://xml.apache.org/xerces-j/index.html).
-    
-    6.1.3. XT from James Clark
-      Some of the Java source code in FOP is generated from XML using
-      XSLT. XT must be used to generate this code.
-      XT is an XSL stylesheet processor written in java. At the moment you
-      can't use any other processor, because the make file makes use of some
-      proprietary features of Clark's xt which allow to write output in more
-      then one document. You can find XT at James Clark's website 
-      (http://www.jclark.com/xml/xt.html). You have to use XT version 19991105 
-      or later. (Under windows you shouldn't use the prepackaged xt.exe but also the
-      generic jar file, otherwise make won't work)
-      
-      XT relies on an sax parser like XP (also J. Clark), which can be
-      downloaded at James Clark's Website (http://www.jclark.com/xml/xp/index.html)
-    
-    6.1.4. make
-      Under windows it has been reported that the use of the cygnus solutions port 
-      of the GNU utilities works. You can find it at 
-      Cygnus Solutions (http://sourceware.cygnus.com/cygwin/)
-  
-  6.2. Compiling FOP on MacOS
-    We strongly recommend the use of Codewarrior Java. You will find 
-    a link to more information in the near future.
-
-
-7.  Embedding FOP 
-
-     Instantiate org.apache.fop.apps.Driver. Once this class is 
-     instantiated, methods are called to set the
-     Renderer to use, the (possibly multiple) ElementMapping(s) to
-     use and the PrintWriter to use to output the results of the
-     rendering (where applicable). In the case of the Renderer and
-     ElementMapping(s), the Driver may be supplied either with the
-     object itself, or the name of the class, in which case Driver will
-     instantiate the class itself. The advantage of the latter is it
-     enables runtime determination of Renderer and ElementMapping(s).
-  
-     Once the Driver is set up, the buildFOTree method
-     is called. Depending on whether DOM or SAX is being used, the
-     invocation of the method is either buildFOTree(Document) or
-     buildFOTree(Parser, InputSource) respectively.
-  
-     A third possibility may be used to build the FO Tree, namely
-     calling getDocumentHandler() and firing the SAX events yourself.
-  
-     Once the FO Tree is built, the format() and render() methods may be
-     called in that order.
-  
-     Here is an example use of Driver from CommandLine.java:
-
-     Driver driver = new Driver();
-     driver.setRenderer("org.apache.fop.render.pdf.PDFRenderer", version);
-     driver.addElementMapping("org.apache.fop.fo.StandardElementMapping");
-     driver.addElementMapping("org.apache.fop.svg.SVGElementMapping");
-     driver.setWriter(new PrintWriter(new FileWriter(args[1])));
-     driver.buildFOTree(parser, fileInputSource(args[0]));
-     driver.format();
-     driver.render();
-
-8.  Getting involved
-  8.1. First steps
-  1. Subscribe to fop-dev@xml.apache.org by sending an email 
-        to fop-dev-subscribe@xml.apache.org
-  2. Read the archives to fop-dev to get an idea of the issues being 
-        discussed. 
-  3. Subscribe to fop-cvs@xml.apache.org by sending an email to 
-        fop-cvs-subscribe@xml.apache.org (it is important 
-        that you follow changes being made). 
-  4. Try :-) to wrap your head around the XSL working draft. 
-  5. Get CVS working on your system. 
-  6. Ask, on fop-dev, any questions you have at all about the code, design, etc. 
-  7. When you feel comfortable modifying the code, send diffs to 
-        fop-dev with your contributions. 
-  8. Have fun!
-  
-  8.2. The Ways of FOP
-    The following shows an example use of FOP from org.apache.fop.apps.CommandLine.java:
-
-    1)   Driver driver = new Driver();
-    2)   driver.setRenderer ("org.apache.fop.render.pdf.PDFRenderer", version);
-    3)   driver.addElementMapping ("org.apache.fop.fo.StandardElementMapping");
-    3)   driver.addElementMapping ("org.apache.fop.svg.SVGElementMapping");
-    4)   driver.setWriter (new PrintWriter(new FileWriter(args[1])));
-    5)   driver.buildFOTree(parser, fileInputSource(args[0]));
-    6)   driver.format();
-    7)   driver.render();
-
-    1. step: Initiate class Driver
-       Driver is the primary class that drives overall FOP process.
-
-    2. step: Set Renderer
-       You set the renderer for the output format of your choice. At the moment 3 formats are 
-       supported: a) pdf (org.apache.fop.render.pdf.PDFRenderer)
-    b) awt (org.apache.fop.render.awt.AWTRenderer)
-    c) xml (org.apache.fop.render.xml.XMLRenderer)
-
-       All renderers implement the interface Renderer which defines the methods an area 
-       needs to be laid out. 
-
-       The xml renderer is meant for debugging purposes.
-
-       The interface Renderer takes a string as a version argument indicating the application 
-       that is producing the output. Many output formats like PDF allow the inclusion 
-       of a "Producer" string. 
-
-
-    3. step: Set Element Mapping
-       By setting the element mapping you choose the dictionaries of elements which 
-       FOP can handle. At the moment two dictionaries are available: 
-    a) Standard xsl elements (org.apache.fop.fo.StandardElementMapping)
-    b) Graphic elements described by SVG (org.apache.fop.svg.SVGElementMapping)
-
-       All element mappings implement the interface ElementMapping.
-
-    4. step: Set output destination 
-       Normally this will be a Printwriter of some sort. If you are just displaying the 
-       output on screen you can skip this step.
-
-    5. step: Build FO Tree
-       Builds the  tree of formatting objects contained in the input source. Either walks 
-       the tree of the input document (DOM) or uses SAX events to build up the tree 
-       by looking up the definitions of the fo in the element mappings. Depending on 
-       whether DOM or SAX is being used, the invocation of the method is either 
-       buildFOTree(Document) or buildFOTree(Parser, InputSource) respectively.
-
-    6. step: Build Area Tree from FO Tree
-       By calling format() of the driver class the fo tree is written/formatted into 
-       a area tree. Every formatting object knows how to layout itself, that is every 
-       formatting object has a an layout method which is now called to produce an area. 
-       The setup of the font info for the renderer is also done in this step. 
-
-    7. step: Renderer renders Areas
-       The renderer, which has been set in step 2, is given the area tree. It uses the 
-       layout information to output it in its specific format. Example: For the PDF 
-       renderer there is a set of methods to create a  pdf file containing the FOP 
-       supported kind of layout features.
-
-    --------------------------------------------------------------------------
-    If you want to extend the functionality of FOP by adding new formatting objects, 
-       you should do the following: 
-
-    1. FO Object: Write a class which contains the description of your formatting 
-          object and put it into the package fop.fo.flow, fop.fo.pagination (if it 
-          is a property it goes to fop.fo.properties. The classes in this package are 
-          generated via an xslt stylesheet located in codegen/properties.xml)
-    2. Element Mapping: Add it to the list in fop.fo.StandardElementMapping (if it 
-          is a property you need to add it to fop.fo.PropertyListBuilder)
-    3. Area: Either your need can be fulfilled within one of the existing classes 
-          in fop.layout, then just add the code to handle the new fo/property or you 
-          must write a new one.
-    4. Renderer: Choose the renderer you are interested in. If you worked on an 
-          existing layout class you must add code to handle the new features to the 
-          already existing area specific method in the renderer class. Otherwise you 
-          have to add a new method. 
-
-
-9.  FOP Relevant Specifications
-  
-    XML Recommendation (http://www.w3.org/TR/REC-xml)
-    XSL-FO Working Draft (http://www.w3.org/TR/WD-xsl/)
-    XSLT Recommendation (http://www.w3.org/TR/xslt)
-    PDF Documentation (http://partners.adobe.com/asn/developer/acrosdk/DOCS/pdfspec.pdf)
-    Simple API for XML (SAX) (http://www.megginson.com/SAX/)
-    Document Object Model (DOM) (http://www.w3.org/TR/REC-DOM-Level-1)
-    Namespaces in XML Recommendation (http://www.w3.org/TR/REC-xml-names/)
-    Java JDK 1.1 Documentation (http://java.sun.com/products/jdk/1.1/docs/index.html)
-
-
-10.  License
-
-     The Apache Software License, Version 1.1
-     Copyright (C) 1999 The Apache Software Foundation. All rights reserved.
-     Redistribution and use in source and binary forms, with or without modification, 
-     are permitted provided that the following conditions are met:
-    1. Redistributions of  source code must  retain the above copyright  notice,
-       this list of conditions and the following disclaimer.
-    2. Redistributions in binary form must reproduce the above copyright notice,
-       this list of conditions and the following disclaimer in the documentation
-       and/or other materials provided with the distribution.
-    3. The end-user documentation included with the redistribution, if any, must
-        include  the following  acknowledgment:  "This product includes  software
-        developed  by the  Apache Software Foundation  (http://www.apache.org/)."
-        Alternately, this  acknowledgment may  appear in the software itself,  if
-        and wherever such third-party acknowledgments normally appear.
-    4. The names "FOP" and  "Apache Software Foundation"  must not be used to
-        endorse  or promote  products derived  from this  software without  prior
-        written permission. For written permission, please contact
-        apache@apache.org.
-    5. Products  derived from this software may not  be called "Apache", nor may
-        "Apache" appear  in their name,  without prior written permission  of the
-        Apache Software Foundation.
-     
-       THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
-       INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
-       FITNESS  FOR A PARTICULAR  PURPOSE ARE  DISCLAIMED.  IN NO  EVENT SHALL  THE
-       APACHE SOFTWARE  FOUNDATION  OR ITS CONTRIBUTORS  BE LIABLE FOR  ANY DIRECT,
-       INDIRECT, INCIDENTAL, SPECIAL,  EXEMPLARY, OR CONSEQUENTIAL  DAMAGES (INCLU-
-       DING, BUT NOT LIMITED TO, PROCUREMENT  OF SUBSTITUTE GOODS OR SERVICES; LOSS
-       OF USE, DATA, OR  PROFITS; OR BUSINESS  INTERRUPTION)  HOWEVER CAUSED AND ON
-       ANY  THEORY OF LIABILITY,  WHETHER  IN CONTRACT,  STRICT LIABILITY,  OR TORT
-       (INCLUDING  NEGLIGENCE OR  OTHERWISE) ARISING IN  ANY WAY OUT OF THE  USE OF
-       THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-    
-       This software  consists of voluntary contributions made  by many individuals
-       on  behalf of the Apache Software  Foundation and was  originally created by
-       James Tauber <jtauber@jtauber.com>. For more  information on the Apache 
-       Software Foundation, please see http://www.apache.org/ (http://www.apache.org/).