<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.2//EN" "dtd/faq-v12.dtd" [
<!ENTITY s '<code>site.xml</code>'>
]>

<faqs title="Frequently Asked Questions">

  <part id="getting_started">
    <title>Building Forrest</title>
    <faq id="checked_out_now_what">
      <question>
        I have checked out a working copy of <code>xml-forrest</code> CVS, now what?
      </question>
      <answer>
        <p>
          Run &quot;<code>./build.sh</code>&quot; to build forrest, then run
          &quot;<code>forrest</code>&quot; to generate the documentation
          for Forrest, built with Forrest.
          The documentation is generated in the <code>build/site/</code> directory.
          Logfiles are in the <code>build/tmp/context/WEB-INF/logs/</code> directory.
          When you thereafter update your cvs, then run "build clean" before building.
        </p>
        <p>
          The <link href="site:your-project">Using Forrest</link> guide provides
          further step-by-step assistance in getting started with Forrest for your project.
        </p>
      </answer>
    </faq>

    <faq id="cygwin_mutex_error">
      <question>
        When running <code>./build.sh</code> in cygwin, I get an error:
        <code>cygpath.exe: *** can't create title mutex, Win32 error 6</code>. 
      </question>
      <answer>
        <p>
          This <link
            href="http://issues.cocoondev.org/jira//secure/ViewIssue.jspa?key=FOR-10">appears
            to be a bug in cygwin</link>.  Please use the .bat script instead.
        </p>
      </answer>
    </faq>
  </part>



  <part id="technical">
    <title>Technical</title>
    <faq id="ignoring_javadocs">
      <question>
        How do I stop Forrest breaking on links to external files that may not
        exist, like javadocs?
      </question>
      <answer>
        <p>
          This can be done by overriding the <code>cli.xconf</code> config file,
          and defining patterns for URLs to exclude.
        </p>
        <p>
          This means creating a directory <code>src/documentation/conf</code>
          (or wherever <code>${forrest.conf-dir}</code> points) and copying
          <code>$FORREST_HOME/WEB-INF/cli.xconf</code> to it.  Then edit
          cli.xconf, and add any exclude sections you require at the end.  The
          default cli.xconf ignores directory links and links containing
          'apidocs' or starting with 'api/':
        </p>
        <source><![CDATA[
   ....
   <!-- Includes and excludes can be used to limit which URLs are rendered -->
   ]]><strong><![CDATA[
   <exclude pattern="**/"/>
   <exclude pattern="**apidocs**"/>
   <exclude pattern="api/**"/>
   ]]></strong><![CDATA[

   <uri src="favicon.ico"/>
</cocoon>]]></source>
        <p>This is just an example, and you should modify it appropriately for
          your site.</p>
        <note>
          Wildcards may be used.  Wildcards work as in Cocoon's sitemap.  <strong>foo/*</strong> would match
          <code>foo/bar</code>, but not <code>foo/bar/baz</code> &mdash; use <strong>foo/**</strong> to match that.
        </note>
      </answer>
    </faq>

    <faq id="link_raw">
      <question>How do I link to raw files such as config.txt and brochure.pdf?
      </question>
      <answer>
        <p>
          Place them in the <code>src/documentation/content</code> directory
          and they will get copied into the output tree where you can link to
          them. You can also have sub-directories there to reflect your xdocs
          tree. See the samples documents when you 'forrest seed' a new
          project for a demonstration of this ability.
        </p>
      </answer>
    </faq>

    <faq id="build_msg_a">
      <question>What do the numbers in square brackets mean when Forrest lists
        each document that it has built?
      </question>
      <answer>
        <source><![CDATA[
 * [37] index.html
 * [0] images/project-logo.png
 * [0] skin/images/printer.gif
 * [32] components/index.html
 * [31] components/resolver/index.html
...
          ]]></source>
        <p>
         This is the number of links that were gathered from that page.
        </p>
      </answer>
    </faq>

    <faq id="pdf_images">
      <question>Image don't display in PDFs. How do I fix this?</question>
      <answer>
        <p>
          Forrest uses <link href="http://xml.apache.org/fop/">Apache FOP</link>
          for rendering images.  FOP cannot handle all image types natively, and
          requires third-party jars to be added.  For an overview, see <link
            href="http://xml.apache.org/fop/graphics.html">FOP Graphics
            formats</link>
        </p>
        <p>Specifically, to get PNGs working in PDFs with Jimi:</p>
        <ol>
          <li>Download Jimi from <link
              href="http://java.sun.com/products/jimi/">http://java.sun.com/products/jimi/</link></li>
          <li>Unpack the Jimi distribution and copy JimiProClasses.zip to
            <code>lib/core/jimi-1.0.jar</code> (or to
            <code>src/documentation/lib/jimi-1.0.jar</code> so that each
            developer does not need to modify their Forrest installation).</li>
          <li>Rebuild Forrest (if you used the lib/core/ option above).</li>
        </ol>
        <p>Alternative you can use JAI (Java Advanced Imaging API). For more
          info, see <link
            href="http://xml.apache.org/fop/graphics.html#packages">FOP Graphics 
            Packages</link>
        </p>
        <note>Due to Sun's licensing, we cannot redistribute Jimi or JAI with
          Forrest</note>
      </answer>
    </faq>


     <faq id="index.html">
      <question>
        The tab link in my site incorrectly assumes that 'index.html' is present in
        the linked-to directory. How do I fix this?
      </question>
      <answer>
        <p>
          In <code>tabs.xml</code>, use @href instead of @dir, and omit the trailing
          '/'. That will leave which file to serve up to the sitemap.  For example, if
          the 'User Manual' tab should link to <code>manual/Introduction.html</code>,
          <code>tabs.xml</code> should contain:
        </p>
        <source><![CDATA[
          <tab label="User Manual" href="manual"/>
          ]]></source>
        <p>
          and add this rule to the sitemap:
        </p>
        <source><![CDATA[
          <map:match pattern="manual">
            <map:redirect-to uri="manual/Introduction.html"/>
          </map:match>
          ]]></source>
     </answer>
    </faq>

    <faq id="headless_operation">
      <question>
        When generating PNG images from SVG, I get an error: Can't connect to X11 window server using ':0.0' as the value of the DISPLAY variable.
      </question>
      <answer>
        <p>
          If you are using JDK 1.4.0 or newer, you can enable <em>headless</em>
          operation by running Forrest with the <code>forrest.jvmarg</code>
          parameter set to <code>-Djava.awt.headless=true</code>, like this:
        </p>
        <source>forrest -Dforrest.jvmargs=-Djava.awt.headless=true site</source>
      </answer>
    </faq>

    <faq id="xsp">
      <question>How do I enable <acronym title="eXtensible Server Pages">XSP</acronym> processing?</question>
      <answer>
        <p>First consider whether your needs would be better met by Cocoon itself, rather than Forrest.  Forrest was
          designed primarily with static sites in mind, and is not a general-purpose Cocoon distribution.</p>
        <p>That said, there are valid reasons for wanting programmatically generated content, so here is how to enable
          XSP:</p>
        <ol>
          <li>Download <link
              href="http://cvs.apache.org/viewcvs.cgi/*checkout*/cocoon-2.1/lib/optional/jdtcore-2.1.0.jar?rev=1.1&amp;content-type=application/java">jdtcore-2.1.0.jar</link>,
            and copy it to the $FORREST_HOME/WEB-INF/lib directory (or lib/core/ directory in the source
            distribution).</li>
          <li><p>Override sitemap.xmap in your local project (copy $FORREST_HOME/context/sitemap.xmap to
              src/documentation/conf/), and add the following generator definition in the map:generators section:</p>
            <source>
              &lt;map:generator name="serverpages" pool-grow="2"
              pool-max="32" pool-min="4" src="org.apache.cocoon.generation.ServerPagesGenerator"/&gt;
            </source>
          </li>
          <li><p>Decide how you want to use XSP.  For single files, you could just define a *.xml matcher:</p>
            <source><![CDATA[
<map:match pattern="dynamic.xml">
  <map:generate src="content/xdocs/dynamic.xsp" type="serverpages"/>
  ...
  <map:serialize type="xml"/>
</map:match>]]></source>
            <p>You may instead wish to override forrest.xmap to define a general mapping for XSPs.</p>
          </li>

        </ol>
        <p>See also the <link
            href="http://wiki.cocoondev.org/Wiki.jsp?page=AddingXSPToForrest">AddingXSPToForrest</link> Wiki page.</p>
      </answer>
    </faq>

  </part>

  <part id="old_faqs">
    <title>Older versions</title>
    <faq id="unresolved_project.home">
      <question>When invoking Forrest 0.4 from the
        <code>forrest.antproxy.xml</code>, the build fails because
        <code>${project.home}</code> isn't resolved.
      </question>
      <answer>
        <p>This is a bug in 0.4. The following modification to
          <code>FORREST_HOME/forrest.antproxy.xml</code> should fix it:</p>
        <source
