xmlgraphics-fop-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From gad...@apache.org
Subject svn commit: r1357814 [4/7] - in /xmlgraphics/fop/branches/fop-1_1: ./ src/documentation/content/ src/documentation/content/xdocs/ src/documentation/content/xdocs/1.1rc1/ src/documentation/content/xdocs/1.1rc1/fotree/ src/documentation/content/xdocs/1.1...
Date Thu, 05 Jul 2012 19:15:15 GMT
Added: xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/hyphenation.xml
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/hyphenation.xml?rev=1357814&view=auto
==============================================================================
--- xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/hyphenation.xml (added)
+++ xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/hyphenation.xml Thu Jul  5 19:15:13 2012
@@ -0,0 +1,237 @@
+<?xml version="1.0" encoding="UTF-8" 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" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+  <header>
+    <title>Apache™ FOP: Hyphenation</title>
+    <version>$Revision$</version>
+  </header>
+  <body>
+    <section id="support">
+    <title>Hyphenation Support</title>
+    <section id="intro">
+      <title>Introduction</title>
+      <p>Apache™ FOP uses Liang's hyphenation algorithm, well known from TeX. It needs
+       language specific pattern and other data for operation.</p>
+      <p>Because of <a href="#license-issues">licensing issues</a> (and for 
+       convenience), all hyphenation patterns for FOP are made available through 
+       the <a class="fork" href="http://offo.sourceforge.net/hyphenation/index.html">Objects For 
+       Formatting Objects</a> project.</p>
+      <note>If you have made improvements to an existing Apache™ FOP hyphenation pattern,
+       or if you have created one from scratch, please consider contributing these 
+       to OFFO so that they can benefit other FOP users as well. 
+       Please inquire on the <a href="../maillist.html#fop-user">FOP User
+       mailing list</a>.</note>
+    </section>
+    <section id="license-issues">
+      <title>License Issues</title>
+      <p>Many of the hyphenation files distributed with TeX and its offspring are
+       licenced under the <a class="fork" href="http://www.latex-project.org/lppl.html">LaTeX
+       Project Public License (LPPL)</a>, which prevents them from being
+       distributed with Apache software. The LPPL puts restrictions on file names
+       in redistributed derived works which we feel can't guarantee. Some
+       hyphenation pattern files have other or additional restrictions, for
+       example against use for commercial purposes.</p>
+      <p>Although Apache FOP cannot redistribute hyphenation pattern files that do
+       not conform with its license scheme, that does not necessarily prevent users
+       from using such hyphenation patterns with FOP. However, it does place on
+       the user the responsibility for determining whether the user can rightly use
+       such hyphenation patterns under the hyphenation pattern license.</p>
+      <warning>The user is responsible to settle license issues for hyphenation
+       pattern files that are obtained from non-Apache sources.</warning>
+    </section>
+    <section id="sources">
+      <title>Sources of Custom Hyphenation Pattern Files</title>
+      <p>The most important source of hyphenation pattern files is the
+       <a class="fork" href="http://www.ctan.org/tex-archive/language/hyphenation/">CTAN TeX
+        Archive</a>.</p>
+    </section>
+    <section id="install">
+      <title>Installing Custom Hyphenation Patterns</title>
+      <p>To install a custom hyphenation pattern for use with FOP:</p>
+      <ol>
+        <li>Convert the TeX hyphenation pattern file to the FOP format. The FOP
+         format is an xml file conforming to the DTD found at
+         <code>{fop-dir}/hyph/hyphenation.dtd</code>.</li>
+        <li>Name this new file following this schema:
+         <code>languageCode_countryCode.xml</code>. The country code is
+          optional, and should be used only if needed. For example:
+          <ul>
+            <li><code>en_US.xml</code> would be the file name for American
+             English hyphenation patterns.</li>
+            <li><code>it.xml</code> would be the file name for Italian
+             hyphenation patterns.</li>
+          </ul>
+          The language and country codes must match the XSL-FO input, which
+          follows <a href="http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt">ISO
+          639</a> (languages) and <a href="http://www.ics.uci.edu/pub/ietf/http/related/iso3166.txt">ISO
+          3166</a> (countries). NOTE: The ISO 639/ISO 3166 convention is that
+          language names are written in lower case, while country codes are written
+          in upper case. FOP does not check whether the language and country specified
+          in the FO source are actually from the current standard, but it relies
+          on it being two letter strings in a few places. So you can make up your
+          own codes for custom hyphenation patterns, but they should be two
+          letter strings too (patches for proper handling extensions are welcome)</li>
+        <li>There are basically three ways to make the FOP-compatible hyphenation pattern 
+          file(s) accessible to FOP:
+          <ul>
+            <li>Download the precompiled JAR from <a class="fork" href="http://offo.sourceforge.net/hyphenation/index.html">OFFO
+            </a> and place it either in the <code>{fop-dir}/lib</code> directory, or 
+             in a directory of your choice (and append the full path to the JAR to 
+             the environment variable <code>FOP_HYPHENATION_PATH</code>).</li>
+            <li>Download the desired FOP-compatible hyphenation pattern file(s) from 
+             <a class="fork" href="http://offo.sourceforge.net/hyphenation/index.html">OFFO</a>,
+             and/or take your self created hyphenation pattern file(s), 
+             <ul>
+                <li>place them in the directory <code>{fop-dir}/hyph</code>, </li>
+                <li>or place them in a directory of your choice and set the Ant variable
+                <code>user.hyph.dir</code> to point to that directory (in
+                <code>build-local.properties</code>),</li>
+             </ul>
+             and run Ant with build target
+             <code>jar-hyphenation</code>. This will create a JAR containing the 
+             compiled patterns in <code>{fop-dir}/build</code> that will be added to the 
+             classpath on the next run.
+             (When FOP is built from scratch, and there are pattern source file(s) 
+             present in the directory pointed to by the
+             <code>user.hyph.dir</code> variable, this JAR will automatically 
+             be created from the supplied pattern(s)).</li>
+            <li>Put the pattern source file(s) into a directory of your choice and 
+             configure FOP to look for custom patterns in this directory, by setting the
+             <a href="configuration.html">&lt;hyphenation-base&gt;</a> 
+             configuration option.</li>
+          </ul>
+        </li>
+      </ol>
+      <warning>
+        Either of these three options will ensure hyphenation is working when using
+        FOP from the command-line. If FOP is being embedded, remember to add the location(s)
+        of the hyphenation JAR(s) to the CLASSPATH (option 1 and 2) or to set the 
+        <a href="configuration.html#hyphenation-dir">&lt;hyphenation-dir&gt;</a> 
+        configuration option programmatically (option 3).
+      </warning>
+    </section>
+  </section>
+  <section id="patterns">
+    <title>Hyphenation Patterns</title>
+    <p>If you would like to build your own hyphenation pattern files, or modify
+     existing ones, this section will help you understand how to do so. Even
+     when creating a pattern file from scratch, it may be beneficial to start
+     with an existing file and modify it. See <a class="fork" href="http://offo.sourceforge.net/hyphenation/index.html">
+     OFFO's Hyphenation page</a> for examples. 
+     Here is a brief explanation of the contents of FOP's hyphenation patterns:</p>
+    <warning>The remaining content of this section should be considered "draft"
+     quality. It was drafted from theoretical literature, and has not been
+     tested against actual FOP behavior. It may contain errors or omissions.
+     Do not rely on these instructions without testing everything stated here.
+     If you use these instructions, please provide feedback on the
+     <a href="../maillist.html#fop-user">FOP User mailing list</a>, either
+     confirming their accuracy, or raising specific problems that we can
+     address.</warning>
+    <ul>
+      <li>The root of the pattern file is the &lt;hyphenation-info&gt; element.</li>
+      <li>&lt;hyphen-char&gt;: its attribute "value" contains the character signalling
+       a hyphen in the &lt;exceptions&gt; section. It has nothing to do with the
+       hyphenation character used in FOP, use the XSLFO hyphenation-character
+       property for defining the hyphenation character there. At some points
+       a dash U+002D is hardwired in the code, so you'd better use this too
+       (patches to rectify the situation are welcome). There is no default,
+       if you declare exceptions with hyphenations, you must declare the
+       hyphen-char too.</li>
+      <li>&lt;hyphen-min&gt; contains two attributes:
+        <ul>
+          <li>before: the minimum number of characters in a word allowed to exist
+           on a line immediately preceding a hyphenated word-break.</li>
+          <li>after: the minimum number of characters in a word allowed to exist
+           on a line immediately after a hyphenated word-break.</li>
+        </ul>
+        This element is unused and not even read. It should be considered a
+        documentation for parameters used during pattern generation.
+      </li>
+      <li>&lt;classes&gt; contains whitespace-separated character sets. The members
+       of each set should be treated as equivalent for purposes of hyphenation,
+       usually upper and lower case of the same character. The first character
+       of the set is the canonical character, the patterns and exceptions
+       should only contain these canonical representation characters (except
+       digits for weight, the period (.) as word delimiter in the patterns and
+       the hyphen char in exceptions, of course).</li>
+      <li>&lt;exceptions&gt; contains whitespace-separated words, each of which
+       has either explicit hyphen characters to denote acceptable breakage
+       points, or no hyphen characters, to indicate that this word should
+       never be hyphenated, or contain explicit &lt;hyp&gt; elements for specifying
+       changes of spelling due to hyphenation (like backen -&gt; bak-ken or
+       Stoffarbe -&gt; Stoff-farbe in the old german spelling). Exceptions override
+       the patterns described below. Explicit &lt;hyp&gt; declarations don't work
+       yet (patches welcome). Exceptions are generally a bit brittle, test
+       carefully.</li>
+      <li>&lt;patterns&gt; includes whitespace-separated patterns, which are what
+       drive most hyphenation decisions. The characters in these patterns are
+       explained as follows:
+        <ul>
+          <li>non-numeric characters represent characters in a sub-word to be
+           evaluated</li>
+          <li>the period character (.) represents a word boundary, i.e. either
+           the beginning or ending of a word</li>
+          <li>numeric characters represent a scoring system for indicating the
+           acceptability of a hyphen in this location. Odd numbers represent an
+           acceptable location for a hyphen, with higher values overriding lower
+           inhibiting values. Even numbers indicate an unacceptable location, with
+           higher values overriding lower values indicating an acceptable position.
+           A value of zero (inhibiting) is implied when there is no number present.
+           Generally patterns are constructed so that valuse greater than 4 are rare.
+           Due to a bug currently patterns with values of 8 and greater don't
+           have an effect, so don't wonder.</li>
+        </ul>
+        Here are some examples from the English patterns file:
+        <ul>
+          <li>Knuth (<em>The TeXBook</em>, Appendix H) uses the example <strong>hach4</strong>, which indicates that it is extremely undesirable to place a hyphen after the substring "hach", for example in the word "toothach-es".</li>
+          <li><strong>.leg5e</strong> indicates that "leg-e", when it occurs at the beginning of a word, is a very good place to place a hyphen, if one is needed. Words like "leg-end" and "leg-er-de-main" fit this pattern.</li>
+        </ul>
+        Note that the algorithm that uses this data searches for each of the word's substrings in the patterns, and chooses the <em>highest</em> value found for letter combination.
+      </li>
+    </ul>
+    <p>If you want to convert a TeX hyphenation pattern file, you have to undo
+     the TeX encoding for non-ASCII text. FOP uses Unicode, and the patterns
+     must be proper Unicode too. You should be aware of the XML encoding issues,
+     preferably use a good Unicode editor.</p>
+    <p>Note that FOP does not do Unicode character normalization. If you use
+     combining chars for accents and other character decorations, you must
+     declare character classes for them, and use the same sequence of base character
+     and combining marks in the XSLFO source, otherwise the pattern wouldn't match.
+     Fortunately, Unicode provides precomposed characters for all important cases
+     in common languages, until now nobody run seriously into this issue. Some dead
+     languages and dialects, especially ancient ones, may pose a real problem
+     though.</p>
+    <p>If you want to generate your own patterns, an open-source utility called
+     patgen can be used to assist in creating pattern files from dictionaries.
+     It is available in many Unix/Linux distributions and every TeX distribution.
+     Pattern creation for languages like english or german is an art. Read
+     Frank Liang's original paper <a class="fork" href="http://www.tug.org/docs/liang/">"Word
+     Hy-phen-a-tion by Com-pu-ter"</a> (yes, with hyphens) for details.
+     The original patgen.web source, included in the TeX source distributions,
+     contains valuable comments, unfortunately technical details often obscure the
+     high level issues. Another important source of information is
+     <a class="fork" href="http://mirrors.ctan.org/systems/knuth/dist/tex/texbook.tex">The
+     TeX Book</a>, appendix H (either read the TeX source, or run it through
+     TeX to typeset it). Secondary articles, for example the works by Petr Sojka,
+     may also give some much needed insight into problems arising in automated
+     hyphenation.</p>
+  </section>
+  </body>
+</document>
\ No newline at end of file

