Added a comment about the cofiguration schema and some other means to determine configuration errors.

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

2 files changed, 82 insertions, 0 deletions

diff --git a/src/documentation/content/xdocs/0.92/configuration.xml b/src/documentation/content/xdocs/0.92/configuration.xml
index 9bc5bebc2..85cb8e25b 100644
--- a/src/documentation/content/xdocs/0.92/configuration.xml
+++ b/src/documentation/content/xdocs/0.92/configuration.xml
@@ -247,6 +247,47 @@
     </renderer>]]></source>
     </section>
   </section>
+
+	<section>
+	  <title>When it does not work</title>
+
+	  <p>FOP searches the configuration file for the information it
+expects, at the position it expects. When that information is not
+present, FOP will not complain, it will just continue. When there is
+other information in the file, FOP will not complain, it will just
+ignore it. That means that when your configuration information is in
+the file but in a different XML element, or in a different XML path,
+than FOP expects, it will be silently ignored.</p>
+
+	  <p>Check the following possibilities:</p>
+
+	  <ul>
+		<li>The format of the configuration file has changed
+considerably between FOP 0.20.5 and FOP 1.0 and its beta versions. Did
+you convert your file to the new format?</li>
+
+		<li>The FOP distribution contains a schema for configuration
+files, at src/foschema/fop-configuration.xsd. Did you validate your
+configuration file against it? Add the following schema location to
+the <code>schema</code> element:
+
+<source><![CDATA[<fop
+xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+xsi:noNamespaceSchemaLocation=
+"http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/foschema/fop-configuration.xsd?view=co">]]>
+</source>
+
+and run the configuration file through a validating schema
+parser. Note that the schema cannot detect all errors, and that it is
+stricter about the order of some elements than FOP itself is.</li>
+
+		<li>Run FOP in debug mode (command line option
+<code>-d</code>). This makes FOP report which configuration
+information it finds. Check if FOP finds what you expect.</li>
+
+	  </ul>
+
+	</section>
   </body>
 </document>
 
diff --git a/src/documentation/content/xdocs/trunk/configuration.xml b/src/documentation/content/xdocs/trunk/configuration.xml
index 99b92c7d3..c40a64de5 100644
--- a/src/documentation/content/xdocs/trunk/configuration.xml
+++ b/src/documentation/content/xdocs/trunk/configuration.xml
@@ -289,6 +289,47 @@
       </p>
     </section>
   </section>
+
+	<section>
+	  <title>When it does not work</title>
+
+	  <p>FOP searches the configuration file for the information it
+expects, at the position it expects. When that information is not
+present, FOP will not complain, it will just continue. When there is
+other information in the file, FOP will not complain, it will just
+ignore it. That means that when your configuration information is in
+the file but in a different XML element, or in a different XML path,
+than FOP expects, it will be silently ignored.</p>
+
+	  <p>Check the following possibilities:</p>
+
+	  <ul>
+		<li>The format of the configuration file has changed
+considerably between FOP 0.20.5 and FOP 1.0 and its beta versions. Did
+you convert your file to the new format?</li>
+
+		<li>The FOP distribution contains a schema for configuration
+files, at src/foschema/fop-configuration.xsd. Did you validate your
+configuration file against it? Add the following schema location to
+the <code>schema</code> element:
+
+<source><![CDATA[<fop
+xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+xsi:noNamespaceSchemaLocation=
+"http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/foschema/fop-configuration.xsd?view=co">]]>
+</source>
+
+and run the configuration file through a validating schema
+parser. Note that the schema cannot detect all errors, and that it is
+stricter about the order of some elements than FOP itself is.</li>
+
+		<li>Run FOP in debug mode (command line option
+<code>-d</code>). This makes FOP report which configuration
+information it finds. Check if FOP finds what you expect.</li>
+
+	  </ul>
+
+	</section>
   </body>
 </document>