From: Glenn Adams <gadams@apache.org>
Date: Fri, 25 May 2012 19:10:28 +0000 (+0000)
Subject: Update FAQ and New Bug documentation.
X-Git-Tag: fop-1_1rc1old~9
X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=b14cfce3f812f97852d88db7b837b55b0c55c625;p=xmlgraphics-fop.git

Update FAQ and New Bug documentation.

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

diff --git a/src/documentation/content/xdocs/bugs.xml b/src/documentation/content/xdocs/bugs.xml
index e2f36d50d..caeb728b2 100644
--- a/src/documentation/content/xdocs/bugs.xml
+++ b/src/documentation/content/xdocs/bugs.xml
@@ -45,21 +45,66 @@ an email as changes are made to the issue.</li>
     </section>
     <section id="issues_new">
       <title>Unreported Issues (Reporting New Issues)</title>
-      <p>User reports of bugs and requests for enhancements are extremely
-important parts of FOP development, and we appreciate the time you take to help
-us track these issues down.</p>
+      <p>
+        User reports of bugs and requests for enhancements are extremely
+        important parts of FOP development, and we appreciate the time you take to help
+        us track these issues down.
+      </p>
       <ul>
-        <li>To help us ensure that the bug database is as useful as it should be, please
-use the <link href="gethelp.html">Getting Help</link> checklist to determine whether a bug report should be entered.</li>
-        <li>Review the <link href="http://issues.apache.org/bugzilla/page.cgi?id=bug-writing.html">Apache Bug Writing Guidelines</link> before submitting your report.</li>
-        <li>Enter a new issue report at <link href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Fop">The FOP issue database (Bugzilla)</link>.
-You will be asked to login to an existing Bugzilla account or to create a new
-one.
-When entering the bug report, please make your description complete and concise.
-If appropriate, attach a minimal fo file to your report which demonstrates the
-problem.</li>
-        <li>After submission, a copy of your bug report will be automatically
-sent to the FOP developer discussion list.</li>
+        <li>
+          To help us ensure that the bug database is as useful as it should be, please
+          use the <link href="gethelp.html">Getting Help</link> checklist to determine whether a bug report should be entered.
+        </li>
+        <li>
+          Review the <link href="http://issues.apache.org/bugzilla/page.cgi?id=bug-writing.html">Apache Bug
+          Writing Guidelines</link> before submitting your report.
+        </li>
+        <li>
+          Enter a new issue report at <link href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Fop">The
+          FOP issue database (Bugzilla)</link>. You will be asked to login to an existing Bugzilla account or to
+          create a new one. When entering the bug report, please make your description complete and concise.
+          If the issue involves a specific input or output file, then you <strong>MUST</strong> include the
+          following information in the bug report (preferably as one or more attachments):
+          <ul>
+            <li>
+              an input XSL-FO file (an input XML plus XSLT file is not acceptable, unless and only if the
+              issue being reported is related to the built-in XSLT transform processing convenience function provided
+              by FOP); this input <strong>SHOULD</strong> be <em>maximally minimal</em>, which means that it should
+              contain nothing more than the minimum needed to demonstrate the problem; if you do not take the effort
+              to provide a maximally minimal input FO file, then you will be subsequently asked to do so before the
+              bug is processed;
+            </li>
+            <li>
+              a resulting output file, preferably in PDF format; if the issue being reported involves a different output
+              format, then provide both a PDF output file and the output file for the output format for which the report
+              applies;
+            </li>
+            <li>
+              a copy of the FOP configuration file you used (e.g., fop.xconf);
+            </li>
+            <li>
+              if FOP was invoked using the command line (or an equivalent), then a dump of both the input
+              command line and any console output (stderr or stdout) produced; if the report involves an
+              exception, then this <strong>MUST</strong> include the full stack back trace;
+            </li>
+            <li>
+              information describing the version of FOP you are using and the platform (and OS) on which
+              you are invoking FOP;
+            </li>
+            <li>
+              if the report applies to the use of a specific font other than one of the built-in, base 14
+              fonts, then information that describes where to obtain the font.
+            </li>
+          </ul>
+        </li>
+        <li>
+          After submission, a copy of your bug report will be automatically
+          sent to the FOP developer discussion list. If additional information is needed to
+          process the bug, then the bug will be set to the <code>NEEDSINFO</code> state, and
+          you will be asked to provide the additional information. You can avoid this extra
+          step by being diligent about providing <strong>all</strong> of the information
+          indicated above.
+        </li>
       </ul>
     </section>
   </body>
diff --git a/src/documentation/content/xdocs/faq.xml b/src/documentation/content/xdocs/faq.xml
index c4ddc6054..845c24045 100644
--- a/src/documentation/content/xdocs/faq.xml
+++ b/src/documentation/content/xdocs/faq.xml
@@ -25,7 +25,7 @@
       <question>What is Apache™ FOP?</question>
       <answer>
       <p>
-        FOP is a print formatter for <link href="#XSLFO">XSL formatting
+        FOP is a print formatter for <link href="#xslfo">XSL formatting
         objects</link>.
       </p>
       <p>
