<?xml version="1.0" encoding="UTF-8"?>
<!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 &amp; 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:bugs">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>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're 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>
