Frequently Asked Questions

There is no particular order to these FAQs. Use your browser's "Find in this page" facility to search for keywords.

See the Using Forrest guide.

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.

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.

Forrest switched from a CVS code repository to SVN (Subversion) code repository. The old CVS repository is closed and not kept current.

Follow these Building Forrest notes.

The Using Forrest guide provides further step-by-step assistance in getting started with Forrest for your project.

Sometimes one does not want to use the most recent functionality of a plugin and instead need to use an older version. Information about changes to each plugin can be found in its documentation.

In the forrest.properties file, specify the version of the plugin that you require, e.g.

project.required.plugins=org.apache.forrest.plugin.input.PhotoGallery-0.1,...

Users of Forrest-0.7 will need to do this for the projectInfo plugin if you get the following error ...

Could not find component for role:
 [org.apache.cocoon.components.modules.input.InputModule/lm]
 (Key='org.apache.cocoon.components.modules.input.InputModule/

... then sorry, we mistakenly added new "locationmap" functionality (due in version 0.8). So do this ...

project.required.plugins=org.apache.forrest.plugin.input.projectInfo-0.1,...

forrest site -Dproject.start-uri=myfile.pdf

The Using Forrest guide provides further step-by-step assistance in getting started with Forrest for your project.

This appears to be a bug in cygwin. Please use the .bat script instead.

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.

The maxmemory property in the forrest.properties file controls how much memory Cocoon uses. Like many other properties you can copy them from the default configuration at src/core/fresh-site/forrest.properties

Set the ANT_OPTS environment variable before you run forrest. The exact value you set it to is dependant on your JVM, but something like ANT_OPTS=-Xmx500M will probably work.

If you are using the Apache Forrest xml document format 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 configuration notes for various editors.

There are content management systems like Apache Lenya.

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.

The site.xml 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 Menus and Linking. Here is a precis:

The labels can be whatever text you want.

<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>

That will create a menu like this with three links:

FAQs
   Technical
   User

These documents can be linked to from other documents, like this:

<a href="site:v0.70//faq/tech"> link to the top of the Tech FAQs
<a href="site:v0.70//faq/tech/docbook"> link to the DocBook FAQ in the Tech FAQs

If that "docbook" entry was a unique name in your site.xml then you can shorten that latter link:

<a href="site:v0.70//docbook"> link to the DocBook FAQ in the Tech FAQs

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).

Add the following entries to your site.xml file:

  <about tab="home" label="About" href="">
 	  ...
    <all_site label="Full HTML" href="wholesite.html"/>    
    <all_sitePDF label="Full PDF" href="wholesite.pdf"/>  
     ...
  </about>

In this case the menu labeled "About" will have 2 new items: "Full PDF" and "Full HTML". (See also How to create a PDF document for each tab.)

This assumes that you use the site.xml method for your site structure and navigation, rather than the old book.xml method.

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.

To insert a page break in a PDF document simply add pageBreakBefore and/or pageBreakAfter 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.

If you want these classes to be processed in your HTML documents as well you should add the following to the extra-css element in your projects skinconf.xml

 .pageBreakBefore { margin-bottom: 0; page-break-before: always; } .pageBreakAfter {
          margin-bottom: 0; page-break-after: always; } 

You would override $FORREST_HOME/main/webapp/skins/common/xslt/html/document2html.xsl and edit the "headers/authors" template.

Handling of raw files was significantly changed in Forrest 0.7. See Upgrading to Apache Forrest 0.7 for all the details.

Forrest uses Apache FOP 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 FOP Graphics formats

To get PNGs working in PDFs with Jimi:

1. Download Jimi from http://java.sun.com/products/jimi/
2. Unpack the Jimi distribution and copy JimiProClasses.zip to $FORREST/lib/optional/jimi-1.0.jar.

