<commit_before><?xml version="1.0" encoding="UTF-8"?>
<!--
  Copyright 2002-2004 The Apache Software Foundation or its licensors,
  as applicable.

  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:v0.80//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 Apache Ant.
        </p>
        <p>
          Java 1.4 (or newer) is required. If you are only going to use Forrest
          as-is then you need only the Java Runtime Environment (JRE).
          If you intend to enhance and rebuild Forrest (or use the Forrest sources
          with Subversion or use a source snapshot) then you need the full JDK.
        </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 closed and 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:v0.80//build">Building Forrest</link> notes. </p>
        <p> The <link href="site:v0.80//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="single-document">
      <question> What is the best way to generate "standalone documents" using Forrest? </question>
      <answer>
        <p> forrest site -Dproject.start-uri=myfile.pdf </p>
        <p> The <link href="site:v0.80//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.apache.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> 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="content_faqs">
    <title>Content Creation</title>
    <faq id="edit-content">
      <question>What tools can be used to edit the content?</question>
      <answer>
        <p>If you are using the Apache Forrest xml <link href="site:v0.80//dtd-docs">document format</link>
          or DocBook or other xml document types, then you can use any text editor or even a
          dedicated xml editor. You must ensure valid xml. See our <link href="site:v0.80//catalog"
            >configuration notes</link> for various editors. </p>
        <p>There are content management systems like <link href="ext:lenya">Apache Lenya</link>. </p>
        <p>Remember that Forrest can also use other source formats, such as OpenOffice.org docs or
          JSPWiki. Use the appropriate editor for those document types and ensure that the document
          stucture is consistent. Forrest can also use "html" as the source format, in which case
          you can use text editors or "html editors" such as the one provided with the Mozilla web
          browser. </p>
      </answer>
    </faq>
    <faq id="site-xml">
      <question>
        How to use the <code>site.xml</code> configuration file for menus and linking.
      </question>
      <answer>
        <p>
          The <code>site.xml</code> configuration file is used for two different purposes:
          defining the left-hand navigation menus, and as a method for defining references
          to be used when linking between documents.
          This file is fully explained in
          <link href="site:v0.80//linking">Menus and Linking</link>. Here is a precis:
        </p>
        <p>
          The labels can be whatever text you want.
        </p>
        <source><![CDATA[<faq label="FAQs" href="faq.html">
  <tech label="Technical" href="faq-tech.html">
    <docbook href="#docbook"/>
    <ignoring_javadocs href="#ignoring_javadocs"/>
  </tech>
  <user label="User" href="faq-user.html">
</faq>]]></source>
        <p>
          That will create a menu like this with three links:
        </p>
        <source>FAQs
   Technical
   User</source>

        <p>
          These documents can be linked to from other documents, like this:
        </p>
        <source><![CDATA[<a href="site:v0.80//faq/tech"> link to the top of the Tech FAQs
<a href="site:v0.80//faq/tech/docbook"> link to the DocBook FAQ in the Tech FAQs]]></source>

        <p>
          If that "docbook" entry was a unique name in your site.xml then you
          can shorten that latter link:
        </p>
        <source><![CDATA[<a href="site:v0.80//docbook"> link to the DocBook FAQ in the Tech FAQs]]></source>
      </answer>
    </faq>
    <faq id="examples">
      <question>
        Where are examples of documents and site.xml and tabs.xml files?
      </question>
      <answer>
        <p>
          There are examples in the 'forrest seed site' and also the Forrest website documents
          are included with the distribution (cd forrest/site-author; forrest run).
        </p>
      </answer>
    </faq>
    <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:v0.80//howto/pdf-tab">How to create a PDF document for each
          tab</link>.) </p>
        <p> This assumes that you use the <link href="site:v0.80//linking">site.xml</link> method for your
          site structure and navigation, rather than the old book.xml method. </p>
      </answer>
    </faq>
    <faq id="pageBreaks">
      <question>How do I insert page breaks into documents?</question>
      <answer>
        <p>Page breaks do not make a great deal of sense in HTML documents intended for display on a
          screen. However, PDF documents are intended for printing and therefore page breaks can be
          important.</p>
        <p>To insert a page break in a PDF document simply add <em>pageBreakBefore</em> and/or
            <em>pageBreakAfter</em> to the class attribute of the block you wish to force a
            page break on. All the common block grouping elements support this class, for example, 
            note, warning, p and so on.</p>
        <p>If you want these classes to be processed in your HTML documents as well you should add
          the following to the <code>extra-css</code> element in your projects
          <code>skinconf.xml</code>
        </p>
        <source> .pageBreakBefore { margin-bottom: 0; page-break-before: always; } .pageBreakAfter {
          margin-bottom: 0; page-break-after: always; } </source>
      </answer>
    </faq>
    <faq id="clickable-email-address">
      <question>How can I generate html-pages to show a 'clickable' email-address (of the
        author-element)?</question>
      <answer>
        <p>You would override <code>
            $FORREST_HOME/main/webapp/skins/common/xslt/html/document2html.xsl</code> and edit the
          "headers/authors" template. </p>
      </answer>
    </faq>
    <faq id="link_raw">
      <question>How do I link to raw files such as config.txt and brochure.pdf? </question>
      <answer>
        <p>Handling of raw files was significantly changed in Forrest 0.7. See 
          <link href="site:v0.70//upgrading_07/raw">Upgrading to Apache Forrest 0.7</link> for
          all the details.</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="tab-index">
      <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="tab-site">
      <question>I need help with the interaction between tabs.xml and site.xml </question>
      <answer>
        <p>
          See the <link href="site:v0.80//linking/tab-site">tips</link>.
        </p>
      </answer>
    </faq>
    <faq id="defaultFileName">
      <question> How can I change the default file name that Forrest will look for when I request a
        URL like <code>http://myserver</code> or <code>http://myserver/mydir/</code> ? </question>
      <answer>
        <p>To change the default file name from 'index.html' (default) to 'overview.html' you need to
          make the following changes:</p>
        <ol>
          <li> Create a '<link href="#cli-xconf">cli.xconf</link>' file for your project </li>
          <li> Edit that file to replace 'index.html' in
            <![CDATA[<default-filename>index.html</default-filename>]]>
            with 'overview.html'. </li>
          <li> Edit your project's <link href="site:v0.80//project-sitemap">sitemap.xmap</link> file. </li>
          <li> Add the following code just before the end of the pipelines-element:<source><![CDATA[
  <map:pipeline>
    <map:match type="regexp" pattern="^.+/$">
       <map:redirect-to uri="overview.html"/>
    </map:match>
  </map:pipeline>
          ]]></source></li>
        </ol>
      </answer>
    </faq>
    <faq id="defaultStartPage">
      <question> How can I use a start-up-page other than index.html? </question>
      <answer>
        <p>Forrest by default assumes that the first page (home page) of your site is named
          index.html. Which is good because most web servers are configured to look for index.html
          when you call a url like http://myserver</p>
        <p>Like most settings in Forrest however this can be changed, for example when you want your
          start-up-page for a CD-based documentation project to be named 'start.html'. </p>
        <p>To change the start page of a site:</p>
        <ol>
          <li>Edit your project's <link href="site:v0.80//project-sitemap">sitemap.xmap</link> file.</li>
          <li>Add the following code just before the end of the pipelines-element:<source><![CDATA[
  <map:pipeline>
    <map:match pattern="">
      <map:redirect-to uri="start.html" />
    </map:match>
  </map:pipeline>
          ]]></source></li>
          <li>Name the uri-attribute whatever you'd like your start page to be.</li>
          <li>Don't forget to create that page and refer to it in your site.xml</li>
        </ol>
      </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.apache.org/jira/browse/FOR-244">Issue FOR-244</link>. </p>
      </answer>
    </faq>
    <faq id="encoding">
      <question>Does Forrest handle accents for non-English languages?</question>
      <answer>
        <p>Yes, Forrest can process text in any language, so you can include:</p>
        <ul>
          <li>accents: á é í ó ú</li>
          <li>diereses: ä ë ï ö ü</li>
          <li>tildes: ã ñ ĩ õ ũ</li>
        </ul>
        <p>This is because sources for Forrest docs are xml documents, which can include any of
          these, provided the encoding declared by the xml doc matches the actual encoding used in
          the file. For example if you declare the default encoding:</p>
        <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>]]></source>
        <p>but the file content is actually using ISO-8859-1 then you will receive validation
          errors, especially if you include some non-ASCII characters.</p>
        <p> This situation is commonly encountered when you edit the templates created by
            <code>forrest seed</code> with your favorite (probably localized) editor without paying
          attention to the encoding, or when you create a new file and simply copy the headers from
          another file. </p>
        <p>Although UTF-8 is an encoding well-suited for most languages, it is not usually the
          default in popular editors or systems. In UNIX-like systems, most popular editors can
          handle different encodings to write the file in disk. With some editors the encoding of
          the file is preserved, while with others the default is used regardless of the original
          encoding. In most cases the encoding used to write files can be controlled by setting the
          environment variable <code>LANG</code> to an appropriate value, for instance: </p>
        <source>[localhost]$ export LANG=en_US.UTF-8</source>
        <p>Of course the <em>appropriate</em> way to set the encoding depends on the editor/OS, but
          ultimately relys on the user preferences. So you can use the encoding you prefer, as long
          as the <code>encoding</code> attribute of the xml declaration matches the actual encoding
          of the file. This means that if you are not willing to abandon ISO-8859-1 you can always
          use the following declaration instead:</p>
        <source><![CDATA[<?xml version="1.0" encoding="ISO-8859-1"?>]]></source>
        <p>Another option is to use "character entities" such as <code><![CDATA[&ouml;]]></code>
          (&ouml;) or the numeric form <code><![CDATA[&#246;]]></code> (&#246;). </p>
        <p>Another related issue is that your webserver needs to send http headers with the matching
          charset definitions to the html page. </p>
        <p>Here are some references which explain further: <link
            href="http://orixo.com/events/gt2004/bios.html#torsten">GT2004 presentation by Torsten
            Schlabach</link> and <link href="http://www.alanwood.net/unicode/">Alan Wood's Unicode
            resources</link>. </p>
      </answer>
    </faq>
    <faq id="cleanSite">
      <question> How can I make Forrest properly clean up the build/site-directory? </question>
      <answer>
        <p>Forrest for performance reasons doesn't clean out the build/site-directory each time you
          compile your project. This usually doesn't matter during development but might become a
          problem in a production environment.</p>
        <p>To ensure a clean build call 'forrest clean site' instead of just 'forrest' so Forrest
          will delete all build directories before creating new content. </p>
      </answer>
    </faq>
    <faq id="i18n">
      <question>How can I internationalise (i18n) my content?</question>
      <answer>
        <p>The i18n features of Forrest are still under development (as of 0.7) however there are
        some features available. For example, navigation menus can be i18n'd (see fresh-site for an
        example). Currently, <link href="http://issues.apache.org/jira/browse/FOR-506">work is underway</link> to 
        i18n skins</p>
        
        <p>All internationalistation of tokens in, for example, the skins and the menus, is carried out
        by the <link href="http://cocoon.apache.org/2.1/userdocs/transformers/i18n-transformer.html">Cocoon i18n 
        Transformer</link>. You can see an example of how it works in the above linked issue.</p>
      </answer>
    </faq>
    <faq id="rawTML">
      <question>How can I include HTML content that is not to be skinned by Forrest?</question>
      <answer>
        <p>To server, for example, a legacy HTML site add something like the following 
        to your projects sitemap:</p>
        <source>
&lt;map:match pattern="old_site/**.html"&gt;
 &lt;map:select type="exists"&gt;
  &lt;map:when test="{project:content}{0}"&gt;
    &lt;map:read src="{project:content}/{0}" mime-type="text/html"/&gt;
    &lt;!--
      Use this instead if you want JTidy to clean up your HTML
      &lt;map:generate type="html" src="{project:content}/{0}" /&gt;
      &lt;map:serialize type="html"/&gt;
    --&gt;
  &lt;/map:when&gt;
&lt;/map:match&gt;
        </source>
      </answer>
    </faq>
  </part>
  <part id="technical">
    <title>Technical</title>
    <faq id="proxy_config">
      <question>I'm behind a proxy and it's preventing Plugins from being downloaded, what should I
        do?</question>
      <answer>
        <p>You can configure the proxy in the <code>forrest.properties</code> file. Set the
            <code>proxy.host</code> and <code>proxy.port</code> accordingly (the port will default
          to port 80).</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:v0.80//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="cli-xconf">
      <question> How to control the processing of URIs by Cocoon, e.g. exclude certain URIs, include
        other additional ones. </question>
      <answer>
        <p> Forrest uses a configuration file to control the processing done by the Apache Cocoon
          command-line called cli.xconf </p>
        <p> Your project can supply its own <code>cli.xconf</code> and define patterns for URIs to
          exclude. There are also other powerful configuration features. </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/main/webapp/WEB-INF/cli.xconf</code> to it. Declare the location of
          this file in the forrest.properties configuration, e.g.
            <code>project.configfile=${project.home}/src/documentation/conf/cli.xconf</code>
        </p>
        <p> Then edit cli.xconf, and add any exclude sections that you require. 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:v0.80//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="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 <link href="#cli-xconf">
            <code>cli.xconf</code>
          </link> Cocoon config file, and defining patterns for URLs to exclude. </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. faq.html or faq-interview.html would fail, but
          interview-faq.html would be fine. In future versions of Forrest we will attempt to deal
          with this issue (<link href="http://issues.apache.org/jira/browse/FOR-217">FOR-217</link>).
        </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[...
* [212/166] [0/0]  1.16s  62.4Kb  docs_0_60/your-project.pdf
X [0]         /docs_0_80/upgrading_08.html  BROKEN: No pipeline matched...
* [213/164] [0/0]  0.391s 29.2Kb  docs_0_70/howto/howto-buildPlugin.pdf
^                           apidocs/index.html
* [214/170] [7/66] 1.476s 45.5Kb  docs_0_60/sitemap-ref.html
...]]></source>
        <ul>
          <li>Column 1 is the page build status (*=okay X=brokenLink ^=pageSkipped).</li>
          <li>Column 2 is the page count - the number of pages processed and the number remaining. The latter will change because during processing one page, Cocoon will discover more.</li>
          <li>Column 3 is the number of links that were gathered from that page.</li>
          <li>Column 4 is the time taken.</li>
          <li>Column 5 is the page size.</li>
        </ul>
      </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="project-logo-svg">
      <question> 
        The project logo that is generated from SVG is truncating my project name.
      </question>
      <answer>
        <p>
          In a 'forrest seed site' the project and the group logo are generated from a
          Scalable Vector Graphics (SVG) file, using the text from the
          <code>&lt;project-name&gt;</code> and
          <code>&lt;group-name&gt;</code> elements of the <code>skinconf.xml</code> file.
          If you have a long project-name then you may need to adjust the width of the image.
          Perhaps you want to change the colours too. Edit the file at
          <code>src/documentation/content/xdocs/images/project.svg</code> and adjust the "width"
          attribute of the &lt;svg&gt; element. For further details see
          <link href="http://www.w3.org/Graphics/SVG/">SVG</link> resources.
        </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:v0.80//catalog">Using Catalog Entity
            Resolver for local DTDs</link>. </p>
      </answer>
    </faq>
    <faq id="skin">
      <question> How to make the site look better and change its skin? </question>
      <answer>
        <p> There are <link href="site:v0.80//skins">default skins</link> provided, which are configurable
          and so should meet the needs of most projects. The aim is to provide many capabilities so
          that extra skins are not needed. </p>
        <p> See notes about <link href="site:v0.80//your-project/skins">configuration</link> of the skins.
          Some projects may have special needs and can define their <link
            href="site:v0.80//your-project/new-skin">own skin</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/main/webapp/WEB-INF/lib
            directory (or lib/core/ directory in the source distribution).</li>
          <li>
            <p> Add the following generator definition in the map:generators section of your <link
                href="site:v0.80//project-sitemap">project sitemap</link>
            </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>
    <faq id="run_port">
      <question>How do I make <code>forrest run</code> listen on a different port?</question>
      <answer>
        <p>
          <code>forrest run -Dforrest.jvmargs="-Djetty.port=80"</code>
        </p>
        <p>Or copy Forrest's main/webapp/jettyconf.xml file to your project's src/documentation
          directory and set the port number in that file. Then do <code>forrest run</code>
        </p>
      </answer>
    </faq>
  </part>
  <part id="old_faqs">
    <title>Older version: 0.6</title>
    <faq id="old_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. faq.html or faq-interview.html would fail, but
          interview-faq.html would be fine. In future versions of Forrest we will attempt to deal
          with this issue (<link href="http://issues.apache.org/jira/browse/FOR-217">FOR-217</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:v0.80//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 has a <code>simplifiedDocbook</code> plugin which 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:v0.80//project-sitemap">project
            sitemap</link> as explained in <link href="site:v0.80//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[<?xml version="1.0"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
 <map:pipelines>
  <map:pipeline>
   <map:match pattern="resolver-*.html">
    <map:generate src="{project:content.xdocs}resolver-{1}.xml"/>
    <map:transform
      src="file:///usr/share/sgml/docbook/xsl-stylesheets/xhtml/docbook.xsl"/>
    <map:serialize type="xhtml"/>
   </map:match>
  </map:pipeline>
 </map:pipelines>
</map:sitemap>]]></source>
        <p>You need to define the xhtml serializer used in &lt;map:serialize type="xhtml"/&gt;
        in the components section of the sitemap. See the 
        <link href="http://cocoon.apache.org/2.1/userdocs/serializers/xhtml-serializer.html">Cocoon
        docs</link> for the elements you need to add to define this component. You can see examples 
        of other components being added in the <code>FORREST_HOME/main/webapp/sitemap.xmap</code> file.</p>
        <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:v0.80//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/main/webapp/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> before diving in. </p>
      </answer>
    </faq>
  </part>
