<?xml version="1.0" encoding="UTF-8"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You 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>
    <abstract>
      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.
    </abstract>
  </header>
  <body>
    <p>
      The Apache Forrest project uses the opensource
      <link href="site:license">Apache License 2.0</link> and adheres to
      <link href="site:way">open development</link> ideals.
    </p>
    <note>
      Please realise that Forrest is still pre-1.0 release version. It is
      certainly usable for those who are prepared to move with it. See more
      notes about <link href="#status">status</link> below.
    </note>
    <section>
      <title>Explanation and features</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:v0.70//your-project">Using Forrest</link> guide.
        </li>
      </ul>
<!-- FIXME: Needs review for 0.8 -->
      <note>
        The first time you run Forrest it may attempt to retrieve some plugins
        from the Internet (it depends on which distribution of Forrest you have
        installed). In some cases this will happen whenever a new plugin is
        specified, in other cases, for example when you have installed all
        plugins locally or have checked out the full source tree, the plugins
        will be retrieved from your local installation. In all cases once a
        plugin has been installed locally there is no need for Forrest to access
        the Internet. For more information see the
        <link href="site:pluginVersions/overview">plugins documentation</link>.
      </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. 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>
      <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:write-howto">How-To</link>,
          <link href="site:v0.70//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>
      <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 id="status">
      <title>History and project status</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>
      <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. There is also documentation for each plugin and the
        forrest seed site contains further examples and documentation (see
        <link href="site:faq/docs">FAQ</link>).
      </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>
         
         <link href="http://apachecon.com/2006/EU/">ApacheCon EU 2006</link>
         - Please make plans to join us for the conference in
         Dublin, Ireland on 26-30 June 2006.-->
<!--
         See our <link href="site:events">events</link> list for the schedule
         of Forrest meetings at ApacheCon.
--></li>
        <li>Apache Forrest 0.8 was released on 2007-04-16.
          Locationmaps define the mapping from requests to locations,
          which enables content and resources to be located at various
          different sources.
        </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>
