<?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" "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 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.
      </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>
        </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: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 one of the world's leading XML application frameworks, 
        <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:howto">How-To</link>,
          <link href="site:faq"><acronym title="Frequently Asked
              Questions">FAQ</acronym></link>,
          <link href="site:changes">changelogs</link> and
          <link href="site: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: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, 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>
          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: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>
        The documentation on the Apache Forrest website relates to the current
        head development version of the source repository. Whatever version
        of Forrest that you are using, will provide the local documentation for
        that specific version.
        Do '<link href="build.html#run">forrest run</link>'
        to view it.
        The <link href="ext:forrest">Apache Forrest website</link> is updated
        manually as needed, while we develop the 
        <link href="site:forrestbot">forrestbot</link> deployment facility.
           <!-- FIXME: It is out-of-date.
           which produces the
          <link href="http://forrestbot.cocoondev.org/">automatically
            generated</link> site.
            -->
      </p>
    </section>
    <section id="news">
      <title>News and events</title>
      <ul>
        <li>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.
        </li>
        <li>Apache Forrest 0.5 was released on 2003-09-13 - much faster, new flexible
         tab and menu system, numerous skin improvements, support for a sub-set
         of DocBook and Wiki source formats,
         improved PDF output, eased maintenance of sitemaps, and more.
        </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) XML, Ant, HTML 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>
