Welcome to Forrest | ![]() |
Introduction
Forrest is an XML standards-oriented project documentation framework based on Apache Cocoon, providing XSLT stylesheets and schemas, images and other resources. Forrest uses these to render the XML source content into a website via command-line, robot, or a dynamic web application.
User-friendly
Forrest is designed with the new user in mind. Much effort has gone into making the process of generating a new site easy and simple:
- Step 1: Type forrest seed, to populate the directory with template site structure and contents.
- Step 2: Add content by editing docs in task-specific, presentation-neutral XML.
- Step 3: Type forrest to generate a complete website from the XML. Various website styles (known as skins) are available, and custom skins can be developed.
Forrest's focus on low "startup cost" makes it ideal for rapid development of small sites, where time and budget constraints do not allow time-wasting HTML experiments. By separating content from presentation, providing content templates and pre-written skins, Forrest is unequalled at letting content producers get their message out fast. This makes Forrest great for project documentation (notably software projects), intranets and home pages.
Powerful
Forrest is far from a quick & dirty solution however. Forrest is built on one of the world's leading XML publishing frameworks, Apache Cocoon, which provides advanced users with extremely powerful publishing capabilities.
- Multiple task-specific XML formats can be used (howtos, FAQs, changelogs and todo lists supported natively). This list will soon expand to include Docbook and Wiki formats.
- Multiple output formats supported, currently HTML and PDF (using Apache FOP).
- SVG to PNG rendering (using Apache Batik); simply drop a SVG in the appropriate directory and it will be rendered as PNG.
- Transparent inclusion and aggregation of external content, like RSS feeds.
- Anything else possible with the Cocoon sitemap. Database queries, charting, web services integration; the possibilities are constantly growing as Cocoon grows.
- Based on Java, Forrest is platform-independent, making for a documentation system that is just as portable as the XML data it processes.
Static or Dynamic
Uniquely amongst comparable documentation tools, Forrest generates sites that can run both interactively as a dynamic web application, or as statically rendered pages.
This provides a path for site growth: start off small and static, and if dynamic features (user login, forms processing, runtime data, site search etc) are one day needed, these can be accommodated by switching to webapp mode.
Running as a webapp has another advantage: content can be written, and then the rendered output viewed almost instantly in a web browser. This technique requires a bit setting up, but once working it makes Forrest's edit/review cycle faster than command-line transformation tools.
History
Forrest was started in January 2002, with the intention being to create a consistent xml.apache.org website, with a uniform, lightweight, easy-to-navigate layout and structure. In addition, Forrest was to be a Sourceforge-like project management tool, complementing Jakarta Gump (hence the name 'Forrest').
Over time, the grander goals were shelved, and focus shifted to making Forrest a generic documentation tool, rather than something specific to xml.apache.org.
Project Status
Forrest is currently progressing rapidly through a series of 0.x releases. Forrest is quite usable, and used in a number of live sites, including xml.apache.org.
In general, prior to 1.0, ensuring quality of design will be considered more important than retaining backwards-compatibility. Users (particularly those with custom sitemaps and skins) should be aware that this is evolving software, and read the release notes carefully before upgrading. That said, we appreciate the commitment in time that adopters make, and will not make capricious or undocumented backwards-incompatible changes.
Website status
The Forrest website is updated irregularly and manually, while we develop the forrestbot facility which produces the automatically generated site.
Help Wanted!
Forrest is fairly new, and is in need of developers. If you know (or want to learn) XML, Ant, HTML or CSS, then you're qualified to help! As with all Apache projects, Forrest is a meritocracy; the more you put in, the more you get to define the project's future. See the "contributing" page for more information.