><![CDATA[--- forrest.antproxy.xml        7 Feb 2003 22:21:15 -0000       1.2
+++ forrest.antproxy.xml        22 Feb 2003 09:39:42 -0000
@@ -41,6 +41,7 @@
   </path>
 
   <target name="forrest">
+    <property name="project.home" location="."/>
     <java classname="org.apache.tools.ant.Main" fork="true">
       <classpath refid="forrest-classpath"/>
       <jvmarg value="-Dforrest.home=${forrest.home}"/>]]></source>
      </answer>
    </faq>

    <faq id="odd_html">
      <question>
        After upgrading to 0.4 my HTML looks significantly different, and table
        widths are wrong. What happened?
      </question>
      <answer>
        <p>
          Forrest now uses a HTML 4.0.1 <code>DOCTYPE</code> declaration,
          <code><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01
            Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">]]></code>.
          This causes browsers to render the page in standards-compliance mode,
          or rather, not in "quirks" mode. For some operations (like determining
          table column widths), quirks mode results in better looking pages.
          For the old pre-0.4 behaviour, create a custom sitemap and remove the
          line:</p>
        <source><![CDATA[
          <doctype-system>http://www.w3.org/TR/html4/loose.dtd</doctype-system>
          ]]></source>
      </answer>
    </faq>
    <faq id="validation_error:doctype_root_null">
      <question>
        When building my project, I get an validation error: <code>Document root
          element "site", must match DOCTYPE root "null".</code>.
      </question>
      <answer>
        <p>
          You are probably trying to build the project with an old version of
          Forrest (built before 2003-01-08) that is incorrectly trying to validate
          the &s; file.  If so, please update your Forrest
          installation.
        </p>
        <p>
          Alternatively, you may be building with an up-to-date Forrest, but have
          overridden <code>forrest.validate.xdocs.excludes</code> in
          <code>forrest.properties</code>.  With the introduction of
          &s;, the above property must have &s;
          listed to prevent an attempt at DTD-based validation.
        </p>
      </answer>
    </faq>

  </part>

  <part id="general">
    <title>General</title>

    <faq id="generating_menus">
      <question>What is the relation between &s; and
        <code>book.xml</code>?
      </question>
      <answer>
        <p>
          One &s; file in your project root can replace all the book.xml files
          (one per directory) in your site.  Internally, Forrest uses &s; to
          dynamically generate book.xml files.  However, Forrest first checks
          for the existence of a book.xml file, so backwards-compatibility is
          preserved.  If a directory has a book.xml file, the book.xml will be
          used to generate the menu.  This is useful in situations where
          &s;-generated menus aren't appropriate.
      </p>
      </answer>
    </faq>

    <faq id="docbook">
      <question>
        How do I use DocBook as the xml documentation format?
      </question>
      <answer>
        <p>
         There are two ways. Forrest can transform the DocBook format into the
         Forrest "document" DTD on-the-fly and then render that as normal.
         The stylesheet that does this transformation still needs a little
         work but it handles most things.
        </p>
        <p>
         The other way is to use the DocBook stylesheets directly. The DocBook
         DTDs are shipped with Forrest and automatically handled. However, you
         will need to have the DocBook stylesheets on your system (they are
         too massive to ship with Forrest) and configure Forrest accordingly.
         You will need to create a "sitemap" as explained in
         <link href="site:your-project">Using Forrest</link>
         and add matches to handle your DocBook documents, e.g.
        </p>
        <source><![CDATA[
...
  <map:match pattern="**/resolver-*.html">
    <map:generate src="content/xdocs/{1}/resolver-{2}.xml"/>
    <map:transform
      src="file:///usr/share/sgml/docbook/xsl/xhtml/docbook.xsl"/>
    <map:serialize/>
  </map:match>
...
]]>
        </source>
        <p>
         You can also use a mixture of the two methods, some handled
         automatically by Forrest and some directly using DocBook stylesheets.
         You can also have a mixture of "document-v*" DTD and DocBook.
        </p>
      </answer>
    </faq>

    <faq id="how_can_I_help">
      <question>
        How can I help?
      </question>
      <answer>
        <p>
          Join the forrest-dev <link href="site:mail-lists">mailing list</link>,
          and tell us what you'd like to see improved.  We regard all feedback
          as valuable, particularly from newcomers&mdash;often, close proximity
          blinds software developers to faults that are obvious to everyone
          else. Don't be shy!
        </p>
        <p>
          More info on contributing can be found on the <link
            href="site:contrib">Contributing to Forrest</link> page.  Its always
          a good idea to check the Forrest <link href="site:todo">to do</link>
          list before diving in.
        </p>
      </answer>
    </faq>
  </part>
</faqs>
