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

diff --git a/src/documentation/content/xdocs/configuration.xml b/src/documentation/content/xdocs/configuration.xml
index 4ed2d188dbb8663ac2a12a2e5d64d0196b94baf5..a8d8576ebd3bd8c68eb150400016d9e451025d53 100644 (file)
--- a/src/documentation/content/xdocs/configuration.xml
+++ b/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>

diff --git a/src/documentation/content/xdocs/faq.xml b/src/documentation/content/xdocs/faq.xml
index ba6335d88487ee38dcbe36e6d95beaaa00d9b41b..7064e34173a361e0b1618747db4c97a2f25bd283 100644 (file)
--- a/src/documentation/content/xdocs/faq.xml
+++ b/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">

diff --git a/src/documentation/content/xdocs/fo.xml b/src/documentation/content/xdocs/fo.xml
index 80c502a991aad8ac822aa71343950f7c762ec229..40f92eb256cf34d1ba6eab15eebd0ea8f0d3091f 100644 (file)
--- a/src/documentation/content/xdocs/fo.xml
+++ b/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>