Created a static known-issues item in the release tab. Updated the

documenation for running.


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

7 files changed, 658 insertions, 52 deletions

diff --git a/src/documentation/content/xdocs/0.93/fotree/disabled-testcases.xml b/src/documentation/content/xdocs/0.93/fotree/disabled-testcases.xml
new file mode 100644
index 000000000..196eafcc4
--- /dev/null
+++ b/src/documentation/content/xdocs/0.93/fotree/disabled-testcases.xml
@@ -0,0 +1,31 @@
+<?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$ -->
+<disabled-testcases>
+  <testcase>
+    <name>demo test failure</name>
+    <file>demo-test-failure.fo</file>
+    <description></description>
+  </testcase>
+  <testcase>
+    <name>Markers and core function evaluation</name>
+    <file>from-table-column_marker.fo</file>
+    <description>The code currently evaluates this function according to the column in which the 
+    marker appears in the source document, rather than the column it is retrieved in.</description>
+  </testcase>
+</disabled-testcases>
diff --git a/src/documentation/content/xdocs/0.93/known-issues.xml b/src/documentation/content/xdocs/0.93/known-issues.xml
new file mode 100644
index 000000000..25af2a217
--- /dev/null
+++ b/src/documentation/content/xdocs/0.93/known-issues.xml
@@ -0,0 +1,102 @@
+<?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>
+        MIF and SVG output support have not been restored, yet.
+      </known-issue>
+      <known-issue>
+        Java2D/AWT support has been improved, but some problems remain,
+        for example with block-containers.
+      </known-issue>
+      <known-issue>
+        Auto table layout is not implemented, yet.
+      </known-issue>
+      <known-issue>
+        The collapsing border model on tables is not implemented, yet. Please 
+        use border-collapse="separate" for now.
+      </known-issue>
+      <known-issue>
+        Footnotes may overlap with text of the region-body in multi-column 
+        documents.
+      </known-issue>
+      <known-issue>
+        Space resolution does not work between footnote regions.
+      </known-issue>
+      <known-issue>
+        There's a problem involving nested block-containers and 
+        reference-orientation 180/-180 (<a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=36391">Bugzilla #36391</a>)
+      </known-issue>
+      <known-issue>
+        block-containers with no height currently don't create a fence for
+        spaces as they should (they behave like a normal block).
+      </known-issue>
+      <known-issue>
+        Preserved linefeeds in fo:character are not handled correctly.
+      </known-issue>
+      <known-issue>
+        An empty block currently produces a fence for stacking constraints
+        which it shouldn't.
+      </known-issue>
+      <known-issue>
+        There are several small problems around white space handling.
+      </known-issue>
+      <known-issue>
+        Images currently don't shrink so they fit on a page when they are 
+        too big and shrinking is allowed to happen.
+      </known-issue>
+      <known-issue>
+        inline-container may not work as expected.
+      </known-issue>
+      <known-issue>
+        letter-spacing and word-spacing properties may not work as expected.
+      </known-issue>
+      <known-issue>
+        leaders with leader-pattern="use-content" may not work as expected.
+      </known-issue>
+      <known-issue>
+        keep-with-previous doesn't work inside tables and lists, yet.
+      </known-issue>
+      <known-issue>
+        If two consecutive pages don't have the same available width, the 
+        content currently isn't properly fit into the available space on
+        the new page.
+      </known-issue>
+      <known-issue>
+        background-images on page-number-citations are not placed correctly.
+      </known-issue>
+      <known-issue>
+        Not all FO elements can be referenced by their "id", most notably:
+        table-body, table-header, table-footer and table-row.
+      </known-issue>
+      <known-issue>
+        The backgrounds of table-body, table-header, table-footer and 
+        table-column are not painted, yet.
+      </known-issue>
+      <known-issue>
+        Border and padding conditionality are not supported on table-cells, yet.
+      </known-issue>
+      <known-issue>
+        Column balancing in multi-column documents may not work as expected
+        (<a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=36356">Bugzilla #36356</a>)
+      </known-issue>
+      <known-issue>
+        Internal basic-links don't point to the exact location on a page, yet, as they
+        did in 0.20.5. Currently you land in the upper left corner of the page.
+      </known-issue>
+</known-issues>
diff --git a/src/documentation/content/xdocs/0.93/knownissues_overview.xml b/src/documentation/content/xdocs/0.93/knownissues_overview.xml
new file mode 100644
index 000000000..0f91bb482
--- /dev/null
+++ b/src/documentation/content/xdocs/0.93/knownissues_overview.xml
@@ -0,0 +1,72 @@
+<?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" "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 currently disabled test cases in the test suite for the FO tree tests.
+      The data for this section comes from 
+      <a href="http://svn.apache.org/repos/asf/xmlgraphics/fop/trunk/test/fotree/disabled-testcases.xml">test/fotree/disabled-testcases.xml</a>.
+    </p>
+    <xi:include href="cocoon://knownissues-raw-fotree_0.93.xml#xpointer(/document/body/*)"/>
+  </section>
+  <section>
+    <title>Layout Engine</title>
+    <p>
+      This section lists currently disabled test cases in the test suite for the layout engine tests.
+      The data for this section comes from 
+      <a href="http://svn.apache.org/repos/asf/xmlgraphics/fop/trunk/test/layoutengine/disabled-testcases.xml">test/layoutengine/disabled-testcases.xml</a>.
+    </p>
+    <xi:include href="cocoon://knownissues-raw-layoutengine_0.93.xml#xpointer(/document/body/*)"/>
+  </section>
+  <section>
+    <title>Other known issues</title>
+    <p>This section lists other known issues.</p>
+    <xi:include href="cocoon://knownissues-raw-static_0.93.xml#xpointer(/document/body/*)"/>
+  </section>
+</section>
+</body>
+</document>
+
diff --git a/src/documentation/content/xdocs/0.93/layoutengine/disabled-testcases.xml b/src/documentation/content/xdocs/0.93/layoutengine/disabled-testcases.xml
new file mode 100644
index 000000000..cdaaaa741
--- /dev/null
+++ b/src/documentation/content/xdocs/0.93/layoutengine/disabled-testcases.xml
@@ -0,0 +1,328 @@
+<?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>External link around an SVG not properly sized</name>
+    <file>basic-link_external-destination_2.xml</file>
+    <description>The bpd trait of the inlineparent area for the basic-link
+    is not sized correctly if it wraps an image that is higher than the 
+    nominal line.</description>
+  </testcase>
+  <testcase>
+    <name>Bugzilla #36391: reference-orientation</name>
+    <file>block-container_reference-orientation_bug36391.xml</file>
+    <description>There's a problem involving nested block-containers
+    and reference-orientation 180/-180.</description>
+    <reference>http://issues.apache.org/bugzilla/show_bug.cgi?id=36391</reference>
+  </testcase>
+  <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>Hyphenation with preserved linefeeds</name>
+    <file>block_hyphenation_linefeed_preserve.xml</file>
+    <description>When hyphenation is enabled and linefeeds are preserved linefeeds 
+    are painted as '#' and the text is output multiple times.</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>Footnotes swallowed in hyphenated fo:inlines</name>
+    <file>footnote_in_inline.xml</file>
+    <description>getChangedKnuthElements probably loses the footnote 
+    layout manager somewhere along the way.</description>
+  </testcase>
+  <testcase>
+    <name>Footnotes swallowed in lists</name>
+    <file>footnote_in_list.xml</file>
+    <description>Element lists for lists are created by combining the 
+    element lists from list-item-label and list-item-body. The 
+    footnotes contained in the KnuthBlockBoxes are not propagated to 
+    the combined element list.</description>
+    <reference>http://issues.apache.org/bugzilla/show_bug.cgi?id=37579</reference>
+  </testcase>
+  <testcase>
+    <name>Footnotes swallowed in tables</name>
+    <file>footnote_in_table.xml</file>
+    <description>Element lists for tables are created by combining the 
+    element lists from the individual table-cells. The footnotes 
+    contained in the KnuthBlockBoxes are not propagated to the combined 
+    element list.</description>
+    <reference>http://issues.apache.org/bugzilla/show_bug.cgi?id=37579</reference>
+  </testcase>
+  <testcase>
+    <name>keeps on inlines NYI</name>
+    <file>inline_keep-together.xml</file>
+    <description>Keeps are not implemented in inline-level elements, yet.</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>keep-with-previous doesn't work in lists</name>
+    <file>list-block_keep-with-previous.xml</file>
+    <description>Keep-with-previous doesn't work inside tables and
+    lists, yet.</description>
+  </testcase>
+  <testcase>
+    <name>keep-with-previous doesn't work in lists</name>
+    <file>list-item_block_keep-with-previous.xml</file>
+    <description>Keep-with-previous doesn't work inside tables and
+    lists, yet.</description>
+  </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>page-number-citation-last: FOs spanning multiple pages are not properly handled.</name>
+    <file>page-number-citation-last_basic.xml</file>
+    <description>Resolution of forward references does not wait until an FO is fully finished when an FO spans multiple pages.</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>No background-images on table-body</name>
+    <file>table-body_background-image.xml</file>
+    <description>The backgrounds of table-body, table-header,
+    table-footer and table-column are not painted, yet.</description>
+  </testcase>
+  <testcase>
+    <name>Collapsing Border Model NYI</name>
+    <file>table_border-collapse_collapse_1.xml</file>
+    <description>Border-collapse="collapse" is not yet
+    implemented.</description>
+  </testcase>
+  <testcase>
+    <name>Collapsing Border Model NYI</name>
+    <file>table_border-collapse_collapse_2.xml</file>
+    <description>Border-collapse="collapse" is not yet
+    implemented.</description>
+  </testcase>
+  <testcase>
+    <name>Problems with border and padding on tables</name>
+    <file>table_border_padding.xml</file>
+    <description>The element list seems to not be fully correct, yet, causing
+    the layout to look odd.</description>
+  </testcase>
+  <testcase>
+    <name>keep-with-previous doesn't work inside tables</name>
+    <file>table-cell_block_keep-with-previous.xml</file>
+    <description>Keep-with-previous doesn't work inside tables and
+    lists, yet.</description>
+  </testcase>
+  <testcase>
+    <name>Border and padding conditionality is NYI on table-cells</name>
+    <file>table-cell_border_padding_conditionality.xml</file>
+    <description>Border and padding conditionality are not supported
+    on table-cells, yet.</description>
+  </testcase>
+  <testcase>
+    <name>No background-images on table-header</name>
+    <file>table-header_background-image.xml</file>
+    <description>The backgrounds of table-body, table-header,
+    table-footer and table-column are not painted, yet.</description>
+  </testcase>
+  <testcase>
+    <name>keep-with-previous doesn't work on table-rows</name>
+    <file>table-row_keep-with-previous.xml</file>
+    <description>Keep-with-previous doesn't work inside tables and
+    lists, yet.</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>fo:wrapper around block-level content</name>
+    <file>wrapper_block.xml</file>
+    <description>A ClassCastException occurs when fo:wrapper directly surrounds a 
+    block-level element because its layout manager is written to handle only 
+    inline content.</description>
+  </testcase>
+  <testcase>
+    <name>Bugzilla #40230: invalid extra page break</name>
+    <file>block_break-after_bug40230.xml</file>
+    <description>Currently an extra page is created even if there is nothing
+      after a block with break-after="page"</description>
+    <reference>http://issues.apache.org/bugzilla/show_bug.cgi?id=40230</reference>
+  </testcase>
+</disabled-testcases>
diff --git a/src/documentation/content/xdocs/0.93/running.xml b/src/documentation/content/xdocs/0.93/running.xml
index 8cc0fe280..492c55ca1 100644
--- a/src/documentation/content/xdocs/0.93/running.xml
+++ b/src/documentation/content/xdocs/0.93/running.xml
@@ -89,14 +89,12 @@
     </section>
     <section id="standalone-start">
       <title>Starting FOP as a Standalone Application</title>
+      <section id="fop-script">
+        <title>Using the fop script or batch file</title>
       <p>
         The usual and recommended practice for starting FOP from the command line is to run the 
         batch file fop.bat (Windows) or the shell script fop (Unix/Linux).
-        If you write your own scripts, be sure to review these standard scripts to make sure that 
-        you get your environment properly configured.
-      </p>
-      <p>
-        The standard scripts for starting FOP require that the environment variable JAVA_HOME be 
+        These scripts require that the environment variable JAVA_HOME be 
         set to a path pointing to the appropriate Java installation on your system. Macintosh OSX 
         includes a Java environment as part of its distribution. We are told by Mac OSX users that 
         the path to use in this case is <code>/Library/Java/Home</code>. <strong>Caveat:</strong>
@@ -105,73 +103,144 @@
         <a href="http://developer.apple.com/java/faq">Java on Mac OSX FAQ</a> for information as 
         it becomes available.
       </p>
-      <p>
-        As an alternative to the start scripts you can run "java -jar build/fop.jar" in which case
-        FOP tries to build the classpath for running FOP dynamically. Please note, that this might
-        not always work as expected.
-      </p>
       <source><![CDATA[
 USAGE
-Fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-rtf|-tiff|-png|-pcl|-ps|-txt|-at|-print] <outfile>
- [OPTIONS]
-  -d          debug mode
-  -x          dump configuration settings
-  -q          quiet mode
-  -c cfg.xml  use additional configuration file cfg.xml
-  -l lang     the language to use for user information
-  -r          relaxed/less strict validation (where available)
-  -dpi xxx    target resolution in dots per inch (dpi) where xxx is a number
-  -s          for area tree XML, down to block areas only
-  -v          to show FOP version being used
+Fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-rtf|-tiff|-png|-pcl|-ps|-txt|-at [mime]|-print] <outfile>
+ [OPTIONS]  
+  -d                debug mode   
+  -x                dump configuration settings  
+  -q                quiet mode  
+  -c cfg.xml        use additional configuration file cfg.xml
+  -l lang           the language to use for user information 
+  -r                relaxed/less strict validation (where available)
+  -dpi xxx          target resolution in dots per inch (dpi) where xxx is a number
+  -s                for area tree XML, down to block areas only
+  -v                to show FOP version being used
+
+  -o [password]     PDF file will be encrypted with option owner password
+  -u [password]     PDF file will be encrypted with option user password
+  -noprint          PDF file will be encrypted without printing permission
+  -nocopy           PDF file will be encrypted without copy content permission
+  -noedit           PDF file will be encrypted without edit content permission
+  -noannotations    PDF file will be encrypted without edit annotation permission
+  -pdfprofile prof  PDF file will be generated with the specified profile
+                    (Examples for prof: PDF/A-1b or PDF/X-3:2003)
 
- [INPUT]
-  infile            xsl:fo input file (the same as the next)
-  -fo  infile       xsl:fo input file
-  -xml infile       xml input file, must be used together with -xsl
-  -xsl stylesheet   xslt stylesheet
-  -atin infile      area tree input file
+ [INPUT]  
+  infile            xsl:fo input file (the same as the next) 
+  -fo  infile       xsl:fo input file  
+  -xml infile       xml input file, must be used together with -xsl 
+  -atin infile      area tree input file 
+  -xsl stylesheet   xslt stylesheet 
+ 
   -param name value <value> to use for parameter <name> in xslt stylesheet
                     (repeat '-param name value' for each parameter)
-
- [OUTPUT]
-  outfile           input will be rendered as pdf file into outfile
-  -pdf outfile      input will be rendered as pdf file (outfile req'd)
-  -awt              input will be displayed on screen
-  -mif outfile      input will be rendered as mif file (outfile req'd)
-  -rtf outfile      input will be rendered as rtf file (outfile req'd)
-  -tiff outfile     input will be rendered as tiff file (outfile req'd)
-  -png outfile      input will be rendered as png file (outfile req'd)
-  -pcl outfile      input will be rendered as pcl file (outfile req'd)
-  -ps outfile       input will be rendered as PostScript file (outfile req'd)
-  -txt outfile      input will be rendered as text file (outfile req'd)
-  -svg outfile      input will be rendered as an svg slides file (outfile req'd)
-  -at [mime] out    representation of area tree as XML (outfile req'd)
+ 
+ [OUTPUT] 
+  outfile           input will be rendered as PDF into outfile
+  -pdf outfile      input will be rendered as PDF (outfile req'd)
+  -pdfa1b outfile   input will be rendered as PDF/A-1b compliant PDF
+                    (outfile req'd, same as "-pdf outfile -pdfprofile PDF/A-1b")
+  -awt              input will be displayed on screen 
+  -rtf outfile      input will be rendered as RTF (outfile req'd)
+  -pcl outfile      input will be rendered as PCL (outfile req'd) 
+  -ps outfile       input will be rendered as PostScript (outfile req'd) 
+  -afp outfile      input will be rendered as AFP (outfile req'd)
+  -tiff outfile     input will be rendered as TIFF (outfile req'd)
+  -png outfile      input will be rendered as PNG (outfile req'd)
+  -txt outfile      input will be rendered as plain text (outfile req'd) 
+  -at [mime] out    representation of area tree as XML (outfile req'd) 
                     specify optional mime output to allow AT to be converted
                     to final format later
-  -print            input file will be rendered and sent to the printer
-                    see options with "-print help"
+  -print            input file will be rendered and sent to the printer 
+                    see options with "-print help" 
   -out mime outfile input will be rendered using the given MIME type
                     (outfile req'd) Example: "-out application/pdf D:\out.pdf"
                     (Tip: "-out list" prints the list of supported MIME types)
-                    
-  -foout outfile    input will only be XSL transformed. The intermediate
-                    XSL-FO file is saved and no rendering is performed.
+  -mif outfile      input will be rendered as MIF (FrameMaker) (outfile req'd)
+                    Experimental feature - requires additional fop-sandbox.jar.
+  -svg outfile      input will be rendered as an SVG slides file (outfile req'd) 
+                    Experimental feature - requires additional fop-sandbox.jar.
+
+  -foout outfile    input will only be XSL transformed. The intermediate 
+                    XSL-FO file is saved and no rendering is performed. 
                     (Only available if you use -xml and -xsl parameters)
 
+
  [Examples]
-  Fop foo.fo foo.pdf
+  Fop foo.fo foo.pdf 
   Fop -fo foo.fo -pdf foo.pdf (does the same as the previous line)
   Fop -xml foo.xml -xsl foo.xsl -pdf foo.pdf
   Fop -xml foo.xml -xsl foo.xsl -foout foo.fo
   Fop foo.fo -mif foo.mif
   Fop foo.fo -rtf foo.rtf
-  Fop foo.fo -print or Fop -print foo.fo
+  Fop foo.fo -print or Fop -print foo.fo 
   Fop foo.fo -awt]]></source>
       <p>
         PDF encryption is only available if FOP was compiled with encryption support 
         <strong>and</strong> if compatible encryption support is availabe at run time. 
         Currently, only the JCE is supported. Check the <a href="pdfencryption.html">Details</a>.
       </p>
+      </section>
+      <section id="your-own-script">
+        <title>Writing your own script</title>
+        <p>FOP's entry point for your own scripts is the class
+<code>org.apache.fop.cli.Main</code>. The general pattern for the
+        command line is: <code>java -classpath &lt;CLASSPATH>
+        org.apache.fop.cli.Main &lt;arguments></code>. The arguments
+        consist of the options and infile and outfile specifications
+        as shown above for the standard scripts. You may wish to review
+        the standard scripts to make sure that 
+        you get your environment properly configured. 
+        </p>
+      </section>
+      <section id="jar-option">
+        <title>Running with java's <code>-jar</code> option</title>
+      <p>
+        As an alternative to the start scripts you can run <code>java
+        -jar path/to/build/fop.jar &lt;arguments></code>, relying on
+        FOP to build the classpath for running FOP dynamically, see <a
+        href="#dynamical-classpath">below</a>. If you use hyphenation,
+        you must put <code>fop-hyph.jar</code> in the <code>lib</code>
+        directory.
+      </p>
+
+      <p>You can also run <code>java -jar path/to/fop.jar
+      &lt;arguments></code>, relying on the <code>Class-Path</code>
+      entry in the manifest file. This works if you put
+      <code>fop.jar</code> and all jar files from the <code>lib</code>
+      directory in a single directory. If you use hyphenation, you
+      must also put <code>fop-hyph.jar</code> in that directory.</p>
+
+		<p>In both cases the arguments consist of the options and
+        infile and outfile specifications as shown above for the
+        standard scripts.</p>
+      </section>
+      <section id="dynamical-classpath">
+		<title>FOP's dynamical classpath construction</title>
+
+		<p>If FOP is started without a proper classpath, it tries to
+		add its dependencies dynamically. FOP uses the current working
+		directory as the base directory for its search. If the base
+		directory is called <code>build</code>, then its parent
+		directory becomes the base directory.</p>
+
+        <p>FOP expects to find <code>fop.jar</code> in the
+		<code>build</code> subdirectory of the base directory, and
+		adds it to the classpath. Subsequently FOP adds all
+		<code>jar</code> files in the lib directory to the
+		classpath. The lib directory is either the <code>lib</code>
+		subdirectory of the base directory, or, if that does not
+		exist, the base directory itself.</p>
+
+        <p>If the system property <code>fop.optional.lib</code>
+		contains the name of a directory, then all <code>jar</code>
+		files in that directory are also added to the classpath. See
+		the methods <code>getJARList</code> and
+		<code>checkDependencies</code> in
+		<code>org.apache.fop.cli.Main</code>.</p>
+
+	  </section>
     </section>
     <section id="check-input">
       <title>Using Xalan to Check XSL-FO Input</title>
diff --git a/src/documentation/content/xdocs/site.xml b/src/documentation/content/xdocs/site.xml
index c33403bcb..164842c9c 100644
--- a/src/documentation/content/xdocs/site.xml
+++ b/src/documentation/content/xdocs/site.xml
@@ -91,6 +91,7 @@
     <about label="About" href="index.html"/>
     <release label="Release Notes" href="releaseNotes_0.93.html"/>
     <changes label="Changes" href="changes_0.93.html"/>
+    <knownissues label="Known Issues" href="knownissues_overview.html"/>
     <upgrading label="Upgrading" href="upgrading.html"/>
     
     <using label="Using FOP">
diff --git a/src/documentation/content/xdocs/trunk/running.xml b/src/documentation/content/xdocs/trunk/running.xml
index 5ab36f4a2..d08d5f963 100644
--- a/src/documentation/content/xdocs/trunk/running.xml
+++ b/src/documentation/content/xdocs/trunk/running.xml
@@ -142,14 +142,13 @@ Fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-rtf|-tiff|-png|-pcl
   -pdfa1b outfile   input will be rendered as PDF/A-1b compliant PDF
                     (outfile req'd, same as "-pdf outfile -pdfprofile PDF/A-1b")
   -awt              input will be displayed on screen 
-  -mif outfile      input will be rendered as MIF (FrameMaker) (outfile req'd)
   -rtf outfile      input will be rendered as RTF (outfile req'd)
-  -tiff outfile     input will be rendered as TIFF (outfile req'd)
-  -png outfile      input will be rendered as PNG (outfile req'd)
   -pcl outfile      input will be rendered as PCL (outfile req'd) 
   -ps outfile       input will be rendered as PostScript (outfile req'd) 
+  -afp outfile      input will be rendered as AFP (outfile req'd)
+  -tiff outfile     input will be rendered as TIFF (outfile req'd)
+  -png outfile      input will be rendered as PNG (outfile req'd)
   -txt outfile      input will be rendered as plain text (outfile req'd) 
-  -svg outfile      input will be rendered as an SVG slides file (outfile req'd) 
   -at [mime] out    representation of area tree as XML (outfile req'd) 
                     specify optional mime output to allow AT to be converted
                     to final format later
@@ -158,6 +157,10 @@ Fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-rtf|-tiff|-png|-pcl
   -out mime outfile input will be rendered using the given MIME type
                     (outfile req'd) Example: "-out application/pdf D:\out.pdf"
                     (Tip: "-out list" prints the list of supported MIME types)
+  -mif outfile      input will be rendered as MIF (FrameMaker) (outfile req'd)
+                    Experimental feature - requires additional fop-sandbox.jar.
+  -svg outfile      input will be rendered as an SVG slides file (outfile req'd) 
+                    Experimental feature - requires additional fop-sandbox.jar.
 
   -foout outfile    input will only be XSL transformed. The intermediate 
                     XSL-FO file is saved and no rendering is performed.