src/documentation/content/xdocs/faq.xml - forrest - Git at Google

 <?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" "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="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>
         What happened to CVS?
       </question>
       <answer>
         <p>
           Forrest switched from a CVS code repository to a SVN (subversion) code repository.  The 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/jira//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>
          Set the <code>maxmemory</code> property in the
          <code>forrest.properties</code> file. Like many other properties
          you can copy them from the default configuration at
          <code>src/resources/fresh-site/forrest.properties</code>
         </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><![CDATA[
         <about tab="home" label="Home" href="">
  	  ...
           <all_site label="Full HTML" href="site.html"/>
           <all_sitePDF label="Full PDF" href="site.pdf"/>
           ...
         </about>]]>
        In this case the menu labeled "About" will have 2 new items:
        "Full PDF" and "Full HTML".
        </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/resources/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 <link
       href="http://xml.apache.org/forrest/your-project.html">
       http://xml.apache.org/forrest/your-project.html</link></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/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>
         <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>
       </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>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>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
           '/'. 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>
         <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="catalog.html">Using Catalog Entity Resolver for
           local DTDs</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/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>

     <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's 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 aren't 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 looking at the site locally, there is no domain and so
       there will only be the breadcrumbs 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,
           <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>
     <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 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 "document" DTD on-the-fly and then render that as normal.
          Be aware that the stylesheet that does this transformation is
          deliberately very limited.
         </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>
         <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="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>
	<?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" "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="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>
	What happened to CVS?
	</question>
	<answer>
	<p>
	Forrest switched from a CVS code repository to a SVN (subversion) code repository. The 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/jira//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>
	Set the <code>maxmemory</code> property in the
	<code>forrest.properties</code> file. Like many other properties
	you can copy them from the default configuration at
	<code>src/resources/fresh-site/forrest.properties</code>
	</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><![CDATA[
	<about tab="home" label="Home" href="">
	...
	<all_site label="Full HTML" href="site.html"/>
	<all_sitePDF label="Full PDF" href="site.pdf"/>
	...
	</about>]]>
	In this case the menu labeled "About" will have 2 new items:
	"Full PDF" and "Full HTML".
	</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/resources/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><version>$Revision: 1.30
	$</version></code>The '1.30' will be extracted and
	displayed at the bottom of the page as "version 1.30". See for
	example the bottom of <link
	href="http://xml.apache.org/forrest/your-project.html">
	http://xml.apache.org/forrest/your-project.html</link></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/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> — 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><link href="tool.zip"></code> then put
	<code>tool.zip</code> in the
	<code>src/documentation/content/tools/</code> directory.
	</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>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>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
	'/'. 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>
	<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="catalog.html">Using Catalog Entity Resolver for
	local DTDs</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&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>
	<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.cocoondev.org/Wiki.jsp?page=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's 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 aren't 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 looking at the site locally, there is no domain and so
	there will only be the breadcrumbs 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,
	<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>
	<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 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 "document" DTD on-the-fly and then render that as normal.
	Be aware that the stylesheet that does this transformation is
	deliberately very limited.
	</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>
	<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="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—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>