<?xml version="1.0" encoding="UTF-8"?>
<!--
  Copyright 2002-2005 The Apache Software Foundation or its licensors,
  as applicable.

  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" "http://forrest.apache.org/dtd/document-v12.dtd">
<document>
  <header>
    <title>Welcome to Apache Forrest</title>
  </header>
  <body>
    <section>
      <title>Introduction</title>
      <p>
        Apache Forrest is a publishing framework that transforms
        input from various sources into a unified presentation
        in one or more output formats. The modular and extensible
        plugin architecture is based on Apache Cocoon and relevant
        standards, which separates presentation from content.
        Forrest can generate static documents, or be used as a
        dynamic server, or be deployed by its automated facility.
      </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>: Do <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>: Do <code>'forrest run'</code> then use
          the web browser to immediately review
          changes at <code>http://localhost:8888/</code>
          <ul><li>
             <note>The first time you run Forrest it will attempt to retrieve some plugins
             from the Internet. This will happen whenever a new plugin is specified. For more 
             information see the <link href="site:pluginVersions/overview">plugins documentation</link>.</note>
          </li></ul>
        </li>
        <li><strong>Step 4</strong>: Do <code>'forrest'</code> to generate the
          complete website from the XML sources.
          Various styles (known as skins) are available. Custom skins
          can be developed.</li>
        <li><strong>Step 5</strong>: For more information about installation
          and use, see the
          <link href="site:v0.70//your-project">Using Forrest</link> guide.
        </li>
      </ul>
      <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. Of course, that same methodology
        can scale up 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.
      </p>
      <p>
        By <strong>separating content from
          presentation</strong>, providing <strong>content templates</strong>
        and <strong>pre-written skins</strong>, Forrest is unequalled at enabling
        content producers to get their message out fast.  This separation of
        concerns makes Forrest excellent
        to publish <strong>project documentation</strong> (notably software projects),
        <strong>intranets</strong>, and <strong>home pages</strong>,
        and anything else you can think of.
      </p>
    </section>
    <section>
      <title>Powerful</title>
      <p>
        Forrest is far from a quick and dirty solution however.  Forrest is
        built on the world's leading XML application framework,
        <link href="ext:cocoon">Apache Cocoon</link>, which provides advanced
        users with extremely powerful publishing capabilities.
      </p>
      <ul>
        <li>Multiple task-specific source XML formats can be used
         (<link href="site:v0.70//howto">How-To</link>,
          <link href="site:v0.70//documentation/faq"><acronym title="Frequently Asked
              Questions">FAQ</acronym></link>,
          <link href="site:v0.70//changes">changelogs</link> and
          <link href="site:v0.70//todo">todo lists</link> supported natively).
          Source formats include: Apache xdocs xml format, plain html
          documents, some Wiki formats, a subset of DocBook, ...
        </li>
        <li>Multiple output formats supported, for example 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 the 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:v0.70//changes-rss">RSS feeds</link>.
        </li>
        <li>
          Anything else possible with the
          <link href="ext:cocoon/sitemap">Cocoon sitemap</link>.  Using database
          queries, <link href="ext:apache-stats">charting</link>, web services
          integration; the possibilities are constantly growing as Cocoon grows.
          See the <link href="ext:cocoon/features">Cocoon Features</link> list
          for the full suite of capabilities.
        </li>
        <li>
          Based on Java and XML standards, Forrest is platform-independent,
          making for a documentation system that is just as portable as the
          XML data that it processes.
        </li>
      </ul>
      <section>
        <title>Static or Dynamic</title>
        <p>
          Unique 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 a major advantage during development:
          content can be written, and
          then the rendered output viewed almost instantly in a web browser.
          This <link href="site:v0.70//your-project/webapp">webapp technique</link>
          enables Forrest's edit/review cycle to be faster than command-line
          transformation tools.
        </p>
      </section>
    </section>

    <section>
      <title>History</title>
      <p>Apache Forrest was started in January 2002, with the major use-case being to
        create a consistent and efficient
        <link href="http://xml.apache.org/">xml.apache.org</link> 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 <link href="ext:gump">Apache Gump</link> (hence
        the name 'Forrest').
      </p>
      <p>
        The focus shifted for Apache Forrest to primarily be a generic documentation
        tool capable of meeting many needs. Certain relevant project management
        facilities are being added.
      </p>
    </section>

    <section id="status">
      <title>Project status and website status</title>
      <p>Apache 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
         <link href="site:live-sites">example sites</link> including
         many Apache sites.
      </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>

      <p>
        Documentation on the Apache Forrest website exists for various versions
        including the latest release, the current development, and past releases.
        All versions of Forrest include their own copy of the documentation.
        To view it, do 'cd site-author;
        <link href="site:v0.70//build/run">forrest run</link>' and visit
        http://127.0.0.1:8888/ in your browser.
        The <link href="site:forrest">Apache Forrest website</link> is updated
        manually as needed, while we develop the
        <link href="site:asf-forrestbot">forrestbot</link> deployment facility.
      </p>
    </section>
    <section id="news">
      <title>News and events</title>
      <p>See the <link href="site:events">events</link> list for more detail.
      </p>
      <ul>
        <li>
         <link href="http://apachecon.com/">
           <img src="http://apache.org/images/ac2005eu_135x50.gif"
             alt="ApacheCon Europe 2005" width="135" height="50"/>
         </link>
         Please make plans to join us in Stuttgart, Germany on July 18-22, 2005.
         See our <link href="site:events">events</link> list for the schedule
         of Forrest meetings at ApacheCon.
        </li>
        <li>Apache Forrest 0.6 was released on 2004-10-15. Uses all resources
         in-place so no more copying; workflow and productivity improvements;
         project sitemaps get first chance processing then pass-through
         to core sitemaps; new skins use CSS rather than tables and are
         configurable; enhanced forrestbot.
        </li>
        <li>The Forrest project has evolved to become a "top-level" Apache
         project.
        </li>
      </ul>
    </section>
    <section id="help">
      <title>Help Wanted!</title>
      <p>
        Apache Forrest is fairly new, and is in need of developers.
        If you know (or want to learn) any of XML, Ant, HTML, XSLT, or CSS,
        then you are qualified to help.
      </p>
      <p>
        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>
