Update lib README based on recent findings.

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

1 files changed, 60 insertions, 42 deletions

diff --git a/lib/README.txt b/lib/README.txt
index 8d6356eaa..46c716b77 100644
--- a/lib/README.txt
+++ b/lib/README.txt
@@ -51,58 +51,33 @@ Normal Dependencies
     
     Apache License v2.0
 
-- Apache XML Commons Externals
+- Apache XML Commons Externals (JAXP API)
 
-    xml-apis-ext-*.jar
+    xml-apis.jar
     http://xml.apache.org/commons/components/external/
-    (additional DOM APIs from W3C, like SVG, SMIL and Simple API for CSS)
+    (the JAXP API, plus SAX and various W3C DOM Java bindings,
+    maintained in XML Commons Externals)
     
     Apache License v2.0 (applies to the distribution)
+    SAX is in the public domain
+        http://www.saxproject.org/copying.html
     W3C Software Notice and License (applies to the various DOM Java bindings)
     W3C Document License (applies to the DOM documentation)
         http://www.w3.org/Consortium/Legal/copyright-software
         http://www.w3.org/Consortium/Legal/copyright-documents
         http://www.w3.org/Consortium/Legal/
 
-
-
-Special Dependencies
------------------------
-
-The special dependencies are the whole JAXP set which required for users
-on JDK 1.3.x which doesn't include JAXP. But it is also interesting for
-users on JDKs >= 1.4 if they want to replace the default JAXP 
-implementation delivered by the JDK.
-
-Replacing the default implementations involves understanding the 
-"Endorsed Standards Override Mechanism".
-More information can be found here:
-http://java.sun.com/j2se/1.4.2/docs/guide/standards/index.html
-
-- JAXP API
-
-    xml-apis.jar
+    xml-apis-ext-*.jar
     http://xml.apache.org/commons/components/external/
-    (the JAXP API, plus SAX and various W3C DOM Java bindings,
-    maintained in XML Commons Externals)
+    (additional DOM APIs from W3C, like SVG, SMIL and Simple API for CSS)
     
     Apache License v2.0 (applies to the distribution)
-    SAX is in the public domain
-        http://www.saxproject.org/copying.html
     W3C Software Notice and License (applies to the various DOM Java bindings)
     W3C Document License (applies to the DOM documentation)
         http://www.w3.org/Consortium/Legal/copyright-software
         http://www.w3.org/Consortium/Legal/copyright-documents
         http://www.w3.org/Consortium/Legal/
 
-- Apache Xerces-J
-
-    xercesImpl-*.jar
-    http://xerces.apache.org
-    (JAXP-compliant XML parser and DOM Level 3 implementation)
-    
-    Apache License v2.0
-
 - Apache Xalan-J
 
     xalan-*.jar and serializer-*.jar
@@ -116,6 +91,45 @@ http://java.sun.com/j2se/1.4.2/docs/guide/standards/index.html
         (see xalan.runtime.LICENSE.txt)
 
 
+Special Dependencies
+-----------------------
+
+- Apache Xerces-J
+
+    xercesImpl-*.jar
+    http://xerces.apache.org
+    (JAXP-compliant XML parser and DOM Level 3 implementation)
+    
+    Apache License v2.0
+    
+    Xerces-J is not directly referenced by FOP or any of its dependencies.
+    
+
+A note on JAXP
+-----------------------
+
+Since Java 1.4, JAXP (Java API for XML Processing) is part of the 
+JRE/JDK. Every JVM includes the APIs and an implementation. However, 
+older JREs often contain implementations with bugs that are triggered 
+by code in Apache FOP and therefore need to be overridden. Now, since 
+JAXP is part of the class library, special precautions are necessary 
+to replace the original implementations. This is not done by simply 
+adding new JARs to the classpath as these classes would never be 
+loaded (due to Java's class loader hierarchy). 
+
+Replacing the default implementations involves understanding the 
+"Endorsed Standards Override Mechanism".
+More information can be found here:
+http://java.sun.com/j2se/1.4.2/docs/guide/standards/index.html
+
+See also:
+http://xml.apache.org/xalan-j/faq.html#faq-N100EF
+
+Essentially, you have two different possibilities:
+- add the replacement JARs in the jre/lib/endorsed directory of your JRE.
+- Use the -Xbootclasspath/p: option when starting the JVM (may not be
+  available for every JVM).
+
 
 Optional Dependencies
 ------------------------
@@ -123,15 +137,13 @@ Optional Dependencies
 The following libraries are not bundled with FOP and must be installed manually.
 Please make sure you've read the license of each package.
 
-- JIMI Image library
-
-    http://java.sun.com/products/jimi
-    Sun Binary Code License
-
-- JAI (Java Advanced Imaging API)
+- JAI Image I/O Tools
 
-    http://java.sun.com/products/java-media/jai
-    Java Research License and Java Distribution License (Check which one applies to you!)
+    https://jai-imageio.dev.java.net/
+    BSD license
+    
+    Note: Not the whole JAI is needed, only the ImageIO-compatible codecs
+    packaged as "Image I/O Tools". The name may be misleading.
 
 - JEuclid (MathML implementation, for the MathML extension)
 
@@ -164,4 +176,10 @@ Additional development-time dependencies
 
     (not bundled, provided by Apache Ant or your IDE)
     http://www.junit.org
-    Common Public License V1.0
\ No newline at end of file
+    Common Public License V1.0
+
+- XMLUnit (optional)
+
+    (not bundled, to be added to your Apache Ant installation)
+    http://xmlunit.sourceforge.net/
+    BSD style license
\ No newline at end of file