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

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

diff --git a/src/documentation/content/xdocs/0.92/configuration.xml b/src/documentation/content/xdocs/0.92/configuration.xml
index 9bc5bebc2fff093ad46707508f5fc34ad00fe4c1..85cb8e25b4fb89e7305d0e6795e9c9a448b71446 100644 (file)
--- 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 99b92c7d377edb0b27ea028ad583b941b25b1d0d..c40a64de5f713b55c9ad37ad54e0cfc80edd1b01 100644 (file)
--- 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>