From: William Victor Mote <vmote@apache.org>
Date: Tue, 15 Apr 2003 16:38:38 +0000 (+0000)
Subject: Move memory discussion from faq.xml to running.xml.
X-Git-Tag: Root_Temp_KnuthStylePageBreaking~1612
X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=41979b16e8556868ad09af812ba509413db461b8;p=xmlgraphics-fop.git

Move memory discussion from faq.xml to running.xml.


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

diff --git a/src/documentation/content/xdocs/faq.xml b/src/documentation/content/xdocs/faq.xml
index 0d8f9d2d8..6f4942856 100644
--- a/src/documentation/content/xdocs/faq.xml
+++ b/src/documentation/content/xdocs/faq.xml
@@ -187,70 +187,7 @@
       <question>I get an OutOfMemoryException.</question>
       <answer>
         <p>
-          FOP can consume quite a bit of memory, even though this has been
-          continually improved. The memory consumption is partially inherent to
-          the formatting process and partially caused by implementation
-          choices. For certain layouts, all FO processors currently on the
-          market have memory problems.
-        </p>
-        <p>
-          Some hints regarding your document structure:
-        </p>
-        <ul>
-          <li>
-            Increase memory settings of the JVM, see for example <link
-              href="http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/java.html">the
-              -Xmx option</link>. Be aware that it is usually unwise to
-            increase the memory allocated to the JVM beyond the amount of
-            physical RAM, it will significantly slow down. YMMV.
-          </li>
-          <li>
-            Avoid forward references, that is page number citations to pages to
-            places on pages which follow the citation. Forward references cause
-            all pages from the page with the reference on to be held in memory
-            until the page with the referenced element is encountered. Common
-            forward references are table of contents at the beginning of the
-            document and the <link href="#pagenum">"page N of TOTAL"</link> in
-            footers. Forward references may be required by the task, however,
-            if you are getting a memory overflow you should at least check
-            whether this is really as necessary as claimed. A TOC, for example,
-            could often be placed at the end of the document without dimishing
-            it's value too much, the paper can be reshuffled after printing,
-            and you can use bookmarks in PDF.
-          </li>
-          <li>
-            Avoid large images, especially if they are scaled down. Scale them
-            outside of FOP and use the already scaled images for the FOP
-            run. For many image formats it is mainly the size of the image file
-            which matters, not width*height, so you can try other means like
-            using a higher compression rate.
-          </li>
-          <li>
-            Use multiple page sequences. FOP starts rendering after the end of
-            a page sequence is encountered. While the actual rendering is done
-            page by page, some additional memory allocated for other purposes
-            could be freed after the page sequence has been rendered.
-          </li>
-          <li>
-            Break down large tables. If you don't use table headers and
-            footers, just start a new table every N rows. With headers and
-            footers, consider integrating them as normal table rows, or, if
-            they are used at page breaks, try to put the information into
-            static content. You can use markers to change them.
-          </li>
-        </ul>
-        <p>
-          There are also some bugs which cause FOP to go into an nonterminating
-          loop, which also often results in a memory overflow. A characteristic
-          symptom are continuous <link href="#boxoverflow">box
-          overflows</link>. Most of them are triggered by elements not fitting
-          in the available space, like big images and improperly specified width
-          of nested block elements. Look for such stuff and correct it.
-        </p>
-        <p>
-          Reducing memory consumption in general and squishing bugs is an
-          ongoing effort, partially addressed in the <link
-          href="dev/index.html">redesign</link>.
+          See <link href="running.html#memory">FOP Memory</link>.
         </p>
       </answer>
     </faq>
diff --git a/src/documentation/content/xdocs/running.xml b/src/documentation/content/xdocs/running.xml
index 7767cef5b..b043dd07c 100644
--- a/src/documentation/content/xdocs/running.xml
+++ b/src/documentation/content/xdocs/running.xml
@@ -101,6 +101,61 @@
         Note that there are subtle differences to the FOP command line.
       </p>
     </section>
+    <section id="memory">
+      <title>Memory Usage</title>
+      <p>
+FOP can consume quite a bit of memory, even though this has been continually improved.
+This is partly inherent to the formatting process and partly caused by implementation choices.
+All FO processors currently on the market have memory problems with certain layouts.
+      </p>
+      <p>
+If you are running out of memory when using FOP, here are some ideas that may help:
+      </p>
+      <ul>
+        <li>
+Increase memory available to the JVM. See <link href="http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/java.html">the -Xmx option</link> for more information.
+          <warning>
+It is usually unwise to increase the memory allocated to the JVM beyond the amount of physical RAM, as this will generally cause significantly slower performance.
+          </warning>
+        </li>
+        <li>
+Avoid forward references.
+Forward references are references to some later part of a document.
+Examples include page number citations which refer to pages which follow the citation, tables of contents at the beginning of a document, and page numbering schemes that include the total number of pages in the document (<link href="faq.html#pagenum">"page N of TOTAL"</link>).
+Forward references cause all subsequent pages to be held in memory until the reference can be resolved, i.e. until the page with the referenced element is encountered.
+Forward references may be required by the task, but if you are getting a memory overflow, at least consider the possibility of eliminating them.
+A table of contents might be eliminated, relying on PDF bookmarks instead.
+Or it might be moved to the end of the document without dimishing its value very much.
+Or, in some circumstances, the paper could even be reshuffled after printing.
+        </li>
+        <li>
+Avoid large images, especially if they are scaled down.
+If they need to be scaled, scale them in another application upstream from FOP.
+For many image formats, memory consumption is driven mainly by the size of the image file itself, not its dimensions (width*height), so increasing the compression rate may help.
+        </li>
+        <li>
+Use multiple page sequences.
+FOP starts rendering after the end of a page sequence is encountered.
+While the actual rendering is done page-by-page, some additional memory allocated for other purposes could be freed after the page sequence has been rendered.
+        </li>
+        <li>
+Break down large tables.
+If you don't use table headers and footers, just start a new table every N rows.
+With headers and footers, consider integrating them as normal table rows, or, if they are used at page breaks, try to put the information into static content.
+You can then use markers to change them.
+        </li>
+      </ul>
+      <p>
+There are currently some bugs which cause FOP to go into a nonterminating loop, which will also often result in a memory overflow.
+A characteristic symptom is continuous <link href="faq.html#boxoverflow">box overflows</link> in the log.
+Most of these loops are triggered by elements that do not fit in the available space, such as big images or an improperly specified width in nested block elements.
+The only workaround is to locate such problems and correct them.
+      </p>
+      <p>
+One of FOP's stated design goals is to be able to process input of arbitrary size.
+Addressing this goal is one of the prime motivations behind the <link href="dev/index.html">FOP Redesign</link>.
+      </p>
+    </section>
     <section>
       <title>Problems</title>
       <p>If you have problems running FOP, please have a look at the <jump href="gethelp.html">"How to get Help" page</jump>.</p>