@@ -65,16 +65,23 @@
       <question>How does FOP interact with other Apache Projects?</question>
       <answer>
         <p>
-          FOP is distributed with <link
-          href="http://xml.apache.org/cocoon">Cocoon</link> as a PDF serializer
-          for XSL (FO) documents.
+          <link href="http://xmlgraphics.apache.org/commons">XML Graphics Commons</link> is used with
+          FOP to provide graphics functions that are common to a number of Apache projects.
         </p>
         <p>
-          <link href="http://xmlgraphics.apache.org/batik">Batik</link> can be used with
+          <link href="http://xmlgraphics.apache.org/batik">Batik</link> is used with
           FOP to <link
           href="http://xmlgraphics.apache.org/batik/svgrasterizer.html">transcode an SVG
           image</link> into a PDF document.
         </p>
+        <p>FOP also makes use of the following Apache projects:</p>
+        <ul>
+          <li><link href="http://excalibur.apache.org/framework/">Avalon Framework</link></li>
+          <li><link href="http://jakarta.apache.org/commons/io/">Jakarta Commons IO</link></li>
+          <li><link href="http://jakarta.apache.org/commons/logging/">Jakarta Commons Logging</link></li>
+          <li><link href="http://xalan.apache.org/">Xalan-J</link></li>
+          <li><link href="http://xml.apache.org/commons/components/external/">XML Commons Externals</link></li>
+        </ul>
       </answer>
     </faq>
     <faq id="xsl-def">
@@ -83,7 +90,7 @@
         <p>
           XSL is a W3C standard concerned with publishing XML documents. It
           consists of two parts: <link href="#XSLT">XSLT</link> and <link
-          href="#XSLFO">XSL-FO</link>. The acronym expands to
+          href="#xslfo">XSL-FO</link>. The acronym expands to
           e<strong>X</strong>tensible <strong>S</strong>tylesheet
           <strong>L</strong>anguage.
         </p>
@@ -93,7 +100,9 @@
       <question>What is XSL-FO?</question>
       <answer>
         <p>
-          XSLFO (aka XSL-FO) is an XML vocabulary that is used to specify a pagination and
+          XSLFO (aka XSL-FO) is an XML vocabulary, defined by W3C Recommendation
+          <link href="http://www.w3.org/TR/xsl/">Extensible Stylesheet Language (XSL)
+          Version 1.1</link>, that is used to specify a pagination and
           other styling for page layout output. The acronym &#8220;FO&#8221;
           stands for
           <strong>F</strong>ormatting <strong>O</strong>bjects. XSLFO can be
@@ -226,8 +235,7 @@
       <answer>
         <p>
           This is usually caused by an older version of one of the FOP jars or
-          old XML tools in the classpath. Check in particular for parser.jar,
-          jaxp.jar, xml4j.jar or lotusxsl.jar.
+          old XML tools in the classpath.
         </p>
         <p>
           Incompatible versions of Batik may also cause this problem. Use the
@@ -269,8 +277,9 @@
           the <code>file:</code> prefix, for example <code>file.ext</code>,
           <code>path/file.ext</code> or <code>../file.ext</code>. The string
           <code>file:path/file.ext</code> is <em>not</em> a relative URL,
-          in fact, it isn't a valid URL at all. A relative URL is subject to a
-          resolving process, which transforms it into an absolute
+          in fact, it isn't a valid URL at all since the <code>file</code>
+          scheme does not (officially) support relative paths. A relative URL
+          is subject to a resolving process, which transforms it into an absolute
           URL.
         </p>
         <!--p>
@@ -283,31 +292,8 @@
       <question>I get an "[ERROR]: null", or a NullPointerException.</question>
       <answer>
         <p>
-          This is often caused by an invalid FO document. Currently only very
-          common errors are intercepted and produce a comprehensible error
-          message. If you forgot container elements like <code>fo:page-sequence</code> or
-          <code>fo:flow</code> and put blocks and inline elements directly as children of
-          <code>fo:root</code> or <code>fo:page-sequence</code>, you'll only get a
-          NullPointerException. Check whether your FO file has a proper
-          structure. In some cases there are mandatory properties, like the
-          master-reference in <code>fo:conditional-page-master-reference</code>, check also
-          whether you got them right.
-        </p>
-        <p>
-          You may find it helpful to use the <link href="#fo-validate">validation tools</link> to validate your
-          FO document. This will catch most problems, but should not be
-          relied upon to catch all.
-        </p>
-        <p>
-          If you use XSLT, problems in your style sheet and in your
-          source XML also can produce a NullPointerException. <link
-          href="1.0/running.html#check-input">Run the transformation
-          separately</link> to check for this, usually you'll get a
-          detailed error message from the XSLT processor.
-        </p>
-        <p>
-          If you turn on debugging with the "<code>-d</code>" option you may be able to
-          see more detailed information.
+          This is a very likely a bug in FOP. If you encounter this error, please
+          <link href="bugs.html#issues_new">Open a New Bug</link>.
         </p>
       </answer>
     </faq>
