Merged revisions 687576,687657,687786,688078,688087,688139,688508,688633,688652-688653,688660,688664,688666,688674,688698,688994,689000 via svnmerge from

https://svn.eu.apache.org/repos/asf/xmlgraphics/fop/trunk

........
  r687576 | maxberger | 2008-08-21 07:25:40 +0100 (Thu, 21 Aug 2008) | 1 line
  
  Included patched retroweaver which does not modify Boolean.valueOf
........
  r687657 | jeremias | 2008-08-21 09:51:50 +0100 (Thu, 21 Aug 2008) | 1 line
  
  Added an FAQ entry about the element mismatch error message.
........
  r687786 | jeremias | 2008-08-21 16:49:13 +0100 (Thu, 21 Aug 2008) | 1 line
  
  Added some performance statistics to MemoryEater.
........
  r688078 | jeremias | 2008-08-22 14:02:37 +0100 (Fri, 22 Aug 2008) | 1 line
  
  Final statistics output after the test with average speed indication.
........
  r688087 | jeremias | 2008-08-22 15:16:58 +0100 (Fri, 22 Aug 2008) | 2 lines
  
  Merge from branch https://svn.apache.org/repos/asf/xmlgraphics/fop/branches/fop-0_95:
  Fixed text stroking in SVG when the stroke-width is zero.
........
  r688139 | maxberger | 2008-08-22 19:08:36 +0100 (Fri, 22 Aug 2008) | 1 line
  
  minor spelling mistakes
........
  r688508 | maxberger | 2008-08-24 14:12:02 +0100 (Sun, 24 Aug 2008) | 2 lines
  
  Moved DataURIResolver from FOP to commons; use new URIResolver registry
........
  r688633 | jeremias | 2008-08-25 07:42:44 +0100 (Mon, 25 Aug 2008) | 2 lines
  
  Fixed memory leak in property cache (not cleaning stale PropertyCache$CacheEntry instances).
  Special thanks to Andreas Delmelle for his help!
........
  r688652 | maxberger | 2008-08-25 09:19:13 +0100 (Mon, 25 Aug 2008) | 1 line
  
  Re-added moved class as deprecated
........
  r688653 | jeremias | 2008-08-25 09:23:31 +0100 (Mon, 25 Aug 2008) | 1 line
  
  Added a page on metadata (partly ported from the FOP Wiki).
........
  r688660 | jeremias | 2008-08-25 09:41:29 +0100 (Mon, 25 Aug 2008) | 2 lines
  
  Fixed example.
  Thanks for noticing, Pascal Sancho!
........
  r688664 | jeremias | 2008-08-25 09:59:27 +0100 (Mon, 25 Aug 2008) | 1 line
  
  Minor documentation improvements, most notably a comment about keep-together="always".
........
  r688666 | maxberger | 2008-08-25 10:00:27 +0100 (Mon, 25 Aug 2008) | 1 line
  
  CommonURIResolver is no longer a singleton
........
  r688674 | jeremias | 2008-08-25 10:15:22 +0100 (Mon, 25 Aug 2008) | 1 line
  
  Hmm, I missed the redirects for the 0.95 release.
........
  r688698 | jeremias | 2008-08-25 12:24:15 +0100 (Mon, 25 Aug 2008) | 2 lines
  
  Merge from 0.95 branch:
  Fixed jar-sources target.
........
  r688994 | acumiskey | 2008-08-26 09:34:45 +0100 (Tue, 26 Aug 2008) | 1 line
  
  Deprecate UnitConv now that it resides only in xmlgraphics commons.
........
  r689000 | acumiskey | 2008-08-26 09:59:31 +0100 (Tue, 26 Aug 2008) | 1 line
  
  Forgot to add deprecated public statics.
........


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

7 files changed, 576 insertions, 32 deletions

diff --git a/src/documentation/content/.htaccess b/src/documentation/content/.htaccess
index 561900fde..5203ea63e 100644
--- a/src/documentation/content/.htaccess
+++ b/src/documentation/content/.htaccess
@@ -1,28 +1,38 @@
 # redirect moved files
