<?xml version="1.0" encoding="UTF-8"?>
<!--
  Copyright 2002-2004 The Apache Software Foundation

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.2//EN" "http://forrest.apache.org/dtd/faq-v12.dtd" [
<!ENTITY s '<code>site.xml</code>'>
]>

<faqs title="Frequently Asked Questions">

  <part id="getting_started">
    <title>Getting Started and Building Forrest</title>
    <faq id="overview">
      <question>
        Where can i read an overview about how to work with Forrest?
      </question>
      <answer>
        <p>
          See the <link href="site:your-project">Using Forrest</link> guide.
        </p>
      </answer>
    </faq>

    <faq id="website-status">
      <question>
       Which version of Forrest does the website documentation relate to? 
      </question>
      <answer>
        <p>
          The documentation on the Forrest website relates to the current
          head development version of the source repository. See
          <link href="index.html#status">further explanation</link>.
        </p>
      </answer>
    </faq>

    <faq id="requirements">
      <question>
        What are the system requirements for Forrest?
      </question>
      <answer>
        <p>
          Forrest includes everything necessary to build and run, except
          of course for Java. In addition to all the Cocoon JARs, Forrest
          includes and uses its own version of Ant. The
          <link href="http://cocoon.apache.org/2.1/installing/requirements.html">Cocoon requirements</link>
          indicate that Java 1.3+ is required.
        </p>
      </answer>
    </faq>

    <faq id="cvs">
      <question>
        The old xml-forrest CVS code repository seems to be stale. What happened?
      </question>
      <answer>
        <p>
          Forrest switched from a CVS code repository to SVN (subversion)
          code repository. The old CVS repository is not kept current.
        </p>
      </answer>
    </faq>
    <faq id="svn">
      <question>
        How can I use SVN to keep up to date with the latest codebase?
      </question>
      <answer>
        <p>
          Follow these <link href="site:build">Building Forrest</link> notes.
        </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/secure/ViewIssue.jspa?key=FOR-10">appears
            to be a bug in cygwin</link>. Please use the .bat script instead.
        </p>
      </answer>
    </faq>

    <faq id="maxmemory">
      <question>
        How can I specify the amount of memory to be used by Java?
      </question>
      <answer>
        <p>
         There are two ways to control this.  If you get an OutOfMemoryError when Cocoon is generating pages,
         see the first paragraph.  If you get an OutOfMemoryError when outside of Cocoon (e.g., copying raw
         files), see the second paragraph.
        </p>
        <p>
         The <code>maxmemory</code> property in the <code>forrest.properties</code> file controls how much
         memory Cocoon uses. Like many other properties you can copy them from the default configuration at
         <code>src/core/fresh-site/forrest.properties</code>
        </p>
        <p>
         Set the <code>ANT_OPTS</code> environment variable before you run forrest.  The exact value you set
         it to is dependant on your JVM, but something like <code>ANT_OPTS=-Xmx500M</code> will probably work.
        </p>
      </answer>
    </faq>
  </part>



  <part id="technical">
    <title>Technical</title>
    <faq id="PDF-output">
      <question>How can I generate one pdf-file out of
      the whole site or selected pages of the site?</question>
      <answer>
      <p>Add the following entries to your site.xml file:</p>
        <source><![CDATA[
  <about tab="home" label="About" href="">
 	  ...
    <all_site label="Full HTML" href="wholesite.html"/>    
    <all_sitePDF label="Full PDF" href="wholesite.pdf"/>  
     ...
  </about>]]></source>
       <p>
       In this case the menu labeled "About" will have 2 new items: 
       "Full PDF" and "Full HTML". (See also
       <link href="site:howto/pdf-tab">How to create a PDF document for each tab</link>.)
       </p>
       <p>
         This assumes that you use the
         <link href="site:linking">site.xml</link> method for your site
         structure and navigation, rather than the old book.xml method.
       </p>
       </answer>
    </faq>
    <faq id="clickable-email-adress">
      <question>How can I generate html-pages to show a 
      'clickable' email-address (of the author-element)?</question>
       <answer>
       <p>You would override <code>
       src/core/context/skins/common/xslt/html/document2html.xsl</code>
       and edit the "headers/authors" template.
       </p>
       </answer>
    </faq>
    <faq id="CVS_revison_tags">
      <question>How can I generate html-pages to show the
      revision tag of cvs?</question>
      <answer>
      <p>If you have:<code>&#60;version&#62;$Revision: 1.30
      $&#60;/version&#62;</code>The &#39;1.30&#39; will be extracted and
      displayed at the bottom of the page as &#34;version 1.30&#34;. See for
      example the bottom of the
      <link href="site:your-project"> Using Forrest</link> document.</p>
      <p>This technique could also be used for a modification date with
      $Date: 2004/01/15 08:52:47 $</p>
      </answer>
    </faq>

    <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/context/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.  These are a powerful feature of Cocoon's
          <link href="site:sitemap-ref">sitemap</link>.
          For example, <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>
        <p>
         For example, if
         <code>src/documentation/content/xdocs/tools/downloads.xml</code>
         has a <code>&lt;link href="tool.zip"&gt;</code> then put
         <code>tool.zip</code> in the
         <code>src/documentation/content/tools/</code> directory.
        </p>
        <p>
          See the explanation and demonstration of "linking" in your local
          'forrest seed' site.
        </p>
      </answer>
    </faq>

    <faq id="claimed_patterns">
      <question>Some of my files are not being processed because they use
      common filenames.
      </question>
      <answer>
        <p>
          Certain patterns are claimed by the default sitemaps for
          special processing. These include:
          <code>site, changes, todo, faq, images, my-images, skinconf,
          community, howto</code>
        </p>
        <p>
          Sometimes there are workarounds, e.g. perhaps "my_site".
          In future versions of Forrest we will attempt to deal with this issue.
        </p>
      </answer>
    </faq>

    <faq id="build_msg_a">
      <question>What do the symbols and numbers mean when Forrest lists each
        document that it has built?
      </question>
      <answer>
        <source><![CDATA[
* [56/0]     6.281s 23.0Kb  index.html
* [0/0]      0.0060s 4.0Kb   images/project-logo.gif
^                           apidocs/index.html
* [50/0]     1.582s 18.7Kb  todo.html
X [0]                       brokenlink.html     BROKEN: reason
* [50/0]     1.222s 20.2Kb  dreams.html
* [0/0]      0.535s 11.1Kb  dreams.pdf
...]]></source>
        <p>
         Column 1 is the page build status (*=okay X=brokenLink ^=pageSkipped).
         Column 2 is the number of links that were gathered from that page.
         Column 3 is the time taken.
         Column 4 is the page size.
        </p>
      </answer>
    </faq>

    <faq id="pdf_images">
      <question>Images 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 PDFs.  FOP cannot handle all image types natively, and
          requires third-party jars to be added. FOP natively handles BMP, GIF,
	  JPG, TIFF and EPS (with a few limitations). FOP can also handle SVG
	  (via Batik!and PNG (see below). For details, see 
	  <link href="http://xml.apache.org/fop/graphics.html">FOP Graphics
          formats</link>
        </p>
        <p>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>$FORREST/lib/optional/jimi-1.0.jar</code>.</li>
        </ol>
        <p>Alternatively you can use JAI (Java Advanced Imaging API at 
	  http://java.sun.com/products/java-media/jai). 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 '/'. Which file to serve is then a concern of the sitemap.
          For example, if the "User Manual" tab should link to
          <code>manual/Introduction.html</code> then
          <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>
        <p>
          See also
          <link href="http://cocoon.apache.org/2.1/faq/faq-configure-environment.html">Cocoon FAQ</link>.
        </p>
      </answer>
    </faq>

    <faq id="catalog">
      <question>
        How do i configure my favourite XML editor or parser to find the
        local Forrest DTDs?
      </question>
      <answer>
        <p>
          Notes are provided for various tools at
          <link href="site:catalog">Using Catalog Entity Resolver for
          local DTDs</link>.
        </p>
      </answer>
    </faq>

    <faq id="label-entity">
      <question>
        How to use special characters in the labels of the site.xml file?
      </question>
      <answer>
        <p>
        Use the numeric values for character entities.
        For example, rather than using
        <code><![CDATA[&ouml;]]></code> use
        <code><![CDATA[&#246;]]></code>
        </p>
        <p>
        See the
        <link href="http://www.w3.org/TR/xhtml-modularization/dtd_module_defs.html#a_xhtml_character_entities">XHTML Character Entities</link>
        and see more discussion at
        <link href="http://issues.cocoondev.org/browse/FOR-244">Issue FOR-244</link>.
        </p>
      </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.
        </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/context/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/), and add the following generator definition in the map:generators section:</p>
            <source><![CDATA[
  <map:generator name="serverpages"
     pool-grow="2" pool-max="32" pool-min="4"
     src="org.apache.cocoon.generation.ServerPagesGenerator"/>]]></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.apache.org/cocoon/AddingXSPToForrest">AddingXSPToForrest</link> Wiki page.</p>
      </answer>
    </faq>
    
    <faq id="breadcrumbs">
      <question>How do breadcrumbs work?  Why don't they work locally?</question>
      <answer>
      <p>Breadcrumbs begin with up to three URLs specified in
      <code>skinconf.xml</code>.  Here is what the Forrest site uses:</p>
      <source><![CDATA[
  <trail>
    <link1 name="apache" href="http://www.apache.org/"/>
    <link2 name="xml.apache" href="http://xml.apache.org/"/>
    <link3 name="" href=""/>
  </trail>]]></source>
      <p>If any links are blank, they are not used.  After these first links,
      JavaScript looks at the URL for the current page and
      makes a link for each directory after the domain.  If you are viewing
      the site locally, there is no domain and so
      there will be no extra breadcrumbs, only the ones that are specified
      in <code>skinconf.xml</code>.
      </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:</p>
          <source><![CDATA[
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
  "http://www.w3.org/TR/html4/loose.dtd">]]></source>
        <p>
          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>
    <faq id="building_error-custom_sitemap">
      <question>
        When building my project, I get any of these errors: 
	<code>menu.xmap (The system cannot find the file specified)</code>
	<code>static.xmap (The system cannot find the file specified)</code>
	<code>Type 'xml-document' is not defined for 'serialize'</code>
      </question>
      <answer>
        <p>
          You are using an old version of sitemap.xmap (see the document
          <link href="site:upgrading_05">Upgrading to Forrest 0.5</link>).
        </p>
      </answer>
    </faq>

  </part>

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

    <faq id="generating_menus">
      <question>What is the relationship 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 supplement is useful in situations
          where &s;-generated menus aren't appropriate.
          See <link href="site:linking">Menus and Linking</link>.
      </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 "xdocs" format on-the-fly and then render that as normal
         Forrest documents.
         Be aware that the stylesheet that does this transformation is
         deliberately very limited and does not attempt to deal with all
         DocBook elements.
        </p>
        <p>
         The other way is to use the full 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
         <link href="site:project-sitemap">project sitemap</link>
          as explained in
         <link href="site:your-project">Using Forrest</link>
         and add matches to handle your DocBook documents.
         Here is an example. Note that you need to change it to suit your
         situation. The match must be very specific so that only the
         DocBook documents are matched. The rest of the documents will be
         handled by Forrest core. Powerful regex capabilities are available.
        </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 source files as "document-v*" DTD and DocBook.
        </p>
        <p>
         Ensure that the document type declaration in your xml instance is
         well specified. Use a public identifier. The DTD will then be properly
         resolved by Forrest. If you need to use different DTDs, then see
         <link href="site:your-project/new_dtd">Using Forrest</link>
         for configuration guidance.
        </p>
      </answer>
    </faq>

    <faq id="version">
      <question>
        How to report which version of Forrest is being used and the
        properties that are set?
      </question>
      <answer>
        <p>
          Do <code>'forrest -projecthelp'</code> or <code>'./build.sh'</code>
          to find the version number.
        </p>
        <p>
          To list the properties, add "forrest.echo=true" to your
          forrest.properties file and watch the build messages.
          Doing <code>'forrest -v'</code> will provide verbose build messages.
        </p>
      </answer>
    </faq>

    <faq id="logs">
      <question>
        Where are the log files to find more infomation about errors?
      </question>
      <answer>
        <p>
          The logfiles are at <code>build/webapp/WEB-INF/logs/</code>
        </p>
        <p>
          The log level can be raised with the <code>logkit.xconf</code>
          configuration. If you are using Forrest in the interactive webapp
          mode (which is generally easiest for debugging errors) then see the
          <code>build/webapp/WEB-INF/logkit.xconf</code> file.
          If you are generating a static site (with command-line 'forrest')
          then copy <code>$FORREST_HOME/context/WEB-INF/logkit.xconf</code>
          to your project at
          <code>src/documentation/content/conf/logkit.xconf</code>
          and modify it. See more information and efficiency tips with
          <link href="http://wiki.apache.org/cocoon/ExploringTheLogs">Cocoon logging</link>.
        </p>
        <p>
          Doing <code>'forrest -v'</code> will provide verbose build messages
          to the standard output.
        </p>
      </answer>
    </faq>

    <faq id="how_can_I_help">
      <question>
        How to help?
      </question>
      <answer>
        <p>
          Join one of the Forrest project
          <link href="site:mail-lists">mailing lists</link>
          and tell us what you would 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>
      </answer>
    </faq>

    <faq id="patch">
      <question>
        How to contribute a patch?
      </question>
      <answer>
        <p>Please send all contributions via our
          <link href="site:bugs">issue tracker</link>.
          Here are notes about
          <link href="site:contrib/patch">making patches</link>.
        </p>
        <p>More info about contributing can be found at the 
          <link href="site:contrib">Contributing to Forrest</link> page.
          It is always a good idea to check the Forrest
          <link href="site:bugs">issue tracker</link>
          and 
          <link href="site:todo">to do list</link>
          before diving in.
        </p>
      </answer>
    </faq>
  </part>
</faqs>
