1. add section about external resources in fo.xml

2. update the faq regarding external resources to point to this new section
3. update configuration.xml to include additional information about the default baseDir (which information was formerly in the faq).


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

src/documentation/content/xdocs/configuration.xml

@@ -45,7 +45,7 @@ Also, since the configuration file is XML, be sure to keep it well-formed.</p>
       <tr>
         <td>baseDir</td>
         <td>URL</td>
-        <td>directory containing the input FO file</td>
+        <td>For command-line, the directory containing the input FO or XML file. For embedded, the current working directory.</td>
       </tr>
       <tr>
         <td>fontBaseDir</td>
@@ -53,7 +53,7 @@ Also, since the configuration file is XML, be sure to keep it well-formed.</p>
         <td>value of baseDir</td>
       </tr>
       <tr>
-        <td>hyphenation-dir</td>
+        <td><link href="#hyphenation-dir">hyphenation-dir</link></td>
         <td>URL</td>
         <td>None. This is for custom hyphenation patterns.</td>
       </tr>

src/documentation/content/xdocs/faq.xml

@@ -309,22 +309,7 @@
     <faq id="cannot-find-external-graphics">
       <question>FOP cannot find a file for fo:external-graphics.</question>
       <answer>
-        <p>
-          The src attribute of the fo:external-graphics element takes an URI,
-          not a file name.
-        </p>
-        <p>
-          Relative URLs are resolved against the baseDir property of FOP. For
-          the command line FOP application, the baseDir is the directory of the
-          input file, either the FO file or the XML source. If FOP is used
-          embedded in a servlet, <link href="embedding.html">baseDir can be
-            set explicitely</link>. If it's not set, it is usually the current
-          working directory of the process which runs FOP.
-        </p>
-        <!--p>
-          See Understanding URIs and URLs and Understanding
-          URL resolving.
-        </p-->
+        <p>The src attribute of the fo:external-graphics element requires a URI, not a file name. See <link href="fo.html#external-resources">External Resources</link> for more information about specifying URIs.</p>
       </answer>
     </faq>
     <faq id="fonts-not-found">

src/documentation/content/xdocs/fo.xml

@@ -436,6 +436,14 @@ See the notes near the beginning of the document for instructions on how to use
   </fo:simple-page-master>
 </fo:layout-master-set>]]></source>
       </section>
+      <section id="external-resources">
+        <title>External Resources</title>
+        <p>Resources needed by an XSL-FO file that are external to it (graphics, for example), are defined in the XSL-FO standard as being of type "uri-specification". This is defined in the standard at <jump href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice5.html#section-N8794-Property-Datatypes">Section 5.11 Property Datatypes</jump>, which includes a link to the URI standard itself. Refer to the XSL-FO and URI standards themselves for more detailed instructions.</p>
+        <p>URIs may be either absolute or relative to a base URI. (See <link href="configuration.html">FOP: Configuration</link> for information on setting the base URI for a FOP session). Here is an example referencing an external-graphic that is relative to the base URI:</p>
+        <source><![CDATA[<fo:external-graphic src="url('images/logo.jpg')"/>]]></source>
+        <p>Here is an example referencing an external-graphic that is an absolute URI on a local filesystem:</p>
+        <source><![CDATA[fo:external-graphic src="url('file:d:///images/logo.jpg')"/>]]></source>
+      </section>
     </section>
   </body>
 </document>