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.
You have a local copy of the main documentation with your version of
Forrest. Do 'cd site-author; forrest run' and visit
http://localhost:8888/
in your browser. The most recent documentation
is in SVN trunk which creates the forrest.apache.org website.
Each plugin has its own documentation and working examples of its techniques.
The example seed site has other documentation and working examples of various techniques. Do 'cd my-new-directory; forrest seed-sample; forrest run'. Every hour the forrestbot generates a static version of this documentation on our testing zone.
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.5 (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.
Users of Forrest-0.7 will need to do this for the projectInfo plugin if you get the following error ...
... then sorry, we mistakenly added new "locationmap" functionality (due in version 0.8). So do this ...
There is a trick that can cut down your turnaround time with building. In forrest.properties ...
Uncomment that and set it to the specific page that you want. Forrest will build that single document, then of course it will keep crawling links from there. It might be confined to a sub-directory, but depending on links could end up generating the whole site. The main thing is that your page of interest is built first.
It is probably easiest to make this change temporarily as a command-line parameter, e.g.
You can terminate forrest with 'kill' or Ctrl-C after it has built your pages of interest.
Cocoon can be instructed via the Cocoon cli.xconf file to not follow links (see its "follow-links" parameter). So this will build only the document that was specified. Be careful, if you also usually build PDF pages, then they will not be built.
Cocoon can also be instructed to not process certain URIs if you need to temporarily exclude then.
Another useful technique is to use 'wget' or Apache Ant's Get task to
retrieve individual files, e.g. Do 'forrest run' and then
'wget http://localhost:8888/index.pdf'
./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. Please use the .bat script instead.
The version of Jing needs to be updated.
This is fixed in Forrest-0.9-dev version. See FOR-984.
One workaround is to update your copy of the
Jing jar at
$FORREST_HOME/lib/core/
Another workaround is to edit the forrest.properties configuration file to expose the "forrest.validate.sitemap" property and set it to "false". Might need to do the same for the "forrest.validate.stylesheets" property.
Cough, yes!. See this explanation on the Forrest mail lists.
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 main/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.
The forrest.jvmargs
property in the
forrest.properties
file can be used to start forrest in
debug mode on a specific port. forrest.jvmargs=-Xdebug
-Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n
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.
site.xml
configuration file for menus and linking.
The site.xml
configuration file is used for two different
purposes: defining the 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.
That will create a menu like this with three links:
These documents can be linked to from other documents, like this:
If that "docbook" entry was a unique name in your site.xml then you can shorten that latter link:
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
).
Did you make a link to it? Forrest does not find documents by scanning the filesystem to find the source documents. Rather it starts at one document and crawls the links to find other documents to process.
There are essentially two ways to create links. Via a site.xml file to define the navigation and menu structure, or via direct relative linking. See the to previous FAQs.
Normally the source material will be local. The Forrest crawler does not follow and process off-site links. The new locationmap (0.8+) enables content to be drawn from remote sources.
Add the following entries to your site.xml file. Note that the href must be exactly "wholesite" or "site" which triggers a special match in the sitemap to aggregate all documents.
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
You would override
$FORREST_HOME/main/webapp/skins/common/xslt/html/document-to-html.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:
$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:
and add this rule to the sitemap:
See the tips.
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:
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:
Use the power of the Cocoon sitemaps. There is default handling for *.php (see main/webapp/sitemap.xmap) to map the 'php' extension to an internal request for "html". See more about PHP below.
Use the same internal re-direction technique for your special needs, e.g. copy that php match to your project sitemap and use ".htm" instead.
Use the *.php filename extension (see above) for the output html links in site.xml navigation. Add your php processing instructions to the source documents.
However, beware FOR-999 "processing-instruction nodes in source are not always passed through to html output" whereby only PIs in certain body elements are handled.
Use the numeric values for character entities. For example, rather
than using
ö
use
ö
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:
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:
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 and Alan Wood's Unicode resources.
A set of symbols is available. See the demonstration in a fresh
'forrest seed' site (at
samples-b/xml-entities.html).
For example, use
"&myp-t;
" to represent the project name together with
trademark symbol "My Project Name™". Avoid lengthy typing and
potential spelling errors.
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.
For example, navigation menus can be internationalized and different content can be served.
There is an example to demonstrate and explain the facilities. See a 'forrest seed-sample' site.
All internationalisation of tokens is carried out by the Cocoon i18n Transformer.
To serve, for example a legacy HTML site, add something like the
following to your project's sitemap and place the source content in a
src/documentation/content/old_site/
directory.
Exactly what the match should be is dependant on your content structure. It is outside the scope of this FAQ to provide full details, but new users may like to refer to the Cocoon sitemap docs.
There is a more detailed discussion of this topic in the samples of a freshly seeded site. To see this documentation do the following:
http://localhost:8888/samples-b/linking.html#no-decoration
Place various resources (e.g. javascript, css) into the "project skins" directory. The default forrest.properties has this at src/documentation/skins/$skin-name/ Javascript files would go in a "scripts" subdirectory. CSS files would go in a "css" subdirectory.
Then refer to those from your source documents with URIs like /skin/blah.js and /skin/foo.css
See how this is handled in the core sitemap called forrest/main/webapp/resources.xmap Search for "javascript" then follow to the <map:resource name="skin-read"> section.
Every site has an automatically generated document at
/linkmap.html
which is produced from the site.xml
navigation configuration. It uses the @label and absolutized @href and
element name and @description attribute for each node.
For example, the Forrest project's Site Linkmap Table of Contents.
The document is also useful when developing your documentation and linking to other docs. The element names (column #2) e.g. href="site:mail-lists" or href="site:howto/overview"
This is also the document that 'forrest site' uses to kick-start the Cocoon crawler which then follows links to build each page. See the project.start-uri in the forrest.properties file.
Because we are based on Apache Cocoon, a lot of the functionality is provided behind-the-scenes, i.e. we use Cocoon's sitemaps and sitemap components such as XSLT transformers. So there is not much need for Java code in Forrest.
For Forrest developers who want to explore or enhance that code, see the Apache Cocoon SVN trunk. From time-to-time we update Forrest's packaged version of Cocoon and so can include your contributions.
That said, you will find some Java code in Forrest at main/java/... for Cocoon components that have been developed at Forrest, e.g. Locationmap and Dispatcher. There is also Java code for some plugins with specialised purpose, e.g. PhotoGallery.
Apache Cocoon has a sophisticated cache. When running Forrest in dynamic mode, the initial visitor will receive slower response. The very first page served will cause Cocoon to cache the pipelines. Later requests will re-use those cached components and add others to the cache. A good technique is to warm up the cache after the forrest webapp has been re-started. Requesting the front page alone will populate the cache with the common items used for other pages. Using a spider such as wget, will warm up everything.
The Cocoon cache and sitemaps can be tuned. See Cocoon Performance Tips and CocoonPerformance and the "Object Stores" section of main/webapp/WEB-INF/cocoon.xconf
Responsiveness can be further enhanced by utilising a transparent proxy server, e.g. Apache HTTP Server as a frontend. See CocoonAndApacheModProxy.
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.
forrest.properties
files, you can do once in your
${user.home}/forrest.properties
!
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/':
This is just an example, and you should modify it appropriately for your site.
foo/bar
, but not
foo/bar/baz
— use foo/** to match
that.
See the example "HowTo Generate an ASF mirrors page" which explains how to include non-linked extra documents to the processing using the Cocoon CLI.
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 reserved words include: site, wholesite, 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).
Each time that Cocoon processes a link, it will report the status messages ...
If you are using JDK 1.5 or newer, you can enable headless
operation by running Forrest with the forrest.jvmarg
parameter set to -Djava.awt.headless=true
, like this:
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.
See Using Forrest for configuration guidance.
See Using Forrest for configuration guidance.
See XML validation.
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:
Add the following generator definition in the map:generators section of your project sitemap
Decide how you want to use XSP. For single files, you could just define a *.xml matcher:
You may instead wish to override forrest.xmap to define a general mapping for XSPs.
See also the AddingXSPToForrest Wiki page.
forrest run
listen on a different port?
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
If you use an IDE like Eclipse and want to debug java code in Forrest
you need to start Forrest with debugging mode turned on. To do this
you need to add -Xdebug
-Xrunjdwp:transport=dt_socket,address=8000,server=y,susp end=n
to the forrest.jvmargs
property in the
forrest.properties
file. Don't forget to ensure the
property is uncommented in that file.
Why might you want to do this? There is really no effect on Cocoon processing, but a little time can be saved on filesystem writes, which will accumulate to a big savings for a site with thousands of files.
Some tools depend on the "date-last-modified" timestamp of the generated files. For example, the Forrestbot will then deploy only the modified files.
There was some discussion about this on the Forrest developer mailing list: Cocoon Checksum Specifically note that this feature only stops Cocoon from writing to disk if the new file is the same as the existing file. Cocoon still spends the same amount of time generating the content as it would if checksums were not enabled.
Locate the checksums-uri
tag within cli.xconf and replace
the contents with an absolute path and filename for the checksums
file. Projects can supply their own (see FAQ:
Cocoon cli.xconf) or use the default
installation-wide cli.xconf file.
The core Cocoon components are defined in the
main/webapp/sitemap.xmap
file. Normally the default
settings are suitable. There are some things that you might like to
change per project. For example, change the html encoding for output
html files from the default UTF-8 or configure a different document
type declaration for the Dispatcher.
Create a fresh site with 'forrest seed' and see the set of symbols at the
src/documentation/resources/schema/symbols-project-v10.ent
file.
Copy that file to your own projects at the same location. Also add the
entry to your project xml catalog as shown in the seed site at
src/documentation/resources/schema/catalog.xcat
file.
Now copy the particular entity that you wish to re-define from
main/webapp/resources/schema/entity/symbols-core-v10.ent
file into your project symbols file and edit the entity declaration.
Re-start Forrest.
These un-necessary differences happen because the comitter who did 'svn add' for those files did not have their Subversion client configured properly for the "svn:eol-style" setting. See some notes about rectifying this issue.
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).
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.
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. Alternatively
use the "html" DocBook stylesheets and the default Cocoon serializer,
i.e. <map:serialize type="html"/>
The output of the above sitemap will be plain html not adorned with a Forrest theme and navigation. If instead you need the latter, then use the following technique instead. This transforms DocBook xml to html, then uses a Forrest core stylesheet to transform and serialize to the internal xml format, then the normal machinery takes over and does the output transformation. This use the Content Aware Pipelines (SourceTypeAction) to peek at the source xml. If it is DocBook-4.2 then this sitemap match is triggered, if not then it falls through to the core of Forrest.
You can also use a mixture of the 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.
Also when starting 'forrest'
or 'forrest run'
the versions are reported for forrest, java, and ant.
To list the properties and other stuff, add "forrest.echo=true" to your
forrest.properties file and watch the build messages. Doing
'forrest -v'
will provide verbose build messages and other useful
information.
In 'forrest run'
mode, use the
Forrestbar to see the build-info
and properties, or access them directly:
http://localhost:8888/build-info
http://localhost:8888/module.properties.properties
See the documentation about the new Properties system.
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
main/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/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.
Where normally you would do
'forrest'
or 'forrest run'
etc. instead use
the "quiet" option, and do
'forrest -q'
or 'forrest -q run'
etc.
If errors are reported, then drop the "quiet" option and run again to
get the context for the error.
Doing 'forrest -v'
will provide very verbose build messages to
the standard output.
Adding colour to the forrest output messages will greatly assist readability.
Set the ANT_ARGS environment variable like so:
export ANT_ARGS="$ANT_ARGS -logger org.apache.tools.ant.listener.AnsiColorLogger"
To change the default colours, set the ANT_OPTS environment variable
like so:
export ANT_OPTS="$ANT_OPTS -Dant.logger.defaults=$FORREST_HOME/etc/AnsiColorLogger.properties"
and create that configuration file as
explained
in the Apache Ant Manual.
That is required on Mac OS X and the "Attribute" for each colour needs
to be "0" rather than the default "2".
Note that not all terminals support ANSI color codes.
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.
Employers can send notices about employment opportunities. There is a special jobs<AT>apache.org mailing list. You can also send these notices to the project mailing lists, e.g. dev list at Forrest or Cocoon (add [jobs] to the subject line). You can also approach particular developers off-list. However only genuine jobs, not pleas for free support (see mailing lists).
Some enlightened employers enable their employees to contribute material which was created during work time using work-related resources. Please note the need to file a Corporate Contributor License Agreement (CCLA) with The Apache Software Foundation.
Press enquiries should be co-ordinated through the ASF Public Relations Committee (PRC). See contact information. The PRC also provides guidelines and handles particular usage of ASF trademarks and logos (see also FAQ and Guidelines).
The Apache Forrest logo (PNG) and banner (SVG | PNG) are available. Unfortunately the logo is only available as PNG.
Security and vulnerability issues are co-ordinated through the ASF Security Team. This is only for reporting undisclosed security vulnerabilities in Apache products. For other issues, use the Forrest project Issue tracker.