Added: xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/index.xml
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/index.xml?rev=1357814&view=auto
==============================================================================
--- xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/index.xml (added)
+++ xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/index.xml Thu Jul  5 19:15:13 2012
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  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" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+  <header>
+    <title>Apache™ FOP Version 1.1rc1</title>
+    <version>$Revision$</version>
+  </header>
+  <body>
+    <section id="intro">
+      <title>Introduction</title>
+      <p>
+        This is Release Candidate 1 (rc1) of an upcoming minor (dot) release of FOP. FOP 1.1rc1 contains many bux
+        fixes and a number of improvements, including
+        important features such as support for <a href="complexscripts.html">Complex Scripts</a>
+        (e.g., Arabic, Hebrew, Indic, and Southeast Asian scripts). To see what has changed since the last release,
+        please visit <a href="releaseNotes_1.1rc1.html">Release Notes</a>.
+      </p>
+      <p>
+	This release implements a substantial subset of the W3C XSL-FO 1.1
+	Recommendation. For a detailed overview of FOP's
+	compliance with this recommendation, see <a href="../compliance.html">Compliance</a>.
+      </p>
+    </section>
+    <section id="upgrading">
+      <title>Upgrading from an earlier version</title>
+      <p>
+        If you're upgrading to this version from an earlier version of FOP, please read the 
+        information on <a href="upgrading.html">Upgrading</a>!
+      </p>
+    </section>
+    <section id="download">
+      <title>Download</title>
+      <p>
+        To download this version, please visit <a href="../download.html">Downloading</a>.
+      </p>
+    </section>
+  </body>
+</document>

