| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <head> |
| <META http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <meta content="Apache Forrest" name="Generator"> |
| <meta name="Forrest-version" content="0.8-dev"> |
| <meta name="Forrest-skin-name" content="pelt"> |
| <title>The Forrest Primer (v0.8-dev)</title> |
| <link type="text/css" href="../skin/basic.css" rel="stylesheet"> |
| <link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet"> |
| <link media="print" type="text/css" href="../skin/print.css" rel="stylesheet"> |
| <link type="text/css" href="../skin/profile.css" rel="stylesheet"> |
| <script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script> |
| <link rel="shortcut icon" href="../favicon.ico"> |
| </head> |
| <body onload="init()"> |
| <script type="text/javascript">ndeSetTextSize();</script> |
| <div id="top"> |
| <!--+ |
| |breadtrail |
| +--> |
| <div class="breadtrail"> |
| <a href="http://www.apache.org/">apache</a> > <a href="http://forrest.apache.org/">forrest</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script> |
| </div> |
| <!--+ |
| |header |
| +--> |
| <div class="header"> |
| <!--+ |
| |start group logo |
| +--> |
| <div class="grouplogo"> |
| <a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="../images/apache-forrest.png" title="The Apache Software Foundation"></a> |
| </div> |
| <!--+ |
| |end group logo |
| +--> |
| <!--+ |
| |start Project Logo |
| +--> |
| <div class="projectlogo"> |
| <a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="../images/project-logo.gif" title="Apache Forrest"></a> |
| </div> |
| <!--+ |
| |end Project Logo |
| +--> |
| <!--+ |
| |start Search |
| +--> |
| <div class="searchbox"> |
| <form action="http://www.google.com/search" method="get" class="roundtopsmall"> |
| <input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google"> |
| <input name="Search" value="Search" type="submit"> |
| </form> |
| </div> |
| <!--+ |
| |end search |
| +--> |
| <!--+ |
| |start Tabs |
| +--> |
| <ul id="tabs"> |
| <li> |
| <a class="unselected" href="../index.html">Welcome</a> |
| </li> |
| <li> |
| <a class="unselected" href="../contrib.html">Developers</a> |
| </li> |
| <li class="current"> |
| <a class="selected" href="../versions/index.html">Versioned Docs</a> |
| </li> |
| <li> |
| <a class="unselected" href="../pluginDocs/index.html">Plugins</a> |
| </li> |
| <li> |
| <a class="unselected" href="../tools/index.html">Tools</a> |
| </li> |
| </ul> |
| <!--+ |
| |end Tabs |
| +--> |
| </div> |
| </div> |
| <div id="main"> |
| <div id="publishedStrip"> |
| <!--+ |
| |start Subtabs |
| +--> |
| <div id="level2tabs"> |
| <a class="unselected" href="../docs_0_70/index.html">0.70 (current)</a><a class="selected" href="../docs_0_80/index.html">0.80-dev (under development)</a><a class="unselected" href="../docs_0_60/index.html">0.60 (past)</a> |
| </div> |
| <!--+ |
| |end Endtabs |
| +--> |
| <script type="text/javascript"><!-- |
| document.write("Last Published: " + document.lastModified); |
| // --></script> |
| </div> |
| <!--+ |
| |breadtrail |
| +--> |
| <div class="breadtrail"> |
| |
| |
| </div> |
| <!--+ |
| |start Menu, mainarea |
| +--> |
| <!--+ |
| |start Menu |
| +--> |
| <div id="menu"> |
| <div onclick="SwitchMenu('menu_selected_1.1', '../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">0.80-dev</div> |
| <div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;"> |
| <div class="menuitem"> |
| <a href="../docs_0_80/index.html">Overview</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/your-project.html">Using Forrest</a> |
| </div> |
| <div onclick="SwitchMenu('menu_1.1.3', '../skin/')" id="menu_1.1.3Title" class="menutitle">How-To</div> |
| <div id="menu_1.1.3" class="menuitemgroup"> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/index.html">Overview</a> |
| </div> |
| <div onclick="SwitchMenu('menu_1.1.3.2', '../skin/')" id="menu_1.1.3.2Title" class="menutitle">Install Forrest</div> |
| <div id="menu_1.1.3.2" class="menuitemgroup"> |
| <div class="menuitem"> |
| <a href="../docs_0_80/build.html" title="Build and install the current unreleased version">Building Forrest from Source</a> |
| </div> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/upgrading_08.html">Upgrading to 0.8</a> |
| </div> |
| <div class="menuitem"> |
| <a href="">Use Forrest</a> |
| </div> |
| <div onclick="SwitchMenu('menu_1.1.3.5', '../skin/')" id="menu_1.1.3.5Title" class="menutitle">Customize Forrest</div> |
| <div id="menu_1.1.3.5" class="menuitemgroup"> |
| <div class="menuitem"> |
| <a href="../docs_0_80/sitemap-explain.html">Sitemaps explained</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/howto-custom-html-source.html">Custom html source</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/project-sitemap.html">Project sitemap</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/howto-editcss.html">Edit CSS (WYSIWYG)</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/howto-pdf-tab.html" title="Generate one pdf-document for all pages of a tab">Create tab PDF</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/howto-corner-images.html">CSS corner SVG</a> |
| </div> |
| </div> |
| <div onclick="SwitchMenu('menu_1.1.3.6', '../skin/')" id="menu_1.1.3.6Title" class="menutitle">Integrate Forrest with tools</div> |
| <div id="menu_1.1.3.6" class="menuitemgroup"> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/howto-forrest-from-maven.html">Maven Integration</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/catalog.html">Using DTD Catalogs</a> |
| </div> |
| </div> |
| <div onclick="SwitchMenu('menu_1.1.3.7', '../skin/')" id="menu_1.1.3.7Title" class="menutitle">Extend Forrest</div> |
| <div id="menu_1.1.3.7" class="menuitemgroup"> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/howto-buildPlugin.html">Build a Plugin</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/skin-package.html">Package new Skins</a> |
| </div> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/howto-asf-mirror.html">Download mirror</a> |
| </div> |
| <div onclick="SwitchMenu('menu_1.1.3.9', '../skin/')" id="menu_1.1.3.9Title" class="menutitle">Adding Documentation</div> |
| <div id="menu_1.1.3.9" class="menuitemgroup"> |
| <div class="menuitem"> |
| <a href="../howto-howto.html" title="Instructions for writing a new howto-document">Write a How-to</a> |
| </div> |
| <div onclick="SwitchMenu('menu_1.1.3.9.2', '../skin/')" id="menu_1.1.3.9.2Title" class="menutitle">Multipage HowTo</div> |
| <div id="menu_1.1.3.9.2" class="menuitemgroup"> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/multi/howto-multi.html">Introduction</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/multi/step1.html">Step 1</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/multi/step2.html">Step 2</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/multi/step3.html">Step 3</a> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/faq.html">FAQs</a> |
| </div> |
| <div onclick="SwitchMenu('menu_1.1.5', '../skin/')" id="menu_1.1.5Title" class="menutitle">Background</div> |
| <div id="menu_1.1.5" class="menuitemgroup"> |
| <div class="menuitem"> |
| <a href="../docs_0_80/linking.html">Menus and Linking</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/searching.html">Search Options in Forrest</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/locationmap.html">Locationmap</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/sitemap-ref.html">Sitemap Reference</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/skins.html" title="About default skins, their naming and features">Skins</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/status-themes.html">Dispatcher versus Skins</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/cap.html">Sourcetype Action</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/validation.html">XML validation and entity resolution</a> |
| </div> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/changes.html">Changes</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/glossary.html">Glossary</a> |
| </div> |
| <div onclick="SwitchMenu('menu_1.1.8', '../skin/')" id="menu_1.1.8Title" class="menutitle">Reference docs</div> |
| <div id="menu_1.1.8" class="menuitemgroup"> |
| <div onclick="SwitchMenu('menu_1.1.8.1', '../skin/')" id="menu_1.1.8.1Title" class="menutitle">DTD documentation</div> |
| <div id="menu_1.1.8.1" class="menuitemgroup"> |
| <div class="menuitem"> |
| <a href="../dtdx/dtd-docs.html">Overview</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../dtdx/document-v20.dtdx.html">document-v20</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../dtdx/howto-v20.dtdx.html">howto-v20</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../dtdx/faq-v20.dtdx.html">faq-v20</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../dtdx/document-v13.dtdx.html">document-v13</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../dtdx/howto-v13.dtdx.html">howto-v13</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../dtdx/faq-v13.dtdx.html">faq-v13</a> |
| </div> |
| </div> |
| <div onclick="SwitchMenu('menu_1.1.8.2', '../skin/')" id="menu_1.1.8.2Title" class="menutitle">Doc samples</div> |
| <div id="menu_1.1.8.2" class="menuitemgroup"> |
| <div class="menuitem"> |
| <a href="../dtdx/document-v13.html">document-v13</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../dtdx/document-v20.html">document-v20</a> |
| </div> |
| </div> |
| </div> |
| <div onclick="SwitchMenu('menu_selected_1.1.9', '../skin/')" id="menu_selected_1.1.9Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Older Docs</div> |
| <div id="menu_selected_1.1.9" class="selectedmenuitemgroup" style="display: block;"> |
| <div class="menupage"> |
| <div class="menupagetitle">Forrest Primer</div> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/libre-intro.html">Libre</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/dreams.html">Dream list</a> |
| </div> |
| <div class="menuitem"> |
| <a href="../docs_0_80/howto/cvs-ssh/howto-cvs-ssh.html">CVS over SSH</a> |
| </div> |
| </div> |
| </div> |
| <div id="credit"> |
| <hr> |
| This is documentation for development version v0.8 |
| (<a href="http://forrest.apache.org/versions/">More</a>)</div> |
| <div id="roundbottom"> |
| <img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div> |
| <!--+ |
| |alternative credits |
| +--> |
| <div id="credit2"> |
| <a href="http://apachecon.com/2007/EU/"><img border="0" title="ApacheCon Europe 2007" alt="ApacheCon Europe 2007 - logo" src="http://apache.org/ads/ApacheCon/2007-europe-125x125.png" style="width: 125px;height: 125px;"></a><a href="http://people.apache.org/calendar.html#200711"><img border="0" title="ApacheCon US 2007" alt="ApacheCon US 2007 - logo" src="http://apache.org/ads/ApacheCon/2007-usa-125x125.png" style="width: 125px;height: 125px;"></a> |
| </div> |
| </div> |
| <!--+ |
| |end Menu |
| +--> |
| <!--+ |
| |start content |
| +--> |
| <div id="content"> |
| <div title="Portable Document Format" class="pdflink"> |
| <a class="dida" href="primer.pdf"><img alt="PDF -icon" src="../skin/images/pdfdoc.gif" class="skin"><br> |
| PDF</a> |
| </div> |
| <div class="trail">Font size: |
| <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button"> |
| <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button"> |
| <input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button"> |
| </div> |
| <h1>The Forrest Primer</h1> |
| <h3>Don't panic!</h3> |
| <div class="abstract"> |
| Forrest is a so-called |
| fledgling |
| project that will have a broad impact on |
| xml.apache.org projects. This |
| document helps you to better understand the vision and scope of Forrest, |
| so that you learn what to expect (or not) from it, and eventually will |
| help you discovering places where your contribution could be valuable to |
| all of us. |
| </div> |
| <div id="motd-area"> |
| This is documentation for development version v0.8 |
| (<a href="http://forrest.apache.org/versions/">More</a>)</div> |
| <div id="minitoc-area"> |
| <ul class="minitoc"> |
| <li> |
| <a href="#History">History</a> |
| </li> |
| <li> |
| <a href="#What+is+Forrest">What is Forrest</a> |
| </li> |
| <li> |
| <a href="#Forrest+roles">Forrest roles</a> |
| </li> |
| <li> |
| <a href="#cvs">Getting your local copy of Forrest through CVS</a> |
| <ul class="minitoc"> |
| <li> |
| <a href="#System+requirements">System requirements</a> |
| </li> |
| <li> |
| <a href="#Getting+Forrest">Getting Forrest</a> |
| </li> |
| <li> |
| <a href="#Step-by-step+cvs+instructions+for+Windows">Step-by-step cvs instructions for Windows</a> |
| </li> |
| <li> |
| <a href="#Step-by-step+cvs+instructions+for+Unix">Step-by-step cvs instructions for Unix</a> |
| </li> |
| </ul> |
| </li> |
| <li> |
| <a href="#Forrest+distribution">Forrest distribution</a> |
| </li> |
| <li> |
| <a href="#The+Forrest+DTDs">The Forrest DTDs</a> |
| </li> |
| <li> |
| <a href="#sitemap">Forrest site generation using Cocoon</a> |
| </li> |
| <li> |
| <a href="#Where+we+are+heading+to">Where we are heading to</a> |
| </li> |
| <li> |
| <a href="#Where+you+can+help">Where you can help</a> |
| </li> |
| </ul> |
| </div> |
| |
| <div class="warning"> |
| <div class="label">Warning</div> |
| <div class="content"> |
| This document is <em>very</em> out of date. There is a lot of good |
| information here, but the focus of the project has shifted away from the |
| Sourceforge-like project management system described here, towards being a |
| simpler project-centric documentation tool -- JT |
| </div> |
| </div> |
| |
| <a name="N10021"></a><a name="History"></a> |
| <h2 class="underlined_10">History</h2> |
| <div class="section"> |
| <p> |
| Forrest has come into existence because of the abysmal state of the |
| <a href="http://xml.apache.org/">xml.apache.org</a> website in |
| comparison with other open source community sites such as Sourceforge. |
| The old site had no consistent visual look and feel, which was largely |
| due to each and every sub-project managing its own site. Furthermore, |
| much information which could potentially support community-based open |
| source development was hidden inside CVS repositories, mailing lists or |
| word of mouth. Once we experienced the usefullness of cross-project |
| collaboration supported by the Jakarta |
| <a href="http://jakarta.apache.org/gump">Gump</a> project, we |
| reckoned having a single application responsible for the management of |
| the xml.apache.org site could be of benefit to our visitors. And if we |
| added aggregated access to other available resources such as download |
| stats or mailing list archives, the new xml.apache.org website could be |
| a true information clearinghouse for interested parties, both users and |
| contributors alike. |
| </p> |
| <p> |
| The Forrest vision was articulated by Stefano Mazzocchi and Sam Ruby, |
| both long-time contributors to Apache projects, in the beginning of |
| 2002, and was rapidly picked up by a bunch of other |
| <a href="../who.html">contributors</a> as well, after a headstart by |
| Nicola Ken Barozzi. So here we are, plenty of work-in-progress to erect |
| what eventually will become a true community website infrastructure for |
| Apache open source development. |
| </p> |
| </div> |
| |
| <a name="N1003A"></a><a name="What+is+Forrest"></a> |
| <h2 class="underlined_10">What is Forrest</h2> |
| <div class="section"> |
| <p> |
| Forrest is a framework that supports the cross-project generation and |
| management of development project websites using Cocoon as its XML |
| publishing framework. It not only provides access to project |
| documentation, but also to other types of information that open source |
| developers depend upon daily: source code repositories, mailing lists, |
| contact info and the like. It aggregates all these resources and |
| publishes them on a regular basis to a website, ensuring a consistent |
| look and feel using skins implemented with XSLT stylesheets. While |
| Forrest's primary focus is XML Apache project websites, it can be |
| adapted to other community development projects as well, as long as they |
| are willing to commit to proven best practices such as Ant for build |
| automation, CVS for source code control and XML as a documentation |
| source format. |
| </p> |
| <p> |
| Forrest is currently based on an |
| <a href="http://jakarta.apache.org/ant/">Ant</a>-based project |
| build system called |
| <a href="http://www.krysalis.org/centipede/">Centipede</a> that |
| drives a <a href="http://cocoon.apache.org/">Cocoon</a>-based |
| document publication system. It contains a set of standard XML document |
| type declarations (DTDs) for project documentation, and different |
| 'skins' consisting of XSLT stylesheets that produce HTML renditions of |
| XML documents using these DTDs. |
| </p> |
| <p> |
| The primary mode of operations for Forrest will be as follows: |
| </p> |
| <div class="note"> |
| <div class="label">Note</div> |
| <div class="content"> |
| This process is not quite ready for prime time yet, but it gives you an |
| idea where we are heading to. Website generation with skins currently |
| works, try using the <span class="codefrag">docs</span> target when invoking the |
| <span class="codefrag">build</span> script. Add a <span class="codefrag">project.skin</span> property when |
| invoking the build script to experience Forrest skins: |
| <span class="codefrag">build{.bat|.sh} -Dproject.skin=<thenameoftheskintouse> |
| docs</span>. Read our <a href="#cvs">CVS crash course</a> to get |
| hold of the current codebase and start playing with it. |
| </div> |
| </div> |
| <ol> |
| |
| <li>Forrest will harvest documentation and related source files from |
| each of the projects within the community that uses Forrest for their website, |
| usually direct from the CVS repository. Which projects are included, and how |
| they are retrieved is configured by a project descriptor file. This is an |
| automated process that occurs several times a day to ensure Forrest has the |
| latest information available.</li> |
| |
| <li>Forrest then uses Cocoon to generate an HTML rendition of each |
| project's website, configured by a generic sitemap. The result is a static |
| collection of HTML documents and related images and stylesheets comprising the |
| project's website. The impact Forrest has on the participating projects should |
| be minimal, i.e. one should simply author XML documents, put them in a |
| well-specified filesystem hierarchy, and Forrest will do its work.</li> |
| |
| <li>Forrest will enrich the documentation source files with common |
| information: a cross-project navigation structure (and rendition, of course), |
| and useful 'community indicators' such as download statistics, number of |
| contributors with commit access, ...</li> |
| |
| <li>If the individual project build runs are successful, the project's |
| website is automagically (re-)published to the (Apache) website, also several |
| times day.</li> |
| |
| </ol> |
| <p> |
| The Forrest website and the overall xml.apache.org website are |
| maintained and published using the same mechanism. |
| </p> |
| </div> |
| |
| <a name="N1007B"></a><a name="Forrest+roles"></a> |
| <h2 class="underlined_10">Forrest roles</h2> |
| <div class="section"> |
| <p> |
| Depending on your interests, your involvement with Forrest may vary, |
| hence your <em>role</em>. We currently envision three different roles: |
| </p> |
| <ul> |
| |
| <li> |
| <strong>User</strong> you want or need to use Forrest for your |
| project because it uses Forrest to manage its documentation.</li> |
| |
| <li> |
| <strong>Adaptor</strong> you want to adapt Forrest to support your |
| individual project needs, presumably outside the XML Apache context, building |
| your own skins or DTDs and the like.</li> |
| |
| <li> |
| <strong>Contributor</strong> you are a fledgling Forresteer and |
| want to contribute to the further development of it. If your contributions are |
| valuable and in true community spirit, you can possibly gain commit access to |
| the Forrest CVS repository and become an Apache committer. The first stage |
| towards becoming a contributor is to join the forrest dev |
| <a href="../mail-lists.html">mailing list</a>, the second is to download |
| Forrest and start playing with it (see below).</li> |
| |
| </ul> |
| <p> |
| Depending on your role, your potential area of interest in Forrest will |
| vary: |
| </p> |
| <table class="ForrestTable" cellspacing="1" cellpadding="4"> |
| |
| <tr> |
| |
| <th colspan="1" rowspan="1">Role</th> |
| <th colspan="1" rowspan="1">Interests</th> |
| |
| </tr> |
| |
| <tr> |
| |
| <td colspan="1" rowspan="1">User</td> |
| <td colspan="1" rowspan="1">Forrest DTDs and documentation filesystem hierarchy (Cocoon |
| sitemap)</td> |
| |
| </tr> |
| |
| <tr> |
| |
| <td colspan="1" rowspan="1">Adaptor</td> |
| <td colspan="1" rowspan="1">+ skin system and build environment</td> |
| |
| </tr> |
| |
| <tr> |
| |
| <td colspan="1" rowspan="1">Contributor</td> |
| <td colspan="1" rowspan="1">+ the Forrest codebase and runtime environment</td> |
| |
| </tr> |
| |
| </table> |
| </div> |
| |
| <a name="N100D8"></a><a name="cvs"></a> |
| <h2 class="underlined_10">Getting your local copy of Forrest through CVS</h2> |
| <div class="section"> |
| <a name="N100DE"></a><a name="System+requirements"></a> |
| <h3 class="underlined_5">System requirements</h3> |
| <p> |
| Forrest requires the following systems to be already installed on your |
| system: |
| </p> |
| <ul> |
| |
| <li> |
| <em>Java Virtual Machine</em> A Java virtual machine must be |
| present. Forrest has been tested against the latest Sun 1.3 JDK.</li> |
| |
| </ul> |
| <a name="N100F0"></a><a name="Getting+Forrest"></a> |
| <h3 class="underlined_5">Getting Forrest</h3> |
| <p> |
| You can retrieve Forrest from its CVS repository or download |
| <a href="http://www.apache.org/dyn/closer.cgi/xml/forrest/">here</a>. |
| <br> |
| Some help with CVS follows (courtesy of our friends of the Cocoon |
| project). |
| </p> |
| <a name="N10100"></a><a name="Step-by-step+cvs+instructions+for+Windows"></a> |
| <h3 class="underlined_5">Step-by-step cvs instructions for Windows</h3> |
| <ol> |
| |
| <li>Download a recent release of WinCVS (homepage is |
| <a href="http://www.wincvs.org/">http://www.wincvs.org/</a>); </li> |
| |
| <li>Install it;</li> |
| |
| <li>Start it;</li> |
| |
| <li>Click on Admin->Preferences;</li> |
| |
| <li> In "Enter the CVSROOT:" enter |
| "<span class="codefrag">:pserver:anoncvs@cvs.apache.org:/home/cvspublic</span>" (without |
| quotes);</li> |
| |
| <li>In "Authentication:" choose "passwd file on the cvs server";</li> |
| |
| <li>Click "Ok";</li> |
| |
| <li>Click Admin->Login;</li> |
| |
| <li> When asked for the password: answer "<span class="codefrag">anoncvs</span>" |
| (without quotes);</li> |
| |
| <li> Click "Create->Checkout module";</li> |
| |
| <li>Module name and path on the server is "<span class="codefrag">xml-forrest</span>" |
| (no quotes);</li> |
| |
| <li>Choose a dir to put the source code in;</li> |
| |
| <li>Click "Ok";</li> |
| |
| <li>If everything goes well, messages will start to appear in the log |
| window;</li> |
| |
| <li>Wait until you see "<span class="codefrag">*****CVS exited normally with code |
| 0*****</span>" in the log window;</li> |
| |
| <li>The Forrest source is now on your harddrive.</li> |
| |
| </ol> |
| <a name="N1014A"></a><a name="Step-by-step+cvs+instructions+for+Unix"></a> |
| <h3 class="underlined_5">Step-by-step cvs instructions for Unix</h3> |
| <ol> |
| |
| <li>Make sure you have a CVS client package installed on your Unix |
| system.</li> |
| |
| <li>Start the shell of your choice.</li> |
| |
| <li>Enter "<span class="codefrag">cvs -d |
| :pserver:anoncvs@cvs.apache.org:/home/cvspublic login</span>".</li> |
| |
| <li>When asked for the password: answer "<span class="codefrag">anoncvs</span>".</li> |
| |
| <li>Enter "<span class="codefrag">cvs -d |
| :pserver:anoncvs@cvs.apache.org:/home/cvspublic -z3 checkout |
| xml-forrest</span>". This will create a directory called |
| "<span class="codefrag">xml-forrest</span>" where the Forrest source will be stored.</li> |
| |
| <li>Wait until cvs has finished.</li> |
| |
| <li>The Forrest source is now on your harddrive.</li> |
| |
| </ol> |
| <p> |
| In case you want to update your Forrest source tree to the current |
| version, change to the "<span class="codefrag">xml-forrest</span>" directory and invoke |
| "<span class="codefrag">cvs -z3 update -d -P</span>". |
| </p> |
| </div> |
| |
| <a name="N1017F"></a><a name="Forrest+distribution"></a> |
| <h2 class="underlined_10">Forrest distribution</h2> |
| <div class="section"> |
| <p> |
| Once you retrieved Forrest from its CVS repository, you will end up with |
| a filesystem hierarchy similar to this inside the |
| <span class="codefrag">xml-forrest</span> home directory: |
| </p> |
| <div class="warning"> |
| <div class="label">Warning</div> |
| <div class="content"> |
| This is highly volatile information! |
| </div> |
| </div> |
| <pre class="code"> |
| +---legal various licenses for included projects |
| +---lib jar library |
| +---src |
| | +---documentation Forrest's documentation (not generally reusable) |
| | | +---content content of the Forrest website |
| | | | +---xdocs Forrest website XML documents |
| | | +---resources Forrest-specific doc resources |
| | | | +---images |
| | +---resources Generic resources for any Forrest-using project. |
| | | +---conf Default (overridable) Forrest config files |
| | | +---library common components (not skin-specific) |
| | | | +---xslt document format transformers e.g. faq->xdoc |
| | | +---convert XSLTs for aiding a transition to Forrest |
| | | +---skins Forrest skins |
| | | +---basic |
| | | +---forrest-site the future xml.apache.org skin |
| | | | +---css Cascading Stylesheets |
| | | | +---images skin-specific images |
| | | | +---xslt the skin stylesheets (per medium) |
| | | | +---fo |
| | | | +---html html rendering skins |
| | | +---jakarta-site |
| | | +---scarab-site |
| | | +---xml-apache-site |
| | | +---schema Generic Forrest DTDs |
| | | +---dtd |
| | | +---relaxng |
| | | +---entity |
| | | +---images Reusable skin-agnostic images |
| | | +---fresh-site A template project structure |
| | | +---forrest-shbat 'shbat' Forrest distribution files |
| | | +---forrestbot Ant-based Forrest deployment tool |
| | | +---forrestbar Mozilla Forrest toolbar |
| | | +---charts charting trials |
| | | +---layout HTML page mock-ups |
| | | | +---resources |
| | | | +---xml.apache.org |
| | | | +---images |
| | |
| +---tools Tools used to build Forrest |
| +---ant Ant 1.6-dev scripts and jars |
| +---stylesheets Stylesheets used for project root XML files |
| |
| </pre> |
| <p> |
| The <span class="codefrag">xml-forrest</span> home directory consists of the main Ant |
| build script (<span class="codefrag">build.xml</span>) and platform-specific batch |
| files/shell scripts to invoke it. Forrest comes with Ant included, so |
| you do not need to install Ant separately. |
| </p> |
| <p> |
| Running Forrest is a batch operation you can start using the provided |
| <span class="codefrag">build.{sh|bat} <targetname></span>. The current main targets |
| are: |
| </p> |
| <ul> |
| |
| <li> |
| <strong><span class="codefrag">docs</span></strong> - generates an HTML rendition of |
| the Forrest website using the default <span class="codefrag">forrest-site</span> skin</li> |
| |
| <li> |
| <strong><span class="codefrag">clean</span></strong> - cleans out the |
| <span class="codefrag">build</span> directory</li> |
| |
| <li> |
| <strong><span class="codefrag">webapp</span></strong> - for those who cannot resist |
| running Forrest live instead of its commandline invocation, this target builds |
| a WAR file you can deploy in your servlet container (currently only tested for |
| Tomcat 4.0.1). Mount-point of the web application will be |
| <span class="codefrag">xml-forrest</span>.</li> |
| |
| </ul> |
| <p> |
| After a build run, Forrest creates a <span class="codefrag">build</span> directory. You |
| can find the generated website in the |
| <span class="codefrag">build/xml-forrest/docs/</span> directory. Forrest also creates a |
| <span class="codefrag">tools/tmp/anttasks/</span> upon its first invocation. These are |
| Centipede-specific compiled Ant tasks. |
| </p> |
| </div> |
| |
| <a name="N101CC"></a><a name="The+Forrest+DTDs"></a> |
| <h2 class="underlined_10">The Forrest DTDs</h2> |
| <div class="section"> |
| <p> |
| Forrest is the reference repository for the XML Apache documentation |
| DTDs. Special care is taken to provide a set of modular, extensible and |
| well-maintained DTDs for project documentation purposes. This modularity |
| is ensured using the |
| <a href="http://www.oasis-open.org/committees/entity/">OASIS |
| catalog</a> mechanism, extensive use of external parameter entities |
| and an entity resolver capable of resolving entities through the |
| aforementioned catalog mechanism. For the docheads amongst us, this |
| means we adhere to the strict use of <span class="codefrag">PUBLIC</span> entity |
| identifiers both in document instances and DTD modules. |
| </p> |
| <p> |
| We have currently identified the following document types: |
| </p> |
| <ul> |
| |
| <li>General documents (<span class="codefrag">document-v11.dtd</span>),</li> |
| |
| <li>How-Tos (<span class="codefrag">howto-v10.dtd</span>),</li> |
| |
| <li>Collections of FAQs (<span class="codefrag">faq-v11.dtd)</span>.</li> |
| |
| </ul> |
| <p> |
| Some work is also under its way for other document types, in close |
| collaboration with the Cocoon project. You will also find some older |
| document types such as <span class="codefrag">changes</span>, <span class="codefrag">javadoc</span>, |
| <span class="codefrag">specification</span> and <span class="codefrag">todo</span>, which are currently |
| under consideration for automatic generation and maintenance using Gump |
| or Centipede descriptors and the like. DTDs will be subject of serious |
| version management as soon as Forrest has a 1.0 release: they are made |
| to depend upon. |
| </p> |
| <p> |
| The DTDs are located in <span class="codefrag">src/resources/schema/dtd</span> and also |
| refer to some character entity collections stored in the |
| <span class="codefrag">src/resources/schema/entity</span> directory. These are referred |
| to by the declarations found in the |
| <span class="codefrag">src/resources/schema/catalog</span> OASIS Catalog file. Take |
| special care using the correct <span class="codefrag">PUBLIC</span> identifiers in the |
| DTD declaration of your instances: |
| </p> |
| <pre class="code"> |
| <?xml version="1.0"?> |
| <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://apache.org/forrest/dtd/document-v12.dtd"> |
| <document> |
| ... |
| |
| </pre> |
| <p> |
| The exact local location of the DTD for validation purposes is obtained |
| by the entity resolver evaluating the mapping scheme as defined in the |
| <span class="codefrag">catalog</span> file. This makes sure that you can move and |
| re-arrange your document instances apart from your DTD files. Later on, |
| the DTDs will be web-accessible from the Forrest website for your |
| perusal. |
| </p> |
| </div> |
| |
| <a name="N1021D"></a><a name="sitemap"></a> |
| <h2 class="underlined_10">Forrest site generation using Cocoon</h2> |
| <div class="section"> |
| <p> |
| The <span class="codefrag">docs</span> target of the Forrest build environment invokes |
| Cocoon as a command-line application to generate an HTML rendition of |
| the project's documentation. It is not within the scope of this document |
| to explain the Cocoon internals, please read its own |
| <a href="http://cocoon.apache.org/">documentation</a> to fully |
| understand the power of Cocoon. |
| </p> |
| <p> |
| Cocoon's site rendition behaviour is configured in a so-called |
| <em>sitemap</em>, a switchboard that binds URLs to an XML processing |
| pipeline. This pipeline typically consists of a Generator, one or more |
| Transformers and a Serializer. Forrest also makes use of Cocoon's |
| aggregation capabilities that merge multiple pipelines into one |
| resulting output document. |
| </p> |
| <p> |
| A typical page generated using Forrest looks like this: |
| </p> |
| <div id="" style="text-align: center;"> |
| <img id="" class="figure" alt="Pages areas" src="images/page-areas.png" height="291" width="336"></div> |
| <p> |
| This page is currently composed of two XML sources which are transformed |
| by a different XSLT stylesheet, aggregated by Cocoon with a |
| post-aggregation stylesheet adding the overall page grid and look & |
| feel. This simple example is handled by the following <em>sitemap</em> |
| snippets (<span class="codefrag">src/documentation/conf/sitemap.xmap</span>): |
| </p> |
| <pre class="code"> |
| <map:match pattern="*.html"> |
| <map:aggregate element="site"> |
| <map:part src="cocoon:/book-{1}.xml"/> |
| <map:part src="cocoon:/body-{1}.xml" label="content"/> |
| </map:aggregate> |
| <map:call resource="skinit"> |
| <map:parameter name="type" value="site2xhtml"/> |
| </map:call> |
| </map:match> |
| </pre> |
| <pre class="code"> |
| <map:match pattern="**book-**.xml"> |
| <map:generate src="content/xdocs/{1}book.xml"/> |
| <map:call resource="skinit"> |
| <map:parameter name="type" value="book2menu"/> |
| </map:call> |
| </map:match> |
| </pre> |
| <pre class="code"> |
| <map:match pattern="body-**.xml"> |
| <map:generate src="content/xdocs/{1}.xml"/> |
| <map:call resource="skinit"> |
| <map:parameter name="type" value="document2html"/> |
| </map:call> |
| </map:match> |
| </pre> |
| <pre class="code"> |
| <map:resource name="skinit"> |
| <map:transform src="skins/@skin@/xslt/html/{type}.xsl"> |
| <map:parameter name="isfaq" value="{isfaq}"/> |
| </map:transform> |
| <map:serialize/> |
| </map:resource> |
| </pre> |
| <p> |
| When an URL (e.g. <span class="codefrag">http://forrest.apache.org/index.html</span>) is |
| passed through the Cocoon system to generate the required page, the |
| pipeline flow is basically as follows: |
| </p> |
| <ol> |
| |
| <li>The URL is matched by the <span class="codefrag">*.html</span> pattern</li> |
| |
| <li>Cocoon responds by aggregating two 'sub-requests'. The first is for |
| the resource <span class="codefrag">book-{1}.xml</span>, the second is for the resource |
| <span class="codefrag">body-{1}.xml</span>. The <span class="codefrag">{1}</span> parameter is replaced by the |
| values of the first wildcard in the matching pattern above. These |
| 'sub-requests' are passed through the Cocoon pipeline just like any other |
| request. This results in the following flow:</li> |
| |
| <ol> |
| |
| <li>The first 'sub-request' (for <span class="codefrag">book-index.xml</span> is matched |
| by the <span class="codefrag">**book-**.xml</span> pattern. This results in the file |
| <span class="codefrag">content/xdocs/book.xml</span> being read. This document is then run |
| through the <span class="codefrag">book2menu</span> stylesheet (which produces an HTML fragment |
| comprising the site navigation, the red area in the image above.</li> |
| |
| <li>The second 'sub-request' is matched by the <span class="codefrag">body-**.xml</span> |
| pattern. This results in the file <span class="codefrag">index.xml</span> being transformed |
| using the <span class="codefrag">document2html</span> stylesheet, the yellow area in the |
| screenshot.</li> |
| |
| </ol> |
| |
| <li>The aggregation result is then transformed using the |
| <span class="codefrag">site2xhtml</span> stylesheet which adds the cherries to the cake. The |
| grey zone.</li> |
| |
| </ol> |
| <p> |
| These <em>skin-specific</em> stylesheets are located in |
| <span class="codefrag">src/documentation/skins/<nameoftheskin>/xslt/html</span>, so |
| if you want to add your own skin, this is the place to be. Apart from |
| these, there exist a number of other stylesheets located in |
| <span class="codefrag">src/documentation/library/xslt</span> and more importantly: |
| </p> |
| <ul> |
| |
| <li> |
| <span class="codefrag">faq2document</span>: transforms documents following the |
| <span class="codefrag">faq-v11</span> DTD to <span class="codefrag">document-v11</span> grammar</li> |
| |
| <li> |
| <span class="codefrag">howto2document</span>: transforms documents following the |
| <span class="codefrag">howto-v10</span> DTD to <span class="codefrag">document-v11</span> grammar</li> |
| |
| <li>and some others.</li> |
| |
| </ul> |
| <p> |
| As you see, all documents, regardless of their original DTD, are |
| transformed to the <span class="codefrag">document</span> DTD prior to rendition. This |
| alleviates the burden of adding new skins to implementing 3 simple |
| stylesheets: <span class="codefrag">book2menu</span>, <span class="codefrag">document2html</span> and |
| <span class="codefrag">site2xhtml</span>. |
| </p> |
| </div> |
| |
| <a name="N102CC"></a><a name="Where+we+are+heading+to"></a> |
| <h2 class="underlined_10">Where we are heading to</h2> |
| <div class="section"> |
| <p> |
| We have been explaining so far where we are now and what already works. |
| The purpose of this document however is to attract newcomers and entice |
| them to start contributing to Forrest. We have a decent generation |
| system for static project documentation, a nice set of skins and some |
| simple but effective DTDs. Our goals however are much more ambitious: we |
| have compiled a <a href="../docs_0_80/dreams.html">dream list</a> that lists |
| most of them. |
| </p> |
| <ul> |
| |
| <li>Our first ambition is to support the project site generation and |
| maintenance of other Apache projects in an automated manner, starting with our |
| own website as a showcase. We are in the process of setting up the shell |
| scripts and Ant tasks for this and will assist projects transitioning to |
| Forrest.</li> |
| |
| <li>As it is often the case with collaborative open source development, |
| there is no formal planning nor task assignments, and we will stick to that |
| practice. We have however compiled a number of functional work areas:</li> |
| |
| </ul> |
| <table class="ForrestTable" cellspacing="1" cellpadding="4"> |
| |
| <tr> |
| |
| <th colspan="1" rowspan="1">URI Namespace Management</th> |
| <td colspan="1" rowspan="1">Forrest will offer access to a broad set of information resources |
| using durable URIs: please review |
| <a href="http://www.w3.org/Provider/Style/URI.html">Tim Berners-Lee</a>'s |
| and <a href="http://www.useit.com/alertbox/990321.html">Jakob |
| Nielsen</a>'s opinion on this. We need a unified URI Namespace management |
| approach, bearing in mind mirroring and 'hackable' URIs.</td> |
| |
| </tr> |
| |
| <tr> |
| |
| <th colspan="1" rowspan="1">Skins</th> |
| <td colspan="1" rowspan="1">We currently have a nice set of skins which should be solidified. |
| Furthermore, we need some serious finetuning of the <span class="codefrag">forrest-site</span> |
| skin that will become the new xml.apache.org look&feel.</td> |
| |
| </tr> |
| |
| <tr> |
| |
| <th colspan="1" rowspan="1">Aggregation<br>and Syndication</th> |
| <td colspan="1" rowspan="1">We plan to aggregate on a per-project basis a number of relevant |
| developer resources, such as project-related news, download statistics, |
| committer bio pages (with photos!), navigable source code listings and the |
| like. Some of these resources need to be made available across content |
| syndication methods such as |
| <a href="http://blogspace.com/rss/">RSS</a>.</td> |
| |
| </tr> |
| |
| <tr> |
| |
| <th colspan="1" rowspan="1">Build Management</th> |
| <td colspan="1" rowspan="1">Fool-proof automation of Forrest runs and site publication using |
| secure transfer methods and <span class="codefrag">cron</span> jobs.</td> |
| |
| </tr> |
| |
| <tr> |
| |
| <th colspan="1" rowspan="1">Document Types</th> |
| <td colspan="1" rowspan="1">Expanding the collection of DTDs, documenting them using formal |
| How-Tos and example documents.</td> |
| |
| </tr> |
| |
| <tr> |
| |
| <th colspan="1" rowspan="1">xml.apache.org</th> |
| <td colspan="1" rowspan="1">Formation of an editorial team for the main xml.apache.org website, |
| working in close collaboration with the |
| <a href="http://xml.apache.org/whoweare.html">PMC</a> and the different |
| sub-project leads.</td> |
| |
| </tr> |
| |
| <tr> |
| |
| <th colspan="1" rowspan="1">Integration</th> |
| <td colspan="1" rowspan="1"> Forrest needs to coexist with existing cross-project collaboration |
| tools such as <a href="http://gump.apache.org/">Gump</a>, |
| <a href="http://scarab.tigris.org/">Scarab</a> and |
| <a href="http://eyebrowse.tigris.org/">Eyebrowse</a> and provide |
| integrated access to them.</td> |
| |
| </tr> |
| |
| <tr> |
| |
| <th colspan="1" rowspan="1">Authoring support</th> |
| <td colspan="1" rowspan="1">Supporting document authors with preconfigured XML editing |
| solutions.</td> |
| |
| </tr> |
| |
| <tr> |
| |
| <th colspan="1" rowspan="1">Content Management</th> |
| <td colspan="1" rowspan="1">Establish an efficient content management practice, supporting |
| versioning, remote access and work flow, presumably supported by a CMS such as |
| <a href="http://jakarta.apache.org/slide/">Slide</a>.</td> |
| |
| </tr> |
| |
| <tr> |
| |
| <th colspan="1" rowspan="1">Information Accessibility</th> |
| <td colspan="1" rowspan="1">We need to be accessible using a wide range of browsing devices |
| operating on different platforms. Special care should be taken to support the |
| <a href="http://www.w3.org/WAI/">WAI</a> guidelines.</td> |
| |
| </tr> |
| |
| </table> |
| </div> |
| |
| <a name="N10394"></a><a name="Where+you+can+help"></a> |
| <h2 class="underlined_10">Where you can help</h2> |
| <div class="section"> |
| <p> |
| By now, you should have a better understanding of Forrest (if that is |
| not the case, consider contributing clarifications to this document). We |
| need more people to get the job done. Forrest is a fun project to work |
| on, and there is something in it for all of us: |
| </p> |
| <ul> |
| |
| <li>XML docheads with skills for document analysis and DTDs |
| development</li> |
| |
| <li>Cocoon developers creating custom Cocoon components connecting |
| Forrest with external resources</li> |
| |
| <li>Graphical whizzkids for true cross-browser HTML/CSS |
| development</li> |
| |
| <li>People who believe XSLT will bring peace to earth (it will, but |
| keep that quiet)</li> |
| |
| <li>Ant wizards able to compete with Nicola and Stefan</li> |
| |
| <li>Unix shell scripting / CVS / cron gurus, preferably bearded</li> |
| |
| </ul> |
| <p> |
| Just drop us a line at the forrest-dev <a href="../mail-lists.html">mail |
| list</a>. |
| </p> |
| </div> |
| |
| <p> |
| That is all, folks. |
| </p> |
| |
| <table class="ForrestTable" cellspacing="1" cellpadding="4"> |
| |
| <tr> |
| |
| <th colspan="1" rowspan="1">Revision history</th> |
| <th colspan="1" rowspan="1"></th> |
| |
| </tr> |
| |
| <tr> |
| |
| <td colspan="1" rowspan="1">2002-05-22</td> |
| <td colspan="1" rowspan="1">Initial version, Steven Noels, stevenn.at.apache.org</td> |
| |
| </tr> |
| |
| <tr> |
| |
| <td colspan="1" rowspan="1">2002-05-23</td> |
| <td colspan="1" rowspan="1">Various rephrasings and clarifications thanks to Ross Gardler, |
| ross.at.saafe.org</td> |
| |
| </tr> |
| |
| <tr> |
| |
| <td colspan="1" rowspan="1">2002-09-23</td> |
| <td colspan="1" rowspan="1">Updated the directory outline (jefft.at.apache.org)</td> |
| |
| </tr> |
| |
| </table> |
| |
| </div> |
| <!--+ |
| |end content |
| +--> |
| <div class="clearboth"> </div> |
| </div> |
| <div id="footer"> |
| <!--+ |
| |start bottomstrip |
| +--> |
| <div class="lastmodified"> |
| <script type="text/javascript"><!-- |
| document.write("Last Published: " + document.lastModified); |
| // --></script> |
| </div> |
| <div class="copyright"> |
| Copyright © |
| 2002-2007 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a> |
| </div> |
| <!--+ |
| |end bottomstrip |
| +--> |
| </div> |
| </body> |
| </html> |