-RedirectMatch Permanent ^/fop/anttask(.*) http://xmlgraphics.apache.org/fop/0.94/anttask$1
-RedirectMatch Permanent ^/fop/compiling(.*) http://xmlgraphics.apache.org/fop/0.94/compiling$1
-RedirectMatch Permanent ^/fop/configuration(.*) http://xmlgraphics.apache.org/fop/0.94/configuration$1
-RedirectMatch Permanent ^/fop/embedding(.*) http://xmlgraphics.apache.org/fop/0.94/embedding$1
-RedirectMatch Permanent ^/fop/extensions(.*) http://xmlgraphics.apache.org/fop/0.94/extensions$1
-RedirectMatch Permanent ^/fop/fonts(.*) http://xmlgraphics.apache.org/fop/0.94/fonts$1
-RedirectMatch Permanent ^/fop/graphics(.*) http://xmlgraphics.apache.org/fop/0.94/graphics$1
-RedirectMatch Permanent ^/fop/hyphenation(.*) http://xmlgraphics.apache.org/fop/0.94/hyphenation$1
-RedirectMatch Permanent ^/fop/intermediate(.*) http://xmlgraphics.apache.org/fop/0.94/intermediate$1
-RedirectMatch Permanent ^/fop/output(.*) http://xmlgraphics.apache.org/fop/0.94/output$1
-RedirectMatch Permanent ^/fop/pdfa(.*) http://xmlgraphics.apache.org/fop/0.94/pdfa$1
-RedirectMatch Permanent ^/fop/pdfencryption(.*) http://xmlgraphics.apache.org/fop/0.94/pdfencryption$1
-RedirectMatch Permanent ^/fop/pdfx(.*) http://xmlgraphics.apache.org/fop/0.94/pdfx$1
-RedirectMatch Permanent ^/fop/running(.*) http://xmlgraphics.apache.org/fop/0.94/running$1
-RedirectMatch Permanent ^/fop/servlets(.*) http://xmlgraphics.apache.org/fop/0.94/servlets$1
-RedirectMatch Permanent ^/fop/upgrading(.*) http://xmlgraphics.apache.org/fop/0.94/upgrading$1
+RedirectMatch Permanent ^/fop/anttask(.*) http://xmlgraphics.apache.org/fop/0.95/anttask$1
+RedirectMatch Permanent ^/fop/compiling(.*) http://xmlgraphics.apache.org/fop/0.95/compiling$1
+RedirectMatch Permanent ^/fop/configuration(.*) http://xmlgraphics.apache.org/fop/0.95/configuration$1
+RedirectMatch Permanent ^/fop/embedding(.*) http://xmlgraphics.apache.org/fop/0.95/embedding$1
+RedirectMatch Permanent ^/fop/extensions(.*) http://xmlgraphics.apache.org/fop/0.95/extensions$1
+RedirectMatch Permanent ^/fop/fonts(.*) http://xmlgraphics.apache.org/fop/0.95/fonts$1
+RedirectMatch Permanent ^/fop/graphics(.*) http://xmlgraphics.apache.org/fop/0.95/graphics$1
+RedirectMatch Permanent ^/fop/hyphenation(.*) http://xmlgraphics.apache.org/fop/0.95/hyphenation$1
+RedirectMatch Permanent ^/fop/intermediate(.*) http://xmlgraphics.apache.org/fop/0.95/intermediate$1
+RedirectMatch Permanent ^/fop/output(.*) http://xmlgraphics.apache.org/fop/0.95/output$1
+RedirectMatch Permanent ^/fop/pdfa(.*) http://xmlgraphics.apache.org/fop/0.95/pdfa$1
+RedirectMatch Permanent ^/fop/pdfencryption(.*) http://xmlgraphics.apache.org/fop/0.95/pdfencryption$1
+RedirectMatch Permanent ^/fop/pdfx(.*) http://xmlgraphics.apache.org/fop/0.95/pdfx$1
+RedirectMatch Permanent ^/fop/running(.*) http://xmlgraphics.apache.org/fop/0.95/running$1
+RedirectMatch Permanent ^/fop/servlets(.*) http://xmlgraphics.apache.org/fop/0.95/servlets$1
+RedirectMatch Permanent ^/fop/upgrading(.*) http://xmlgraphics.apache.org/fop/0.95/upgrading$1
 
 # redirect to versioned documentation