Added: xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/intermediate.xml
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/intermediate.xml?rev=1357814&view=auto
==============================================================================
--- xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/intermediate.xml (added)
+++ xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/intermediate.xml Thu Jul  5 19:15:13 2012
@@ -0,0 +1,331 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  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" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+  <header>
+    <title>Apache™ FOP: Intermediate Format</title>
+    <version>$Revision$</version>
+  </header>
+  <body>
+    <note>
+      Please note that the intermediate formats described here are
+      <strong>advanced features</strong> and can be ignored by most users of Apache FOP.
+    </note>
+    <section id="introduction">
+      <title>Introduction</title>
+      <p>
+        Apache™ FOP now provides two different so-called intermediate formats. The first one
+        (let's call it the area tree XML format) is basically a 1:1 XML representation of FOP's
+        area tree as generated by the layout engine. The area tree is conceptually defined in the 
+        <a href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice1.html#section-N742-Formatting">XSL-FO specification in chapter 1.1.2</a>.
+        Even though the area tree is mentioned in the XSL-FO specification, this part is not
+        standardized. Therefore, the area tree XML format is a FOP-proprietary XML file format.
+        The area tree XML can be generated through the area tree XML Renderer (the XMLRenderer).
+      </p>
+      <p>
+        The second intermediate format (which we shall name exactly like this: the intermediate 
+        format)
+        is a recent addition which tries to meet a slightly different set of goals. It is highly
+        optimized for speed.
+      </p>
+      <p>
+        The intermediate format can be used to generate intermediate documents that are modified 
+        before they are finally rendered to their ultimate output format. Modifications include
+        adjusting and changing trait values, adding or modifying area objects, inserting prefabricated
+        pages, overlays, imposition (n-up, rotation, scaling etc.). Multiple IF files can be combined
+        to a single output file.
+      </p>
+    </section>
+    <section id="which-if">
+      <title>Which Intermediate Format to choose?</title>
+      <p>
+        Both formats have their use cases, so the choice you will make will depend on your 
+        particular situation. Here is a list of strengths and use cases for both formats:
+      </p>
+      <section id="strengths-at">
+        <title>Area Tree XML (AT XML)</title>
+        <ul>
+          <li>1:1 representation of FOP's area tree in XML.</li>
+          <li>Contains more structure information than the new intermediate format.</li>
+          <li>Used in FOP's layout engine test suite for regression testing.</li>
+        </ul>
+      </section>
+      <section id="strengths-if">
+        <title>Intermediate Format (IF)</title>
+        <ul>
+          <li>Highly optimized for speed.</li>
+          <li>Smaller XML files.</li>
+          <li>Easier to post-process.</li>
+          <li>XML Schema is available.</li>
+          <li>
+            Recommended for use cases where documents are formatted concurrently and later
+            concatenated to a single print job.
+          </li>
+        </ul>
+      </section>
+      <p>
+        More technical information about the two formats can be found on the
+        <a href="http://wiki.apache.org/xmlgraphics-fop/AreaTreeIntermediateXml/NewDesign">FOP Wiki</a>.
+      </p>
+    </section>
+    <section id="architecture">
+      <title>Architectural Overview</title>
+      <figure src="images/if-architecture-overview.png"
+        alt="Diagram with an architectural overview over the intermediate formats"/>
+    </section>
+    <section id="usage">
+      <title>Usage of the Area Tree XML format (AT XML)</title>
+      <p>
+        As already mentioned, the area tree XML format is generated by using the
+        <strong>XMLRenderer</strong> (MIME type: <strong>application/X-fop-areatree</strong>).
+        So, you basically set the right MIME type for the output format and process your FO files
+        as if you would create a PDF file.
+      </p>
+      <p>
+        However, there is an important detail to consider: The
+        various Renderers don't all use the same font sources. To be able to create the right
+        area tree for the ultimate output format, you need to create the area tree XML file using
+        the right font setup. This is achieved by telling the XMLRenderer to mimic another
+        renderer. This is done by calling the XMLRenderer's mimicRenderer() method with an
+        instance of the ultimate target renderer as the single parameter. This has a consequence:
+        An area tree XML file rendered with the Java2DRenderer may not look as expected when it
+        was actually generated for the PDF renderer. For renderers that use the same font setup,
+        this restriction does not apply (PDF and PS, for example). Generating the area tree XML
+        format file is the first step.
+      </p>
+      <p>
+        The second step is to reparse the file using the <strong>AreaTreeParser</strong> which is
+        found in the org.apache.fop.area package. The pages retrieved from the area tree XML file
+        are added to an AreaTreeModel instance from where they are normally rendered using one of
+        the available Renderer implementations. You can find examples for the area tree XML
+        processing in the 
+        <a href="http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/examples/embedding/java/embedding/intermediate/"><code>examples/embedding</code></a>
+        directory in the FOP distribution.
+      </p>
+      <p>
+        The basic pattern to parse the area tree XML format looks like this:
+      </p>
+      <source><![CDATA[
+FopFactory fopFactory = FopFactory.newInstance();      
+      
+// Setup output
+OutputStream out = new java.io.FileOutputStream(pdffile);
+out = new java.io.BufferedOutputStream(out);
+try {
+    //Setup fonts and user agent
+    FontInfo fontInfo = new FontInfo();
+    FOUserAgent userAgent = fopFactory.newFOUserAgent();
+
+    //Construct the AreaTreeModel that will received the individual pages
+    AreaTreeModel treeModel = new RenderPagesModel(userAgent, 
+            MimeConstants.MIME_PDF, fontInfo, out);
+            
+    //Parse the area tree file into the area tree
+    AreaTreeParser parser = new AreaTreeParser();
+    Source src = new StreamSource(myIFFile);
+    parser.parse(src, treeModel, userAgent);
+            
+    //Signal the end of the processing. The renderer can finalize the target document.
+    treeModel.endDocument();
+} finally {
+    out.close();
+}]]></source>
+      <p>
+        This example simply reads an area tree file and renders it to a PDF file. Please note, that in normal
+        FOP operation you're shielded from having to instantiate the FontInfo object yourself. This
+        is normally a task of the AreaTreeHandler which is not present in this scenario. The same
+        applies to the AreaTreeModel instance, in this case an instance of a subclass called 
+        RenderPagesModel. RenderPagesModel is ideal in this case as it has very little overhead 
+        processing the individual pages. An important line in the example is the call to 
+        <code>endDocument()</code> on the AreaTreeModel. This lets the Renderer know that the processing
+        is now finished.
+      </p>
+      <p>
+        The area tree XML format can also be used from the <a href="running.html#standalone-start">command-line</a>
+        by using the "-atin" parameter for specifying the area tree XML as input file. You can also 
+        specify a "mimic renderer" by inserting a MIME type between "-at" and the output file.
+      </p>
+      <section id="concat">
+        <title>Concatenating Documents</title>
+        <p>
+          This initial example is obviously not very useful. It would be faster to create the PDF file 
+          directly. As the <a href="http://svn.apache.org/repos/asf/xmlgraphics/fop/trunk/examples/embedding/java/embedding/atxml/ExampleConcat.java">ExampleConcat.java</a>
+          example shows you can easily parse multiple area tree files in a row and add the parsed pages to the
+          same AreaTreeModel instance which essentially concatenates all the input document to one single
+          output document.
+        </p>
+      </section>
+      <section id="modifying">
+        <title>Modifying Documents</title>
+        <p>
+          One of the most important use cases for this format is obviously modifying the area
+          tree XML before finally rendering it to the target format. You can easily use XSLT to process
+          the AT XML file according to your needs. Please note, that we will currently not formally describe
+          the area tree XML format. You need to have a good understanding its structure so you don't
+          create any non-parseable files. We may add an XML Schema and more detailed documentation at a
+          later time. You're invited to help us with that.
+        </p>
+        <note>
+          The area tree XML format is sensitive to changes in whitespace. If you're not careful,
+          the modified file may not render correctly.
+        </note>
+      </section>
+      <section id="advanced">
+        <title>Advanced Use</title>
+        <p>
+          The generation of the area tree format as well as it parsing process has been designed to allow
+          for maximum flexibility and optimization. Please note that you can call <code>setTransformerHandler()</code> on
+          XMLRenderer to give the XMLRenderer your own TransformerHandler instance in case you would like to
+          do custom serialization (to a W3C DOM, for example) and/or to directly modify the area tree using 
+          XSLT. The AreaTreeParser on the other side allows you to retrieve a ContentHandler instance where
+          you can manually send SAX events to to start the parsing process (see <code>getContentHandler()</code>).
+        </p>
+      </section>
+    </section>
+    <section id="usage-if">
+      <title>Usage of the Intermediate Format (IF)</title>
+      <p>
+        The Intermediate Format (IF) is generated by the <strong>IFSerializer</strong>
+        (MIME type: <strong>application/X-fop-intermediate-format</strong>).
+        So, you basically set the right MIME type for the output format and process your FO files
+        as if you would create a PDF file.
+      </p>
+      <p>
+        The IFSerializer is an implementation of the <strong>IFDocumentHandler</strong> and
+        <strong>IFPainter</strong> interfaces. The <strong>IFRenderer</strong> class is responsible
+        for converting FOP's area tree into calls against these two interfaces.
+      </p>
+      <ul>
+        <li>
+          IFDocumentHandler: This interface is used on the document-level and defines the
+          overall structure of the Intermediate Format.
+        </li>
+        <li>
+          IFPainter: This interface is used to generate graphical page content like text, images
+          and borders.
+        </li>
+      </ul>
+      <p>
+        As with the AT XML, there is an important detail to consider: The various output
+        implementations don't all use the same font sources. To be able
+        to create the right IF for the ultimate output file, you need to create the IF file using
+        the right font setup. This is achieved by telling the IFRenderer (responsible for
+        converting the area tree into calls to the IFDocumentHandler and IFPainter interfaces) 
+        to mimic another renderer. This is done by calling the IFSerializer's
+        mimicDocumentHandler() method with an instance of the ultimate target document handler
+        as the single parameter. This has a consequence: An IF file rendered with the
+        Java2DDocumentHandler may not look as expected when it was actually generated for the PDF
+        implementation. For implementations that use the same font setup,
+        this restriction does not apply (PDF and PS, for example). Generating the Intermediate
+        Format file is the first step.
+      </p>
+      <p>
+        The second step is to reparse the file using the <strong>IFParser</strong> which is
+        found in the org.apache.fop.render.intermediate package. The IFParser simply takes an
+        IFDocumentHandler instance against which it generates the appropriate calls. The IFParser
+        is implemented as a SAX ContentHandler so you're free to choose the method for
+        post-processing the IF file(s). You can use XSLT or write SAX- or DOM-based code to
+        manipulate the contents. You can find examples for the Intermediate Format
+        processing in the 
+        <a href="http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/examples/embedding/java/embedding/intermediate/"><code>examples/embedding</code></a>
+        directory in the FOP distribution.
+      </p>
+      <p>
+        The basic pattern to parse the intermediate format looks like this:
+      </p>
+      <source><![CDATA[
+FopFactory fopFactory = FopFactory.newInstance();
+      
+// Setup output
+OutputStream out = new java.io.FileOutputStream(pdffile);
+out = new java.io.BufferedOutputStream(out);
+try {
+    //Setup user agent
+    FOUserAgent userAgent = fopFactory.newFOUserAgent();
+
+    //Create IFDocumentHandler instance
+    IFDocumentHandler targetHandler;
+    String mime = MimeConstants.MIME_PDF;
+    targetHandler = fopFactory.getRendererFactory().createDocumentHandler(
+            userAgent, mime);
+
+    //Setup fonts
+    IFUtil.setupFonts(targetHandler);
+    
+    //Tell the target handler where to write the PDF to
+    targetHandler.setResult(new StreamResult(pdffile));
+
+    //Parse the IF file
+    IFParser parser = new IFParser();
+    Source src = new StreamSource(myIFFile);
+    parser.parse(src, targetHandler, userAgent);
+            
+} finally {
+    out.close();
+}]]></source>
+      <p>
+        This example simply reads an intermediate file and renders it to a PDF file. Here
+        IFParser.parse() is used, but you can also just get a SAX ContentHandler by using the
+        IFParser.getContentHandler() method.
+      </p>
+      <section id="concat-if">
+        <title>Concatenating Documents</title>
+        <p>
+          This initial example is obviously not very useful. It would be faster to create the PDF file 
+          directly (without the intermediate step). As the
+          <a href="http://svn.apache.org/repos/asf/xmlgraphics/fop/trunk/examples/embedding/java/embedding/intermediate/ExampleConcat.java">ExampleConcat.java</a>
+          example shows you can easily parse multiple intermediate files in a row and use the
+          IFConcatenator class to concatenate page sequences from multiple source files to a single
+          output file. This particular example does the concatenation on the level of the
+          IFDocumentHandler interface. You could also do this in XSLT or using SAX on the XML level.
+          Whatever suits your process best.
+        </p>
+      </section>
+      <section id="modifying-if">
+        <title>Modifying Documents</title>
+        <p>
+          One of the most important use cases for this format is obviously modifying the
+          intermediate format before finally rendering it to the target format. You can easily use
+          XSLT to process the IF file according to your needs.
+        </p>
+        <p>
+          There is an XML Schema (located under
+          <a href="http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/documentation/intermediate-format-ng/">src/documentation/intermediate-format-ng</a>)
+          that helps you verify that your modified content is correct.
+        </p>
+        <p>
+          For certain output formats there's a caveat: Formats like AFP and PCL do not support
+          arbitrary transformations on the IF's "viewport" and "g" elements. Possible are
+          only rotations in 90 degree steps and translations.
+        </p>
+      </section>
+      <section id="advanced-if">
+        <title>Advanced Use</title>
+        <p>
+          The generation of the intermediate format as well as it parsing process has been
+          designed to allow for maximum flexibility and optimization. So rather than just passing
+          in a StreamResult to IFSerializer's setResult() method, you can also use a SAXResult
+          or a DOMResult. And as you've already seen , the IFParser on the other side allows you
+          to retrieve a ContentHandler instance where you can manually send SAX events to
+          start the parsing process (see <code>getContentHandler()</code>).
+        </p>
+      </section>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Added: xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/known-issues.xml
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/known-issues.xml?rev=1357814&view=auto
==============================================================================
--- xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/known-issues.xml (added)
+++ xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/known-issues.xml Thu Jul  5 19:15:13 2012
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!--
+  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$ -->
+<known-issues>
+  <known-issue>
+    Support for Unicode characters outside of the Base Multilingual Plane (BMP), i.e., characters
+    whose code points are greater than 65535, is not yet implemented.
+    See <link href="http://issues.apache.org/bugzilla/show_bug.cgi?id=51843">bug 51843</link>.
+  </known-issue>
+  <known-issue>
+    The writing-mode property does not produce the expected behavior when specified on
+    <code>fo:simple-page-master</code>  or <code>fo:region-*</code> elements.
+    See <link href="http://issues.apache.org/bugzilla/show_bug.cgi?id=53276">bug 53276</link>.
+  </known-issue>
+  <known-issue>
+    Support for Devanagari and other Indic scripts is not yet complete.
+  </known-issue>
+  <known-issue>
+    Use of Unicode U+200C ZERO WIDTH NON-JOINER (ZWNJ) or U+200D ZERO WIDTH JOINER (ZWJ)
+    does not prevent or force contextual substitution, respectively, when used with Arabic script.
+  </known-issue>
+  <known-issue>
+    Use of Unicode U+200C ZERO WIDTH NON-JOINER (ZWNJ) or U+200D ZERO WIDTH JOINER (ZWJ)
+    does not affect conjunct formation or other special behavior prescribed when used with Indic scripts.
+  </known-issue>
+  <known-issue>
+    Support for automatic line breaking at orthographic syllable segment boundaries in Indic
+    or Southeast Asian scripts is not yet available. In the mean time, use U+200B ZERO WIDTH SPACE (ZWSP).
+  </known-issue>
+  <known-issue>
+    Complex script content is presently supported only with AT, IF, and PDF output formats.
+  </known-issue>
+  <known-issue>
+    When complex script text encounters an  <code>fo:inline</code> or <code>fo:character</code> boundary,
+    contextual substitution and ligature formation will not occur across the boundary. This prevents,
+    for example, applying a different color to an Arabic Letter within an Arabic word, unless that letter
+    is a non-joining letter (on both sides).
+  </known-issue>
+</known-issues>

Added: xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/knownissues_overview.xml
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/knownissues_overview.xml?rev=1357814&view=auto
==============================================================================
--- xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/knownissues_overview.xml (added)
+++ xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/knownissues_overview.xml Thu Jul  5 19:15:13 2012
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8" 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" "http://forrest.apache.org/dtd/document-v20.dtd">
+<document xmlns:xi="http://www.w3.org/2001/XInclude">
+  <header>
+    <title>Apache™ FOP: Known Issues</title>
+    <version>$Revision$</version>
+  </header>
+<body>
+<section>
+  <title>Known issues</title>
+  <p>
+    This page lists currently known issues in the current release.
+  </p>
+  <note>
+    <p>
+      For additional information on known issues in Apache™ FOP, please have a look at the following pages, too:
+    </p>
+    <ul>
+      <li><a href="../bugs.html">the bug list in Bugzilla</a></li>
+      <li><a href="http://wiki.apache.org/xmlgraphics-fop/FOPProjectTasks">the task list in the Wiki</a></li>
+    </ul>
+  </note>
+  <p>
+    Apache™ FOP has an extensive automated testing infrastructure. Parts of this infrastructure are several
+    sets of test cases. When a test case is listed in disabled-testcases.xml it is disabled in the JUnit 
+    tests during the normal build process. This indicates a problem in the current codebase. When a bug is 
+    fixed or a missing feature is added the entry for the relevant test case(s) are removed.
+  </p>
+  <section>
+    <title>FO Tree</title>
+    <p>
+      This section lists disabled test cases in the test suite for the FO tree tests, at the time
+      of the release.
+    </p>
+    <xi:include href="cocoon://knownissues-raw-fotree_1.1rc1.xml#xpointer(/document/body/*)"/>
+  </section>
+  <section>
+    <title>Layout Engine</title>
+    <p>
+      This section lists disabled test cases in the test suite for the layout engine tests, at the
+      time of the release.
+    </p>
+    <xi:include href="cocoon://knownissues-raw-layoutengine_1.1rc1.xml#xpointer(/document/body/*)"/>
+  </section>
+  <section>
+    <title>Other known issues</title>
+    <p>This section lists some other issues that post-date the release of FOP 1.0. For known issues that pre-date FOP 1.0, see
+      <link href="http://issues.apache.org/bugzilla/buglist.cgi?chfieldto=2010-07-20&amp;chfield=%5BBug%20creation%5D&amp;query_format=advanced&amp;chfieldfrom=2001-01-01&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;bug_status=NEEDINFO&amp;product=Fop">older bugs that remain open</link>.
+      For all open issues that post-date FOP 1.0, see
+      <link href="http://issues.apache.org/bugzilla/buglist.cgi?chfieldto=Now&amp;chfield=%5BBug%20creation%5D&amp;query_format=advanced&amp;chfieldfrom=2010-07-20&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;bug_status=NEEDINFO&amp;product=Fop">newer bugs that remain open</link>.
+    </p>
+    <!-- See <root>/known-issues.xml for the source document of this section! -->
+    <xi:include href="cocoon://knownissues-raw-static_1.1rc1.xml#xpointer(/document/body/*)"/>
+  </section>
+</section>
+</body>
+</document>

Added: xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/layoutengine/disabled-testcases.xml
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/layoutengine/disabled-testcases.xml?rev=1357814&view=auto
==============================================================================
--- xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/layoutengine/disabled-testcases.xml (added)
+++ xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/layoutengine/disabled-testcases.xml Thu Jul  5 19:15:13 2012
@@ -0,0 +1,223 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?xml-stylesheet type="text/xsl" href="disabled-testcases.xsl"?>
+<!--
+  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 disabled-testcases SYSTEM "disabled-testcases.dtd"-->
+<disabled-testcases>
+  <testcase>
+    <name>Auto-height block-containers produce fences</name>
+    <file>block-container_space-before_space-after_3.xml</file>
+    <description>Block-containers with no height currently don't
+    create a fence for spaces as they should (they behave like a
+    normal block).</description>
+  </testcase>
+  <testcase>
+    <name>font-stretch NYI</name>
+    <file>block_font-stretch.xml</file>
+    <description>Font-stretch is not implemented, yet.</description>
+  </testcase>
+  <testcase>
+    <name>linefeed-treatment</name>
+    <file>block_linefeed-treatment.xml</file>
+    <description>Preserved linefeeds in a fo:character are not handled
+    correctly.</description>
+  </testcase>
+  <testcase>
+    <name>white-space-treatment</name>
+    <file>block_white-space-treatment_3.xml</file>
+    <description>White space handling incorrectly stops at fo:inline
+      boundaries when it comes to formatter generated line breaks.</description>
+  </testcase>
+  <testcase>
+    <name>Empty blocks produce fences</name>
+    <file>block_space-before_space-after_8.xml</file>
+    <description>An empty block currently produces a fence for
+    stacking constraints which it shouldn't.</description>
+  </testcase>
+  <testcase>
+    <name>block white-space nbsp 2</name>
+    <file>block_white-space_nbsp_2.xml</file>
+    <description>The nbsp given as an fo:character is not adjustable and therefore
+    the justification does not work in this case.</description>
+  </testcase>
+  <testcase>
+    <name>block word-spacing</name>
+    <file>block_word-spacing.xml</file>
+    <description>Word-spacing may not work as expected.</description>
+  </testcase>
+  <testcase>
+    <name>block word-spacing text-align justify</name>
+    <file>block_word-spacing_text-align_justify.xml</file>
+    <description>Word-spacing may not work as expected.</description>
+  </testcase>
+  <testcase>
+    <name>external-graphic don't shrink</name>
+    <file>external-graphic_oversized.xml</file>
+    <description>Images currently don't shrink so they fit on a page
+    when they are too big and shrinking is allowed to
+    happen (min/opt/max).</description>
+  </testcase>
+  <testcase>
+    <name>Test case with HTTP URL</name>
+    <file>external-graphic_src_uri.xml</file>
+    <description>Doesn't work behind a proxy which requires
+    authorization.</description>
+  </testcase>
+  <testcase>
+    <name>Space Resolution in foot note area</name>
+    <file>footnote_space-resolution.xml</file>
+    <description>Space resolution does not work between footnote
+    regions.</description>
+  </testcase>
+  <testcase>
+    <name>NPE for table inside an inline</name>
+    <file>inline_block_nested_3.xml</file>
+    <description>Placing a table as a child of an fo:inline produces a 
+    NullPointerException.</description>
+  </testcase>
+  <testcase>
+    <name>inline-container is not implemented, yet.</name>
+    <file>inline-container_block_nested.xml</file>
+    <description>inline-container is not implemented, yet. Content of an 
+    inline-container will get swallowed. The test case contains no checks.</description>
+  </testcase>
+  <testcase>
+    <name>inline-container is not implemented, yet.</name>
+    <file>inline-container_border_padding.xml</file>
+    <description>inline-container is not implemented, yet. Content of an 
+    inline-container will get swallowed.</description>
+  </testcase>
+  <testcase>
+    <name>inline letter-spacing</name>
+    <file>inline_letter-spacing.xml</file>
+    <description>Letter-spacing may not work as
+    expected within fo:inline.</description>
+  </testcase>
+  <testcase>
+    <name>inline word-spacing</name>
+    <file>inline_word-spacing.xml</file>
+    <description>Word-spacing may not work as expected within
+    fo:inline.</description>
+  </testcase>
+  <testcase>
+    <name>inline word-spacing text-align justify</name>
+    <file>inline_word-spacing_text-align_justify.xml</file>
+    <description></description>
+  </testcase>
+  <testcase>
+    <name>leader-alignment NYI</name>
+    <file>leader-alignment.xml</file>
+    <description>Leader-alignment is not yet
+    implemented.</description>
+  </testcase>
+  <testcase>
+    <name>leader-pattern="use-content": Problem with line height</name>
+    <file>leader_leader-pattern_use-content_bug.xml</file>
+    <description>Line height is not correctly calculated for
+    use-content leaders whose height is larger than the rest of the
+    line.</description>
+    <reference>http://www.nabble.com/leaders-with-leader-pattern%3D%22use-content%22-t546244.html</reference>
+  </testcase>
+  <testcase>
+    <name>Page breaking doesn't deal with IPD changes</name>
+    <file>page-breaking_4.xml</file>
+    <description>Page breaking currently doesn't support changing available IPD 
+    between pages of a single page-sequence. Element list generation has to be reset to
+    redetermine line breaks in this case.</description>
+  </testcase>
+  <testcase>
+    <name>Overflow handing is incomplete</name>
+    <file>page-breaking_6.xml</file>
+    <description>Line breaking is not 100% correct when there's too little space. 
+    Overflows are not detected and warned.</description>
+  </testcase>
+  <testcase>
+    <name>Indefinite page height handling is imcomplete</name>
+    <file>page-height_indefinite_simple.xml</file>
+    <description>A RuntimeException is thrown for a page of indefinite height. Lots of warnings.</description>
+  </testcase>
+  <testcase>
+    <name>page-number-citation: Problem with background-image</name>
+    <file>page-number-citation_background-image.xml</file>
+    <description>Background-images on page-number-citations are not
+    placed correctly.</description>
+  </testcase>
+  <testcase>
+    <name>IDs are not working on all FO elements</name>
+    <file>page-number-citation_complex_1.xml</file>
+    <description>The "id" attributes are not properly handled for all block-level FO elements.</description>
+  </testcase>
+  <testcase>
+    <name>IDs are not working on all FO elements</name>
+    <file>page-number-citation_complex_2.xml</file>
+    <description>The "id" attributes are not properly handled for all inline-level FO elements.</description>
+  </testcase>
+  <testcase>
+    <name>Footnotes in multi-column documents</name>
+    <file>region-body_column-count_footnote.xml</file>
+    <description>Footnotes may overlap with text of the region-body in
+    multi-column documents.</description>
+  </testcase>
+  <testcase>
+    <name>Column Balancing problems</name>
+    <file>region-body_column-count_balance_4col.xml</file>
+    <description>Situation in a 4-column document where the column balancing doesn't work and even causes some
+    content to disappear.</description>
+  </testcase>
+  <testcase>
+    <name>Column Balancing problems</name>
+    <file>region-body_column-count_bug36356.xml</file>
+    <description>Column balancing doesn't work as expected.</description>
+  </testcase>
+  <testcase>
+    <name>table-cell empty area with marker.xml</name>
+    <file>table-cell_empty_area_with_marker.xml</file>
+    <description>A table-cell producing an empty area does currently not add any markers to a page. 
+      See TODO entry in AreaAdditionUtil.</description>
+  </testcase>
+  <testcase>
+    <name>Border conditionality on table</name>
+    <file>table_border-width_conditionality.xml</file>
+    <description>The code should be ok, but the test case uses shorthands and therefore
+    is probably not expressing the indended outcome according to the spec. The test
+    case should be revisited.</description>
+  </testcase>
+  <testcase>
+    <name>Soft hyphen with normal hyphenation enabled</name>
+    <file>block_shy_linebreaking_hyph.xml</file>
+    <description>A soft hyphen should be a preferred as break compared to a
+    normal hyphenation point but is not.</description>
+  </testcase>
+  <testcase>
+    <name>Page-keep not respected in multi-column layout</name>
+    <file>keep_within-page_multi-column_overflow.xml</file>
+    <description>The block should cause overflow in the
+    last column on the page, rather than be broken.</description>
+  </testcase>
+  <testcase>
+    <name>Block Container Reference Orientation Bug</name>
+    <file>block-container_reference-orientation_bug36391.xml</file>
+    <description>An assert is failing</description>
+  </testcase>
+  <testcase>
+    <name>Writing mode problems</name>
+    <file>simple-page-master_writing-mode_rl_region-body_writing-mode-lr.xml</file>
+    <description>Test erroneously depends upon incorrect implementation of writing-mode trait
+    derivation on fo:region-*.</description>
+  </testcase>
+</disabled-testcases>

Added: xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/metadata.xml
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/metadata.xml?rev=1357814&view=auto
==============================================================================
--- xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/metadata.xml (added)
+++ xmlgraphics/fop/branches/fop-1_1/src/documentation/content/xdocs/1.1rc1/metadata.xml Thu Jul  5 19:15:13 2012
@@ -0,0 +1,243 @@
+<?xml version="1.0" encoding="UTF-8" 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>Apache™ FOP: 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>
\ No newline at end of file



---------------------------------------------------------------------
To unsubscribe, e-mail: fop-commits-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: fop-commits-help@xmlgraphics.apache.org


Mime
View raw message