apache > forrest
 
Font size:      

Welcome to Apache Forrest

Introduction

Forrest is an XML standards-oriented 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.
Note
For more information on Forrest installation and use, see the Using Forrest guide.

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. Of course, that same methodology can be applied to large projects. Your development team does not need Java experience or even XML skills, to use Forrest. The framework lets you concentrate on content and design.

By separating content from presentation, providing content templates and pre-written skins, Forrest is unequalled at enabling content producers to get their message out fast. This separation of concerns makes Forrest excellent to publish project documentation (notably software projects), intranets, and home pages, and anything else you can think of.

Powerful

Forrest is far from a quick and dirty solution however. Forrest is built on one of the world's leading XML application frameworks, Apache Cocoon, which provides advanced users with extremely powerful publishing capabilities.

  • Multiple task-specific source XML formats can be used (How-To, FAQ, changelogs and todo lists supported natively). Source formats include: Apache xdocs xml format, plain html documents, some Wiki formats, a subset of DocBook, ...
  • Multiple output formats supported, for example 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. Using database queries, charting, web services integration; the possibilities are constantly growing as Cocoon grows. See the Cocoon Features list for the full suite of capabilities.
  • 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

Unique 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 a major advantage during development: content can be written, and then the rendered output viewed almost instantly in a web browser. This webapp technique enables Forrest's edit/review cycle to be faster than command-line transformation tools.

History

Forrest was started in January 2002, with the major use-case being to create a consistent and efficient xml.apache.org group of project websites with a uniform, lightweight, easy-to-navigate layout and structure. In addition, Forrest was to be a Sourceforge-like project management tool, complementing Apache Gump (hence the name 'Forrest').

The focus shifted for Forrest to primarily be a generic documentation tool capable of meeting many needs. Certain relevant project management facilities are being added.

Project Status

Forrest is currently progressing rapidly through a series of 0.x releases. It is certainly usable now (despite not yet being version 1.x). See the growing list of example sites including Many Apache sites.

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 documentation on the Forrest website relates to the current head development version of the source repository. Whatever version of Forrest that you are using provides the local documentation for that specific version. Do 'forrest run' to view it.

The Forrest website is updated manually as needed, while we develop the forrestbot facility.

News and events

  • The Forrest project has evolved to become a "top-level" Apache project. We are making good progress towards the 0.6 release which has many efficiency and usability improvements.
  • Forrest 0.5 was released on 2003-09-13 - much faster, new flexible tab and menu system, numerous skin improvements, DocBook support, Wiki support, improved PDF output, eased maintenance of sitemaps, and more.

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