-Redirect Temp /fop/stable http://xmlgraphics.apache.org/fop/0.94
+# Current stable release
+Redirect Temp /fop/stable http://xmlgraphics.apache.org/fop/0.95
+
+# Current unstable release (or trunk if no beta is the latest release)
+Redirect Temp /fop/unstable http://xmlgraphics.apache.org/fop/trunk
+
+# Latest release
 Redirect Temp /fop/current http://xmlgraphics.apache.org/fop/0.95
-Redirect Temp /fop/unstable http://xmlgraphics.apache.org/fop/0.95
-Redirect Temp /fop/latest http://xmlgraphics.apache.org/fop/trunk
-Redirect Temp /fop/maintenance http://xmlgraphics.apache.org/fop/0.93
-Redirect Temp /fop/previous http://xmlgraphics.apache.org/fop/0.93
-Redirect Temp /fop/0.90alpha1 http://xmlgraphics.apache.org/fop/0.93
-Redirect Temp /fop/0.91beta http://xmlgraphics.apache.org/fop/0.93
-Redirect Temp /fop/0.92beta http://xmlgraphics.apache.org/fop/0.93
+Redirect Temp /fop/latest http://xmlgraphics.apache.org/fop/0.95
+
+# Previous stable release
+Redirect Temp /fop/previous http://xmlgraphics.apache.org/fop/0.94
+
+# Old releases
+Redirect Temp /fop/maintenance http://xmlgraphics.apache.org/fop/0.94
+Redirect Temp /fop/0.90alpha1 http://xmlgraphics.apache.org/fop/0.94
+Redirect Temp /fop/0.91beta http://xmlgraphics.apache.org/fop/0.94
+Redirect Temp /fop/0.92beta http://xmlgraphics.apache.org/fop/0.94
+Redirect Temp /fop/0.93 http://xmlgraphics.apache.org/fop/0.94
diff --git a/src/documentation/content/xdocs/0.95/metadata.xml b/src/documentation/content/xdocs/0.95/metadata.xml
new file mode 100644
index 000000000..8c273fff5
--- /dev/null
+++ b/src/documentation/content/xdocs/0.95/metadata.xml
@@ -0,0 +1,243 @@
+<?xml version="1.0" standalone="no"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+<!-- $Id$ -->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd">
+<document>
+  <header>
+    <title>Metadata</title>
+  </header>
+  <body>
+    <section id="overview">
+      <title>Overview</title>
+      <p>
+        Document metadata is an important tool for categorizing and finding documents.
+        Various formats support different kinds of metadata representation and to
+        different levels. One of the more popular and flexible means of representing
+        document or object metadata is
+        <a href="http://www.adobe.com/products/xmp/">XMP (eXtensible Metadata Platform, specified by Adobe)</a>.
+        PDF 1.4 introduced the use of XMP. The XMP specification lists recommendation for
+        embedding XMP metdata in other document and image formats. Given its flexibility it makes
+        sense to make use this approach in the XSL-FO context. Unfortunately, unlike SVG which
+        also refers to XMP, XSL-FO doesn't recommend a preferred way of specifying document and
+        object metadata. Therefore, there's no portable way to represent metadata in XSL-FO
+        documents. Each implementation does it differently.
+      </p>
+    </section>
+    <section id="xmp-in-fo">
+      <title>Embedding XMP in an XSL-FO document</title>
+      <p>
+        As noted above, there's no officially recommended way to embed metadata in XSL-FO.
+        Apache FOP supports embedding XMP in XSL-FO. Currently, only support for document-level
+        metadata is implemented. Object-level metadata will be implemented when there's
+        interest.
+      </p>
+      <p>
+        Document-level metadata can be specified in the <code>fo:declarations</code> element.
+        XMP specification recommends to use <code>x:xmpmeta</code>, <code>rdf:RDF</code>, and
+        <code>rdf:Description</code> elements as shown in example below. Both
+        <code>x:xmpmeta</code> and <code>rdf:RDF</code> elements are recognized as the top-level
+        element introducing an XMP fragment (as per the XMP specification).
+      </p>
+      <section id="xmp-example">
+        <title>Example</title>
+        <source><![CDATA[[..]
+</fo:layout-master-set>
+<fo:declarations>
+  <x:xmpmeta xmlns:x="adobe:ns:meta/">
+    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
+      <rdf:Description rdf:about=""
+          xmlns:dc="http://purl.org/dc/elements/1.1/">
+        <!-- Dublin Core properties go here -->
+        <dc:title>Document title</dc:title>
+        <dc:creator>Document author</dc:creator>
+        <dc:description>Document subject</dc:description>
+      </rdf:Description>
+      <rdf:Description rdf:about=""
+          xmlns:xmp="http://ns.adobe.com/xap/1.0/">
+        <!-- XMP properties go here -->
+        <xmp:CreatorTool>Tool used to make the PDF</xmp:CreatorTool>
+      </rdf:Description>
+    </rdf:RDF>
+  </x:xmpmeta>
+</fo:declarations>
+<fo:page-sequence ...
+[..]]]></source>
+        <note>
+          <code>fo:declarations</code> <strong>must</strong> be declared after
+          <code>fo:layout-master-set</code> and before the first <code>page-sequence</code>.
+        </note>
+      </section>
+    </section>
+    <section id="xmp-impl-in-fop">
+      <title>Implementation in Apache FOP</title>
+      <p>
+        Currently, XMP support is only available for PDF output.
+      </p>
+      <p>
+        Originally, you could set some metadata information through FOP's FOUserAgent by
+        using its set*() methods (like setTitle(String) or setAuthor(String). These values are
+        directly used to set value in the PDF Info object. Since PDF 1.4, adding metadata as an
+        XMP document to a PDF is possible. That means that there are now two mechanisms in PDF
+        that hold metadata.
+      </p>
+      <p>
+        Apache FOP now synchronizes the Info and the Metadata object in PDF, i.e. when you
+        set the title and the author through the FOUserAgent, the two values will end up in
+        the (old) Info object and in the new Metadata object as XMP content. If instead of
+        FOUserAgent, you embed XMP metadata in the XSL-FO document (as shown above), the
+        XMP metadata will be used as-is in the PDF Metadata object and some values from the
+        XMP metadata will be copied to the Info object to maintain backwards-compatibility
+        for PDF readers that don't support XMP metadata.
+      </p>
+      <p>
+        The mapping between the Info and the Metadata object used by Apache FOP comes from
+        the <a href="http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=38920">PDF/A-1 specification</a>.
+        For convenience, here's the mapping table:
+      </p>
+      <table>
+        <tr>
+          <th colspan="2">Document information dictionary</th>
+          <th colspan="3">XMP</th>
+        </tr>
+        <tr>
+          <th>Entry</th>
+          <th>PDF type</th>
+          <th>Property</th>
+          <th>XMP type</th>
+          <th>Category</th>
+        </tr>
+        <tr>
+          <td>Title</td>
+          <td>text string</td>
+          <td>dc:title</td>
+          <td>Text</td>
+          <td>External</td>
+        </tr>
+        <tr>
+          <td>Author</td>
+          <td>text string</td>
+          <td>dc:creator</td>
+          <td>seq Text</td>
+          <td>External</td>
+        </tr>
+        <tr>
+          <td>Subject</td>
+          <td>text string</td>
+          <td>dc:description["x-default"]</td>
+          <td>Text</td>
+          <td>External</td>
+        </tr>
+        <tr>
+          <td>Keywords</td>
+          <td>text string</td>
+          <td>pdf:Keywords</td>
+          <td>Text</td>
+          <td>External</td>
+        </tr>
+        <tr>
+          <td>Creator</td>
+          <td>text string</td>
+          <td>xmp:CreatorTool</td>
+          <td>Text</td>
+          <td>External</td>
+        </tr>
+        <tr>
+          <td>Producer</td>
+          <td>text string</td>
+          <td>pdf:Producer</td>
+          <td>Text</td>
+          <td>Internal</td>
+        </tr>
+        <tr>
+          <td>CreationDate</td>
+          <td>date</td>
+          <td>xmp:CreationDate</td>
+          <td>Date</td>
+          <td>Internal</td>
+        </tr>
+        <tr>
+          <td>ModDate</td>
+          <td>date</td>
+          <td>xmp:ModifyDate</td>
+          <td>Date</td>
+          <td>Internal</td>
+        </tr>
+      </table>
+      <note>
+        "Internal" in the Category column means that the user should not set this value.
+        It is set by the application. 
+      </note>
+      <note>
+        The "Subject" used to be mapped to <code>dc:subject</code> in the initial publication of
+        PDF/A-1 (ISO 19005-1). In the
+        <a href="http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=45613">Technical Corrigendum 1</a>
+        this was changed to map to <code>dc:description["x-default"]</code>. 
+      </note>
+      <section id="namespaces">
+        <title>Namespaces</title>
+        <p>
+          Metadata is made of property sets where each property set uses a different namespace URI.
+        </p>
+        <p>
+          The following is a listing of namespaces that Apache FOP recognizes and acts upon,
+          mostly to synchronize the XMP metadata with the PDF Info dictionary: 
+        </p>
+        <table>
+          <tr>
+            <th>Set/Schema</th>
+            <th>Namespace Prefix</th>
+            <th>Namespace URI</th>
+          </tr>
+          <tr>
+            <td>Dublin Core</td>
+            <td>dc</td>
+            <td>http://purl.org/dc/elements/1.1/</td>
+          </tr>
+          <tr>
+            <td>XMP Basic</td>
+            <td>xmp</td>
+            <td>http://ns.adobe.com/xap/1.0/</td>
+          </tr>
+          <tr>
+            <td>Adobe PDF Schema</td>
+            <td>pdf</td>
+            <td>http://ns.adobe.com/pdf/1.3/</td>
+          </tr>
+        </table>
+        <p>
+          Please refer to the <a href="http://partners.adobe.com/public/developer/en/xmp/sdk/XMPspecification.pdf">XMP Specification</a>
+          for information on other metadata namespaces.
+        </p>
+        <p>
+          Property sets (Namespaces) not listed here are simply passed through to the final
+          document (if supported). That is useful if you want to specify a custom metadata
+          schema.
+        </p>
+      </section>
+    </section>
+    <section id="links">
+      <title>Links</title>
+      <ul>
+        <li><a href="http://www.adobe.com/products/xmp/">Adobe's Extensible Metadata Platform (XMP) website</a></li>
+        <li><a href="http://partners.adobe.com/public/developer/en/xmp/sdk/XMPspecification.pdf">Adobe XMP Specification</a></li>
+        <li><a href="http://partners.adobe.com/public/developer/en/xmp/sdk/XMPspecification.pdf">Adobe XMP Specification</a></li>
+        <li><a href="http://dublincore.org/">http://dublincore.org/</a></li>
+      </ul>
+    </section>
+  </body>
+</document>
diff --git a/src/documentation/content/xdocs/0.95/pdfa.xml b/src/documentation/content/xdocs/0.95/pdfa.xml
index 1b3b75561..bfa1ae33e 100644
--- a/src/documentation/content/xdocs/0.95/pdfa.xml
+++ b/src/documentation/content/xdocs/0.95/pdfa.xml
@@ -28,9 +28,6 @@
   <body>
     <section id="overview">
       <title>Overview</title>
-      <warning>
-        Support for PDF/A is available beginning with version 0.92.
-      </warning>
       <p>
         PDF/A is a standard which turns PDF into an "electronic document file 
         format for long-term preservation". PDF/A-1 is the first part of the 
diff --git a/src/documentation/content/xdocs/faq.xml b/src/documentation/content/xdocs/faq.xml
index a75cd41e0..ac2693d8b 100644
--- a/src/documentation/content/xdocs/faq.xml
+++ b/src/documentation/content/xdocs/faq.xml
@@ -385,6 +385,47 @@
         </p>
       </answer>
     </faq>
+    <faq id="saxexception-mismatch">
+      <question>I get a SAXException: Mismatch: page-sequence vs. root
+        (or similar).</question>
+      <answer>
+        <p>
+          The full exception usually looks similar to this:
+        </p>
+        <source>Mismatch: page-sequence (http://www.w3.org/1999/XSL/Format) vs. root
+        (http://www.w3.org/1999/XSL/Format)</source>
+        <p>
+          This exception is usually a follow-up error after another exception. Sometimes
+          the original exception gets swallowed by Xalan's default <code>ErrorListener</code>
+          (should be fixed in the latest Xalan release).
+        </p>
+        <p>
+          The work-around is to set an explicit <code>ErrorListener</code> on the
+          <code>Transformer</code>. The <code>ErrorListener</code> can be as simple as this:
+        </p>
+        <source><![CDATA[
+import javax.xml.transform.ErrorListener;
+import javax.xml.transform.TransformerException;
+
+public class DefaultErrorListener implements ErrorListener {
+    
+    public void warning(TransformerException exc) {
+        System.err.println(exc.toString());
+    }
+
+    public void error(TransformerException exc)
+            throws TransformerException {
+        throw exc;
+    }
+
+    public void fatalError(TransformerException exc)
+            throws TransformerException {
+        throw exc;
+    }
+
+}]]></source>
+      </answer>
+    </faq>
   </part>
   <part id="part-output">
     <title>Problems with FOP output</title>
@@ -551,8 +592,10 @@ Check the following:</p>
         text flows into adjacent cells/block, obscuring stuff there.</question>
       <answer>
         <p>
-          Clipping as specified by the <code>overflow="hidden"</code> is not yet
-          implemented.  If you have long words overflowing table cells, try to
+          Since the <code>overflow</code> property doesn't apply to table-cell, you
+          can wrap the cell content in a block-container and specify
+          <code>overflow="hidden"</code> there. Alternatively,
+          if you have long words overflowing table cells, try to
           get them hyphenated. Artificial names like product identifications or
           long numbers usually aren't hyphenated. You can try special processing
           at XSLT level, like
@@ -574,6 +617,15 @@ Check the following:</p>
           <link href="http://www.mulberrytech.com/xsl/xsl-list/">XSL list
           archive</link> for how to perform these tasks.
         </p>
+        <p>
+          If your text is not hyphenated at all and overflows the cell, please check
+          if you've specified <code>keep-together="always"</code> on the table-cell
+          or one of its parent elements. <code>keep-together="always"</code> implicitely
+          also sets <code>keep-together.within-line="always"</code> which forbids FOP
+          to break the text into multiple lines. This is important as FOP supports inline-level
+          keeps since version 0.94. It's a good idea not to use the shorthand
+          <code>keep-together="always"</code> at all!
+        </p>
       </answer>
     </faq>
     <faq id="row-height-constraint">
diff --git a/src/documentation/content/xdocs/site.xml b/src/documentation/content/xdocs/site.xml
index 5ebdef322..d87b68aab 100644
--- a/src/documentation/content/xdocs/site.xml
+++ b/src/documentation/content/xdocs/site.xml
@@ -123,6 +123,7 @@
       <fonts label="Fonts" href="fonts.html"/>
       <hyphenation label="Hyphenation" href="hyphenation.html"/>    
       <extensions label="Extensions" href="extensions.html"/>
+      <metadata label="Metadata" href="metadata.html"/>
     </features>
     
   </trunk>
@@ -157,6 +158,7 @@
       <hyphenation label="Hyphenation" href="hyphenation.html"/>    
       <extensions label="Extensions" href="extensions.html"/>
       <events label="Events" href="events.html"/>
+      <metadata label="Metadata" href="metadata.html"/>
     </features>
     
   </trunk>
diff --git a/src/documentation/content/xdocs/trunk/metadata.xml b/src/documentation/content/xdocs/trunk/metadata.xml
new file mode 100644
index 000000000..8c273fff5
--- /dev/null
+++ b/src/documentation/content/xdocs/trunk/metadata.xml
@@ -0,0 +1,243 @@
+<?xml version="1.0" standalone="no"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+<!-- $Id$ -->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd">
+<document>
+  <header>
+    <title>Metadata</title>
+  </header>
+  <body>
+    <section id="overview">
+      <title>Overview</title>
+      <p>
+        Document metadata is an important tool for categorizing and finding documents.
+        Various formats support different kinds of metadata representation and to
+        different levels. One of the more popular and flexible means of representing
+        document or object metadata is
+        <a href="http://www.adobe.com/products/xmp/">XMP (eXtensible Metadata Platform, specified by Adobe)</a>.
+        PDF 1.4 introduced the use of XMP. The XMP specification lists recommendation for
+        embedding XMP metdata in other document and image formats. Given its flexibility it makes
+        sense to make use this approach in the XSL-FO context. Unfortunately, unlike SVG which
+        also refers to XMP, XSL-FO doesn't recommend a preferred way of specifying document and
+        object metadata. Therefore, there's no portable way to represent metadata in XSL-FO
+        documents. Each implementation does it differently.
+      </p>
+    </section>
+    <section id="xmp-in-fo">
+      <title>Embedding XMP in an XSL-FO document</title>
+      <p>
+        As noted above, there's no officially recommended way to embed metadata in XSL-FO.
+        Apache FOP supports embedding XMP in XSL-FO. Currently, only support for document-level
+        metadata is implemented. Object-level metadata will be implemented when there's
+        interest.
+      </p>
+      <p>
+        Document-level metadata can be specified in the <code>fo:declarations</code> element.
+        XMP specification recommends to use <code>x:xmpmeta</code>, <code>rdf:RDF</code>, and
+        <code>rdf:Description</code> elements as shown in example below. Both
+        <code>x:xmpmeta</code> and <code>rdf:RDF</code> elements are recognized as the top-level
+        element introducing an XMP fragment (as per the XMP specification).
+      </p>
+      <section id="xmp-example">
+        <title>Example</title>
+        <source><![CDATA[[..]
+</fo:layout-master-set>
+<fo:declarations>
+  <x:xmpmeta xmlns:x="adobe:ns:meta/">
+    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
+      <rdf:Description rdf:about=""
+          xmlns:dc="http://purl.org/dc/elements/1.1/">
+        <!-- Dublin Core properties go here -->
+        <dc:title>Document title</dc:title>
+        <dc:creator>Document author</dc:creator>
+        <dc:description>Document subject</dc:description>
+      </rdf:Description>
+      <rdf:Description rdf:about=""
+          xmlns:xmp="http://ns.adobe.com/xap/1.0/">
+        <!-- XMP properties go here -->
+        <xmp:CreatorTool>Tool used to make the PDF</xmp:CreatorTool>
+      </rdf:Description>
+    </rdf:RDF>
+  </x:xmpmeta>
+</fo:declarations>
+<fo:page-sequence ...
+[..]]]></source>
+        <note>
+          <code>fo:declarations</code> <strong>must</strong> be declared after
+          <code>fo:layout-master-set</code> and before the first <code>page-sequence</code>.
+        </note>
+      </section>
+    </section>
+    <section id="xmp-impl-in-fop">
+      <title>Implementation in Apache FOP</title>
+      <p>
+        Currently, XMP support is only available for PDF output.
+      </p>
+      <p>
+        Originally, you could set some metadata information through FOP's FOUserAgent by
+        using its set*() methods (like setTitle(String) or setAuthor(String). These values are
+        directly used to set value in the PDF Info object. Since PDF 1.4, adding metadata as an
+        XMP document to a PDF is possible. That means that there are now two mechanisms in PDF
+        that hold metadata.
+      </p>
+      <p>
+        Apache FOP now synchronizes the Info and the Metadata object in PDF, i.e. when you
+        set the title and the author through the FOUserAgent, the two values will end up in
+        the (old) Info object and in the new Metadata object as XMP content. If instead of
+        FOUserAgent, you embed XMP metadata in the XSL-FO document (as shown above), the
+        XMP metadata will be used as-is in the PDF Metadata object and some values from the
+        XMP metadata will be copied to the Info object to maintain backwards-compatibility
+        for PDF readers that don't support XMP metadata.
+      </p>
+      <p>
+        The mapping between the Info and the Metadata object used by Apache FOP comes from
+        the <a href="http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=38920">PDF/A-1 specification</a>.
+        For convenience, here's the mapping table:
+      </p>
+      <table>
+        <tr>
+          <th colspan="2">Document information dictionary</th>
+          <th colspan="3">XMP</th>
+        </tr>
+        <tr>
+          <th>Entry</th>
+          <th>PDF type</th>
+          <th>Property</th>
+          <th>XMP type</th>
+          <th>Category</th>
+        </tr>
+        <tr>
+          <td>Title</td>
+          <td>text string</td>
+          <td>dc:title</td>
+          <td>Text</td>
+          <td>External</td>
+        </tr>
+        <tr>
+          <td>Author</td>
+          <td>text string</td>
+          <td>dc:creator</td>
+          <td>seq Text</td>
+          <td>External</td>
+        </tr>
+        <tr>
+          <td>Subject</td>
+          <td>text string</td>
+          <td>dc:description["x-default"]</td>
+          <td>Text</td>
+          <td>External</td>
+        </tr>
+        <tr>
+          <td>Keywords</td>
+          <td>text string</td>
+          <td>pdf:Keywords</td>
+          <td>Text</td>
+          <td>External</td>
+        </tr>
+        <tr>
+          <td>Creator</td>
+          <td>text string</td>
+          <td>xmp:CreatorTool</td>
+          <td>Text</td>
+          <td>External</td>
+        </tr>
+        <tr>
+          <td>Producer</td>
+          <td>text string</td>
+          <td>pdf:Producer</td>
+          <td>Text</td>
+          <td>Internal</td>
+        </tr>
+        <tr>
+          <td>CreationDate</td>
+          <td>date</td>
+          <td>xmp:CreationDate</td>
+          <td>Date</td>
+          <td>Internal</td>
+        </tr>
+        <tr>
+          <td>ModDate</td>
+          <td>date</td>
+          <td>xmp:ModifyDate</td>
+          <td>Date</td>
+          <td>Internal</td>
+        </tr>
+      </table>
+      <note>
+        "Internal" in the Category column means that the user should not set this value.
+        It is set by the application. 
+      </note>
+      <note>
+        The "Subject" used to be mapped to <code>dc:subject</code> in the initial publication of
+        PDF/A-1 (ISO 19005-1). In the
+        <a href="http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=45613">Technical Corrigendum 1</a>
+        this was changed to map to <code>dc:description["x-default"]</code>. 
+      </note>
+      <section id="namespaces">
+        <title>Namespaces</title>
+        <p>
+          Metadata is made of property sets where each property set uses a different namespace URI.
+        </p>
+        <p>
+          The following is a listing of namespaces that Apache FOP recognizes and acts upon,
+          mostly to synchronize the XMP metadata with the PDF Info dictionary: 
+        </p>
+        <table>
+          <tr>
+            <th>Set/Schema</th>
+            <th>Namespace Prefix</th>
+            <th>Namespace URI</th>
+          </tr>
+          <tr>
+            <td>Dublin Core</td>
+            <td>dc</td>
+            <td>http://purl.org/dc/elements/1.1/</td>
+          </tr>
+          <tr>
+            <td>XMP Basic</td>
+            <td>xmp</td>
+            <td>http://ns.adobe.com/xap/1.0/</td>
+          </tr>
+          <tr>
+            <td>Adobe PDF Schema</td>
+            <td>pdf</td>
+            <td>http://ns.adobe.com/pdf/1.3/</td>
+          </tr>
+        </table>
+        <p>
+          Please refer to the <a href="http://partners.adobe.com/public/developer/en/xmp/sdk/XMPspecification.pdf">XMP Specification</a>
+          for information on other metadata namespaces.
+        </p>
+        <p>
+          Property sets (Namespaces) not listed here are simply passed through to the final
+          document (if supported). That is useful if you want to specify a custom metadata
+          schema.
+        </p>
+      </section>
+    </section>
+    <section id="links">
+      <title>Links</title>
+      <ul>
+        <li><a href="http://www.adobe.com/products/xmp/">Adobe's Extensible Metadata Platform (XMP) website</a></li>
+        <li><a href="http://partners.adobe.com/public/developer/en/xmp/sdk/XMPspecification.pdf">Adobe XMP Specification</a></li>
+        <li><a href="http://partners.adobe.com/public/developer/en/xmp/sdk/XMPspecification.pdf">Adobe XMP Specification</a></li>
+        <li><a href="http://dublincore.org/">http://dublincore.org/</a></li>
+      </ul>
+    </section>
+  </body>
+</document>
diff --git a/src/documentation/content/xdocs/trunk/pdfa.xml b/src/documentation/content/xdocs/trunk/pdfa.xml
index 1b3b75561..bfa1ae33e 100644
--- a/src/documentation/content/xdocs/trunk/pdfa.xml
+++ b/src/documentation/content/xdocs/trunk/pdfa.xml
@@ -28,9 +28,6 @@
   <body>
     <section id="overview">
       <title>Overview</title>
-      <warning>
-        Support for PDF/A is available beginning with version 0.92.
-      </warning>
       <p>
         PDF/A is a standard which turns PDF into an "electronic document file 
         format for long-term preservation". PDF/A-1 is the first part of the