Alternatively you can use JAI (Java Advanced Imaging API at http://java.sun.com/products/java-media/jai). For more info, see FOP Graphics Packages

In tabs.xml, 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 manual/Introduction.html then tabs.xml should contain:

  <tab label="User Manual" href="manual"/>

and add this rule to the sitemap:

  <map:match pattern="manual">
    <map:redirect-to uri="manual/Introduction.html"/>
  </map:match>

See the tips.

To change the default file name from 'index.html' (default) to 'overview.html' you need to make the following changes:

1. Create a 'cli.xconf' file for your project
2. Edit that file to replace 'index.html' in <default-filename>index.html</default-filename> with 'overview.html'.
3. Edit your project's sitemap.xmap file.
4. Add the following code just before the end of the pipelines-element:

     <map:pipeline>
       <map:match type="regexp" pattern="^.+/$">
          <map:redirect-to uri="overview.html"/>
       </map:match>
     </map:pipeline>
             

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

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'.

To change the start page of a site:

1. Edit your project's sitemap.xmap file.
2. Add the following code just before the end of the pipelines-element:

     <map:pipeline>
       <map:match pattern="">
         <map:redirect-to uri="start.html" />
       </map:match>
     </map:pipeline>
             

3. Name the uri-attribute whatever you'd like your start page to be.
4. Don't forget to create that page and refer to it in your site.xml

Use the numeric values for character entities. For example, rather than using &ouml; use &#246;

See the XHTML Character Entities and see more discussion at Issue FOR-244.

Yes, Forrest can process text in any language, so you can include:

• accents: á é í ó ú
• diereses: ä ë ï ö ü
• tildes: ã ñ ĩ õ ũ

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:

<?xml version="1.0" encoding="UTF-8"?>

but the file content is actually using ISO-8859-1 then you will receive validation errors, especially if you include some non-ASCII characters.

This situation is commonly encountered when you edit the templates created by forrest seed 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.

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 LANG to an appropriate value, for instance:

[localhost]$ export LANG=en_US.UTF-8

Of course the appropriate 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 encoding 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:

<?xml version="1.0" encoding="ISO-8859-1"?>

Another option is to use "character entities" such as &ouml; (ö) or the numeric form &#246; (ö).

Another related issue is that your webserver needs to send http headers with the matching charset definitions to the html page.

Here are some references which explain further: GT2004 presentation by Torsten Schlabach and Alan Wood's Unicode resources.

By default Forrest does not clean its build directories in the project workspaces. This enables Cocoon to use its disk cache to speed up successive runs of forrest.

Doing 'forrest clean-site' will remove the contents of the project's generated documents directory. Doing 'forrest clean-work' will remove the project's work directories (usually build/tmp and build/webapp which include the Cocoon cache and the Cocoon logs). Doing 'forrest clean' will remove both sections.

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, work is underway to i18n skins

All internationalistation of tokens in, for example, the skins and the menus, is carried out by the Cocoon i18n Transformer. You can see an example of how it works in the above linked issue.

To server, for example, a legacy HTML site add something like the following to your projects sitemap:

<map:match pattern="old_site/**.html">
 <map:select type="exists">
  <map:when test="{properties:content}{0}">
    <map:read src="{properties:content}/{0}" mime-type="text/html"/>
    <!--
      Use this instead if you want JTidy to clean up your HTML
      <map:generate type="html" src="{properties:content}/{0}" />
      <map:serialize type="html"/>
    -->
  </map:when>
</map:match>
        

There is a more detailed discussion of this topic in the samples of a freshly seeded site. To see this documentation do the following:

1. mkdir seed
2. cd seed
3. forrest seed
4. forrest
5. Read the doc

You can configure the proxy in the forrest.properties file. Set the proxy.host and proxy.port accordingly.

You can also cross an authenticated proxy by setting the proxy.user and proxy.password accordingly.

If you have:<version>$Revision: 1.30 $</version>The '1.30' will be extracted and displayed at the bottom of the page as "version 1.30". See for example the bottom of the Using Forrest document.

This technique could also be used for a modification date with $Date: 2004/01/15 08:52:47 $

Forrest uses a configuration file to control the processing done by the Apache Cocoon command-line called cli.xconf

Your project can supply its own cli.xconf and define patterns for URIs to exclude. There are also other powerful configuration features.

This means creating a directory src/documentation/conf (or wherever ${forrest.conf-dir} points) and copying $FORREST_HOME/main/webapp/WEB-INF/cli.xconf to it. Declare the location of this file in the forrest.properties configuration, e.g. project.configfile=${project.home}/src/documentation/conf/cli.xconf

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/':

   ....
   <!-- Includes and excludes can be used to limit which URLs are rendered -->
   
   <exclude pattern="**/"/>
   <exclude pattern="**apidocs**"/>
   <exclude pattern="api/**"/>
   
   <uri src="favicon.ico"/>
</cocoon>

This is just an example, and you should modify it appropriately for your site.

This can be done by overriding the cli.xconf Cocoon config file, and defining patterns for URLs to exclude.

Certain patterns are claimed by the default sitemaps for special processing. These include: site, changes, todo, faq, images, my-images, skinconf, community, howto

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 (FOR-217).

...
* [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
...

• Column 1 is the page build status (*=okay X=brokenLink ^=pageSkipped).
• 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.
• Column 3 is the number of links that were gathered from that page.
• Column 4 is the time taken.
• Column 5 is the page size.

If you are using JDK 1.4.0 or newer, you can enable headless operation by running Forrest with the forrest.jvmarg parameter set to -Djava.awt.headless=true, like this:

forrest -Dforrest.jvmargs=-Djava.awt.headless=true site

See also Cocoon FAQ.

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 <project-name> and <group-name> elements of the skinconf.xml 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 src/documentation/content/xdocs/images/project.svg and adjust the "width" attribute of the <svg> element. For further details see SVG resources.

Notes are provided for various tools at Using Catalog Entity Resolver for local DTDs.

There are default skins 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.

See notes about configuration of the skins. Some projects may have special needs and can define their own skin.

First consider whether your needs would be better met by Cocoon itself, rather than Forrest.

That said, there are valid reasons for wanting programmatically generated content, so here is how to enable XSP:

1. Download jdtcore-2.1.0.jar, and copy it to the $FORREST_HOME/main/webapp/WEB-INF/lib directory (or lib/core/ directory in the source distribution).

2. Add the following generator definition in the map:generators section of your project sitemap

     <map:generator name="serverpages"
        pool-grow="2" pool-max="32" pool-min="4"
        src="org.apache.cocoon.generation.ServerPagesGenerator"/>

3. Decide how you want to use XSP. For single files, you could just define a *.xml matcher:

   <map:match pattern="dynamic.xml">
     <map:generate src="content/xdocs/dynamic.xsp" type="serverpages"/>
     ...
     <map:serialize type="xml"/>
   </map:match>

   You may instead wish to override forrest.xmap to define a general mapping for XSPs.

See also the AddingXSPToForrest Wiki page.

Breadcrumbs begin with up to three URLs specified in skinconf.xml. Here is what the Forrest site uses:

  <trail>
    <link1 name="apache" href="http://www.apache.org/"/>
    <link2 name="xml.apache" href="http://xml.apache.org/"/>
    <link3 name="" href=""/>
  </trail>

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 skinconf.xml.

forrest run -Dforrest.jvmargs="-Djetty.port=80"

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 forrest run

Certain patterns are claimed by the default sitemaps for special processing. These include: site, changes, todo, faq, images, my-images, skinconf, community, howto

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 (FOR-217).

One site.xml file in your project root can replace all the book.xml files (one per directory) in your site. Internally, Forrest uses site.xml 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 site.xml-generated menus aren't appropriate. See Menus and Linking.

There are two ways. Forrest has a simplifiedDocbook 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.

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 project sitemap as explained in Using Forrest 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.

<?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="{properties: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>

You need to define the xhtml serializer used in <map:serialize type="xhtml"/> in the components section of the sitemap. See the Cocoon docs for the elements you need to add to define this component. You can see examples of other components being added in the FORREST_HOME/main/webapp/sitemap.xmap file.

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.

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 Using Forrest for configuration guidance.

Do 'forrest -projecthelp' or './build.sh' to find the version number.

To list the properties, add "forrest.echo=true" to your forrest.properties file and watch the build messages. Doing 'forrest -v' will provide verbose build messages.

The logfiles are at build/webapp/WEB-INF/logs/

The log level can be raised with the logkit.xconf configuration. If you are using Forrest in the interactive webapp mode (which is generally easiest for debugging errors) then see the build/webapp/WEB-INF/logkit.xconf file. If you are generating a static site (with command-line 'forrest') then copy $FORREST_HOME/main/webapp/WEB-INF/logkit.xconf to your project at src/documentation/content/conf/logkit.xconf and modify it. See more information and efficiency tips with Cocoon logging.

Doing 'forrest -v' will provide verbose build messages to the standard output.

Join one of the Forrest project mailing lists and tell us what you would 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!

Please send all contributions via our issue tracker. Here are notes about making patches.

More info about contributing can be found at the Contributing to Forrest page. It is always a good idea to check the Forrest issue tracker before diving in.