Frequently Asked Questions
Table Of Contents
=================
Questions
1. Getting Started and Building Forrest
1.1. Where can I read an overview about how to work with Forrest?
1.2. What are the system requirements for Forrest?
1.3. The old xml-forrest CVS code repository seems to be stale. What happened?
1.4. How can I use SVN to keep up to date with the latest codebase?
1.5. What is the best way to generate "standalone documents" using Forrest?
1.6. When running ./build.sh in cygwin, I get an error: cygpath.exe: *** can't create title mutex, Win32 error 6.
1.7. How can I specify the amount of memory to be used by Java?
2. Content Creation
2.1. What tools can be used to edit the content?
2.2. How to use the site.xml configuration file for menus and linking.
2.3. Where are examples of documents and site.xml and tabs.xml files?
2.4. How can I generate one pdf-file out of the whole site or selected pages of the site?
2.5. How do I insert page breaks into documents?
2.6. How can I generate html-pages to show a 'clickable' email-address (of the author-element)?
2.7. How do I link to raw files such as config.txt and brochure.pdf?
2.8. Images don't display in PDFs. How do I fix this?
2.9. The tab link in my site incorrectly assumes that 'index.html' is present in the linked-to directory. How do I fix this?
2.10. I need help with the interaction between tabs.xml and site.xml
2.11. How can I change the default file name that Forrest will look for when I request a URL like http://myserver or http://myserver/mydir/ ?
2.12. How can I use a start-up-page other than index.html?
2.13. How to use special characters in the labels of the site.xml file?
2.14. Does Forrest handle accents for non-English languages?
2.15. How can I make Forrest properly clean up the build/site-directory?
2.16. How can I internationalise (i18n) my content?
2.17. How can I include HTML content that is not to be skinned by Forrest?
3. Technical
3.1. I'm behind a proxy and it's preventing Plugins from being downloaded, what should I do?
3.2. How can I generate html-pages to show the revision tag of cvs?
3.3. How to control the processing of URIs by Cocoon, e.g. exclude certain URIs, include other additional ones.
3.4. How do I stop Forrest breaking on links to external files that may not exist, like javadocs?
3.5. Some of my files are not being processed because they use common filenames.
3.6. What do the symbols and numbers mean when Forrest lists each document that it has built?
3.7. 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.
3.8. The project logo that is generated from SVG is truncating my project name.
3.9. How do i configure my favourite XML editor or parser to find the local Forrest DTDs?
3.10. How to make the site look better and change its skin?
3.11. How do I enable XSP processing?
3.12. How do breadcrumbs work? Why don't they work locally?
3.13. How do I make forrest run listen on a different port?
4. Older version: 0.6
4.1. Some of my files are not being processed because they use common filenames.
5. General
5.1. What is the relationship between site.xml and book.xml?
5.2. How do I use DocBook as the xml documentation format?
5.3. How to report which version of Forrest is being used and the properties that are set?
5.4. Where are the log files to find more infomation about errors?
5.5. How to help?
5.6. How to contribute a patch?
Questions
=========
1. Getting Started and Building Forrest
---------------------------------------
1.1. Where can I read an overview about how to work with Forrest?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.
See the Using Forrest [Link: ../docs_0_70/your-project.html]
guide.
1.2. What are the system requirements for Forrest?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
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.
1.3. The old xml-forrest CVS code repository seems to be stale. What happened?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
Forrest switched from a CVS code repository to SVN (Subversion)
code repository. The old CVS repository is closed and not kept
current.
1.4. How can I use SVN to keep up to date with the latest codebase?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.
Follow these Building Forrest [Link: error:site:v0.70//build]
notes.
The Using Forrest [Link: ../docs_0_70/your-project.html] guide
provides further step-by-step assistance in getting started
with Forrest for your project.
1.5. What is the best way to generate "standalone documents" using Forrest?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.
forrest site -Dproject.start-uri=myfile.pdf
The Using Forrest [Link: ../docs_0_70/your-project.html] guide
provides further step-by-step assistance in getting started
with Forrest for your project.
1.6. When running ./build.sh in cygwin, I get an error: cygpath.exe: *** can't create title mutex, Win32 error 6.
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.
This appears to be a bug in cygwin [Link:
http://issues.apache.org/jira/secure/ViewIssue.jspa?key=FOR-10].
Please use the .bat script instead.
1.7. How can I specify the amount of memory to be used by Java?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.
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.
2. Content Creation
-------------------
2.1. What tools can be used to edit the content?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
If you are using the Apache Forrest xml document format [Link:
error:site:v0.70//dtd-docs] 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
[Link: error:site:v0.70//catalog] for various editors.
There are content management systems like Apache Lenya [Link:
http://lenya.apache.org/].
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.
2.2. How to use the site.xml configuration file for menus and linking.
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
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
[Link: ../docs_0_70/linking.html]. Here is a precis:
The labels can be whatever text you want.
That will create a menu like this with three links:
FAQs
Technical
User
These documents can be linked to from other documents, like
this:
link to the top of the Tech FAQs
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:
link to the DocBook FAQ in the Tech FAQs
2.3. Where are examples of documents and site.xml and tabs.xml files?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.
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).
2.4. How can I generate one pdf-file out of the whole site or selected pages of the site?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.
Add the following entries to your site.xml file:
...
...
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 [Link:
../docs_0_70/howto/howto-pdf-tab.html].)
This assumes that you use the site.xml [Link:
../docs_0_70/linking.html] method for your site structure and
navigation, rather than the old book.xml method.
2.5. How do I insert page breaks into documents?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
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; }
2.6. How can I generate html-pages to show a 'clickable' email-address (of the author-element)?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.
You would override
$FORREST_HOME/main/webapp/skins/common/xslt/html/document2html.x
sl and edit the "headers/authors" template.
2.7. How do I link to raw files such as config.txt and brochure.pdf?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
Handling of raw files was significantly changed in Forrest 0.7.
See Upgrading to Apache Forrest 0.7 [Link:
error:site:v0.70//upgrading_07/raw] for all the details.
2.8. Images don't display in PDFs. How do I fix this?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.
Forrest uses Apache FOP [Link: http://xml.apache.org/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 [Link:
http://xml.apache.org/fop/graphics.html]
To get PNGs working in PDFs with Jimi:
1. Download Jimi from http://java.sun.com/products/jimi/ [Link:
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 [Link:
http://xml.apache.org/fop/graphics.html#packages]
** Note **
Due to Sun's licensing, we cannot redistribute Jimi or JAI with
Forrest.
----------------------------------------------------------------------
2.9. The tab link in my site incorrectly assumes that 'index.html' is present in the linked-to directory. How do I fix this?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
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:
and add this rule to the sitemap:
2.10. I need help with the interaction between tabs.xml and site.xml
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
See the tips [Link: ../docs_0_70/linking.html#tab-site].
2.11. How can I change the default file name that Forrest will look for when I request a URL like http://myserver or http://myserver/mydir/ ?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.
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 [Link: #cli-xconf]' file for your project
2. Edit that file to replace 'index.html' in
index.html with 'overview.html'.
3. Edit your project's sitemap.xmap [Link:
error:site:v0.70//project-sitemap] file.
4. Add the following code just before the end of the
pipelines-element:
2.12. How can I use a start-up-page other than index.html?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
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 [Link:
error:site:v0.70//project-sitemap] file.
2. Add the following code just before the end of the
pipelines-element:
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
2.13. How to use special characters in the labels of the site.xml file?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.
Use the numeric values for character entities. For example,
rather than using ö use ö
See the XHTML Character Entities [Link:
http://www.w3.org/TR/xhtml-modularization/dtd_module_defs.html#a
_xhtml_character_entities] and see more discussion at Issue
FOR-244 [Link: http://issues.apache.org/jira/browse/FOR-244].
2.14. Does Forrest handle accents for non-English languages?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
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:
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:
Another option is to use "character entities" such as ö
(ö) or the numeric form ö (ö).
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 [Link:
http://orixo.com/events/gt2004/bios.html#torsten] and Alan
Wood's Unicode resources [Link:
http://www.alanwood.net/unicode/].
2.15. How can I make Forrest properly clean up the build/site-directory?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
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.
To ensure a clean build call 'forrest clean site' instead of
just 'forrest' so Forrest will delete all build directories
before creating new content.
2.16. How can I internationalise (i18n) my content?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.
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 [Link:
http://issues.apache.org/jira/browse/FOR-506] to i18n skins
All internationalistation of tokens in, for example, the skins
and the menus, is carried out by the Cocoon i18n Transformer
[Link:
http://cocoon.apache.org/2.1/userdocs/transformers/i18n-transfor
mer.html]. You can see an example of how it works in the above
linked issue.
2.17. How can I include HTML content that is not to be skinned by Forrest?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
To server, for example, a legacy HTML site add something like
the following to your projects sitemap:
3. Technical
------------
3.1. I'm behind a proxy and it's preventing Plugins from being downloaded, what should I do?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
You can configure the proxy in the forrest.properties file. Set
the proxy.host and proxy.port accordingly (the port will
default to port 80).
3.2. How can I generate html-pages to show the revision tag of cvs?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.
If you have:$Revision: 1.30 $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
[Link: ../docs_0_70/your-project.html] document.
This technique could also be used for a modification date with
$Date: 2004/01/15 08:52:47 $
3.3. How to control the processing of URIs by Cocoon, e.g. exclude certain URIs, include other additional ones.
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.
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.xc
onf
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/':
....
This is just an example, and you should modify it appropriately
for your site.
** Note **
Wildcards may be used. These are a powerful feature of Cocoon's
sitemap [Link: error:site:v0.70//sitemap-ref]. For example,
foo/* would match foo/bar, but not foo/bar/baz — use foo/** to
match that.
----------------------------------------------------------------------
3.4. How do I stop Forrest breaking on links to external files that may not exist, like javadocs?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.
This can be done by overriding the cli.xconf [Link: #cli-xconf]
Cocoon config file, and defining patterns for URLs to exclude.
3.5. Some of my files are not being processed because they use common filenames.
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
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 [Link:
http://issues.apache.org/jira/browse/FOR-217]).
3.6. What do the symbols and numbers mean when Forrest lists each document that it has built?
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.
... * [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.
3.7. 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.
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.
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 [Link:
http://cocoon.apache.org/2.1/faq/faq-configure-environment.html]
.
3.8. The project logo that is generated from SVG is truncating my project name.
.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.
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 and 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