| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Copyright 2002-2004 The Apache Software Foundation |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd"> |
| <document> |
| <header> |
| <title>Welcome to Forrest</title> |
| </header> |
| <body> |
| <section> |
| <title>Introduction</title> |
| <p>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. |
| </p> |
| </section> |
| |
| <section> |
| <title>User-friendly</title> |
| <p> |
| Forrest is designed with the new user in mind. Much effort has gone |
| into making the process of generating a new site <strong>easy</strong> and |
| <strong>simple</strong>: |
| </p> |
| <ul> |
| <li><strong>Step 1</strong>: Type <code>forrest seed</code>, to populate |
| the directory with template site structure and contents.</li> |
| <li><strong>Step 2</strong>: Add content by editing docs in |
| task-specific, presentation-neutral XML.</li> |
| <li><strong>Step 3</strong>: Type <code>forrest</code> to generate a |
| complete website from the XML. Various website styles (known as skins) |
| are available, and custom skins can be developed.</li> |
| </ul> |
| <note>For more information on Forrest installation and use, see the <link |
| href="site:your-project">Getting Started</link> guide. |
| </note> |
| <p> |
| 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 <strong>separating content from |
| presentation</strong>, providing <strong>content templates</strong> |
| and <strong>pre-written skins</strong>, Forrest is unequalled at letting |
| content producers get their message out fast. This makes Forrest great |
| for <strong>project documentation</strong> (notably software projects), |
| <strong>intranets</strong> and <strong>home pages</strong>. |
| </p> |
| </section> |
| <section> |
| <title>Powerful</title> |
| <p> |
| Forrest is far from a quick & dirty solution however. Forrest is |
| built on one of the world's leading XML publishing frameworks, <link |
| href="ext:cocoon">Apache Cocoon</link>, which provides advanced |
| users with extremely powerful publishing capabilities. |
| </p> |
| <ul> |
| <li>Multiple task-specific XML formats can be used (<link |
| href="site:howto-samples/overview">howtos</link>, <link |
| href="site:faq"><acronym title="Frequently Asked |
| Questions">FAQ</acronym>s</link>, |
| <link href="site:changes">changelogs</link> and <link |
| href="site:todo">todo lists</link> supported natively). This list |
| will soon expand to include Docbook and Wiki formats.</li> |
| <li>Multiple output formats supported, currently HTML and PDF (using |
| <link href="ext:fop">Apache FOP</link>). |
| </li> |
| <li>SVG to PNG rendering (using <link href="ext:batik">Apache |
| Batik</link>); simply drop a SVG in the appropriate directory and it |
| will be rendered as PNG.</li> |
| <li> |
| Transparent inclusion and aggregation of external content, like <link |
| href="site:changes-rss">RSS feeds</link>. |
| </li> |
| <li> |
| Anything else possible with the <link |
| href="ext:cocoon/sitemap">Cocoon sitemap</link>. Database |
| queries, <link href="ext:apache-stats">charting</link>, web services |
| integration; the possibilities are constantly growing as Cocoon grows. |
| </li> |
| <li> |
| Based on Java, Forrest is platform-independent, making for a |
| documentation system that is just as portable as the XML data it |
| processes. |
| </li> |
| </ul> |
| <section> |
| <title>Static or Dynamic</title> |
| <p> |
| Uniquely amongst comparable documentation tools, Forrest generates |
| sites that can run both <strong>interactively</strong> as a dynamic |
| web application, or as statically rendered pages. |
| </p> |
| <p> |
| 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. |
| </p> |
| <p> |
| 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 <link |
| href="site:your-project/webapp">setting up</link>, but once working |
| it makes Forrest's edit/review cycle faster than command-line |
| transformation tools. |
| </p> |
| </section> |
| </section> |
| |
| <section> |
| <title>History</title> |
| <p>Forrest was started in January 2002, with the intention being to |
| create a consistent <link |
| href="http://xml.apache.org/">xml.apache.org</link> website, with a |
| uniform, lightweight, easy-to-navigate layout and structure. In |
| addition, Forrest was to be a Sourceforge-like project management |
| tool, complementing <link href="ext:gump">Jakarta Gump</link> (hence |
| the name 'Forrest'). |
| </p> |
| <p> |
| 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. |
| </p> |
| <warning>This historical xml.apache.org focus can still be observed in a |
| number of this site's older pages. These are being gradually |
| updated.</warning> |
| </section> |
| |
| <section> |
| <title>Project Status</title> |
| <p>Forrest is currently progressing rapidly through a series of 0.x |
| releases. Forrest is quite usable, and used in a number of <link |
| href="site:live-sites">live sites</link>, including <link |
| href="http://xml.apache.org/">xml.apache.org</link>. |
| </p> |
| <p> |
| 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. |
| </p> |
| <section> |
| <title>Website status</title> |
| <p> |
| The <link href="ext:forrest">Forrest website</link> is updated |
| irregularly and manually, while we develop the <link |
| href="site:forrestbot">forrestbot</link> facility which produces the |
| <link href="http://forrestbot.cocoondev.org/">automatically |
| generated</link> site. |
| </p> |
| </section> |
| </section> |
| <section> |
| <title>News and events</title> |
| <ul> |
| <li>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. |
| </li> |
| </ul> |
| </section> |
| <section> |
| <title>Help Wanted!</title> |
| <p> |
| 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 |
| <link href="site:contrib">"contributing"</link> page for more |
| information. |
| </p> |
| </section> |
| </body> |
| </document> |