@@ -322,9 +308,9 @@
       <answer>
         <p>
           The most likely reason is a known problem with the Java run time
-          environment which is triggered by rendering SVGs. Suns JDK 1.4 does
-          not have this problem. See also <link href="#svghangs">FOP does not
-          exit if a SVG is included</link>.
+          environment which is triggered by rendering SVGs. Sun's JDK 1.4 and
+          later do not have this problem. See also <link href="#svghangs">FOP
+          does not exit if a SVG is included</link>.
         </p>
         <p>
           Another possibility is that FOP went into a non terminating
@@ -340,6 +326,10 @@
           the FOP output regularly to empty the pipe buffer. It is best to avoid
           exec'ing FOP, use the library interface instead.
         </p>
+        <p>
+          If you can reproduce this problem given a specific input and configuration,
+          then please <link href="bugs.html#issues_new">Open a New Bug</link>.
+        </p>
       </answer>
     </faq>
     <faq id="boxoverflow">
@@ -441,8 +431,7 @@ public class DefaultErrorListener implements ErrorListener {
           To avoid the warning you can simply delete the
           old Font Cache file, which lives in ${base}\conf\font.cache (see <link
           href="1.0/configuration.html#general-elements">font-base
-          configuration</link>). Or you can disable Font Caching altogether using
-          the option "use-cache."
+          configuration</link>).
         </p>
       </answer>
     </faq>
@@ -524,7 +513,7 @@ Check the following:</p>
           HTTP. Possible issues include security settings on the
           server, server configuration, and missing cookies or other
           authorization information. Any easy way to check this is to
-          cut&amp;paste the source URL from the fo:external-graphic
+          cut and paste the source URL from the <code>fo:external-graphic</code>
           into the Location field of a browser <strong>on the machine
           where the FOP process will be running</strong>.</li>
         </ul>
@@ -627,7 +616,7 @@ Check the following:</p>
             explicit wrapping+clipping,
           </li>
           <li>
-            insert zero width spaces (U+200B or &amp;#x200B;) to allow FOP to
+            insert zero width spaces (&amp;#x200B;) to allow FOP to
             wrap.
           </li>
         </ul>
@@ -1281,7 +1270,7 @@ Can I control this?</question>
       <question>Where can I learn how the FOP docs and web site are built?</question>
       <answer>
         <p>
-          See FOP <link href="dev/doc.html">Doc Management</link>. ;-)
+          See FOP <link href="dev/doc.html">Doc Management</link>.
         </p>
       </answer>
     </faq>
@@ -1307,7 +1296,7 @@ Can I control this?</question>
             If you have a runtime exception or other runtime problem:
             <ul>
               <li>
-                double-check the <link href="#part-running">Runtime FAQs</link>.
+                Double check the <link href="#part-running">Runtime FAQs</link>.
               </li>
               <li>
                 ClassNotFoundException, NoSuchMethodException and
@@ -1325,7 +1314,7 @@ Can I control this?</question>
           </li>
           <li>
             In the case where something works properly with another formatter,
-            (AntennaHouse, PassiveTex, etc.) but doesn't work with FOP, please
+            (e.g., AntennaHouse, PassiveTex, etc.) but doesn't work with FOP, please
             check the <!--link href="relnotes.html"-->Release Notes<!--/link-->, the
             <link href="compliance.html">FOP Standards Compliance</link> document,
             and the remaining FAQ in this document. If not found there, look at the
@@ -1348,13 +1337,8 @@ Can I control this?</question>
             Problems specific to a certain XSLT processor, like Xalan, Saxon or
             MSXML, should be handled by processor specific lists. This includes
             problems with deployment, processor specific extensions, suspected
-            bugs and processor specific APIs. Note that JDK 1.4 comes with an
-            XML parser and an XSLT processor which are older versions of
-            Xerces and Xalan, respectively, and both have a number of annoying
-            bugs. See http://java.sun.com/developer/EJTechTips/2003/tt0311.html
-            and http://java.sun.com/j2se/1.4.2/docs/guide/standards/ (or similar
-            pages for later Java releases) for some hints on how to use more
-            recent versions or other packages instead.
+            bugs and processor specific APIs. Note that JDK 1.4 and later come with an
+            XML parser and an XSLT processor which may be the source of the problem.
           </li>
           <li>
             Problems with servlet containers should be asked on the vendor
diff --git a/status.xml b/status.xml
index fc5b5c630..a41223e6c 100644
--- a/status.xml
+++ b/status.xml
@@ -63,6 +63,9 @@
       documents. Example: the fix of marks layering will be such a case when it's done.
     -->
     <release version="FOP Trunk" date="TBD">
+      <action context="Docs" dev="GA" type="update">
+        Update FAQ and New Bug documentation.
+      </action>
       <action context="Code" dev="VH" type="add">
         Added support for the role property on fo:page-sequence, fo:flow and fo:static-content. This 
         allows to change the mapping of those FOs to PDF structure types when enabling