This tutorial will lead you through the process of installing Forrest, and using it to create a new project, or add Forrest-based docs to an existing project.
Download the latest release of Forrest, or if you want to try the development version, build Forrest from source.
After downloading and extracting forrest, you need to add environment variables. In Unix/Linux:
In Windows, go to "My Computer", "Properties", "Advanced", "Environment Variables" and add:
FORREST_HOME as C:\full\path\to\apache-forrest-0.5.1 and
PATH as %PATH%;%FORREST_HOME%\bin
To see what the forrest command can do, type 'forrest -projecthelp'
As 'site' is the default target, just running 'forrest' without options will generate a "static HTML website". For example, typing 'forrest' in the xml-forrest directory would build Forrest's own website. But we're going to be building a new site, so read on.
'Seeding' a project is our own arborial term for adding a template documentation set to your project, which you can then customize.
To try this out, create a completely new directory, and type 'forrest seed':
You now have a template documentation structure all set up:
To render this to HTML, type 'forrest'. You should have a HTML site rendered
into the build/site directory:
In the section above, we have run 'forrest seed' in an empty directory. If you have an existing codebase which you wish to add Forrest docs to, run 'forrest seed' in your project base directory, and the Forrest doc structure will be grafted onto your project.
If your project already has XML documentation, it may be easier to tell
Forrest where the XML lives, rather than rearrange your project directories to
accommodate Forrest. This can be done by editing
forrest.properties (consult
the Changing the layout
section for more details).
Having seeded a project with template docs, you will now want to customize it to your project's needs. Here we will deal with configuring the skin, and changing the project layout.
Most Forrest skins can be customized through a single XML file,
src/documentation/skinconf.xml, which (minus its DTD) looks
like this:
Customise this file for your project. The images/ directory
mentioned in 'project-logo' and 'group-logo' elements correspond to the
src/documentation/resources/images directory (this mapping is done
in the sitemap).
Having edited this file (and ensured it is valid XML!), re-run the 'forrest' command in the site root, and the site should be updated.
For a simple site, Forrest's default directory layout may seem rather cumbersome. Forrest allows you to place files anywhere you want in your project, so long as you tell Forrest where you have placed the major file types.
The forrest.properties file is what maps from your directory
layout to Forrest's. If you generated your site with 'forrest seed', you
should have one pre-written, with all the entries commented out. The relevant
forrest.properties entries (with default values) are:
For example, if you wish to keep XML documentation in src/xdocs rather than
src/documentation/content/xdocs simply change the 'project.xdocs-dir'
definition:
Say we wish to emulate the nice and simple Maven format:
/xdocs /xdocs/images /xdocs/stylesheets
Here are the required property definitions:
src/documentation/content/xdocs structure. In the layout above, we have
overlapping directories, so you will end up with duplicate files. This small
glitch doesn't usually cause problems; just always remember that all links
are resolved through the sitemap.
Now you can start adding content of your own, in
src/documentation/content/xdocs
Whenever adding a new file, you should add an entry to the project's
site.xml file. site.xml is like a site index, and is rendered as
the vertical column of links in the default skin. Have a look at Forrest's own
xdocs for an example. More detailed info about site.xml is provided in Menus and Linking.
The tabs.xml file is used to produce the 'tabs' in the top-left
corner of the default skin.
Tabs allow users to quickly jump to sections of your site. See the menu generation documentation for more details, and again, consult Forrest's own docs for a usage example.
You can have one or two levels of tabs. The images above show a
single level. However, you can create a second level that
will only be displayed when its parent tab is selected. For example,
the tabs.xml snippet below will display either one or
two rows of tabs, depending on which of the top level tabs is selected.
The first row will have two tabs, one labelled How-Tos, the
other labelled Apache XML Projects. When the
How-Tos tab is selected there will
be no second row of tabs. However, when the Apache XML
Projects tab is selected, a second row of tabs will be displayed
below the first.
Images usually go in src/documentation/resources/images/
The default sitemap
maps this directory to images/, so image tags will typically look
like <figure src="images/project-logo.png" alt="Project Logo"/>
The Cocoon sitemap is a set of rules for generating content (HTML, PDFs etc) from XML sources. Forrest has a default sitemap, which is adequate for everyday sites (like the Forrest site itself).
Sometimes, one needs to go beyond the default set of rules. This is where Forrest really shines, because its Cocoon backend allows virtually any processing pipeline to be defined. For example, one can:
site.html and site.pdf.
If your site defines its own sitemap, it must perform all the operations of
the Forrest default. To get started, simply copy the Forrest sitemaps from
xml-forrest/src/resources/conf/*.xmap into your
src/documentation directory (or wherever
${project.sitemap-dir} points to).
The sitemap syntax is described in the Cocoon sitemap docs. The Forrest sitemap is broken into multiple files. The main one is sitemap.xmap, which delegates to others. See the Sitemap Reference for a tour of the default sitemap.
Say that download.xml lists downloads for a certain package. It would be
best to represent download information in a custom XML format:
Here are the binaries for FooProject
....
This should be placed in your content directory, typically
src/documentation/content/xdocs, and an entry added to
site.xml.
To handle these special tags, one would write a stylesheet to convert them to regular documentv12 format. Here is such a stylesheet, download2document.xsl:
| File | Size |
|---|
Place this in the default stylesheets directory,
src/documentation/resources/stylesheets (or wherever
${project.stylesheets-dir} points).
Now the sitemap has to be modified to transform our custom format into doc-v12. The Sitemap Reference provides details on how the sitemap works, and how it can be customized for specific projects. Specifically, the part to read is the forrest.xmap section. We have to register our new DTD and associate a transformation with it.
forrest.xmap in your project by copying
$FORREST_HOME/context/forrest.xmap to your project's
src/documentation/ directory.Edit forrest.xmap, locate the
sourcetype action, and register the new document
type:
Locate where the sourcetype action is used, and add a
when clause to handle the conversion for our
document type:
By default, Forrest requires that all XML files be valid: i.e. they must have a DOCTYPE declaration and associated DTD, and validate against it. Our new 'downloads' document type is no exception. The XML Validation section continues this example, showing how to register a new document type. Briefly, this involves:
${project.schema-dir}/dtd${project.schema-dir}/catalog.xcat. Eg:
PUBLIC "-//Acme//DTD Download Documentation V1.0//EN"
"dtd/download-v11.dtd"Please read XML Validation for the full story.
Similar to the previous example, we can integrate RSS into our
site by overriding and editing the sitemap. As described in the 'source pipelines'
section of sitemap reference, Forrest's
sitemap.xmap delegates source
handling to various subsitemaps in a **.xml block.
We can add another *.xml matcher in this section, just before the
catch-all subsitemap:
(You will want to rename and customize
rssissues2document.xsl to your needs)
As Forrest separates content from presentation, we can plug in different
"skins" to instantly change a site's look & feel. Forrest provides one
primary skin, forrest-site, and a handful of others in various
states of maintenance.
To change the skin, edit the forrest.properties file, and
change the following entry:
Projects can define their own skin, in the
src/documentation/skins directory (or wherever
${project.skins-dir} points). The default sitemap assumes a
certain skin layout, so the easiest way to create a new skin is by
copying an existing Forrest skin. For example, copy
xml-forrest/src/resources/skins/template to
src/documentation/skins/myskin, and add
project.skin=myskin to forrest.properties.
In addition, when using a project-specific skin it is a good idea to also use a project-specific sitemap. This is to protect your skin from changes in the Forrest default sitemap. While the sitemap-skin contract (expressed as XSLT parameters) is now fairly stable, this should not be relied on.
The two most interesting XSLT stylesheets involved are:
Typically there is a lot of commonality between skins. XSLT provides an 'import' mechanism whereby one XSLT can extend another. Forrest XSLTs typically 'import' from a common base:
In order to use this feature in your custom skins you must copy
the common skin from the forrest distribution into your custom skins
directory (see xml-forrest/src/resources/skins/common).
This will protect your skin from changes in the Forrest common skin,
but you must remember to update this skin in order to take advantage
of new features added by the Forrest team.
This is particularly relevant for menu rendering (book2menu.xsl), where the common stylesheet does the 'logic' of which item is selected, and overriding stylesheets define the presentation.
In comparison to simpler tools like Anakia, Cocoon's command-line mode (and hence Forrest) is painfully slow. As the dream list notes, Forrest was originally intended to be used for dynamic sites, and the Cocoon crawler used only to create static snapshots for mirroring. This section describes how, by developing with a "live" Forrest webapp instance, Forrest-based doc development can be faster and easier than comparable tools.
Type forrest run in your project root to start Forrest's
built-in Jetty web server. Once it has started, point your browser at
http://localhost:8888, which
should show your website, rendered on demand as each page is clicked.
Alternatively if you wish to run Forrest from within an existing
servlet container, type forrest webapp to build an open
webapp in build/webapp/.
With the setup above, you can edit the XML files in
build/webapp/content/xdocs and see the changes immediately
in the browser.
To get the edited content back to its home directory, either copy it
once you have finished editing (with the forrest
backcopy command), or symlink the
src/documentation/content/xdocs directory to
build/webapp/content/xdocs.
build/ directory. There are also suggestions for making
webapp-based content generation the primary technique. Future
directions like these are debated on
the forrest-dev mail list.
Please join if you have any suggestions.
Established Java projects which use Ant will typically wish to subsume Forrest's build targets ('site', 'webapp', 'validate' etc) into their own build system, to provide a unified interface for users. This section describes how to invoke Forrest operations from an external Ant build file.
Here are the targets that can be included in a project's build.xml file to invoke Forrest:
forrest.antproxy.xml, not
forrest.build.xml. The forrest.antproxy.xml
script invokes forrest.build.xml using Forrest's own
bundled version of Ant.
You'll notice that these targets require ${forrest.home}
to be set. ${forrest.home} must point to the user's
shbat distribution of Forrest. Thus we need a mechanism for the user
to inform the build script of their Forrest's location. Typically
this is done by setting a property in a properties file like
project.properties, but can also be done by looking for the
FORREST_HOME environment variable.
Forrest comes with an Ant snippet file,
forrest-targets.ent that supplies the targets listed
above, as well as searching for a ${forrest.home}
definition in a number of likely places:
FORREST_HOME environment variable.project.properties file.build.properties file.ant.properties file..ant.properties file.
forrest-targets.ent also prints out an informative error
message if ${forrest.home} cannot be resolved.
forrest-targets.ent is supplied as part of the template
Forrest project ('forrest seed'). The comments at the
top describe how to use it in a project's build.xml. Typical usage
is:
Having done this, the Forrest targets (site, webapp, war,
validate) are automatically added to your project.
build.properties
because if your build already reads build.properties then the forrest
targets will not be able to re-set the forrest.home property.