</faqs>
<commit_msg>Change yet another old path src/core/ to main/<commit_after><?xml version="1.0" encoding="UTF-8"?>
<!--
  Copyright 2002-2004 The Apache Software Foundation or its licensors,
  as applicable.

  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:v0.80//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 Apache Ant.
        </p>
        <p>
          Java 1.4 (or newer) is required. If you are only going to use Forrest
          as-is then you need only the Java Runtime Environment (JRE).
          If you intend to enhance and rebuild Forrest (or use the Forrest sources
          with Subversion or use a source snapshot) then you need the full JDK.
        </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 closed and 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:v0.80//build">Building Forrest</link> notes. </p>
        <p> The <link href="site:v0.80//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="single-document">
      <question> What is the best way to generate "standalone documents" using Forrest? </question>
      <answer>
        <p> forrest site -Dproject.start-uri=myfile.pdf </p>
        <p> The <link href="site:v0.80//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.apache.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> 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>main/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="content_faqs">
    <title>Content Creation</title>
    <faq id="edit-content">
      <question>What tools can be used to edit the content?</question>
      <answer>
        <p>If you are using the Apache Forrest xml <link href="site:v0.80//dtd-docs">document format</link>
          or DocBook or other xml document types, then you can use any text editor or even a
          dedicated xml editor. You must ensure valid xml. See our <link href="site:v0.80//catalog"
            >configuration notes</link> for various editors. </p>
        <p>There are content management systems like <link href="ext:lenya">Apache Lenya</link>. </p>
        <p>Remember that Forrest can also use other source formats, such as OpenOffice.org docs or
          JSPWiki. Use the appropriate editor for those document types and ensure that the document
          stucture is consistent. Forrest can also use "html" as the source format, in which case
          you can use text editors or "html editors" such as the one provided with the Mozilla web
          browser. </p>
      </answer>
    </faq>
    <faq id="site-xml">
      <question>
        How to use the <code>site.xml</code> configuration file for menus and linking.
      </question>
      <answer>
        <p>
          The <code>site.xml</code> configuration file is used for two different purposes:
          defining the left-hand navigation menus, and as a method for defining references
          to be used when linking between documents.
          This file is fully explained in
          <link href="site:v0.80//linking">Menus and Linking</link>. Here is a precis:
        </p>
        <p>
          The labels can be whatever text you want.
        </p>
        <source><![CDATA[<faq label="FAQs" href="faq.html">
  <tech label="Technical" href="faq-tech.html">
    <docbook href="#docbook"/>
    <ignoring_javadocs href="#ignoring_javadocs"/>
  </tech>
  <user label="User" href="faq-user.html">
</faq>]]></source>
        <p>
          That will create a menu like this with three links:
        </p>
        <source>FAQs
   Technical
   User</source>

        <p>
          These documents can be linked to from other documents, like this:
        </p>
        <source><![CDATA[<a href="site:v0.80//faq/tech"> link to the top of the Tech FAQs
<a href="site:v0.80//faq/tech/docbook"> link to the DocBook FAQ in the Tech FAQs]]></source>

        <p>
          If that "docbook" entry was a unique name in your site.xml then you
          can shorten that latter link:
        </p>
        <source><![CDATA[<a href="site:v0.80//docbook"> link to the DocBook FAQ in the Tech FAQs]]></source>
      </answer>
    </faq>
    <faq id="examples">
      <question>
        Where are examples of documents and site.xml and tabs.xml files?
      </question>
      <answer>
        <p>
          There are examples in the 'forrest seed site' and also the Forrest website documents
          are included with the distribution (cd forrest/site-author; forrest run).
        </p>
      </answer>
    </faq>
    <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:v0.80//howto/pdf-tab">How to create a PDF document for each
          tab</link>.) </p>
        <p> This assumes that you use the <link href="site:v0.80//linking">site.xml</link> method for your
          site structure and navigation, rather than the old book.xml method. </p>
      </answer>
    </faq>
    <faq id="pageBreaks">
      <question>How do I insert page breaks into documents?</question>
      <answer>
        <p>Page breaks do not make a great deal of sense in HTML documents intended for display on a
          screen. However, PDF documents are intended for printing and therefore page breaks can be
          important.</p>
        <p>To insert a page break in a PDF document simply add <em>pageBreakBefore</em> and/or
            <em>pageBreakAfter</em> to the class attribute of the block you wish to force a
            page break on. All the common block grouping elements support this class, for example, 
            note, warning, p and so on.</p>
        <p>If you want these classes to be processed in your HTML documents as well you should add
          the following to the <code>extra-css</code> element in your projects
          <code>skinconf.xml</code>
        </p>
        <source> .pageBreakBefore { margin-bottom: 0; page-break-before: always; } .pageBreakAfter {
          margin-bottom: 0; page-break-after: always; } </source>
      </answer>
    </faq>
    <faq id="clickable-email-address">
      <question>How can I generate html-pages to show a 'clickable' email-address (of the
        author-element)?</question>
      <answer>
        <p>You would override <code>
            $FORREST_HOME/main/webapp/skins/common/xslt/html/document2html.xsl</code> and edit the
          "headers/authors" template. </p>
      </answer>
    </faq>
    <faq id="link_raw">
      <question>How do I link to raw files such as config.txt and brochure.pdf? </question>
      <answer>
        <p>Handling of raw files was significantly changed in Forrest 0.7. See 
          <link href="site:v0.70//upgrading_07/raw">Upgrading to Apache Forrest 0.7</link> for
          all the details.</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="tab-index">
      <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="tab-site">
      <question>I need help with the interaction between tabs.xml and site.xml </question>
      <answer>
        <p>
          See the <link href="site:v0.80//linking/tab-site">tips</link>.
        </p>
      </answer>
    </faq>
    <faq id="defaultFileName">
      <question> How can I change the default file name that Forrest will look for when I request a
        URL like <code>http://myserver</code> or <code>http://myserver/mydir/</code> ? </question>
      <answer>
        <p>To change the default file name from 'index.html' (default) to 'overview.html' you need to
          make the following changes:</p>
        <ol>
          <li> Create a '<link href="#cli-xconf">cli.xconf</link>' file for your project </li>
          <li> Edit that file to replace 'index.html' in
            <![CDATA[<default-filename>index.html</default-filename>]]>
            with 'overview.html'. </li>
          <li> Edit your project's <link href="site:v0.80//project-sitemap">sitemap.xmap</link> file. </li>
          <li> Add the following code just before the end of the pipelines-element:<source><![CDATA[
  <map:pipeline>
    <map:match type="regexp" pattern="^.+/$">
       <map:redirect-to uri="overview.html"/>
    </map:match>
  </map:pipeline>
          ]]></source></li>
        </ol>
      </answer>
    </faq>
    <faq id="defaultStartPage">
      <question> How can I use a start-up-page other than index.html? </question>
      <answer>
        <p>Forrest by default assumes that the first page (home page) of your site is named
          index.html. Which is good because most web servers are configured to look for index.html
          when you call a url like http://myserver</p>
        <p>Like most settings in Forrest however this can be changed, for example when you want your
          start-up-page for a CD-based documentation project to be named 'start.html'. </p>
        <p>To change the start page of a site:</p>
        <ol>
          <li>Edit your project's <link href="site:v0.80//project-sitemap">sitemap.xmap</link> file.</li>
          <li>Add the following code just before the end of the pipelines-element:<source><![CDATA[
  <map:pipeline>
    <map:match pattern="">
      <map:redirect-to uri="start.html" />
    </map:match>
  </map:pipeline>
          ]]></source></li>
          <li>Name the uri-attribute whatever you'd like your start page to be.</li>
          <li>Don't forget to create that page and refer to it in your site.xml</li>
        </ol>
      </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.apache.org/jira/browse/FOR-244">Issue FOR-244</link>. </p>
      </answer>
    </faq>
    <faq id="encoding">
      <question>Does Forrest handle accents for non-English languages?</question>
      <answer>
        <p>Yes, Forrest can process text in any language, so you can include:</p>
        <ul>
          <li>accents: á é í ó ú</li>
          <li>diereses: ä ë ï ö ü</li>
          <li>tildes: ã ñ ĩ õ ũ</li>
        </ul>
        <p>This is because sources for Forrest docs are xml documents, which can include any of
          these, provided the encoding declared by the xml doc matches the actual encoding used in
          the file. For example if you declare the default encoding:</p>
        <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>]]></source>
        <p>but the file content is actually using ISO-8859-1 then you will receive validation
          errors, especially if you include some non-ASCII characters.</p>
        <p> This situation is commonly encountered when you edit the templates created by
            <code>forrest seed</code> with your favorite (probably localized) editor without paying
          attention to the encoding, or when you create a new file and simply copy the headers from
          another file. </p>
        <p>Although UTF-8 is an encoding well-suited for most languages, it is not usually the
          default in popular editors or systems. In UNIX-like systems, most popular editors can
          handle different encodings to write the file in disk. With some editors the encoding of
          the file is preserved, while with others the default is used regardless of the original
          encoding. In most cases the encoding used to write files can be controlled by setting the
          environment variable <code>LANG</code> to an appropriate value, for instance: </p>
        <source>[localhost]$ export LANG=en_US.UTF-8</source>
        <p>Of course the <em>appropriate</em> way to set the encoding depends on the editor/OS, but
          ultimately relys on the user preferences. So you can use the encoding you prefer, as long
          as the <code>encoding</code> attribute of the xml declaration matches the actual encoding
          of the file. This means that if you are not willing to abandon ISO-8859-1 you can always
          use the following declaration instead:</p>
        <source><![CDATA[<?xml version="1.0" encoding="ISO-8859-1"?>]]></source>
        <p>Another option is to use "character entities" such as <code><![CDATA[&ouml;]]></code>
          (&ouml;) or the numeric form <code><![CDATA[&#246;]]></code> (&#246;). </p>
        <p>Another related issue is that your webserver needs to send http headers with the matching
          charset definitions to the html page. </p>
        <p>Here are some references which explain further: <link
            href="http://orixo.com/events/gt2004/bios.html#torsten">GT2004 presentation by Torsten
            Schlabach</link> and <link href="http://www.alanwood.net/unicode/">Alan Wood's Unicode
            resources</link>. </p>
      </answer>
    </faq>
    <faq id="cleanSite">
      <question> How can I make Forrest properly clean up the build/site-directory? </question>
      <answer>
        <p>Forrest for performance reasons doesn't clean out the build/site-directory each time you
          compile your project. This usually doesn't matter during development but might become a
          problem in a production environment.</p>
        <p>To ensure a clean build call 'forrest clean site' instead of just 'forrest' so Forrest
          will delete all build directories before creating new content. </p>
      </answer>
    </faq>
    <faq id="i18n">
      <question>How can I internationalise (i18n) my content?</question>
      <answer>
        <p>The i18n features of Forrest are still under development (as of 0.7) however there are
        some features available. For example, navigation menus can be i18n'd (see fresh-site for an
        example). Currently, <link href="http://issues.apache.org/jira/browse/FOR-506">work is underway</link> to 
        i18n skins</p>
        
        <p>All internationalistation of tokens in, for example, the skins and the menus, is carried out
        by the <link href="http://cocoon.apache.org/2.1/userdocs/transformers/i18n-transformer.html">Cocoon i18n 
        Transformer</link>. You can see an example of how it works in the above linked issue.</p>
      </answer>
    </faq>
    <faq id="rawTML">
      <question>How can I include HTML content that is not to be skinned by Forrest?</question>
      <answer>
        <p>To server, for example, a legacy HTML site add something like the following 
        to your projects sitemap:</p>
        <source>
&lt;map:match pattern="old_site/**.html"&gt;
 &lt;map:select type="exists"&gt;
  &lt;map:when test="{project:content}{0}"&gt;
    &lt;map:read src="{project:content}/{0}" mime-type="text/html"/&gt;
    &lt;!--
      Use this instead if you want JTidy to clean up your HTML
      &lt;map:generate type="html" src="{project:content}/{0}" /&gt;
      &lt;map:serialize type="html"/&gt;
    --&gt;
  &lt;/map:when&gt;
&lt;/map:match&gt;
        </source>
      </answer>
    </faq>
  </part>
  <part id="technical">
    <title>Technical</title>
    <faq id="proxy_config">
      <question>I'm behind a proxy and it's preventing Plugins from being downloaded, what should I
        do?</question>
      <answer>
        <p>You can configure the proxy in the <code>forrest.properties</code> file. Set the
            <code>proxy.host</code> and <code>proxy.port</code> accordingly (the port will default
          to port 80).</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:v0.80//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="cli-xconf">
      <question> How to control the processing of URIs by Cocoon, e.g. exclude certain URIs, include
        other additional ones. </question>
      <answer>
        <p> Forrest uses a configuration file to control the processing done by the Apache Cocoon
          command-line called cli.xconf </p>
        <p> Your project can supply its own <code>cli.xconf</code> and define patterns for URIs to
          exclude. There are also other powerful configuration features. </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/main/webapp/WEB-INF/cli.xconf</code> to it. Declare the location of
          this file in the forrest.properties configuration, e.g.
            <code>project.configfile=${project.home}/src/documentation/conf/cli.xconf</code>
        </p>
        <p> Then edit cli.xconf, and add any exclude sections that you require. 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:v0.80//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="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 <link href="#cli-xconf">
            <code>cli.xconf</code>
          </link> Cocoon config file, and defining patterns for URLs to exclude. </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. faq.html or faq-interview.html would fail, but
          interview-faq.html would be fine. In future versions of Forrest we will attempt to deal
          with this issue (<link href="http://issues.apache.org/jira/browse/FOR-217">FOR-217</link>).
        </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[...
* [212/166] [0/0]  1.16s  62.4Kb  docs_0_60/your-project.pdf
X [0]         /docs_0_80/upgrading_08.html  BROKEN: No pipeline matched...
* [213/164] [0/0]  0.391s 29.2Kb  docs_0_70/howto/howto-buildPlugin.pdf
^                           apidocs/index.html
* [214/170] [7/66] 1.476s 45.5Kb  docs_0_60/sitemap-ref.html
...]]></source>
        <ul>
          <li>Column 1 is the page build status (*=okay X=brokenLink ^=pageSkipped).</li>
          <li>Column 2 is the page count - the number of pages processed and the number remaining. The latter will change because during processing one page, Cocoon will discover more.</li>
          <li>Column 3 is the number of links that were gathered from that page.</li>
          <li>Column 4 is the time taken.</li>
          <li>Column 5 is the page size.</li>
        </ul>
      </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="project-logo-svg">
      <question> 
        The project logo that is generated from SVG is truncating my project name.
      </question>
      <answer>
        <p>
          In a 'forrest seed site' the project and the group logo are generated from a
          Scalable Vector Graphics (SVG) file, using the text from the
          <code>&lt;project-name&gt;</code> and
          <code>&lt;group-name&gt;</code> elements of the <code>skinconf.xml</code> file.
          If you have a long project-name then you may need to adjust the width of the image.
          Perhaps you want to change the colours too. Edit the file at
          <code>src/documentation/content/xdocs/images/project.svg</code> and adjust the "width"
          attribute of the &lt;svg&gt; element. For further details see
          <link href="http://www.w3.org/Graphics/SVG/">SVG</link> resources.
        </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:v0.80//catalog">Using Catalog Entity
            Resolver for local DTDs</link>. </p>
      </answer>
    </faq>
    <faq id="skin">
      <question> How to make the site look better and change its skin? </question>
      <answer>
        <p> There are <link href="site:v0.80//skins">default skins</link> provided, which are configurable
          and so should meet the needs of most projects. The aim is to provide many capabilities so
          that extra skins are not needed. </p>
        <p> See notes about <link href="site:v0.80//your-project/skins">configuration</link> of the skins.
          Some projects may have special needs and can define their <link
            href="site:v0.80//your-project/new-skin">own skin</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/main/webapp/WEB-INF/lib
            directory (or lib/core/ directory in the source distribution).</li>
          <li>
            <p> Add the following generator definition in the map:generators section of your <link
                href="site:v0.80//project-sitemap">project sitemap</link>
            </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>
    <faq id="run_port">
      <question>How do I make <code>forrest run</code> listen on a different port?</question>
      <answer>
        <p>
          <code>forrest run -Dforrest.jvmargs="-Djetty.port=80"</code>
        </p>
        <p>Or copy Forrest's main/webapp/jettyconf.xml file to your project's src/documentation
          directory and set the port number in that file. Then do <code>forrest run</code>
        </p>
      </answer>
    </faq>
  </part>
  <part id="old_faqs">
    <title>Older version: 0.6</title>
    <faq id="old_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. faq.html or faq-interview.html would fail, but
          interview-faq.html would be fine. In future versions of Forrest we will attempt to deal
          with this issue (<link href="http://issues.apache.org/jira/browse/FOR-217">FOR-217</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:v0.80//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 has a <code>simplifiedDocbook</code> plugin which 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:v0.80//project-sitemap">project
            sitemap</link> as explained in <link href="site:v0.80//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[<?xml version="1.0"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
 <map:pipelines>
  <map:pipeline>
   <map:match pattern="resolver-*.html">
    <map:generate src="{project:content.xdocs}resolver-{1}.xml"/>
    <map:transform
      src="file:///usr/share/sgml/docbook/xsl-stylesheets/xhtml/docbook.xsl"/>
    <map:serialize type="xhtml"/>
   </map:match>
  </map:pipeline>
 </map:pipelines>
</map:sitemap>]]></source>
        <p>You need to define the xhtml serializer used in &lt;map:serialize type="xhtml"/&gt;
        in the components section of the sitemap. See the 
        <link href="http://cocoon.apache.org/2.1/userdocs/serializers/xhtml-serializer.html">Cocoon
        docs</link> for the elements you need to add to define this component. You can see examples 
        of other components being added in the <code>FORREST_HOME/main/webapp/sitemap.xmap</code> file.</p>
        <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:v0.80//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/main/webapp/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> before diving in. </p>
      </answer>
    </faq>
  </part>
</faqs>

{'fraction_non_alphanumeric': 0.11679808595207163, 'fraction_numerical': 0.008952804826282142, 'mean_word_length': 2.5776346065347444, 'pattern_counts': {'":': 0, '<': 1829, '<?xml version=': 8, '>': 1829, 'https://': 0, 'lorem ipsum': 0, 'www.': 10, 'xml': 102}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3302915', 'n_tokens_mistral': 23536, 'n_tokens_neox': 22515, 'n_words': 8395}